@hogsend/engine 0.42.0 → 0.44.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/package.json +10 -7
  2. package/src/container.ts +419 -4
  3. package/src/destinations/define-destination.ts +7 -3
  4. package/src/destinations/presets/posthog.ts +31 -0
  5. package/src/env.ts +28 -0
  6. package/src/index.ts +138 -0
  7. package/src/journeys/execute-journey-run.ts +93 -0
  8. package/src/journeys/journey-boundary.ts +5 -1
  9. package/src/journeys/journey-context.ts +30 -0
  10. package/src/lib/attribution-backfill.ts +285 -0
  11. package/src/lib/attribution.ts +239 -0
  12. package/src/lib/contacts.ts +71 -0
  13. package/src/lib/conversion-dispatch.ts +326 -0
  14. package/src/lib/conversions.ts +197 -0
  15. package/src/lib/crm-deals.ts +320 -0
  16. package/src/lib/crm-ingest.ts +341 -0
  17. package/src/lib/crm-provider-registry.ts +41 -0
  18. package/src/lib/crm-registry-singleton.ts +22 -0
  19. package/src/lib/deal-money-events.ts +85 -0
  20. package/src/lib/email-service-types.ts +16 -1
  21. package/src/lib/event-names.ts +1 -1
  22. package/src/lib/funnel-progress.ts +76 -0
  23. package/src/lib/funnel-registry.ts +108 -0
  24. package/src/lib/funnel-transitions.ts +280 -0
  25. package/src/lib/holdout.ts +62 -0
  26. package/src/lib/ingestion.ts +218 -9
  27. package/src/lib/journey-suppress.ts +33 -2
  28. package/src/lib/lift-stats.ts +125 -0
  29. package/src/lib/mailer.ts +1 -0
  30. package/src/lib/operator.ts +31 -0
  31. package/src/lib/outbound.ts +109 -0
  32. package/src/lib/phone.ts +19 -0
  33. package/src/lib/preferences.ts +32 -0
  34. package/src/lib/revenue.ts +116 -0
  35. package/src/lib/sms-frequency-cap.ts +47 -0
  36. package/src/lib/sms-inbound.ts +200 -0
  37. package/src/lib/sms-link-tracking.ts +160 -0
  38. package/src/lib/sms-mailer.ts +338 -0
  39. package/src/lib/sms-provider-registry.ts +35 -0
  40. package/src/lib/sms-providers-from-env.ts +100 -0
  41. package/src/lib/sms-service-types.ts +175 -0
  42. package/src/lib/sms-tracked.ts +625 -0
  43. package/src/lib/sms.ts +117 -0
  44. package/src/lib/tracked.ts +40 -0
  45. package/src/lib/tracking-event-names.ts +6 -0
  46. package/src/lib/tracking-events.ts +133 -1
  47. package/src/lib/tracking.ts +2 -1
  48. package/src/lib/webhook-signing.ts +24 -1
  49. package/src/lists/channels.ts +21 -0
  50. package/src/routes/admin/attribution.ts +414 -0
  51. package/src/routes/admin/contacts.ts +71 -11
  52. package/src/routes/admin/conversions.ts +247 -0
  53. package/src/routes/admin/deals.ts +472 -0
  54. package/src/routes/admin/funnels.ts +228 -0
  55. package/src/routes/admin/index.ts +8 -0
  56. package/src/routes/admin/journeys.ts +158 -1
  57. package/src/routes/admin/readiness.ts +97 -2
  58. package/src/routes/admin/templates.ts +28 -1
  59. package/src/routes/email/unsubscribe.ts +1 -0
  60. package/src/routes/events/index.ts +12 -0
  61. package/src/routes/index.ts +6 -0
  62. package/src/routes/lists/index.ts +54 -7
  63. package/src/routes/tracking/click-pipeline.ts +105 -16
  64. package/src/routes/tracking/short.ts +61 -0
  65. package/src/routes/webhooks/crm-provider.ts +117 -0
  66. package/src/routes/webhooks/index.ts +9 -1
  67. package/src/routes/webhooks/sms-provider.ts +110 -0
  68. package/src/sources/define-contact-source.ts +159 -0
  69. package/src/sources/registry.ts +71 -0
  70. package/src/sources/webhook-source.ts +109 -0
  71. package/src/worker.ts +4 -0
  72. package/src/workflows/crm-reconcile.ts +129 -0
  73. package/src/workflows/dispatch-conversion.ts +31 -0
  74. package/src/workflows/import-contacts.ts +61 -4
  75. package/src/workflows/send-campaign.ts +5 -0
