feat: contact books public api (#336)

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
This commit is contained in:
Dave Stockley
2026-01-17 06:24:25 +00:00
committed by GitHub
parent 83119f97c8
commit 6786ff003e
14 changed files with 2449 additions and 1803 deletions
@@ -0,0 +1,3 @@
---
openapi: post /v1/contactBooks
---
@@ -0,0 +1,3 @@
---
openapi: delete /v1/contactBooks/{contactBookId}
---
@@ -0,0 +1,3 @@
---
openapi: get /v1/contactBooks/{contactBookId}
---
@@ -0,0 +1,3 @@
---
openapi: get /v1/contactBooks
---
@@ -0,0 +1,3 @@
---
openapi: patch /v1/contactBooks/{contactBookId}
---
+349 -106
View File
@@ -1057,6 +1057,345 @@
}
}
},
"/v1/contactBooks": {
"get": {
"responses": {
"200": {
"description": "Retrieve contact books accessible by the API key",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the contact book",
"example": "clx1234567890"
},
"name": {
"type": "string",
"description": "The name of the contact book",
"example": "Newsletter Subscribers"
},
"teamId": {
"type": "number",
"description": "The ID of the team",
"example": 1
},
"properties": {
"type": "object",
"additionalProperties": { "type": "string" },
"description": "Custom properties for the contact book",
"example": { "customField1": "value1" }
},
"emoji": {
"type": "string",
"description": "The emoji associated with the contact book",
"example": "📙"
},
"createdAt": {
"type": "string",
"description": "The creation timestamp"
},
"updatedAt": {
"type": "string",
"description": "The last update timestamp"
},
"_count": {
"type": "object",
"properties": {
"contacts": {
"type": "number",
"description": "The number of contacts in the contact book"
}
}
}
},
"required": [
"id",
"name",
"teamId",
"properties",
"emoji",
"createdAt",
"updatedAt"
]
}
}
}
}
}
}
},
"post": {
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1 },
"emoji": { "type": "string" },
"properties": {
"type": "object",
"additionalProperties": { "type": "string" }
}
},
"required": ["name"]
}
}
}
},
"responses": {
"200": {
"description": "Create a new contact book",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" },
"teamId": { "type": "number" },
"properties": {
"type": "object",
"additionalProperties": { "type": "string" }
},
"emoji": { "type": "string" },
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [
"id",
"name",
"teamId",
"properties",
"emoji",
"createdAt",
"updatedAt"
]
}
}
}
}
}
}
},
"/v1/contactBooks/{contactBookId}": {
"get": {
"parameters": [
{
"schema": { "type": "string", "example": "clx1234567890" },
"required": true,
"name": "contactBookId",
"in": "path"
}
],
"responses": {
"200": {
"description": "Retrieve the contact book",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" },
"teamId": { "type": "number" },
"properties": {
"type": "object",
"additionalProperties": { "type": "string" }
},
"emoji": { "type": "string" },
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" },
"_count": {
"type": "object",
"properties": {
"contacts": { "type": "number" }
}
}
},
"required": [
"id",
"name",
"teamId",
"properties",
"emoji",
"createdAt",
"updatedAt"
]
}
}
}
},
"403": {
"description": "Forbidden - API key doesn't have access",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": { "error": { "type": "string" } },
"required": ["error"]
}
}
}
},
"404": {
"description": "Contact book not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": { "error": { "type": "string" } },
"required": ["error"]
}
}
}
}
}
},
"patch": {
"parameters": [
{
"schema": { "type": "string", "example": "clx1234567890" },
"required": true,
"name": "contactBookId",
"in": "path"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1 },
"emoji": { "type": "string" },
"properties": {
"type": "object",
"additionalProperties": { "type": "string" }
}
}
}
}
}
},
"responses": {
"200": {
"description": "Update the contact book",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" },
"teamId": { "type": "number" },
"properties": {
"type": "object",
"additionalProperties": { "type": "string" }
},
"emoji": { "type": "string" },
"createdAt": { "type": "string" },
"updatedAt": { "type": "string" }
},
"required": [
"id",
"name",
"teamId",
"properties",
"emoji",
"createdAt",
"updatedAt"
]
}
}
}
},
"403": {
"description": "Forbidden - API key doesn't have access",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": { "error": { "type": "string" } },
"required": ["error"]
}
}
}
},
"404": {
"description": "Contact book not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": { "error": { "type": "string" } },
"required": ["error"]
}
}
}
}
}
},
"delete": {
"parameters": [
{
"schema": { "type": "string", "example": "clx1234567890" },
"required": true,
"name": "contactBookId",
"in": "path"
}
],
"responses": {
"200": {
"description": "Contact book deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": { "type": "string" },
"success": { "type": "boolean" },
"message": { "type": "string" }
},
"required": ["id", "success", "message"]
}
}
}
},
"403": {
"description": "Forbidden - API key doesn't have access",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": { "error": { "type": "string" } },
"required": ["error"]
}
}
}
},
"404": {
"description": "Contact book not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": { "error": { "type": "string" } },
"required": ["error"]
}
}
}
}
}
}
},
"/v1/contactBooks/{contactBookId}/contacts": {
"post": {
"parameters": [
@@ -1288,6 +1627,16 @@
"required": true,
"name": "contactBookId",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 3,
"example": "cuiwqdj74rygf74"
},
"required": true,
"name": "contactId",
"in": "path"
}
],
"requestBody": {
@@ -1358,112 +1707,6 @@
}
},
"/v1/campaigns": {
"get": {
"parameters": [
{
"schema": { "type": "string", "example": "1" },
"required": false,
"name": "page",
"in": "query",
"description": "Page number for pagination (default: 1)"
},
{
"schema": {
"type": "string",
"enum": [
"DRAFT",
"SCHEDULED",
"SENDING",
"PAUSED",
"SENT",
"CANCELLED"
],
"example": "DRAFT"
},
"required": false,
"name": "status",
"in": "query",
"description": "Filter campaigns by status"
},
{
"schema": { "type": "string", "example": "newsletter" },
"required": false,
"name": "search",
"in": "query",
"description": "Search campaigns by name or subject"
}
],
"responses": {
"200": {
"description": "Get list of campaigns",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"campaigns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" },
"from": { "type": "string" },
"subject": { "type": "string" },
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"status": {
"type": "string",
"enum": [
"DRAFT",
"SCHEDULED",
"SENDING",
"PAUSED",
"SENT",
"CANCELLED"
]
},
"scheduledAt": {
"type": "string",
"nullable": true,
"format": "date-time"
},
"total": { "type": "integer" },
"sent": { "type": "integer" },
"delivered": { "type": "integer" },
"unsubscribed": { "type": "integer" }
},
"required": [
"id",
"name",
"from",
"subject",
"createdAt",
"updatedAt",
"status",
"scheduledAt",
"total",
"sent",
"delivered",
"unsubscribed"
]
}
},
"totalPage": { "type": "integer" }
},
"required": ["campaigns", "totalPage"]
}
}
}
}
}
},
"post": {
"requestBody": {
"required": true,
+10
View File
@@ -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": [
@@ -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(),
});
@@ -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;
@@ -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;
@@ -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;
@@ -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;
@@ -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;
+12
View File
@@ -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);