diff --git a/apps/api/package.json b/apps/api/package.json index e8d4488..a7c8876 100644 --- a/apps/api/package.json +++ b/apps/api/package.json @@ -24,6 +24,7 @@ "nodemailer": "^6.9.16", "stripe": "^22.0.0", "telnyx": "^1.23.0", + "uuid": "^11.0.5", "zod": "^4.3.6" }, @@ -31,6 +32,7 @@ "@types/node": "^22.10.7", "@types/node-cron": "^3.0.11", "@types/nodemailer": "^6.4.17", + "@types/uuid": "^10.0.0", "@vitest/coverage-v8": "^3.2.4", "eslint": "^9.18.0", "tsx": "^4.19.2", diff --git a/apps/api/src/index.ts b/apps/api/src/index.ts index 1ed08f2..4dfdb8c 100644 --- a/apps/api/src/index.ts +++ b/apps/api/src/index.ts @@ -29,6 +29,7 @@ import { devRouter } from "./routes/dev.js"; import { adminSeedRouter } from "./routes/admin/seed.js"; import { startReminderScheduler } from "./services/reminders.js"; import { webhooksRouter } from "./routes/stripe-webhooks.js"; +import { telnyxWebhooksRouter } from "./routes/webhooks/telnyx.js"; const app = new Hono(); @@ -69,6 +70,9 @@ app.route("/api/portal", portalRouter); // Public Stripe webhook endpoint — signature-verified, no auth required app.route("/api/webhooks/stripe", webhooksRouter); +// Public Telnyx messaging webhook — signature-verified, no auth required +app.route("/api/webhooks/telnyx", telnyxWebhooksRouter); + // Dev/demo routes — config is always public, users endpoint is guarded internally app.route("/api/dev", devRouter); diff --git a/apps/api/src/routes/webhooks/telnyx.ts b/apps/api/src/routes/webhooks/telnyx.ts new file mode 100644 index 0000000..f8393a3 --- /dev/null +++ b/apps/api/src/routes/webhooks/telnyx.ts @@ -0,0 +1,85 @@ +import { Hono } from "hono"; +import { createHmac } from "crypto"; +import { + handleMessageReceived, + handleMessageFinalized, + TelnyxMessageReceivedPayload, +} from "../../services/messaging/inbound.js"; + +export const telnyxWebhooksRouter = new Hono(); + +function validateTelnyxSignature(rawBody: string, signature: string | null): boolean { + if (!signature) return false; + const secret = process.env.TELNYX_WEBHOOK_SECRET; + if (!secret) return false; + + try { + const hmac = createHmac("sha256", secret); + const expected = `sha256=${hmac.update(rawBody).digest("hex")}`; + + const sigBuf = Buffer.from(signature); + const expBuf = Buffer.from(expected); + + if (sigBuf.length !== expBuf.length) return false; + + let diff = 0; + for (let i = 0; i < sigBuf.length; i++) { + const sigByte = sigBuf[i] ?? 0; + const expByte = expBuf[i] ?? 0; + diff |= sigByte ^ expByte; + } + return diff === 0; + } catch { + return false; + } +} + +telnyxWebhooksRouter.post("/messaging", async (c) => { + const signature = c.req.header("telnyx-signature"); + + let rawBody: string; + try { + rawBody = await c.req.text(); + } catch { + return c.json({ error: "Could not read body" }, 400); + } + + if (!validateTelnyxSignature(rawBody, signature ?? null)) { + return c.json({ error: "Invalid signature" }, 401); + } + + let payload: TelnyxMessageReceivedPayload; + try { + payload = JSON.parse(rawBody) as TelnyxMessageReceivedPayload; + } catch { + return c.json({ error: "Invalid JSON" }, 400); + } + + const eventType = payload.data?.event_type; + if (!eventType) { + return c.json({ error: "Missing event_type" }, 400); + } + + if (eventType === "message.received") { + try { + await handleMessageReceived(payload); + } catch (err) { + const msg = err instanceof Error ? err.message : "Unknown error"; + if (msg.startsWith("No business owns")) { + return c.json({ error: "Unknown messaging number" }, 404); + } + return c.json({ error: msg }, 500); + } + return c.json({ received: true }); + } + + if (eventType === "message.finalized") { + const result = await handleMessageFinalized(payload); + if (result) { + return c.json({ received: true, messageId: result.messageId, status: result.newStatus }); + } + return c.json({ received: true, messageId: null }); + } + + return c.json({ received: true }); +}); \ No newline at end of file diff --git a/apps/api/src/services/messaging/__tests__/inbound.test.ts b/apps/api/src/services/messaging/__tests__/inbound.test.ts new file mode 100644 index 0000000..76dfeaf --- /dev/null +++ b/apps/api/src/services/messaging/__tests__/inbound.test.ts @@ -0,0 +1,275 @@ +import { describe, it, expect, vi, beforeEach } from "vitest"; +import { + findOrCreateConversation, + upsertMessage, + handleMessageReceived, + handleMessageFinalized, + TelnyxMessageReceivedPayload, +} from "../inbound.js"; +import * as schema from "@groombook/db"; + +vi.mock("@groombook/db", () => ({ + getDb: vi.fn(), + conversations: { id: "", businessId: "", clientId: "", externalNumber: "", businessNumber: "", channel: "", lastMessageAt: null, status: "", createdAt: null, updatedAt: null }, + messages: { id: "", conversationId: "", direction: "", body: "", status: "", providerMessageId: "", sentByStaffId: null, createdAt: null, deliveredAt: null, readByClientAt: null }, + businessSettings: { id: "", messagingPhoneNumber: "" }, + eq: vi.fn(), + and: vi.fn(), + sql: vi.fn(), +})); + +const mockDb = { + select: vi.fn().mockReturnThis(), + from: vi.fn().mockReturnThis(), + where: vi.fn().mockReturnThis(), + limit: vi.fn().mockReturnThis(), + insert: vi.fn().mockReturnThis(), + update: vi.fn().mockReturnThis(), + returning: vi.fn().mockReturnThis(), +}; + +vi.mocked(schema.getDb).mockReturnValue(mockDb as unknown as ReturnType); + +const makePayload = ( + eventType: "message.received" | "message.sent" | "message.finalized", + messageId: string, + fromPhone: string, + toPhone: string, + body = "Hello" +): TelnyxMessageReceivedPayload => ({ + data: { + id: "evt-1", + event_type: eventType, + payload: { + message: { + id: messageId, + from: { phone: fromPhone, carrier: "carrier" }, + to: [{ phone: toPhone }], + body, + }, + }, + }, +}); + +describe("signature validation via route", () => { + it("returns 401 when telnyx-signature header is missing", async () => { + const { telnyxWebhooksRouter } = await import("../../../routes/webhooks/telnyx.js"); + const payload = JSON.stringify(makePayload("message.received", "msg-123", "+1555111", "+1555222")); + const req = new Request("http://localhost/api/webhooks/telnyx/messaging", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: payload, + }); + const res = await telnyxWebhooksRouter.fetch(req); + expect(res.status).toBe(401); + }); + + it("returns 401 when signature does not match", async () => { + process.env.TELNYX_WEBHOOK_SECRET = "test-secret"; + const { telnyxWebhooksRouter } = await import("../../../routes/webhooks/telnyx.js"); + const payload = JSON.stringify(makePayload("message.received", "msg-123", "+1555111", "+1555222")); + const req = new Request("http://localhost/api/webhooks/telnyx/messaging", { + method: "POST", + headers: { + "Content-Type": "application/json", + "telnyx-signature": "sha256=bad", + }, + body: payload, + }); + const res = await telnyxWebhooksRouter.fetch(req); + expect(res.status).toBe(401); + }); +}); + +describe("findOrCreateConversation", () => { + beforeEach(() => { + vi.clearAllMocks(); + mockDb.select.mockReset(); + mockDb.from.mockReset(); + mockDb.where.mockReset(); + mockDb.limit.mockReset(); + mockDb.insert.mockReset(); + mockDb.update.mockReset(); + mockDb.returning.mockReset(); + }); + + it("returns existing conversation when found", async () => { + mockDb.select.mockReturnValue({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockReturnValue([{ id: "conv-1", clientId: "client-1" }]), + }), + }), + }); + + const result = await findOrCreateConversation("biz-1", "+1555111", "+1555222"); + expect(result.id).toBe("conv-1"); + }); + + it("creates new conversation when none exists", async () => { + mockDb.select.mockReturnValue({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockReturnValue([]), + }), + }), + }); + mockDb.insert.mockReturnValue({ + values: vi.fn().mockReturnValue({ + returning: vi.fn().mockReturnValue([{ id: "conv-2", clientId: "client-2" }]), + }), + }); + + const result = await findOrCreateConversation("biz-1", "+1555111", "+1555222"); + expect(result.id).toBe("conv-2"); + }); +}); + +describe("upsertMessage", () => { + beforeEach(() => { + vi.clearAllMocks(); + }); + + it("returns isNew=false when message with providerMessageId already exists", async () => { + mockDb.select.mockReturnValue({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockReturnValue([{ id: "msg-existing" }]), + }), + }), + }); + + const result = await upsertMessage("msg-123", "conv-1", "inbound", "Hello", "received"); + expect(result.isNew).toBe(false); + expect(result.id).toBe("msg-existing"); + }); + + it("inserts new message and returns isNew=true", async () => { + mockDb.select.mockReturnValue({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockReturnValue([]), + }), + }), + }); + mockDb.insert.mockReturnValue({ + values: vi.fn().mockReturnValue({ + returning: vi.fn().mockReturnValue([{ id: "msg-new" }]), + }), + }); + + const result = await upsertMessage("msg-new-123", "conv-1", "inbound", "New message", "queued"); + expect(result.isNew).toBe(true); + expect(result.id).toBe("msg-new"); + }); +}); + +describe("handleMessageReceived", () => { + beforeEach(() => { + vi.clearAllMocks(); + mockDb.select.mockReset(); + mockDb.from.mockReset(); + mockDb.where.mockReset(); + mockDb.limit.mockReset(); + mockDb.insert.mockReset(); + mockDb.update.mockReset(); + mockDb.returning.mockReset(); + }); + + it("returns 404 when no business owns the to number", async () => { + mockDb.select.mockReturnValue({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockReturnValue([]), + }), + }), + }); + + const payload = makePayload("message.received", "msg-123", "+1555111", "+1555000"); + await expect(handleMessageReceived(payload)).rejects.toThrow("No business owns messaging number"); + }); + + it("creates conversation and message for valid inbound", async () => { + mockDb.select + .mockReturnValueOnce({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockReturnValue([]), + }), + }), + }) + .mockReturnValueOnce({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockReturnValue([{ id: "biz-1" }]), + }), + }), + }); + + mockDb.insert.mockReturnValue({ + values: vi.fn().mockReturnValue({ + returning: vi.fn().mockReturnValue([{ id: "conv-new", clientId: "client-1" }]), + }), + }); + mockDb.update.mockReturnValue({ + set: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({}), + }), + }); + mockDb.select.mockReturnValueOnce({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockReturnValue([]), + }), + }), + }); + mockDb.insert.mockReturnValueOnce({ + values: vi.fn().mockReturnValue({ + returning: vi.fn().mockReturnValue([{ id: "msg-new" }]), + }), + }); + + const payload = makePayload("message.received", "msg-abc", "+1555111", "+1555222", "Test message"); + const result = await handleMessageReceived(payload); + expect(result.messageId).toBe("msg-new"); + }); +}); + +describe("handleMessageFinalized", () => { + beforeEach(() => { + vi.clearAllMocks(); + }); + + it("returns null when message not found", async () => { + mockDb.select.mockReturnValue({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockReturnValue([]), + }), + }), + }); + + const payload = makePayload("message.finalized", "msg-unknown", "+1555111", "+1555222"); + const result = await handleMessageFinalized(payload); + expect(result).toBeNull(); + }); + + it("updates status to delivered for finalized inbound", async () => { + mockDb.select.mockReturnValue({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockReturnValue([{ id: "msg-1", status: "sent" }]), + }), + }), + }); + mockDb.update.mockReturnValue({ + set: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({}), + }), + }); + + const payload = makePayload("message.finalized", "msg-1", "+1555111", "+1555222"); + const result = await handleMessageFinalized(payload); + expect(result?.newStatus).toBe("delivered"); + }); +}); \ No newline at end of file diff --git a/apps/api/src/services/messaging/__tests__/outbound.test.ts b/apps/api/src/services/messaging/__tests__/outbound.test.ts new file mode 100644 index 0000000..0e8545f --- /dev/null +++ b/apps/api/src/services/messaging/__tests__/outbound.test.ts @@ -0,0 +1,200 @@ +import { describe, it, expect, vi, beforeEach } from "vitest"; + +const mockSendSms = vi.fn(); +const mockGetDb = vi.fn(); +const mockUuidv4 = vi.fn(); + +vi.mock("../../sms.js", () => ({ + sendSms: mockSendSms, +})); + +vi.mock("@groombook/db", () => ({ + getDb: () => mockGetDb(), + conversations: {}, + messages: {}, + clients: {}, + businessSettings: {}, + eq: vi.fn((a, b) => [a, b]), + and: vi.fn((...args) => args), +})); + +vi.mock("uuid", () => ({ + v4: () => mockUuidv4(), +})); + +const { sendMessage, MissingTenantPhoneNumberError } = await import("../outbound.ts"); + +describe("sendMessage", () => { + beforeEach(() => { + vi.clearAllMocks(); + mockUuidv4.mockReturnValue("test-uuid"); + }); + + function buildSelectMock(results: unknown[]) { + return vi.fn().mockReturnValue({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockResolvedValue(results), + }), + }), + }); + } + + it("returns suppressed=true when client has no phone", async () => { + mockGetDb.mockReturnValue({ + select: buildSelectMock([{ phone: null, smsOptIn: true }]), + }); + + const result = await sendMessage({ + businessId: "biz-1", + clientId: "client-1", + body: "Hello", + }); + + expect(result).toEqual({ suppressed: true }); + expect(mockSendSms).not.toHaveBeenCalled(); + }); + + it("returns suppressed=true when client has opted out of SMS", async () => { + mockGetDb.mockReturnValue({ + select: buildSelectMock([{ phone: "+1234567890", smsOptIn: false }]), + }); + + const result = await sendMessage({ + businessId: "biz-1", + clientId: "client-1", + body: "Hello", + }); + + expect(result).toEqual({ suppressed: true }); + expect(mockSendSms).not.toHaveBeenCalled(); + }); + + it("throws MissingTenantPhoneNumberError when tenant has no messaging phone", async () => { + mockGetDb.mockReturnValue({ + select: vi + .fn() + .mockReturnValueOnce({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockResolvedValue([{ phone: "+1234567890", smsOptIn: true }]), + }), + }), + }) + .mockReturnValueOnce({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockResolvedValue([{ messagingPhoneNumber: null }]), + }), + }), + }), + }); + + await expect( + sendMessage({ businessId: "biz-1", clientId: "client-1", body: "Hello" }) + ).rejects.toThrow(MissingTenantPhoneNumberError); + }); + + it("persists provider message id on success", async () => { + const messageId = "msg-1"; + const conversationId = "conv-1"; + + mockGetDb.mockReturnValue({ + select: vi + .fn() + .mockReturnValueOnce({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockResolvedValue([{ phone: "+1234567890", smsOptIn: true }]), + }), + }), + }) + .mockReturnValueOnce({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockResolvedValue([{ messagingPhoneNumber: "+1987654321" }]), + }), + }), + }) + .mockReturnValueOnce({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockResolvedValue([{ id: conversationId }]), + }), + }), + }), + insert: vi.fn().mockReturnValue({ + values: vi.fn().mockReturnValue({ + returning: vi.fn().mockResolvedValue([{ id: messageId }]), + }), + }), + update: vi.fn().mockReturnValue({ + set: vi.fn().mockReturnValue({ + where: vi.fn().mockResolvedValue([]), + }), + }), + }); + + mockSendSms.mockResolvedValue({ messageId: "provider-msg-1", status: "sent" }); + + const result = await sendMessage({ + businessId: "biz-1", + clientId: "client-1", + body: "Hello", + }); + + expect(result).toEqual({ + messageId, + providerMessageId: "provider-msg-1", + status: "sent", + suppressed: false, + }); + expect(mockSendSms).toHaveBeenCalledWith("+1234567890", "Hello", undefined); + }); + + it("persists error on Telnyx failure", async () => { + const messageId = "msg-1"; + + mockGetDb.mockReturnValue({ + select: vi + .fn() + .mockReturnValueOnce({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockResolvedValue([{ phone: "+1234567890", smsOptIn: true }]), + }), + }), + }) + .mockReturnValueOnce({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockResolvedValue([{ messagingPhoneNumber: "+1987654321" }]), + }), + }), + }) + .mockReturnValueOnce({ + from: vi.fn().mockReturnValue({ + where: vi.fn().mockReturnValue({ + limit: vi.fn().mockResolvedValue([]), + }), + }), + }), + insert: vi.fn().mockReturnValue({ + values: vi.fn().mockReturnValue({ + returning: vi.fn().mockResolvedValue([{ id: messageId }]), + }), + }), + update: vi.fn().mockReturnValue({ + set: vi.fn().mockReturnValue({ + where: vi.fn().mockResolvedValue([]), + }), + }), + }); + + mockSendSms.mockRejectedValue(new Error("Telnyx API error")); + + await expect( + sendMessage({ businessId: "biz-1", clientId: "client-1", body: "Hello" }) + ).rejects.toThrow("Telnyx API error"); + }); +}); \ No newline at end of file diff --git a/apps/api/src/services/messaging/inbound.ts b/apps/api/src/services/messaging/inbound.ts new file mode 100644 index 0000000..723afb0 --- /dev/null +++ b/apps/api/src/services/messaging/inbound.ts @@ -0,0 +1,182 @@ +import { getDb, conversations, messages, businessSettings, eq, and, sql } from "@groombook/db"; +import { v4 as uuidv4 } from "uuid"; + +export interface TelnyxMessageReceivedPayload { + data: { + id: string; + event_type: "message.received" | "message.sent" | "message.finalized"; + payload: { + message: { + id: string; + from: { phone: string; carrier?: string }; + to: { phone: string }[]; + body: string; + media?: Array<{ type: string; url: string }>; + }; + recording?: unknown; + leg_count?: number; + }; + }; +} + +export async function findOrCreateConversation( + businessId: string, + clientPhone: string, + businessNumber: string +): Promise<{ id: string; clientId: string }> { + const db = getDb(); + + const [existing] = await db + .select({ id: conversations.id, clientId: conversations.clientId }) + .from(conversations) + .where( + and( + eq(conversations.businessId, businessId), + eq(conversations.externalNumber, clientPhone), + eq(conversations.businessNumber, businessNumber) + ) + ) + .limit(1); + + if (existing) { + return { id: existing.id, clientId: existing.clientId }; + } + + const [business] = await db + .select({ primaryClientId: sql`${businessSettings.id}` }) + .from(businessSettings) + .where(eq(businessSettings.id, businessId)) + .limit(1); + + const clientId = business?.primaryClientId ?? uuidv4(); + + const [created] = await db + .insert(conversations) + .values({ + id: uuidv4(), + businessId, + clientId, + channel: "sms", + externalNumber: clientPhone, + businessNumber, + lastMessageAt: new Date(), + status: "active", + }) + .returning({ id: conversations.id, clientId: conversations.clientId }); + + if (!created) throw new Error("Failed to create conversation"); + + return { id: created.id, clientId: created.clientId }; +} + +export async function upsertMessage( + providerMessageId: string, + conversationId: string, + direction: "inbound" | "outbound", + body: string, + status: "queued" | "sent" | "delivered" | "failed" | "received", + sentByStaffId?: string +): Promise<{ id: string; isNew: boolean }> { + const db = getDb(); + + const [existing] = await db + .select({ id: messages.id }) + .from(messages) + .where(eq(messages.providerMessageId, providerMessageId)) + .limit(1); + + if (existing) { + return { id: existing.id, isNew: false }; + } + + const [inserted] = await db + .insert(messages) + .values({ + id: uuidv4(), + conversationId, + direction, + body, + status, + providerMessageId, + sentByStaffId: sentByStaffId ?? null, + }) + .returning({ id: messages.id }); + + if (!inserted) throw new Error("Failed to insert message"); + + return { id: inserted.id, isNew: true }; +} + +export async function resolveBusinessIdByMessagingNumber(toNumber: string): Promise { + const db = getDb(); + const [settings] = await db + .select({ id: businessSettings.id }) + .from(businessSettings) + .where(eq(businessSettings.messagingPhoneNumber, toNumber)) + .limit(1); + return settings?.id ?? null; +} + +export async function handleMessageReceived(payload: TelnyxMessageReceivedPayload): Promise<{ conversationId: string; messageId: string }> { + const { message } = payload.data.payload; + const fromPhone = message.from.phone; + const toPhone = message.to[0]?.phone; + + if (!toPhone) { + throw new Error("No recipient phone in payload"); + } + + const businessId = await resolveBusinessIdByMessagingNumber(toPhone); + if (!businessId) { + throw new Error(`No business owns messaging number: ${toPhone}`); + } + + const { id: conversationId } = await findOrCreateConversation(businessId, fromPhone, toPhone); + + await getDb() + .update(conversations) + .set({ lastMessageAt: new Date(), updatedAt: new Date() }) + .where(eq(conversations.id, conversationId)); + + const { id: messageId } = await upsertMessage( + message.id, + conversationId, + "inbound", + message.body, + "received" + ); + + return { conversationId, messageId }; +} + +export async function handleMessageFinalized(payload: TelnyxMessageReceivedPayload): Promise<{ messageId: string; newStatus: string } | null> { + const { message } = payload.data.payload; + + if (!message.id) return null; + + const db = getDb(); + const [existing] = await db + .select({ id: messages.id, status: messages.status }) + .from(messages) + .where(eq(messages.providerMessageId, message.id)) + .limit(1); + + if (!existing) return null; + + let newStatus = existing.status; + if (payload.data.event_type === "message.finalized") { + const deliveryReceipt = message as { direction?: string; to?: Array<{ phone: string }> }; + if (deliveryReceipt.direction === "inbound") { + newStatus = "delivered"; + } + } + + if (newStatus !== existing.status) { + await db + .update(messages) + .set({ status: newStatus, deliveredAt: new Date(), updatedAt: new Date() }) + .where(eq(messages.id, existing.id)); + } + + return { messageId: existing.id, newStatus }; +} diff --git a/apps/api/src/services/messaging/outbound.ts b/apps/api/src/services/messaging/outbound.ts new file mode 100644 index 0000000..9b2896e --- /dev/null +++ b/apps/api/src/services/messaging/outbound.ts @@ -0,0 +1,161 @@ +import { getDb, conversations, messages, clients, businessSettings, eq, and } from "@groombook/db"; +import { v4 as uuidv4 } from "uuid"; +import { sendSms } from "../sms.js"; + +export interface SendMessageOptions { + businessId: string; + clientId: string; + body: string; + sentByStaffId?: string; + mediaUrls?: string[]; +} + +export interface SendMessageResult { + messageId: string; + providerMessageId: string; + status: string; + suppressed: false; +} + +export interface SendMessageSuppressed { + suppressed: true; +} + +export type SendMessageResponse = SendMessageResult | SendMessageSuppressed; + +export class MissingTenantPhoneNumberError extends Error { + constructor() { + super("Tenant messagingPhoneNumber is not configured"); + this.name = "MissingTenantPhoneNumberError"; + } +} + +async function findOrCreateConversation( + businessId: string, + clientId: string, + externalNumber: string, + businessNumber: string +): Promise<{ id: string }> { + const db = getDb(); + + const [existing] = await db + .select({ id: conversations.id }) + .from(conversations) + .where( + and( + eq(conversations.businessId, businessId), + eq(conversations.externalNumber, externalNumber), + eq(conversations.businessNumber, businessNumber) + ) + ) + .limit(1); + + if (existing) return { id: existing.id }; + + const [created] = await db + .insert(conversations) + .values({ + id: uuidv4(), + businessId, + clientId, + channel: "sms", + externalNumber, + businessNumber, + lastMessageAt: new Date(), + status: "active", + }) + .returning({ id: conversations.id }); + + if (!created) throw new Error("Failed to create conversation"); + + return { id: created.id }; +} + +async function resolveFromNumber(businessId: string): Promise { + const db = getDb(); + const [settings] = await db + .select({ messagingPhoneNumber: businessSettings.messagingPhoneNumber }) + .from(businessSettings) + .where(eq(businessSettings.id, businessId)) + .limit(1); + return settings?.messagingPhoneNumber ?? null; +} + +export async function sendMessage(opts: SendMessageOptions): Promise { + const db = getDb(); + const { businessId, clientId, body, sentByStaffId, mediaUrls } = opts; + + const [client] = await db + .select({ phone: clients.phone, smsOptIn: clients.smsOptIn }) + .from(clients) + .where(eq(clients.id, clientId)) + .limit(1); + + if (!client?.phone) { + return { suppressed: true }; + } + + if (!client.smsOptIn) { + return { suppressed: true }; + } + + const from = await resolveFromNumber(businessId); + if (!from) throw new MissingTenantPhoneNumberError(); + + const to = client.phone; + const conversationId = (await findOrCreateConversation(businessId, clientId, to, from)).id; + + const [queuedMessage] = await db + .insert(messages) + .values({ + id: uuidv4(), + conversationId, + direction: "outbound", + body, + status: "queued", + sentByStaffId: sentByStaffId ?? null, + }) + .returning({ id: messages.id }); + + if (!queuedMessage) throw new Error("Failed to insert queued message"); + + try { + const result = await sendSms(to, body, mediaUrls); + + await db + .update(messages) + .set({ + status: "sent", + providerMessageId: result.messageId, + updatedAt: new Date(), + }) + .where(eq(messages.id, queuedMessage.id)); + + await db + .update(conversations) + .set({ lastMessageAt: new Date(), updatedAt: new Date() }) + .where(eq(conversations.id, conversationId)); + + return { + messageId: queuedMessage.id, + providerMessageId: result.messageId, + status: result.status, + suppressed: false, + }; + } catch (err) { + const errorCode = err instanceof Error ? err.name : "UNKNOWN"; + const errorMessage = err instanceof Error ? err.message : String(err); + + await db + .update(messages) + .set({ + status: "failed", + errorCode, + errorMessage, + updatedAt: new Date(), + }) + .where(eq(messages.id, queuedMessage.id)); + + throw err; + } +} \ No newline at end of file diff --git a/apps/api/src/services/sms.ts b/apps/api/src/services/sms.ts index 5be4009..5a2a9c3 100644 --- a/apps/api/src/services/sms.ts +++ b/apps/api/src/services/sms.ts @@ -139,4 +139,4 @@ export async function smsSend( await provider.sendSms(to, body, mediaUrls); return true; -} +} \ No newline at end of file diff --git a/packages/db/migrations/0030_messaging.sql b/packages/db/migrations/0030_messaging.sql new file mode 100644 index 0000000..c404505 --- /dev/null +++ b/packages/db/migrations/0030_messaging.sql @@ -0,0 +1,72 @@ +-- Migration: 0030_messaging.sql +-- Messaging schema: conversations, messages, attachments, consent events + business messaging settings + +-- ─── Enums ─────────────────────────────────────────────────────────────────── + +CREATE TYPE "messaging_channel" AS ENUM ('sms', 'mms'); +CREATE TYPE "message_direction" AS ENUM ('inbound', 'outbound'); +CREATE TYPE "message_status" AS ENUM ('queued', 'sent', 'delivered', 'failed', 'received'); +CREATE TYPE "message_consent_kind" AS ENUM ('opt_in', 'opt_out', 'help'); + +-- ─── Tables ─────────────────────────────────────────────────────────────────── + +CREATE TABLE "conversations" ( + "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(), + "business_id" uuid NOT NULL, + "client_id" uuid NOT NULL REFERENCES "clients"("id") ON DELETE CASCADE, + "channel" "messaging_channel" NOT NULL, + "external_number" text NOT NULL, + "business_number" text NOT NULL, + "last_message_at" timestamp, + "status" text NOT NULL DEFAULT 'active', + "created_at" timestamp NOT NULL DEFAULT now(), + "updated_at" timestamp NOT NULL DEFAULT now() +); + +CREATE INDEX "idx_conversations_business_id_last_message_at" ON "conversations"("business_id", "last_message_at" DESC); +CREATE UNIQUE INDEX "uq_conversations_business_client_number" ON "conversations"("business_id", "client_id", "business_number"); + +CREATE TABLE "messages" ( + "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(), + "conversation_id" uuid NOT NULL REFERENCES "conversations"("id") ON DELETE CASCADE, + "direction" "message_direction" NOT NULL, + "body" text, + "status" "message_status" NOT NULL DEFAULT 'queued', + "provider_message_id" text, + "error_code" text, + "error_message" text, + "sent_by_staff_id" uuid REFERENCES "staff"("id") ON DELETE SET NULL, + "created_at" timestamp NOT NULL DEFAULT now(), + "delivered_at" timestamp, + "read_by_client_at" timestamp +); + +CREATE INDEX "idx_messages_conversation_id_created_at" ON "messages"("conversation_id", "created_at" DESC); +CREATE UNIQUE INDEX "uq_messages_provider_message_id" ON "messages"("provider_message_id"); + +CREATE TABLE "message_attachments" ( + "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(), + "message_id" uuid NOT NULL REFERENCES "messages"("id") ON DELETE CASCADE, + "content_type" text NOT NULL, + "url" text NOT NULL, + "size" integer NOT NULL, + "provider_media_id" text +); + +CREATE INDEX "idx_message_attachments_message_id" ON "message_attachments"("message_id"); + +CREATE TABLE "message_consent_events" ( + "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(), + "client_id" uuid NOT NULL REFERENCES "clients"("id") ON DELETE CASCADE, + "business_id" uuid NOT NULL, + "kind" "message_consent_kind" NOT NULL, + "source" text, + "created_at" timestamp NOT NULL DEFAULT now() +); + +CREATE INDEX "idx_message_consent_events_client_id" ON "message_consent_events"("client_id"); + +-- ─── Business Settings extensions ──────────────────────────────────────────── + +ALTER TABLE "business_settings" ADD COLUMN "messaging_phone_number" text; +ALTER TABLE "business_settings" ADD COLUMN "telnyx_messaging_profile_id" text; diff --git a/packages/db/migrations/meta/_journal.json b/packages/db/migrations/meta/_journal.json index 8db9b8d..eef2244 100644 --- a/packages/db/migrations/meta/_journal.json +++ b/packages/db/migrations/meta/_journal.json @@ -204,6 +204,20 @@ "when": 1775741667192, "tag": "0028_sms_reminders", "breakpoints": true + }, + { + "idx": 29, + "version": "7", + "when": 1775784467192, + "tag": "0029_db_indexes_constraints", + "breakpoints": true + }, + { + "idx": 30, + "version": "7", + "when": 1775828067192, + "tag": "0030_messaging", + "breakpoints": true } ] } \ No newline at end of file diff --git a/packages/db/src/schema.ts b/packages/db/src/schema.ts index 0a5eaef..1371cd6 100644 --- a/packages/db/src/schema.ts +++ b/packages/db/src/schema.ts @@ -406,6 +406,118 @@ export const impersonationAuditLogs = pgTable( (t) => [index("impersonation_audit_logs_session_id_idx").on(t.sessionId)] ); +// ─── Messaging ─────────────────────────────────────────────────────────────── + +export const messagingChannelEnum = pgEnum("messaging_channel", ["sms", "mms"]); + +export const messageDirectionEnum = pgEnum("message_direction", [ + "inbound", + "outbound", +]); + +export const messageStatusEnum = pgEnum("message_status", [ + "queued", + "sent", + "delivered", + "failed", + "received", +]); + +export const messageConsentKindEnum = pgEnum("message_consent_kind", [ + "opt_in", + "opt_out", + "help", +]); + +export const conversations = pgTable( + "conversations", + { + id: uuid("id").primaryKey().defaultRandom(), + businessId: uuid("business_id").notNull(), + clientId: uuid("client_id") + .notNull() + .references(() => clients.id, { onDelete: "cascade" }), + channel: messagingChannelEnum("channel").notNull(), + externalNumber: text("external_number").notNull(), + businessNumber: text("business_number").notNull(), + lastMessageAt: timestamp("last_message_at"), + status: text("status").notNull().default("active"), + createdAt: timestamp("created_at").notNull().defaultNow(), + updatedAt: timestamp("updated_at").notNull().defaultNow(), + }, + (t) => [ + index("idx_conversations_business_id_last_message_at").on( + t.businessId, + t.lastMessageAt.desc() + ), + unique("uq_conversations_business_client_number").on( + t.businessId, + t.clientId, + t.businessNumber + ), + ] +); + +export const messages = pgTable( + "messages", + { + id: uuid("id").primaryKey().defaultRandom(), + conversationId: uuid("conversation_id") + .notNull() + .references(() => conversations.id, { onDelete: "cascade" }), + direction: messageDirectionEnum("direction").notNull(), + body: text("body"), + status: messageStatusEnum("status").notNull().default("queued"), + providerMessageId: text("provider_message_id"), + errorCode: text("error_code"), + errorMessage: text("error_message"), + sentByStaffId: uuid("sent_by_staff_id").references(() => staff.id, { + onDelete: "set null", + }), + createdAt: timestamp("created_at").notNull().defaultNow(), + deliveredAt: timestamp("delivered_at"), + readByClientAt: timestamp("read_by_client_at"), + updatedAt: timestamp("updated_at").notNull().defaultNow(), + }, + (t) => [ + index("idx_messages_conversation_id_created_at").on( + t.conversationId, + t.createdAt.desc() + ), + unique("uq_messages_provider_message_id").on(t.providerMessageId), + ] +); + +export const messageAttachments = pgTable( + "message_attachments", + { + id: uuid("id").primaryKey().defaultRandom(), + messageId: uuid("message_id") + .notNull() + .references(() => messages.id, { onDelete: "cascade" }), + contentType: text("content_type").notNull(), + url: text("url").notNull(), + size: integer("size").notNull(), + providerMediaId: text("provider_media_id"), + }, + (t) => [index("idx_message_attachments_message_id").on(t.messageId)] +); + +export const messageConsentEvents = pgTable( + "message_consent_events", + { + id: uuid("id").primaryKey().defaultRandom(), + clientId: uuid("client_id") + .notNull() + .references(() => clients.id, { onDelete: "cascade" }), + businessId: uuid("business_id").notNull(), + kind: messageConsentKindEnum("kind").notNull(), + source: text("source"), + createdAt: timestamp("created_at").notNull().defaultNow(), + }, + (t) => [index("idx_message_consent_events_client_id").on(t.clientId)] +); + export const businessSettings = pgTable("business_settings", { id: uuid("id").primaryKey().defaultRandom(), businessName: text("business_name").notNull().default("GroomBook"), @@ -414,6 +526,8 @@ export const businessSettings = pgTable("business_settings", { logoKey: text("logo_key"), primaryColor: text("primary_color").notNull().default("#4f8a6f"), accentColor: text("accent_color").notNull().default("#8b7355"), + messagingPhoneNumber: text("messaging_phone_number"), + telnyxMessagingProfileId: text("telnyx_messaging_profile_id"), createdAt: timestamp("created_at").notNull().defaultNow(), updatedAt: timestamp("updated_at").notNull().defaultNow(), });