feat: contact books public api (#336)

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

apps/docs/api-reference/contacts/create-contact-book.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /v1/contactBooks
+---

apps/docs/api-reference/contacts/delete-contact-book.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /v1/contactBooks/{contactBookId}
+---

apps/docs/api-reference/contacts/get-contact-book.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /v1/contactBooks/{contactBookId}
+---

apps/docs/api-reference/contacts/list-contact-books.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /v1/contactBooks
+---

apps/docs/api-reference/contacts/update-contact-book.mdx

@@ -0,0 +1,3 @@
+---
+openapi: patch /v1/contactBooks/{contactBookId}
+---

apps/docs/docs.json

@@ -64,6 +64,16 @@
 							"api-reference/emails/cancel-schedule"
 						]
 					},
+					{
+						"group": "Contact Books",
+						"pages": [
+							"api-reference/contacts/list-contact-books",
+							"api-reference/contacts/get-contact-book",
+							"api-reference/contacts/create-contact-book",
+							"api-reference/contacts/update-contact-book",
+							"api-reference/contacts/delete-contact-book"
+						]
+					},
 					{
 						"group": "Contacts",
 						"pages": [

apps/web/src/lib/zod/contact-book-schema.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+export const ContactBookSchema = z.object({
+  id: z
+    .string()
+    .openapi({ description: "The ID of the contact book", example: "clx1234567890" }),
+  name: z
+    .string()
+    .openapi({ description: "The name of the contact book", example: "Newsletter Subscribers" }),
+  teamId: z.number().openapi({ description: "The ID of the team", example: 1 }),
+  properties: z.record(z.string()).openapi({
+    description: "Custom properties for the contact book",
+    example: { customField1: "value1" },
+  }),
+  emoji: z
+    .string()
+    .openapi({ description: "The emoji associated with the contact book", example: "📙" }),
+  createdAt: z.string().openapi({ description: "The creation timestamp" }),
+  updatedAt: z.string().openapi({ description: "The last update timestamp" }),
+  _count: z.object({
+    contacts: z.number().openapi({ description: "The number of contacts in the contact book" }),
+  }).optional(),
+});

apps/web/src/server/public-api/api/contacts/create-contact-book.ts

@@ -0,0 +1,65 @@
+import { createRoute, z } from "@hono/zod-openapi";
+import { ContactBookSchema } from "~/lib/zod/contact-book-schema";
+import { PublicAPIApp } from "~/server/public-api/hono";
+import {
+	createContactBook as createContactBookService,
+	updateContactBook,
+} from "~/server/service/contact-book-service";
+
+const route = createRoute({
+	method: "post",
+	path: "/v1/contactBooks",
+	request: {
+		body: {
+			required: true,
+			content: {
+				"application/json": {
+					schema: z.object({
+						name: z.string().min(1),
+						emoji: z.string().optional(),
+						properties: z.record(z.string()).optional(),
+					}),
+				},
+			},
+		},
+	},
+	responses: {
+		200: {
+			content: {
+				"application/json": {
+					schema: ContactBookSchema,
+				},
+			},
+			description: "Create a new contact book",
+		},
+	},
+});
+
+function createContactBook(app: PublicAPIApp) {
+	app.openapi(route, async (c) => {
+		const team = c.var.team;
+		const body = c.req.valid("json");
+
+		const contactBook = await createContactBookService(team.id, body.name);
+
+		// Update emoji and properties if provided
+		if (body.emoji || body.properties) {
+			const updated = await updateContactBook(contactBook.id, {
+				emoji: body.emoji,
+				properties: body.properties,
+			});
+
+			return c.json({
+				...updated,
+				properties: updated.properties as Record<string, string>,
+			});
+		}
+
+		return c.json({
+			...contactBook,
+			properties: contactBook.properties as Record<string, string>,
+		});
+	});
+}
+
+export default createContactBook;

apps/web/src/server/public-api/api/contacts/delete-contact-book.ts

@@ -0,0 +1,73 @@
+import { createRoute, z } from "@hono/zod-openapi";
+import { PublicAPIApp } from "../../hono";
+import { deleteContactBook as deleteContactBookService } from "~/server/service/contact-book-service";
+import { getContactBook } from "../../api-utils";
+
+const route = createRoute({
+	method: "delete",
+	path: "/v1/contactBooks/{contactBookId}",
+	request: {
+		params: z.object({
+			contactBookId: z.string().openapi({
+				param: {
+					name: "contactBookId",
+					in: "path",
+				},
+				example: "clx1234567890",
+			}),
+		}),
+	},
+	responses: {
+		200: {
+			content: {
+				"application/json": {
+					schema: z.object({
+						id: z.string(),
+						success: z.boolean(),
+						message: z.string(),
+					}),
+				},
+			},
+			description: "Contact book deleted successfully",
+		},
+		403: {
+			content: {
+				"application/json": {
+					schema: z.object({
+						error: z.string(),
+					}),
+				},
+			},
+			description: "Forbidden - API key doesn't have access",
+		},
+		404: {
+			content: {
+				"application/json": {
+					schema: z.object({
+						error: z.string(),
+					}),
+				},
+			},
+			description: "Contact book not found",
+		},
+	},
+});
+
+function deleteContactBook(app: PublicAPIApp) {
+	app.openapi(route, async (c) => {
+		const team = c.var.team;
+		const contactBookId = c.req.valid("param").contactBookId;
+
+		await getContactBook(c, team.id);
+
+		const deletedContactBook = await deleteContactBookService(contactBookId);
+
+		return c.json({
+			id: deletedContactBook.id,
+			success: true,
+			message: "Contact book deleted successfully",
+		});
+	});
+}
+
+export default deleteContactBook;

apps/web/src/server/public-api/api/contacts/get-contact-book.ts

@@ -0,0 +1,85 @@
+import { createRoute, z } from "@hono/zod-openapi";
+import { ContactBookSchema } from "~/lib/zod/contact-book-schema";
+import { PublicAPIApp } from "~/server/public-api/hono";
+import { db } from "~/server/db";
+import { UnsendApiError } from "../../api-error";
+
+const route = createRoute({
+	method: "get",
+	path: "/v1/contactBooks/{contactBookId}",
+	request: {
+		params: z.object({
+			contactBookId: z.string().openapi({
+				param: {
+					name: "contactBookId",
+					in: "path",
+				},
+				example: "clx1234567890",
+			}),
+		}),
+	},
+	responses: {
+		200: {
+			content: {
+				"application/json": {
+					schema: ContactBookSchema,
+				},
+			},
+			description: "Retrieve the contact book",
+		},
+		403: {
+			content: {
+				"application/json": {
+					schema: z.object({
+						error: z.string(),
+					}),
+				},
+			},
+			description:
+				"Forbidden - API key doesn't have access to this contact book",
+		},
+		404: {
+			content: {
+				"application/json": {
+					schema: z.object({
+						error: z.string(),
+					}),
+				},
+			},
+			description: "Contact book not found",
+		},
+	},
+});
+
+function getContactBook(app: PublicAPIApp) {
+	app.openapi(route, async (c) => {
+		const team = c.var.team;
+		const contactBookId = c.req.valid("param").contactBookId;
+
+		const contactBook = await db.contactBook.findFirst({
+			where: {
+				id: contactBookId,
+				teamId: team.id,
+			},
+			include: {
+				_count: {
+					select: { contacts: true },
+				},
+			},
+		});
+
+		if (!contactBook) {
+			throw new UnsendApiError({
+				code: "NOT_FOUND",
+				message: "Contact book not found",
+			});
+		}
+
+		return c.json({
+			...contactBook,
+			properties: contactBook.properties as Record<string, string>,
+		});
+	});
+}
+
+export default getContactBook;

apps/web/src/server/public-api/api/contacts/get-contact-books.ts

@@ -0,0 +1,37 @@
+import { createRoute, z } from "@hono/zod-openapi";
+import { ContactBookSchema } from "~/lib/zod/contact-book-schema";
+import { PublicAPIApp } from "~/server/public-api/hono";
+import { getContactBooks as getContactBooksService } from "~/server/service/contact-book-service";
+
+const route = createRoute({
+	method: "get",
+	path: "/v1/contactBooks",
+	responses: {
+		200: {
+			content: {
+				"application/json": {
+					schema: z.array(ContactBookSchema),
+				},
+			},
+			description: "Retrieve contact books accessible by the API key",
+		},
+	},
+});
+
+function getContactBooks(app: PublicAPIApp) {
+	app.openapi(route, async (c) => {
+		const team = c.var.team;
+
+		const contactBooks = await getContactBooksService(team.id);
+
+		// Ensure properties is a Record<string, string>
+		const sanitizedContactBooks = contactBooks.map((contactBook) => ({
+			...contactBook,
+			properties: contactBook.properties as Record<string, string>,
+		}));
+
+		return c.json(sanitizedContactBooks);
+	});
+}
+
+export default getContactBooks;

apps/web/src/server/public-api/api/contacts/update-contact-book.ts

@@ -0,0 +1,83 @@
+import { createRoute, z } from "@hono/zod-openapi";
+import { ContactBookSchema } from "~/lib/zod/contact-book-schema";
+import { PublicAPIApp } from "~/server/public-api/hono";
+import { updateContactBook as updateContactBookService } from "~/server/service/contact-book-service";
+import { getContactBook } from "../../api-utils";
+
+const route = createRoute({
+	method: "patch",
+	path: "/v1/contactBooks/{contactBookId}",
+	request: {
+		params: z.object({
+			contactBookId: z.string().openapi({
+				param: {
+					name: "contactBookId",
+					in: "path",
+				},
+				example: "clx1234567890",
+			}),
+		}),
+		body: {
+			required: true,
+			content: {
+				"application/json": {
+					schema: z.object({
+						name: z.string().min(1).optional(),
+						emoji: z.string().optional(),
+						properties: z.record(z.string()).optional(),
+					}),
+				},
+			},
+		},
+	},
+	responses: {
+		200: {
+			content: {
+				"application/json": {
+					schema: ContactBookSchema,
+				},
+			},
+			description: "Update the contact book",
+		},
+		403: {
+			content: {
+				"application/json": {
+					schema: z.object({
+						error: z.string(),
+					}),
+				},
+			},
+			description:
+				"Forbidden - API key doesn't have access to this contact book",
+		},
+		404: {
+			content: {
+				"application/json": {
+					schema: z.object({
+						error: z.string(),
+					}),
+				},
+			},
+			description: "Contact book not found",
+		},
+	},
+});
+
+function updateContactBook(app: PublicAPIApp) {
+	app.openapi(route, async (c) => {
+		const team = c.var.team;
+		const contactBookId = c.req.valid("param").contactBookId;
+		const body = c.req.valid("json");
+
+		await getContactBook(c, team.id);
+
+		const updated = await updateContactBookService(contactBookId, body);
+
+		return c.json({
+			...updated,
+			properties: updated.properties as Record<string, string>,
+		});
+	});
+}
+
+export default updateContactBook;

apps/web/src/server/public-api/index.ts

@@ -22,6 +22,11 @@ import getCampaigns from "./api/campaigns/get-campaigns";
 import scheduleCampaign from "./api/campaigns/schedule-campaign";
 import pauseCampaign from "./api/campaigns/pause-campaign";
 import resumeCampaign from "./api/campaigns/resume-campaign";
+import getContactBooks from "./api/contacts/get-contact-books";
+import createContactBook from "./api/contacts/create-contact-book";
+import getContactBook from "./api/contacts/get-contact-book";
+import updateContactBook from "./api/contacts/update-contact-book";
+import deleteContactBook from "./api/contacts/delete-contact-book";
 
 export const app = getApp();
 
@@ -48,6 +53,13 @@ getContacts(app);
 upsertContact(app);
 deleteContact(app);
 
+/**Contact Book related APIs */
+getContactBooks(app);
+createContactBook(app);
+getContactBook(app);
+updateContactBook(app);
+deleteContactBook(app);
+
 /**Campaign related APIs */
 createCampaign(app);
 getCampaign(app);