@@ -7,6 +7,7 @@ import { agentRouter } from "./agent.js";
7
7
  import { alertsRouter } from "./alerts.js";
8
8
  import { analyticsAdminRouter } from "./analytics.js";
9
9
  import { apiKeysRouter } from "./api-keys.js";
10
+ import { adminAttributionRouter } from "./attribution.js";
10
11
  import { auditLogsRouter } from "./audit-logs.js";
11
12
  import { blueprintsRouter } from "./blueprints.js";
12
13
  import { bucketsRouter } from "./buckets.js";
@@ -14,10 +15,13 @@ import { bulkRouter } from "./bulk.js";
14
15
  import { adminCampaignsRouter } from "./campaigns.js";
15
16
  import { adminConnectorsRouter } from "./connectors.js";
16
17
  import { contactsRouter } from "./contacts.js";
18
+ import { adminConversionsRouter } from "./conversions.js";
19
+ import { adminDealsRouter } from "./deals.js";
17
20
  import { dlqRouter } from "./dlq.js";
18
21
  import { domainRouter } from "./domain.js";
19
22
  import { emailsRouter } from "./emails.js";
20
23
  import { eventsRouter } from "./events.js";
24
+ import { adminFunnelsRouter } from "./funnels.js";
21
25
  import { journeyLogsRouter } from "./journey-logs.js";
22
26
  import { journeysRouter } from "./journeys.js";
23
27
  import { linksRouter } from "./links.js";
@@ -47,6 +51,10 @@ adminRouter.route("/open-in-editor", openEditorRouter);
47
51
  adminRouter.route("/buckets", bucketsRouter);
48
52
  adminRouter.route("/lists", adminListsRouter);
49
53
  adminRouter.route("/campaigns", adminCampaignsRouter);
54
+ adminRouter.route("/deals", adminDealsRouter);
55
+ adminRouter.route("/conversions", adminConversionsRouter);
56
+ adminRouter.route("/attribution", adminAttributionRouter);
57
+ adminRouter.route("/funnels", adminFunnelsRouter);
50
58
  adminRouter.route("/events", eventsRouter);
51
59
  adminRouter.route("/emails", emailsRouter);
52
60
  adminRouter.route("/links", linksRouter);
@@ -21,6 +21,7 @@ import {
21
21
  import type { AppEnv } from "../../app.js";
22
22
  import { buildJourneyGraph } from "../../journeys/graph/build-graph.js";
23
23
  import { ingestEvent } from "../../lib/ingestion.js";
24
+ import { computeLift } from "../../lib/lift-stats.js";
24
25
 
25
26
  /**
26
27
  * Per-process cache of the built {@link JourneyGraph}. A journey's `runSource`
@@ -44,6 +45,8 @@ const journeySchema = z.object({
44
45
  completed: z.number(),
45
46
  failed: z.number(),
46
47
  exited: z.number(),
48
+ /** Holdout controls (impact plan §4.1) — would-have-entered contacts. */
49
+ held_out: z.number(),
47
50
  }),
48
51
  });
49
52
 
@@ -111,6 +114,7 @@ const emptyCounts = {
111
114
  completed: 0,
112
115
  failed: 0,
113
116
  exited: 0,
117
+ held_out: 0,
114
118
  };
115
119
 
116
120
  // --- Route definitions ---
@@ -236,7 +240,14 @@ const listStatesRoute = createRoute({
236
240
  limit: z.coerce.number().min(1).max(100).default(50),
237
241
  offset: z.coerce.number().min(0).default(0),
238
242
  status: z
239
- .enum(["active", "waiting", "completed", "failed", "exited"])
243
+ .enum([
244
+ "active",
245
+ "waiting",
246
+ "completed",
247
+ "failed",
248
+ "exited",
249
+ "held_out",
250
+ ])
240
251
  .optional(),
241
252
  userId: z.string().optional(),
242
253
  }),
