@hogsend/engine 0.42.0 → 0.43.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.
@@ -20,3 +20,9 @@ export const LINK_CLICKED = "link.clicked" as const;
20
20
  // "did a known user scan this QR?". Bus + outbound both define `linkId` as the
21
21
  // managed `links.id` and carry `trackedLinkId` separately (no legacy split).
22
22
  export const LINK_ARRIVED = "link.arrived" as const;
23
+
24
+ // First-party BUS event for an SMS short-link click (`/s/:code`) — the SMS
25
+ // sibling of `email.link_clicked`, re-ingested through `ingestEvent` so
26
+ // journeys can trigger / `ctx.waitForEvent` on a click of a link texted to
27
+ // THIS user. The per-hit OUTBOUND counterpart is `sms.clicked`.
28
+ export const SMS_LINK_CLICKED = "sms.link_clicked" as const;
@@ -1,6 +1,11 @@
1
1
  import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
2
  import type { JourneyRegistry } from "@hogsend/core/registry";
3
- import { type Database, emailSends, journeyStates } from "@hogsend/db";
3
+ import {
4
+ type Database,
5
+ emailSends,
6
+ journeyStates,
7
+ smsSends,
8
+ } from "@hogsend/db";
4
9
  import { eq } from "drizzle-orm";
5
10
  import { type IngestResult, ingestEvent } from "./ingestion.js";
6
11
  import type { Logger } from "./logger.js";
@@ -252,3 +257,104 @@ export async function pushLinkClickEvent(
252
257
  },
253
258
  });
254
259
  }
260
+
261
+ export interface SmsSendContext {
262
+ /**
263
+ * The resolved contact key: the enrollment's userId, else the send row's
264
+ * denormalized userId, else NULL. Deliberately NO phone fallback — phone is
265
+ * not a merge-participating contact `Kind`, so a phone-keyed ingest would
266
+ * fork an orphan contact.
267
+ */
268
+ userId: string | null;
269
+ userEmail: string | null;
270
+ templateKey: string | null;
271
+ messageId: string | null;
272
+ to: string;
273
+ }
274
+
275
+ /**
276
+ * The SMS sibling of {@link resolveEmailSendContext}: one LEFT JOIN from
277
+ * `sms_sends` to `journey_states` giving the click pipeline the identity +
278
+ * template context for the bus re-ingest and the `sms.clicked` outbound emit.
279
+ */
280
+ export async function resolveSmsSendContext(
281
+ db: Database,
282
+ smsSendId: string | null,
283
+ ): Promise<SmsSendContext | null> {
284
+ if (!smsSendId) return null;
285
+ const rows = await db
286
+ .select({
287
+ toPhone: smsSends.toPhone,
288
+ templateKey: smsSends.templateKey,
289
+ messageId: smsSends.messageId,
290
+ sendUserId: smsSends.userId,
291
+ userId: journeyStates.userId,
292
+ userEmail: journeyStates.userEmail,
293
+ })
294
+ .from(smsSends)
295
+ .leftJoin(journeyStates, eq(smsSends.journeyStateId, journeyStates.id))
296
+ .where(eq(smsSends.id, smsSendId))
297
+ .limit(1);
298
+
299
+ const row = rows[0];
300
+ if (!row) return null;
301
+
302
+ return {
303
+ userId: row.userId ?? row.sendUserId ?? null,
304
+ userEmail: row.userEmail ?? null,
305
+ templateKey: row.templateKey,
306
+ messageId: row.messageId,
307
+ to: row.toPhone,
308
+ };
309
+ }
310
+
311
+ export interface PushSmsTrackingEventOpts {
312
+ db: Database;
313
+ hatchet: HatchetClient;
314
+ registry: JourneyRegistry;
315
+ logger: Logger;
316
+ event: string;
317
+ smsSendId: string;
318
+ properties?: Record<string, unknown>;
319
+ /** Pre-resolved send context (including null) skips the duplicate read. */
320
+ resolvedContext?: SmsSendContext | null;
321
+ idempotencyKey?: string;
322
+ }
323
+
324
+ /**
325
+ * Re-push a first-party SMS tracking event (short-link click) onto the
326
+ * INTERNAL bus for journey routing + `userEvents` persistence — the SMS
327
+ * sibling of {@link pushTrackingEvent}. Returns undefined without ingesting
328
+ * when the send has no resolvable contact key (`ingestEvent` throws on a
329
+ * zero-key event, and phone is not a contact key).
330
+ */
331
+ export async function pushSmsTrackingEvent(
332
+ opts: PushSmsTrackingEventOpts,
333
+ ): Promise<IngestResult | undefined> {
334
+ const { db, hatchet, registry, logger, event, smsSendId } = opts;
335
+
336
+ const ctx =
337
+ opts.resolvedContext !== undefined
338
+ ? opts.resolvedContext
339
+ : await resolveSmsSendContext(db, smsSendId);
340
+ if (!ctx?.userId) return undefined;
341
+
342
+ return await ingestEvent({
343
+ db,
344
+ registry,
345
+ hatchet,
346
+ logger,
347
+ event: {
348
+ event,
349
+ userId: ctx.userId,
350
+ userEmail: ctx.userEmail ?? undefined,
351
+ eventProperties: {
352
+ smsSendId,
353
+ templateKey: ctx.templateKey,
354
+ ...opts.properties,
355
+ },
356
+ source: "tracking",
357
+ idempotencyKey: opts.idempotencyKey,
358
+ },
359
+ });
360
+ }
@@ -30,7 +30,8 @@ const SKIP_PATTERNS = ["/v1/email/unsubscribe", "/v1/email/preferences"];
30
30
  // them small and scalar (non-scalars don't survive the Hatchet wire anyway).
