@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.
- package/package.json +9 -7
- package/src/container.ts +192 -4
- package/src/env.ts +28 -0
- package/src/index.ts +39 -0
- package/src/journeys/journey-boundary.ts +5 -1
- package/src/journeys/journey-context.ts +26 -0
- package/src/lib/journey-suppress.ts +33 -2
- package/src/lib/outbound.ts +58 -0
- package/src/lib/phone.ts +19 -0
- package/src/lib/preferences.ts +32 -0
- package/src/lib/sms-frequency-cap.ts +47 -0
- package/src/lib/sms-inbound.ts +200 -0
- package/src/lib/sms-link-tracking.ts +160 -0
- package/src/lib/sms-mailer.ts +338 -0
- package/src/lib/sms-provider-registry.ts +35 -0
- package/src/lib/sms-providers-from-env.ts +100 -0
- package/src/lib/sms-service-types.ts +169 -0
- package/src/lib/sms-tracked.ts +590 -0
- package/src/lib/sms.ts +117 -0
- package/src/lib/tracking-event-names.ts +6 -0
- package/src/lib/tracking-events.ts +107 -1
- package/src/lib/tracking.ts +2 -1
- package/src/lib/webhook-signing.ts +17 -1
- package/src/lists/channels.ts +21 -0
- package/src/routes/email/unsubscribe.ts +1 -0
- package/src/routes/index.ts +6 -0
- package/src/routes/lists/index.ts +54 -7
- package/src/routes/tracking/click-pipeline.ts +83 -2
- package/src/routes/tracking/short.ts +61 -0
- package/src/routes/webhooks/index.ts +5 -1
- package/src/routes/webhooks/sms-provider.ts +110 -0
- package/src/workflows/import-contacts.ts +61 -4
|
@@ -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 {
|
|
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
|
+
}
|
package/src/lib/tracking.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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",
|
package/src/lists/channels.ts
CHANGED
|
@@ -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
|
}
|
package/src/routes/index.ts
CHANGED
|
@@ -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
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
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 {
|
|
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 {
|
|
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/:
|
|
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
|
+
}
|