@@ -466,6 +477,60 @@ const graphRoute = createRoute({
466
477
  },
467
478
  });
468
479
 
480
+ /**
481
+ * Holdout lift (impact plan §4.2) — the ONLY surface allowed causal
482
+ * language. Treatment = entered enrollments in the window; control =
483
+ * held_out diversions (§4.1). Outcome = the contact fired ≥1 conversion
484
+ * AFTER their state row was created. Beta-binomial win probability with a
485
+ * suppression floor and a loud small-sample flag (lib/lift-stats.ts).
486
+ */
487
+ const liftCohortSchema = z.object({
488
+ contacts: z.number(),
489
+ converters: z.number(),
490
+ rate: z.number(),
491
+ /** Qualifying conversion value per currency (full, not fractional). */
492
+ value: z.array(
493
+ z.object({ currency: z.string().nullable(), value: z.number() }),
494
+ ),
495
+ });
496
+
497
+ const liftRoute = createRoute({
498
+ method: "get",
499
+ path: "/{id}/lift",
500
+ tags: ["Admin — Journeys"],
501
+ summary: "Holdout lift: entered vs held-out conversion rates",
502
+ request: {
503
+ params: z.object({ id: z.string() }),
504
+ query: z.object({
505
+ days: z.coerce.number().min(1).max(365).default(90),
506
+ /** Scope the outcome to one conversion point; default any. */
507
+ definitionId: z.string().optional(),
508
+ }),
509
+ },
510
+ responses: {
511
+ 200: {
512
+ content: {
513
+ "application/json": {
514
+ schema: z.object({
515
+ journeyId: z.string(),
516
+ days: z.number(),
517
+ definitionId: z.string().nullable(),
518
+ treatment: liftCohortSchema,
519
+ control: liftCohortSchema,
520
+ liftPercent: z.number().nullable(),
521
+ /** Null when suppressed (combined conversions < 10). */
522
+ winProbability: z.number().nullable(),
523
+ suppressed: z.boolean(),
524
+ smallSample: z.boolean(),
525
+ }),
526
+ },
527
+ },
528
+ description:
529
+ "Intent-to-treat lift between entered and held-out cohorts, with honest small-sample presentation",
530
+ },
531
+ },
532
+ });
533
+
469
534
  export const journeysRouter = new OpenAPIHono<AppEnv>()
470
535
  .openapi(listRoute, async (c) => {
471
536
  const { db, registry } = c.get("container");
@@ -1050,4 +1115,96 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
1050
1115
  },
1051
1116
  200,
1052
1117
  );