31
31
  const MAX_PROPS_JSON_LENGTH = 2048;
32
32
 
33
- function shouldSkipUrl(url: string): boolean {
33
+ /** Never rewrite unsubscribe/preference URLs (shared with the SMS rewriter). */
34
+ export function shouldSkipUrl(url: string): boolean {
34
35
  return SKIP_PATTERNS.some((pattern) => url.includes(pattern));
35
36
  }
36
37
 
@@ -25,10 +25,21 @@ import { Webhook } from "svix";
25
25
  */
26
26
 
27
27
  /**
28
- * The 16-event catalog — the SINGLE source of truth (schema, routes, client,
28
+ * The 21-event catalog — the SINGLE source of truth (schema, routes, client,
29
29
  * CLI all derive from this). The `webhook.test` sentinel is intentionally NOT a
30
30
  * member (it is delivered out-of-band regardless of an endpoint's `eventTypes`).
31
31
  *
32
+ * `contact.subscribed` mirrors `contact.unsubscribed` for a genuine opt-IN
33
+ * (resubscribe-all or a category/channel grant), emitted from the single
34
+ * preference-write choke with `source` provenance — the consent audit signal
35
+ * for the explicit-opt-in SMS channel (grants were previously silent).
36
+ *
37
+ * The `sms.*` family mirrors the email lifecycle for the SMS channel:
38
+ * `sms.sent` (provider-accepted, first-party), `sms.delivered` / `sms.failed`
39
+ * (provider status webhook — the single source, no first-party signal), and
40
+ * `sms.clicked` (first-party, per-hit, from the `/s/:code` short-link
41
+ * redirect — the SMS sibling of `email.clicked`).
42
+ *
32
43
  * `link.clicked` is the NON-email click event: a click on a tracked link that
33
44
  * has no email send (Discord/referral/ad-hoc `createTrackedLink`). It is the
34
45
  * deliberate counterpart to `email.clicked` so a non-email click never fires a
@@ -43,6 +54,7 @@ export const WEBHOOK_EVENT_TYPES = [
43
54
  "contact.updated",
44
55
  "contact.deleted",
45
56
  "contact.unsubscribed",
57
+ "contact.subscribed",
46
58
  "email.sent",
47
59
  "email.delivered",
48
60
  "email.opened",
@@ -50,6 +62,10 @@ export const WEBHOOK_EVENT_TYPES = [
50
62
  "email.action",
51
63
  "email.bounced",
52
64
  "email.complained",
65
+ "sms.sent",
66
+ "sms.delivered",
67
+ "sms.failed",
68
+ "sms.clicked",
53
69
  "journey.completed",
54
70
  "bucket.entered",
55
71
  "bucket.left",
@@ -46,6 +46,7 @@ function capitalize(id: string): string {
46
46
  */
47
47
  export function synthesizeChannelLists(
48
48
  actions: DefinedConnectorAction[],
49
+ opts?: { sms?: boolean },
49
50
  ): ListMeta[] {
50
51
  const channels: ListMeta[] = [
51
52
  {
@@ -71,5 +72,25 @@ export function synthesizeChannelLists(
71
72
  });
72
73
  }
73
74
 
75
+ // The SMS channel is minted when an SMS provider is configured (SMS is NOT a
76
+ // connector). UNLIKE every other channel it is OPT-IN polarity
77
+ // (`defaultOptIn: false`, not configurable): TCPA/CASL/PECR all require prior
78
+ // EXPRESS consent for marketing SMS, so a contact is textable only with an
79
+ // explicit `categories.sms === true` grant (API/SDK/preference-center) or
80
+ // phone-track consent (an inbound START). The tracked SMS sender fails closed
81
+ // (`no_consent`) without one; transactional sends are exempt from the consent
82
+ // gate but never from the STOP list. De-duped via `seen` in case a connector
83
+ // also happened to use the id "sms".
84
+ if (opts?.sms && !seen.has("sms")) {
85
+ seen.add("sms");
86
+ channels.push({
87
+ id: "sms",
88
+ name: "SMS",
89
+ defaultOptIn: false,
90
+ enabled: true,
91
+ kind: "channel",
92
+ });
93
+ }
94
+
74
95
  return channels;
75
96
  }
@@ -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(
@@ -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
@@ -1,16 +1,27 @@
1
1
  import { randomUUID } from "node:crypto";
2
- import { emailSends, linkClicks, links, trackedLinks } from "@hogsend/db";
2
+ import {
3
+ emailSends,
4
+ linkClicks,
5
+ links,
6
+ smsSends,
7
+ trackedLinks,
8
+ } from "@hogsend/db";
3
9
  import { and, eq, isNull, sql } from "drizzle-orm";
4
10
  import type { Context } from "hono";
5
11
  import type { AppEnv } from "../../app.js";
6
12
  import { isBotOrPrefetch } from "../../lib/bot-prefetch.js";
7
13
  import { generateIdentityToken } from "../../lib/identity-token.js";
8
14
  import { emitOutbound } from "../../lib/outbound.js";
9
- import { EMAIL_LINK_CLICKED } from "../../lib/tracking-event-names.js";
15
+ import {
16
+ EMAIL_LINK_CLICKED,
17
+ SMS_LINK_CLICKED,
18
+ } from "../../lib/tracking-event-names.js";
10
19
  import {
11
20
  pushLinkClickEvent,
21
+ pushSmsTrackingEvent,
12
22
  pushTrackingEvent,
13
23
  resolveEmailSendContext,
24
+ resolveSmsSendContext,
14
25
  } from "../../lib/tracking-events.js";
15
26
  import { confirmSemanticClickTask } from "../../workflows/confirm-semantic-click.js";
16
27
 
@@ -21,6 +32,10 @@ export const clickSelection = {
21
32
  id: trackedLinks.id,
22
33
  originalUrl: trackedLinks.originalUrl,
23
34
  emailSendId: trackedLinks.emailSendId,
35
+ // The SMS send this per-send short link belongs to (`/s/:code` rewrites).
36
+ // Selected on EVERY resolver, so an SMS row clicked via its raw
37
+ // `/v1/t/c/:id` URL still gets full SMS semantics.
38
+ smsSendId: trackedLinks.smsSendId,
24
39
  distinctId: trackedLinks.distinctId,
25
40
  source: trackedLinks.source,
26
41
  // `event` gates the semantic-confirm dispatch; the confirm task re-reads the
@@ -41,6 +56,7 @@ export type ResolvedClickLink = {
41
56
  id: string;
42
57
  originalUrl: string;
43
58
  emailSendId: string | null;
59
+ smsSendId: string | null;
44
60
  distinctId: string | null;
45
61
  source: string | null;
46
62
  event: string | null;
@@ -127,6 +143,20 @@ export async function handleTrackedClick(
127
143
  ),
128
144
  ]
129
145
  : []),
146
+ // SMS first-touch mirror: set sms_sends.clickedAt exactly once.
147
+ ...(link.smsSendId
148
+ ? [
149
+ db
150
+ .update(smsSends)
151
+ .set({
152
+ clickedAt: new Date(),
153
+ updatedAt: new Date(),
154
+ })
155
+ .where(
156
+ and(eq(smsSends.id, link.smsSendId), isNull(smsSends.clickedAt)),
157
+ ),
158
+ ]
159
+ : []),
130
160
  ]);
