feat(GRO-106): STOP/HELP compliance + consent log

- Add detectKeyword() and handleConsentKeyword() in consent.ts
- Wire keyword detection into handleMessageReceived() in inbound.ts
- Add 25-unit test suite for consent.ts covering all keywords,
  case insensitivity, whitespace tolerance, idempotency, and
  help keyword state preservation

Co-Authored-By: Paperclip <noreply@paperclip.ing>

apps/api/src/services/messaging/__tests__/consent.test.ts

@@ -1,14 +1,12 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { detectKeyword } from "../consent.js";
 
-const mockDb = {
-  insert: vi.fn(),
-  update: vi.fn(),
-  select: vi.fn(),
-};
-
 vi.mock("@groombook/db", () => ({
-  getDb: () => mockDb,
+  db: {
+    insert: vi.fn(),
+    update: vi.fn(),
+    select: vi.fn(),
+  },
   clients: {},
   messageConsentEvents: {},
   businessSettings: {},
@@ -16,6 +14,7 @@ vi.mock("@groombook/db", () => ({
 }));
 
 const { handleConsentKeyword } = await import("../consent.js");
+const { db } = await import("@groombook/db");
 
 describe("detectKeyword", () => {
   it.each([
@@ -66,10 +65,10 @@ describe("detectKeyword", () => {
 describe("handleConsentKeyword", () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    mockDb.insert.mockReturnValue({
+    db.insert.mockReturnValue({
       values: vi.fn().mockResolvedValue([{ id: "event-1" }]),
     } as any);
-    mockDb.update.mockReturnValue({
+    db.update.mockReturnValue({
       set: vi.fn().mockReturnValue({
         where: vi.fn().mockResolvedValue([]),
       }),
@@ -79,12 +78,12 @@ describe("handleConsentKeyword", () => {
   const baseOpts = {
     clientId: "client-1",
     businessId: "biz-1",
-    db: mockDb as unknown as ReturnType<typeof import("@groombook/db").getDb>,
+    db: db as unknown as typeof import("@groombook/db").db,
   };
 
   describe("opt_out", () => {
     it("inserts consent event with sms_keyword source", async () => {
-      mockDb.select.mockReturnValue({
+      db.select.mockReturnValue({
         from: vi.fn().mockReturnValue({
           where: vi.fn().mockReturnValue({
             limit: vi.fn().mockResolvedValue([{ smsOptIn: true }]),
@@ -94,11 +93,11 @@ describe("handleConsentKeyword", () => {
 
       await handleConsentKeyword({ ...baseOpts, kind: "opt_out" });
 
-      expect(mockDb.insert).toHaveBeenCalledOnce();
+      expect(db.insert).toHaveBeenCalledOnce();
     });
 
     it("sets smsOptIn=false and smsOptOutDate when currently opted in", async () => {
-      mockDb.select.mockReturnValue({
+      db.select.mockReturnValue({
         from: vi.fn().mockReturnValue({
           where: vi.fn().mockReturnValue({
             limit: vi.fn().mockResolvedValue([{ smsOptIn: true }]),
@@ -108,11 +107,11 @@ describe("handleConsentKeyword", () => {
 
       await handleConsentKeyword({ ...baseOpts, kind: "opt_out" });
 
-      expect(mockDb.update).toHaveBeenCalled();
+      expect(db.update).toHaveBeenCalled();
     });
 
     it("is idempotent — second opt-out logs event but skips client update", async () => {
-      mockDb.select.mockReturnValue({
+      db.select.mockReturnValue({
         from: vi.fn().mockReturnValue({
           where: vi.fn().mockReturnValue({
             limit: vi.fn().mockResolvedValue([{ smsOptIn: false }]),
@@ -122,11 +121,11 @@ describe("handleConsentKeyword", () => {
 
       await handleConsentKeyword({ ...baseOpts, kind: "opt_out" });
 
-      expect(mockDb.update).not.toHaveBeenCalled();
+      expect(db.update).not.toHaveBeenCalled();
     });
 
     it("returns unsubscribe reply text", async () => {
-      mockDb.select.mockReturnValue({
+      db.select.mockReturnValue({
         from: vi.fn().mockReturnValue({
           where: vi.fn().mockReturnValue({
             limit: vi.fn().mockResolvedValue([{ smsOptIn: true }]),
@@ -143,7 +142,7 @@ describe("handleConsentKeyword", () => {
 
   describe("opt_in", () => {
     it("sets smsOptIn=true and smsConsentDate when currently opted out", async () => {
-      mockDb.select.mockReturnValue({
+      db.select.mockReturnValue({
         from: vi.fn().mockReturnValue({
           where: vi.fn().mockReturnValue({
             limit: vi.fn().mockResolvedValue([{ smsOptIn: false, smsConsentDate: null }]),
@@ -153,11 +152,11 @@ describe("handleConsentKeyword", () => {
 
       await handleConsentKeyword({ ...baseOpts, kind: "opt_in" });
 
-      expect(mockDb.update).toHaveBeenCalled();
+      expect(db.update).toHaveBeenCalled();
     });
 
     it("clears smsOptOutDate on opt-in after opt-out", async () => {
-      mockDb.select.mockReturnValue({
+      db.select.mockReturnValue({
         from: vi.fn().mockReturnValue({
           where: vi.fn().mockReturnValue({
             limit: vi.fn().mockResolvedValue([{ smsOptIn: false }]),
@@ -167,11 +166,11 @@ describe("handleConsentKeyword", () => {
 
       await handleConsentKeyword({ ...baseOpts, kind: "opt_in" });
 
-      expect(mockDb.update).toHaveBeenCalled();
+      expect(db.update).toHaveBeenCalled();
     });
 
     it("is idempotent — second opt-in skips client update", async () => {
-      mockDb.select.mockReturnValue({
+      db.select.mockReturnValue({
         from: vi.fn().mockReturnValue({
           where: vi.fn().mockReturnValue({
             limit: vi.fn().mockResolvedValue([{ smsOptIn: true }]),
@@ -181,11 +180,11 @@ describe("handleConsentKeyword", () => {
 
       await handleConsentKeyword({ ...baseOpts, kind: "opt_in" });
 
-      expect(mockDb.update).not.toHaveBeenCalled();
+      expect(db.update).not.toHaveBeenCalled();
     });
 
     it("returns resubscribe reply text", async () => {
-      mockDb.select.mockReturnValue({
+      db.select.mockReturnValue({
         from: vi.fn().mockReturnValue({
           where: vi.fn().mockReturnValue({
             limit: vi.fn().mockResolvedValue([{ smsOptIn: false }]),
@@ -201,14 +200,34 @@ describe("handleConsentKeyword", () => {
   });
 
   describe("help", () => {
-    it("returns default help reply without querying businessSettings", async () => {
+    it("does not call update — opt-in state unchanged", async () => {
+      db.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ messagingHelpReply: null }]),
+          }),
+        }),
+      } as any);
+
       const result = await handleConsentKeyword({ ...baseOpts, kind: "help" });
 
-      expect(mockDb.update).not.toHaveBeenCalled();
-      expect(mockDb.select).not.toHaveBeenCalled();
+      expect(db.update).not.toHaveBeenCalled();
       expect(result.replyText).toBe(
         "Reply STOP to unsubscribe or START to resubscribe. For help, contact your groomer directly."
       );
     });
+
+    it("uses business messagingHelpReply when configured", async () => {
+      db.select.mockReturnValue({
+        from: vi.fn().mockReturnValue({
+          where: vi.fn().mockReturnValue({
+            limit: vi.fn().mockResolvedValue([{ messagingHelpReply: "Custom help text." }]),
+          }),
+        }),
+      } as any);
+
+      const result = await handleConsentKeyword({ ...baseOpts, kind: "help" });
+      expect(result.replyText).toBe("Custom help text.");
+    });
   });
 });

apps/api/src/services/messaging/consent.ts

@@ -1,5 +1,4 @@
-import { getDb, clients, messageConsentEvents, eq } from "@groombook/db";
-import type { Db } from "@groombook/db";
+import { db, clients, messageConsentEvents, businessSettings, eq } from "@groombook/db";
 
 export type KeywordKind = "opt_in" | "opt_out" | "help";
 
@@ -19,7 +18,7 @@ export async function handleConsentKeyword(opts: {
   clientId: string;
   businessId: string;
   kind: KeywordKind;
-  db: Db;
+  db: typeof import("@groombook/db").db;
 }): Promise<{ replyText: string }> {
   const { clientId, businessId, kind, db: database } = opts;
 
@@ -70,7 +69,14 @@ export async function handleConsentKeyword(opts: {
   }
 
   // kind === "help"
+  const [settings] = await database
+    .select({ messagingHelpReply: businessSettings.messagingHelpReply })
+    .from(businessSettings)
+    .where(eq(businessSettings.id, businessId))
+    .limit(1);
+
   const replyText =
+    settings?.messagingHelpReply ??
     "Reply STOP to unsubscribe or START to resubscribe. For help, contact your groomer directly.";
 
   return { replyText };

apps/api/src/services/messaging/inbound.ts

@@ -154,7 +154,7 @@ export async function handleMessageReceived(payload: TelnyxMessageReceivedPayloa
     throw new Error(`No business owns messaging number: ${toPhone}`);
   }
 
-  const { id: conversationId, clientId } = await findOrCreateConversation(businessId, fromPhone, toPhone);
+  const { id: conversationId } = await findOrCreateConversation(businessId, fromPhone, toPhone);
 
   await getDb()
     .update(conversations)
@@ -181,7 +181,7 @@ export async function handleMessageReceived(payload: TelnyxMessageReceivedPayloa
       businessId,
       clientId,
       body: replyText,
-      sentByStaffId: undefined,
+      staffId: undefined,
     });
   }