1118
+ })
1119
+ .openapi(liftRoute, async (c) => {
1120
+ const { db } = c.get("container");
1121
+ const { id } = c.req.valid("param");
1122
+ const { days, definitionId } = c.req.valid("query");
1123
+ const since = new Date(
1124
+ Date.now() - days * 24 * 60 * 60 * 1000,
1125
+ ).toISOString();
1126
+ const sinceTs = sql`${since}::timestamptz`;
1127
+
1128
+ // Outcome: the contact fired ≥1 qualifying conversion AFTER their state
1129
+ // row was created (post-assignment — the intent-to-treat clock).
1130
+ const definitionSql = definitionId
1131
+ ? sql` and c.definition_id = ${definitionId}`
1132
+ : sql``;
1133
+ const convertedSql = sql`exists (
1134
+ select 1 from conversions c
1135
+ where c.user_key = ${journeyStates.userId}
1136
+ and c.occurred_at >= ${journeyStates.createdAt}${definitionSql}
1137
+ )`;
1138
+
1139
+ const cohort = async (control: boolean) => {
1140
+ const statusFilter = control
1141
+ ? eq(journeyStates.status, "held_out")
1142
+ : sql`${journeyStates.status} != 'held_out'`;
1143
+ const [row] = await db
1144
+ .select({
1145
+ contacts: sql<number>`count(distinct ${journeyStates.userId})::int`,
1146
+ converters: sql<number>`(count(distinct ${journeyStates.userId}) filter (where ${convertedSql}))::int`,
1147
+ })
1148
+ .from(journeyStates)
1149
+ .where(
1150
+ and(
1151
+ eq(journeyStates.journeyId, id),
1152
+ gteCreated(sinceTs),
1153
+ statusFilter,
1154
+ ),
1155
+ );
1156
+ // Full qualifying conversion value per currency (secondary read-out —
1157
+ // the rate is the primary lift instrument).
1158
+ const valueRows = await db.execute<{
1159
+ currency: string | null;
1160
+ value: number;
1161
+ }>(sql`
1162
+ select c.currency, coalesce(sum(c.value), 0)::float8 as value
1163
+ from conversions c
1164
+ where c.value is not null
1165
+ and exists (
1166
+ select 1 from journey_states js
1167
+ where js.journey_id = ${id}
1168
+ and js.created_at >= ${sinceTs}
1169
+ and ${control ? sql`js.status = 'held_out'` : sql`js.status != 'held_out'`}
1170
+ and js.user_id = c.user_key
1171
+ and c.occurred_at >= js.created_at
1172
+ )${definitionId ? sql` and c.definition_id = ${definitionId}` : sql``}
1173
+ group by c.currency
1174
+ `);
1175
+ const contacts = Number(row?.contacts ?? 0);
1176
+ const converters = row?.converters ?? 0;
1177
+ return {
1178
+ contacts,
1179
+ converters,
1180
+ rate: contacts > 0 ? converters / contacts : 0,
1181
+ value: [...valueRows].map((r) => ({
1182
+ currency: r.currency,
1183
+ value: Number(r.value),
1184
+ })),
1185
+ };
1186
+ };
1187
+
1188
+ const [treatment, control] = await Promise.all([
1189
+ cohort(false),
1190
+ cohort(true),
1191
+ ]);
1192
+ const verdict = computeLift({ treatment, control });
1193
+
1194
+ return c.json(
1195
+ {
1196
+ journeyId: id,
1197
+ days,
1198
+ definitionId: definitionId ?? null,
1199
+ treatment,
1200
+ control,
1201
+ ...verdict,
1202
+ },
1203
+ 200,
1204
+ );
1053
1205
  });
1206
+
1207
+ /** `created_at >= since` as a reusable fragment (lift cohort windows). */
1208
+ function gteCreated(sinceTs: ReturnType<typeof sql>) {
1209
+ return sql`${journeyStates.createdAt} >= ${sinceTs}`;
1210
+ }
@@ -1,7 +1,13 @@
1
- import { apiKeys } from "@hogsend/db";
1
+ import {
2
+ apiKeys,
3
+ attributionCredits,
4
+ conversions,
5
+ userEvents,
6
+ } from "@hogsend/db";
2
7
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
- import { count, isNull } from "drizzle-orm";
8
+ import { count, inArray, isNull } from "drizzle-orm";
4
9
  import type { AppEnv } from "../../app.js";
10
+ import { trustedValuedEventFilter } from "../../lib/revenue.js";
5
11
 