131
161
 
132
162
  const { hatchet, registry, logger } = c.get("container");
@@ -275,6 +305,57 @@ export async function handleTrackedClick(
275
305
  }
276
306
  })
277
307
  .catch(logger.warn);
308
+ } else if (link.smsSendId) {
309
+ // SMS short link (`/s/:code`): re-ingest the first-party
310
+ // `sms.link_clicked` bus event and emit the per-hit `sms.clicked`
311
+ // outbound — the SMS sibling of the email branch above. The bus
312
+ // re-ingest is GATED on `!isBot` (iMessage/WhatsApp/RCS link-preview
313
+ // bots prefetch texted URLs — a phantom-enrollment risk the email
314
+ // branch doesn't share because inbox clicks aren't unfurl-prefetched
315
+ // the same way) AND on a resolved contact key (phone is NOT a contact
316
+ // `Kind`; a userless raw send has no subject to ingest).
317
+ const smsSendId = link.smsSendId;
318
+ void resolveSmsSendContext(db, smsSendId)
319
+ .then(async (ctx) => {
320
+ if (!isBot && ctx?.userId) {
321
+ await pushSmsTrackingEvent({
322
+ db,
323
+ hatchet,
324
+ registry,
325
+ logger,
326
+ event: SMS_LINK_CLICKED,
327
+ smsSendId,
328
+ properties: { linkUrl: link.originalUrl, linkId: link.id },
329
+ resolvedContext: ctx,
330
+ }).catch((err) => {
331
+ logger.warn("Failed to push sms click tracking event", {
332
+ linkId: link.id,
333
+ error: err instanceof Error ? err.message : String(err),
334
+ });
335
+ });
336
+ }
337
+ // Per-hit outbound — mirrors the email click emit (every destination
338
+ // gets every click; NO dedupeKey). Gated on a resolved send row only.
339
+ if (ctx) {
340
+ await emitOutbound({
341
+ db,
342
+ hatchet,
343
+ logger,
344
+ event: "sms.clicked",
345
+ payload: {
346
+ smsSendId,
347
+ messageId: ctx.messageId ?? null,
348
+ templateKey: ctx.templateKey ?? null,
349
+ userId: ctx.userId ?? null,
350
+ to: ctx.to,
351
+ at: new Date().toISOString(),
352
+ linkUrl: link.originalUrl,
353
+ linkId: link.id,
354
+ },
355
+ });
356
+ }
357
+ })
358
+ .catch(logger.warn);
278
359
  } else {
279
360
  // Non-email tracked link: emit the catalogued `link.clicked` (NOT
280
361
  // `email.clicked`). `userId` is the link's stitch subject when
@@ -0,0 +1,61 @@
1
+ import { links, trackedLinks } from "@hogsend/db";
2
+ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
+ import { eq } from "drizzle-orm";
4
+ import type { AppEnv } from "../../app.js";
5
+ import { clickSelection, handleTrackedClick } from "./click-pipeline.js";
6
+
7
+ // The SMS short path — `/s/:code` layered over `/v1/t/c/:id`, mirroring the
8
+ // vanity `/l/:slug` route. Mounted at the APP ROOT so the texted URL stays
9
+ // short (every character counts against the GSM-7 segment budget); `/s`
10
+ // collides with nothing (`/v1`, `/l`, `/studio`, `/docs`, `/api/auth`,
11
+ // `/connectors`, webhooks).
12
+ const shortRoute = createRoute({
13
+ method: "get",
14
+ path: "/s/:code",
15
+ tags: ["Tracking"],
16
+ summary: "SMS short link redirect",
17
+ request: {
18
+ params: z.object({
19
+ code: z.string(),
20
+ }),
21
+ },
22
+ responses: {
23
+ 302: { description: "Redirect to original URL" },
24
+ },
25
+ });
26
+
27
+ // Lenient superset of minted codes (8-char lowercase base32): tolerate a
28
+ // hand-retyped code without rejecting future length changes.
29
+ const SHORT_CODE_RE = /^[a-z0-9]{4,32}$/;
30
+
31
+ export const shortLinkRouter = new OpenAPIHono<AppEnv>().openapi(
32
+ shortRoute,
33
+ async (c) => {
34
+ const { code } = c.req.valid("param");
35
+ const { db, env } = c.get("container");
36
+
37
+ // Codes are minted lowercase; normalize a cased retype. A malformed code
38
+ // can't match anything — treat it like an unknown link (redirect home),
39
+ // mirroring the vanity route's malformed-slug behavior.
40
+ const normalized = code.trim().toLowerCase();
41
+ if (!SHORT_CODE_RE.test(normalized)) {
42
+ return c.redirect(env.API_PUBLIC_URL, 302);
43
+ }
44
+
45
+ // LEFT JOIN links purely to satisfy the shared clickSelection shape —
46
+ // SMS-minted rows have `link_id` NULL (mirrors the UUID route).
47
+ const rows = await db
48
+ .select(clickSelection)
49
+ .from(trackedLinks)
50
+ .leftJoin(links, eq(trackedLinks.linkId, links.id))
51
+ .where(eq(trackedLinks.shortCode, normalized))
52
+ .limit(1);
53
+
54
+ const link = rows[0];
55
+ if (!link) {
56
+ return c.redirect(env.API_PUBLIC_URL, 302);
57
+ }
58
+
59
+ return handleTrackedClick(c, link);
60
+ },
61
+ );
@@ -3,6 +3,7 @@ import type { AppEnv } from "../../app.js";
3
3
  import type { DefinedConnector } from "../../connectors/define-connector.js";
4
4
  import { registerEmailProviderRoutes } from "./email-provider.js";
5
5
  import { resendWebhookRouter } from "./resend.js";
6
+ import { registerSmsProviderRoutes } from "./sms-provider.js";
6
7
  import { registerWebhookSourceRoutes } from "./sources.js";
7
8
 
8
9
  export interface RegisterWebhookRoutesOptions {
@@ -17,8 +18,11 @@ export function registerWebhookRoutes(
17
18
  // 1. the thin `/v1/webhooks/resend` alias (static),
18
19
  // 2. the `/v1/webhooks/email/:providerId` id-dispatched route (static
19
20
  // `email/` prefix — MUST come before the catch-all),
20
- // 3. the `/v1/webhooks/:sourceId` consumer-source catch-all (LAST).
21
+ // 3. the `/v1/webhooks/sms/:providerId` id-dispatched route (static `sms/`
22
+ // prefix — MUST come before the catch-all),
23
+ // 4. the `/v1/webhooks/:sourceId` consumer-source catch-all (LAST).
21
24
  app.route("/v1/webhooks", resendWebhookRouter);
22
25
  registerEmailProviderRoutes(app);
26
+ registerSmsProviderRoutes(app);
23
27
  registerWebhookSourceRoutes(app, opts.webhookConnectors);
24
28
  }
@@ -0,0 +1,110 @@
1
+ import { WebhookHandshakeSignal } from "@hogsend/core";
2
+ import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
3
+ import type { Context } from "hono";
4
+ import type { AppEnv } from "../../app.js";
5
+ import { env } from "../../env.js";
6
+ import { headersToRecord } from "../../lib/headers.js";
7
+
8
+ /**
9
+ * Shared SMS-provider webhook dispatch for
10
+ * `POST /v1/webhooks/sms/:providerId`. Resolves the provider from the
11
+ * container's {@link SmsProviderRegistry} (404 on unknown id), reads the raw
12
+ * body as the EXACT received bytes, builds the canonical PUBLIC url (Twilio
13
+ * signs `API_PUBLIC_URL + path + query`, NOT `c.req.url` which has the wrong
14
+ * host behind a proxy), verifies + dispatches the normalized {@link SmsEvent},
15
+ * 200s a {@link WebhookHandshakeSignal} (intermediate status / unrecognized),
16
+ * and 401s a verification error.
17
+ *
18
+ * Responds with an empty TwiML document — Twilio's inbound MO webhook expects
19
+ * TwiML; status callbacks accept any 2xx.
20
+ */
21
+ export async function dispatchSmsProviderWebhook(
22
+ c: Context<AppEnv>,
23
+ providerId: string,
24
+ ) {
25
+ const { smsProviders, smsService, logger } = c.get("container");
26
+
27
+ const provider = smsProviders.get(providerId);
28
+ if (!provider) {
29
+ return c.json({ error: "Unknown SMS provider" }, 404);
30
+ }
31
+
32
+ const payload = await c.req.text();
33
+ const headers = headersToRecord(c.req.raw.headers);
34
+
35
+ // Canonical public URL the provider signed: API_PUBLIC_URL + path (+ query).
36
+ // Twilio's HMAC covers the URL string byte-for-byte, so normalize the one
37
+ // operator-controlled degree of freedom — a trailing slash on
38
+ // API_PUBLIC_URL would otherwise 401 EVERY callback and inbound STOP.
39
+ const requestUrl = new URL(c.req.url);
40
+ const base = env.API_PUBLIC_URL.replace(/\/+$/, "");
41
+ const url = `${base}${requestUrl.pathname}${requestUrl.search}`;
42
+
43
+ try {
44
+ const event = await provider.verifyWebhook({ payload, headers, url });
45
+ const result = await smsService.handleWebhook(event, providerId);
46
+ logger.info("SMS provider webhook processed", {
47
+ providerId,
48
+ type: event.type,
49
+ handled: result.handled,
50
+ });
51
+ return c.body(
52
+ '<?xml version="1.0" encoding="UTF-8"?><Response></Response>',
53
+ 200,
54
+ { "Content-Type": "text/xml" },
55
+ );
56
+ } catch (err) {
57
+ if (err instanceof WebhookHandshakeSignal) {
58
+ logger.info("SMS webhook handshake", { providerId, action: err.action });
59
+ return c.body(
60
+ '<?xml version="1.0" encoding="UTF-8"?><Response></Response>',
61
+ 200,
62
+ { "Content-Type": "text/xml" },
63
+ );
64
+ }
65
+ logger.warn("SMS provider webhook failed", {
66
+ providerId,
67
+ error: err instanceof Error ? err.message : String(err),
68
+ });
69
+ return c.json({ error: "Webhook verification failed" }, 401);
70
+ }
71
+ }
72
+
73
+ const smsProviderWebhookRoute = createRoute({
74
+ method: "post",
75
+ path: "/v1/webhooks/sms/{providerId}",
76
+ tags: ["Webhooks"],
77
+ summary: "SMS provider webhook receiver (status callbacks + inbound STOP)",
78
+ request: {
79
+ params: z.object({ providerId: z.string() }),
80
+ body: {
81
+ content: {
82
+ "application/x-www-form-urlencoded": {
83
+ schema: z.record(z.string(), z.unknown()),
84
+ },
85
+ },
86
+ },
87
+ },
88
+ responses: {
89
+ 200: { description: "Webhook processed (empty TwiML)" },
90
+ 401: {
91
+ content: {
92
+ "application/json": { schema: z.object({ error: z.string() }) },
93
+ },
94
+ description: "Missing or invalid webhook signature",
95
+ },
96
+ 404: {
97
+ content: {
98
+ "application/json": { schema: z.object({ error: z.string() }) },
99
+ },
100
+ description: "Unknown SMS provider",
101
+ },
102
+ },
103
+ });
104
+
105
+ export function registerSmsProviderRoutes(app: OpenAPIHono<AppEnv>) {
106
+ app.openapi(smsProviderWebhookRoute, (c) => {
107
+ const { providerId } = c.req.valid("param");
108
+ return dispatchSmsProviderWebhook(c, providerId);
109
+ });
110
+ }