6
12
  /**
7
13
  * First-time setup readiness — a NON-BLOCKING checklist for Studio's Setup view.
@@ -172,6 +178,95 @@ export const readinessRouter = new OpenAPIHono<AppEnv>().openapi(
172
178
  docsUrl: DOCS,
173
179
  });
174
180
 
181
+ // 7–10. Attribution readiness (impact plan §5.4) — the "how's it doing"
182
+ // wires, in causal order: arrivals → valued events → conversions →
183
+ // credits. ALL optional-tier: attribution never blocks setup-`ready`;
184
+ // the detail text names the exact missing wire. Cheap existence probes,
185
+ // each degrading alone on a DB hiccup.
186
+ const exists = async (probe: () => Promise<unknown[]>) => {
187
+ try {
188
+ return (await probe()).length > 0;
189
+ } catch {
190
+ return null;
191
+ }
192
+ };
193
+ const [hasArrivals, hasValued, hasConversions, hasCredits] =
194
+ await Promise.all([
195
+ exists(() =>
196
+ db
197
+ .select({ id: userEvents.id })
198
+ .from(userEvents)
199
+ .where(
200
+ inArray(userEvents.event, ["campaign.arrived", "link.arrived"]),
201
+ )
202
+ .limit(1),
203
+ ),
204
+ exists(() =>
205
+ db
206
+ .select({ id: userEvents.id })
207
+ .from(userEvents)
208
+ .where(trustedValuedEventFilter())
209
+ .limit(1),
210
+ ),
211
+ exists(() =>
212
+ db.select({ id: conversions.id }).from(conversions).limit(1),
213
+ ),
214
+ exists(() =>
215
+ db
216
+ .select({ id: attributionCredits.id })
217
+ .from(attributionCredits)
218
+ .limit(1),
219
+ ),
220
+ ]);
221
+ const probeCheck = (
222
+ id: string,
223
+ label: string,
224
+ seen: boolean | null,
225
+ okDetail: string,
226
+ missingDetail: string,
227
+ ): Check => ({
228
+ id,
229
+ label,
230
+ status: seen === true ? "ok" : "optional",
231
+ detail:
232
+ seen === null
233
+ ? "Couldn't probe — check the database connection."
234
+ : seen
235
+ ? okDetail
236
+ : missingDetail,
237
+ docsUrl: `${DOCS}/conversions/impact`,
238
+ });
239
+ checks.push(
240
+ probeCheck(
241
+ "attribution_arrivals",
242
+ "Arrival capture",
243
+ hasArrivals,
244
+ "Landing arrivals are being captured.",
245
+ "No arrivals yet — add @hogsend/js to your landing pages (2 minutes) so ad/UTM touches earn credit.",
246
+ ),
247
+ probeCheck(
248
+ "attribution_valued_events",
249
+ "Valued events",
250
+ hasValued,
251
+ "Trusted valued events are flowing.",
252
+ "No valued events yet — point one revenue webhook (Stripe, orders) at a source with value + currency.",
253
+ ),
254
+ probeCheck(
255
+ "attribution_conversions",
256
+ "Conversions firing",
257
+ hasConversions,
258
+ "Conversion points are firing.",
259
+ "No conversions yet — the built-in revenue definition fires on any trusted valued event; or author defineConversion.",
260
+ ),
261
+ probeCheck(
262
+ "attribution_credits",
263
+ "Attribution credits",
264
+ hasCredits,
265
+ "The credit ledger is accruing.",
266
+ "No credits yet — credits appear once a converting contact has touchpoints; run `hogsend attribution backfill` to credit existing history.",
267
+ ),
268
+ );
269
+
175
270
  const doneCount = checks.filter((ch) => ch.status === "ok").length;
176
271
  // "ready" ignores optional rows — only outstanding "action" items block it.
177
272
  const ready = checks.every((ch) => ch.status !== "action");
@@ -9,6 +9,7 @@ import {
9
9
  } from "@hogsend/email";
10
10
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
11
11
  import type { AppEnv } from "../../app.js";
12
+ import { isOperatorAddress } from "../../lib/operator.js";
12
13
  import { errorSchema } from "../../lib/schemas.js";
13
14
  import { requireScope } from "../../middleware/api-key.js";
14
15
 
@@ -157,6 +158,10 @@ const sendTestRoute = createRoute({
157
158
  },
158
159
  description: "Test email dispatched",
159
160
  },
161
+ 403: {
162
+ content: { "application/json": { schema: errorSchema } },
163
+ description: "Recipient is not a verified operator/team address",
164
+ },
160
165
  404: {
161
166
  content: { "application/json": { schema: errorSchema } },
162
167
  description: "Template not found",
@@ -258,7 +263,7 @@ export const templatesRouter = new OpenAPIHono<AppEnv>()
258
263
  }
259
264
  })
260
265
  .openapi(sendTestRoute, async (c) => {
261
- const { emailService, templates } = c.get("container");
266
+ const { emailService, templates, db, env, logger } = c.get("container");
262
267
  const { key } = c.req.valid("param");
263
268
  const { to, props: bodyProps } = c.req.valid("json");
264
269
 
@@ -266,6 +271,28 @@ export const templatesRouter = new OpenAPIHono<AppEnv>()
266
271
  return c.json({ error: "Template not found" }, 404);
267
272
  }
268
273
 
274
+ // Restrict test sends to a verified operator/team address. This route is
275
+ // full-admin-key-only (its `requireScope`), which is exactly how the MCP
276
+ // server / an external agent authenticates — and the send below skips
277
+ // preference checks. Bounding the recipient to the admin team removes the
278
+ // "reach an unintended recipient" capability from a prompt-injected agent.
279
+ if (!(await isOperatorAddress({ db, env, email: to }))) {
280
+ return c.json(
281
+ {
282
+ error:
283
+ "Test sends are restricted to your team's verified addresses (an admin user, HOGSEND_TEST_EMAIL, or STUDIO_ADMIN_EMAIL).",
284
+ },
285
+ 403,
286
+ );
287
+ }
288
+
289
+ const apiKey = c.get("apiKey");
290
+ logger.info("[templates] test send", {
291
+ template: key,
292
+ to,
293
+ actor: apiKey?.id ?? "session",
294
+ });
295
+
269
296
  const definition = getTemplateDefinition({
270
297
  key: key as TemplateName,
271
298
  registry: templates,
@@ -79,6 +79,7 @@ export const unsubscribeRouter = new OpenAPIHono<AppEnv>().openapi(
79
79
  unsubscribedAll: false,
80
80
  }
81
81
  : { unsubscribedAll: false },
82
+ source: "preference_center",
82
83
  });
83
84
 
84
85
  return c.html(
@@ -20,6 +20,16 @@ const eventRequestSchema = z.object({
20
20
  anonymousId: z.string().min(1).max(200).optional(),
21
21
  eventProperties: z.record(z.string(), z.unknown()).optional(),
22
22
  contactProperties: z.record(z.string(), z.unknown()).optional(),
23
+ // The event's monetary worth (order total, deal value). First-class — lands
24
+ // on `user_events.value`, the column revenue rollups, conversion definitions,
25
+ // and attribution credits read. Negative = refunds/adjustments.
26
+ value: z.number().finite().optional(),
27
+ // ISO-4217 alpha code for `value` (uppercased at ingest). Ignored without
28
+ // `value`.
29
+ currency: z
30
+ .string()
31
+ .regex(/^[A-Za-z]{3}$/)
32
+ .optional(),
23
33
  lists: z.record(z.string(), z.boolean()).optional(),
24
34
  idempotencyKey: z.string().optional(),
25
35
  timestamp: z.string().datetime().optional(),
@@ -121,6 +131,8 @@ export const eventsRouter = new OpenAPIHono<AppEnv>().openapi(
121
131
  anonymousId: body.anonymousId,
122
132
  eventProperties: body.eventProperties ?? {},
123
133
  contactProperties: body.contactProperties,
134
+ value: body.value,
135
+ currency: body.currency,
124
136
  idempotencyKey,
125
137
  // §2.5: caller-supplied event time (backfill/replay). The validated
126
138
  // ISO string is coerced to a Date inside ingestEvent.
@@ -15,6 +15,7 @@ import { feedRouter } from "./feed/index.js";
15
15
  import { healthRouter } from "./health.js";
16
16
  import { listsRouter } from "./lists/index.js";
17
17
  import { trackingRouter } from "./tracking/index.js";
18
+ import { shortLinkRouter } from "./tracking/short.js";
18
19
  import { vanityRouter } from "./tracking/vanity.js";
19
20
  import { registerWebhookRoutes } from "./webhooks/index.js";
20
21
 
@@ -141,6 +142,11 @@ export function registerRoutes(
141
142
  // surface (vanity links land in chats/posts/print).
142
143
  app.route("/", vanityRouter);
143
144
 
145
+ // SMS short link redirect — root-mounted so the texted URL stays short
146
+ // (`${SMS_LINK_HOST ?? API_PUBLIC_URL}/s/:code`); every character counts
147
+ // against the GSM-7 segment budget. Unauthenticated like /l.
148
+ app.route("/", shortLinkRouter);
149
+
144
150
  // Generic connector dispatch (oauth/interactions/ingress) — the static
145
151
  // `connectors/` prefix is registered BEFORE the `:sourceId` webhook catch-all
146
152
  // so it wins path matching. These routes self-authenticate (oauth state +
@@ -1,5 +1,5 @@
1
1
  import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
- import { type Database, emailPreferences } from "@hogsend/db";
2
+ import { contacts, type Database, emailPreferences } from "@hogsend/db";
3
3
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
4
4
  import { and, eq } from "drizzle-orm";
5
5
  import type { AppEnv } from "../../app.js";
@@ -17,6 +17,8 @@ import {
17
17
  upsertEmailPreference,
18
18
  } from "../../lib/preferences.js";
19
19
  import { errorSchema } from "../../lib/schemas.js";
20
+ import { grantPhoneConsent, recordPhoneOptOut } from "../../lib/sms-inbound.js";
21
+ import { SMS_CHANNEL_ID } from "../../lib/sms-tracked.js";
20
22
  import { getListRegistry } from "../../lists/registry-singleton.js";
21
23
  import {
22
24
  gatePublishableIdentity,
@@ -319,12 +321,25 @@ async function applyListSubscription(opts: {
319
321
 
320
322
  emitContactCreatedIfNew({ db, hatchet, logger, contactId, created });
321
323
 
322
- await applyListMembership({
323
- db,
324
- userId,
325
- email,
326
- lists: { [id]: subscribed },
327
- });
324
+ try {
325
+ await applyListMembership({
326
+ db,
327
+ userId,
328
+ email,
329
+ lists: { [id]: subscribed },
330
+ });
331
+ } catch (err) {
332
+ // Phone-track fallback for the explicit-consent `sms` channel: a
333
+ // phone-only contact has no email, so `email_preferences` cannot hold
334
+ // its grant — record consent/opt-out on the phone-keyed
335
+ // `sms_suppressions` track instead (the same record an inbound
336
+ // START/STOP writes). Only the missing-email failure falls back; any
337
+ // other error keeps the normal failure path.
338
+ const fellBack =
339
+ id === SMS_CHANNEL_ID &&
340
+ (await applySmsPhoneTrackFallback({ db, contactId, subscribed, err }));
341
+ if (!fellBack) throw err;
342
+ }
328
343
  } catch (err) {
329
344
  return { kind: "failed", message: listMembershipError(err) };
330
345
  }
@@ -332,6 +347,38 @@ async function applyListSubscription(opts: {
332
347
  return { kind: "ok" };
333
348
  }
334
349
 
350
+ /**
351
+ * The `sms` grant/revoke for a contact `applyListMembership` rejected for
352
+ * having no email. Returns true when the contact has a phone and the
353
+ * phone-track write happened; false re-raises the original failure (no phone
354
+ * either, or a different error entirely).
355
+ */
356
+ async function applySmsPhoneTrackFallback(opts: {
357
+ db: Database;
358
+ contactId: string;
359
+ subscribed: boolean;
360
+ err: unknown;
361
+ }): Promise<boolean> {
362
+ const { db, contactId, subscribed, err } = opts;
363
+ const message = err instanceof Error ? err.message : "";
364
+ if (!message.includes("no email")) return false;
365
+
366
+ const rows = await db
367
+ .select({ phone: contacts.phone })
368
+ .from(contacts)
369
+ .where(eq(contacts.id, contactId))
370
+ .limit(1);
371
+ const phone = rows[0]?.phone;
372
+ if (!phone) return false;
373
+
374
+ if (subscribed) {
375
+ await grantPhoneConsent(db, phone, { reason: "api_grant" });
376
+ } else {
377
+ await recordPhoneOptOut(db, phone, "manual");
378
+ }
379
+ return true;
380
+ }
381
+
335
382
  // The lists router does NOT re-apply auth internally — the data-plane prefix
336
383
  // guards in `routes/index.ts` (decision #16) apply `requireApiKey` +
337
384
  // `requireScope("ingest")` to `/v1/lists` (bare + `/*`) before requests reach