@hogsend/engine 0.40.0 → 0.41.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 (62) hide show
  1. package/package.json +9 -7
  2. package/src/buckets/check-membership.ts +6 -1
  3. package/src/campaigns/cohort-sql.ts +198 -0
  4. package/src/campaigns/define-campaign.ts +207 -28
  5. package/src/campaigns/reconcile.ts +105 -11
  6. package/src/campaigns/steps.ts +48 -0
  7. package/src/connectors/define-action.ts +70 -0
  8. package/src/container.ts +124 -42
  9. package/src/destinations/presets/posthog.ts +7 -1
  10. package/src/index.ts +82 -2
  11. package/src/journeys/constants.ts +10 -0
  12. package/src/journeys/define-journey.ts +14 -405
  13. package/src/journeys/execute-journey-run.ts +608 -0
  14. package/src/journeys/graph/build-graph.ts +212 -56
  15. package/src/journeys/journey-boundary.ts +54 -0
  16. package/src/journeys/journey-context.ts +374 -59
  17. package/src/journeys/record-once.ts +110 -0
  18. package/src/lib/blueprints.ts +576 -0
  19. package/src/lib/campaign-send-key.ts +58 -0
  20. package/src/lib/connector-actions.ts +203 -19
  21. package/src/lib/contacts.ts +54 -0
  22. package/src/lib/email-service-types.ts +4 -1
  23. package/src/lib/email.ts +13 -2
  24. package/src/lib/feed.ts +77 -57
  25. package/src/lib/frequency-cap.ts +45 -15
  26. package/src/lib/hatchet-duration.ts +22 -0
  27. package/src/lib/html.ts +1 -0
  28. package/src/lib/ingestion.ts +145 -4
  29. package/src/lib/journey-suppress.ts +87 -0
  30. package/src/lib/links.ts +204 -18
  31. package/src/lib/outbound.ts +20 -0
  32. package/src/lib/preferences.ts +80 -1
  33. package/src/lib/tracked.ts +44 -29
  34. package/src/lib/tracking-event-names.ts +8 -0
  35. package/src/lib/webhook-signing.ts +6 -1
  36. package/src/lists/channels.ts +75 -0
  37. package/src/lists/define-list.ts +34 -0
  38. package/src/lists/registry.ts +29 -2
  39. package/src/mcp/blueprint-tools.ts +460 -0
  40. package/src/routes/admin/blueprints.ts +711 -0
  41. package/src/routes/admin/campaigns.ts +179 -3
  42. package/src/routes/admin/emails.ts +13 -0
  43. package/src/routes/admin/index.ts +4 -0
  44. package/src/routes/admin/journeys.ts +4 -2
  45. package/src/routes/admin/links.ts +303 -36
  46. package/src/routes/admin/lists.ts +51 -0
  47. package/src/routes/campaigns/index.ts +44 -6
  48. package/src/routes/email/preferences.ts +50 -13
  49. package/src/routes/feed/recipient.ts +2 -43
  50. package/src/routes/index.ts +6 -0
  51. package/src/routes/lists/index.ts +138 -18
  52. package/src/routes/tracking/arrive.ts +260 -0
  53. package/src/routes/tracking/click-pipeline.ts +329 -0
  54. package/src/routes/tracking/click.ts +5 -270
  55. package/src/routes/tracking/index.ts +2 -0
  56. package/src/routes/tracking/vanity.ts +64 -0
  57. package/src/worker.ts +5 -0
  58. package/src/workflows/bucket-backfill.ts +4 -2
  59. package/src/workflows/bucket-reconcile.ts +11 -4
  60. package/src/workflows/check-alerts.ts +130 -1
  61. package/src/workflows/journey-blueprint-interpreter.ts +561 -0
  62. package/src/workflows/send-campaign.ts +574 -180
@@ -0,0 +1,329 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { emailSends, linkClicks, links, trackedLinks } from "@hogsend/db";
3
+ import { and, eq, isNull, sql } from "drizzle-orm";
4
+ import type { Context } from "hono";
5
+ import type { AppEnv } from "../../app.js";
6
+ import { isBotOrPrefetch } from "../../lib/bot-prefetch.js";
7
+ import { generateIdentityToken } from "../../lib/identity-token.js";
8
+ import { emitOutbound } from "../../lib/outbound.js";
9
+ import { EMAIL_LINK_CLICKED } from "../../lib/tracking-event-names.js";
10
+ import {
11
+ pushLinkClickEvent,
12
+ pushTrackingEvent,
13
+ resolveEmailSendContext,
14
+ } from "../../lib/tracking-events.js";
15
+ import { confirmSemanticClickTask } from "../../workflows/confirm-semantic-click.js";
16
+
17
+ // The one SELECT shape the click pipeline needs, shared by every resolver:
18
+ // the UUID route (`/v1/t/c/:id`, tracked_links LEFT JOIN links) and the
19
+ // vanity route (`/l/:slug`, links INNER JOIN tracked_links).
20
+ export const clickSelection = {
21
+ id: trackedLinks.id,
22
+ originalUrl: trackedLinks.originalUrl,
23
+ emailSendId: trackedLinks.emailSendId,
24
+ distinctId: trackedLinks.distinctId,
25
+ source: trackedLinks.source,
26
+ // `event` gates the semantic-confirm dispatch; the confirm task re-reads the
27
+ // row by id, so `eventProperties` is deliberately NOT selected here.
28
+ event: trackedLinks.event,
29
+ // Managed-link provenance (NULL for email-rewritten links, whose
30
+ // `tracked_links.link_id` is NULL). `linkId` is the durable `links.id`
31
+ // a journey filters on; it rides ONLY the bus re-ingest (A5), never the
32
+ // unchanged outbound payloads which keep `trackedLinks.id` as `linkId`.
33
+ linkId: links.id,
34
+ campaign: links.campaign,
35
+ linkType: links.type,
36
+ // Arrival attribution opt-in: append `hs_ref=<click id>` to the redirect.
37
+ appendRef: links.appendRef,
38
+ };
39
+
40
+ export type ResolvedClickLink = {
41
+ id: string;
42
+ originalUrl: string;
43
+ emailSendId: string | null;
44
+ distinctId: string | null;
45
+ source: string | null;
46
+ event: string | null;
47
+ linkId: string | null;
48
+ campaign: string | null;
49
+ linkType: string | null;
50
+ appendRef: boolean | null;
51
+ };
52
+
53
+ /**
54
+ * The full click pipeline for an already-resolved tracked link: record the
55
+ * hit, mark first-touch email state, defer semantic confirmation, mint the
56
+ * opt-in `hs_t` identity token, emit the per-hit outbound + bus events, and
57
+ * 302 to the destination. Route handlers only differ in HOW they resolve the
58
+ * row (UUID vs vanity slug) — everything downstream is identical.
59
+ */
60
+ export async function handleTrackedClick(
61
+ c: Context<AppEnv>,
62
+ link: ResolvedClickLink,
63
+ ): Promise<Response> {
64
+ const { db, env } = c.get("container");
65
+
66
+ const ip =
67
+ c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
68
+ c.req.header("x-real-ip") ??
69
+ null;
70
+ const userAgent = c.req.header("user-agent") ?? null;
71
+
72
+ // Unfurl-bot / prefetch detection. A link-preview bot (Discord/Slack/…)
73
+ // auto-fetches a DM'd link BEFORE a human clicks; we still record the click
74
+ // + 302, but must NOT re-ingest it onto the journey bus (it would phantom
75
+ // enroll the recipient). Affects ONLY the non-email bus re-ingest below.
76
+ const isBot = isBotOrPrefetch({
77
+ userAgent,
78
+ purpose: c.req.header("purpose"),
79
+ xPurpose: c.req.header("x-purpose"),
80
+ xMozPrefetch: c.req.header("x-moz"),
81
+ secPurpose: c.req.header("sec-purpose"),
82
+ });
83
+
84
+ // The linkClicks insert + clickCount increment stay UNCONDITIONAL — every
85
+ // tracked link counts clicks, email or not.
86
+ //
87
+ // First-touch state UPDATE: the `WHERE clickedAt IS NULL` sets `clickedAt`
88
+ // exactly once (the first click), which is the row-level state we keep. The
89
+ // outbound emit is NO LONGER gated on this — every destination must receive
90
+ // EVERY click (owner decision 1), so the emit below fires per-hit. The
91
+ // emailSends update is GATED on `emailSendId != null` (MF-6): a non-email
92
+ // link has no send row to mark. This was previously safe-by-accident
93
+ // (`WHERE id = NULL` matches nothing) — the gate makes it explicit.
94
+ // Pre-generate the click id: it is BOTH the row PK and (when the link opts
95
+ // in) the `hs_ref` arrival reference appended to the redirect. The insert is
96
+ // awaited before the redirect, so the ref always resolves.
97
+ const clickId = randomUUID();
98
+ const emailSendId = link.emailSendId;
99
+ await Promise.all([
100
+ db.insert(linkClicks).values({
101
+ id: clickId,
102
+ trackedLinkId: link.id,
103
+ ipAddress: ip,
104
+ userAgent,
105
+ // Per-hit destination provenance: after a re-target, stats stay
106
+ // attributable to whichever destination THIS hit actually went to.
107
+ // The raw target, never the hs_t/hs_ref-decorated variant.
108
+ destinationUrl: link.originalUrl,
109
+ }),
110
+ db
111
+ .update(trackedLinks)
112
+ .set({
113
+ clickCount: sql`${trackedLinks.clickCount} + 1`,
114
+ updatedAt: new Date(),
115
+ })
116
+ .where(eq(trackedLinks.id, link.id)),
117
+ ...(emailSendId
118
+ ? [
119
+ db
120
+ .update(emailSends)
121
+ .set({
122
+ clickedAt: new Date(),
123
+ updatedAt: new Date(),
124
+ })
125
+ .where(
126
+ and(eq(emailSends.id, emailSendId), isNull(emailSends.clickedAt)),
127
+ ),
128
+ ]
129
+ : []),
130
+ ]);
131
+
132
+ const { hatchet, registry, logger } = c.get("container");
133
+
134
+ // SEMANTIC link: the click is a PROVISIONAL answer. Confirmation is
135
+ // deferred past the scanner-burst window (a Hatchet task) so the gate can
136
+ // see the WHOLE burst — an inline check could never suppress a scanner's
137
+ // first click. The task claims the send's answer slot (first answer wins)
138
+ // and emits the consumer event + email.action outbound. GATED on
139
+ // `emailSendId != null` (MF-6): the confirm task is email-semantic (it
140
+ // claims a send's answer slot + emits `email.action`), so a non-email
141
+ // semantic link would have no send to confirm against.
142
+ if (link.event && emailSendId) {
143
+ void confirmSemanticClickTask
144
+ .runNoWait({
145
+ trackedLinkId: link.id,
146
+ clickedAt: new Date().toISOString(),
147
+ })
148
+ .catch((err: unknown) => {
149
+ logger.warn("Failed to enqueue semantic click confirmation", {
150
+ linkId: link.id,
151
+ event: link.event,
152
+ error: err instanceof Error ? err.message : String(err),
153
+ });
154
+ });
155
+ }
156
+
157
+ // Cross-device identity stitch (opt-in): append a short-lived signed
158
+ // `hs_t` token to the destination so the landing site can fold its own anon
159
+ // session INTO the subject at `/v1/t/identify`. Two mint sources by link
160
+ // type (§6.5): a stitch-bearing NON-email link mints from its own
161
+ // `distinct_id` (`src: "<source>:<id>"`); an EMAIL link mints from the
162
+ // resolved send context; a BROADCAST link (no `distinct_id`, no send) mints
163
+ // nothing. The token is minted at CLICK time only — never stored on the
164
+ // shareable `/v1/t/c/:id` artifact (§6.3). The awaited send resolve is
165
+ // shared with the async chain below so the read still happens once.
166
+ let redirectUrl = link.originalUrl;
167
+ let preResolved: Awaited<ReturnType<typeof resolveEmailSendContext>> | null =
168
+ null;
169
+ let preResolvedSet = false;
170
+ let identityToken: string | null = null;
171
+ if (env.TRACKING_IDENTITY_TOKEN) {
172
+ let tokenDistinctId: string | null = null;
173
+ let tokenSrc: string | null = null;
174
+ if (link.distinctId) {
175
+ // Stitch-bearing non-email link: the subject is the link's own
176
+ // `distinct_id` (canonical key). No send resolve needed.
177
+ tokenDistinctId = link.distinctId;
178
+ tokenSrc = `${link.source ?? "link"}:${link.id}`;
179
+ } else if (emailSendId) {
180
+ // Email link: resolve the recipient's canonical key from the send row.
181
+ preResolved = await resolveEmailSendContext(db, emailSendId);
182
+ preResolvedSet = true;
183
+ if (preResolved?.userId) {
184
+ tokenDistinctId = preResolved.userId;
185
+ tokenSrc = `email:${emailSendId}`;
186
+ }
187
+ }
188
+ // else: broadcast link (no distinctId, no send) — mint nothing.
189
+
190
+ if (tokenDistinctId && tokenSrc) {
191
+ // Graceful degradation (pre-extraction behavior): a token-mint throw
192
+ // (crypto failure) must degrade to a plain redirect for the human
193
+ // clicker, never a 500 on the redirect path.
194
+ try {
195
+ identityToken = generateIdentityToken({
196
+ secret: env.BETTER_AUTH_SECRET,
197
+ distinctId: tokenDistinctId,
198
+ src: tokenSrc,
199
+ emailSendId: emailSendId ?? undefined,
200
+ });
201
+ } catch {
202
+ identityToken = null;
203
+ }
204
+ }
205
+ }
206
+
207
+ // ONE URL-build pass for every appended param — two separate
208
+ // `new URL(link.originalUrl)` passes would silently drop the other param.
209
+ // `hs_ref` is the ARRIVAL reference (opt-in per link): the raw click id the
210
+ // landing page reports back to POST /v1/t/arrive. Provenance, not identity —
211
+ // never confuse it with `hs_t`. Reserved query params on destinations:
212
+ // `hs_t`, `hs_ref` (both overwritten if already present).
213
+ if (identityToken || link.appendRef) {
214
+ try {
215
+ const url = new URL(link.originalUrl);
216
+ if (identityToken) url.searchParams.set("hs_t", identityToken);
217
+ if (link.appendRef) url.searchParams.set("hs_ref", clickId);
218
+ redirectUrl = url.toString();
219
+ } catch {
220
+ // Unparseable destination — redirect untouched rather than break it.
221
+ redirectUrl = link.originalUrl;
222
+ }
223
+ }
224
+
225
+ // PER-HIT outbound emit, off the response path. EMAIL links re-ingest the
226
+ // first-party `email.link_clicked` event (journey routing + userEvents) and
227
+ // emit `email.clicked`; NON-email links emit `link.clicked` instead — never
228
+ // a malformed `email.clicked` (MF-missing #3). NO `dedupeKey`: a NULL dedupe
229
+ // key is distinct in Postgres, so every click creates a fresh delivery to
230
+ // every subscribed destination (per-hit, not first-touch).
231
+ if (emailSendId) {
232
+ void (
233
+ preResolvedSet
234
+ ? Promise.resolve(preResolved)
235
+ : resolveEmailSendContext(db, emailSendId)
236
+ )
237
+ .then(async (ctx) => {
238
+ await pushTrackingEvent({
239
+ db,
240
+ hatchet,
241
+ registry,
242
+ logger,
243
+ event: EMAIL_LINK_CLICKED,
244
+ emailSendId,
245
+ properties: { linkUrl: link.originalUrl, linkId: link.id },
246
+ resolvedContext: ctx,
247
+ }).catch((err) => {
248
+ logger.warn("Failed to push click tracking event", {
249
+ linkId: link.id,
250
+ error: err instanceof Error ? err.message : String(err),
251
+ });
252
+ });
253
+
254
+ // Only emit when the send-context resolved. A missing emailSends row
255
+ // (orphaned tracked link / deleted send) has no userId or recipient to
256
+ // attribute, and a keyed destination (PostHog) would otherwise receive
257
+ // an empty distinct_id. A normal click always resolves a non-null userId.
258
+ if (ctx) {
259
+ await emitOutbound({
260
+ db,
261
+ hatchet,
262
+ logger,
263
+ event: "email.clicked",
264
+ payload: {
265
+ emailSendId,
266
+ messageId: ctx.messageId ?? null,
267
+ templateKey: ctx.templateKey ?? null,
268
+ userId: ctx.userId ?? null,
269
+ to: ctx.to ?? ctx.userEmail ?? "",
270
+ at: new Date().toISOString(),
271
+ linkUrl: link.originalUrl,
272
+ linkId: link.id,
273
+ },
274
+ });
275
+ }
276
+ })
277
+ .catch(logger.warn);
278
+ } else {
279
+ // Non-email tracked link: emit the catalogued `link.clicked` (NOT
280
+ // `email.clicked`). `userId` is the link's stitch subject when
281
+ // identity-bearing, else null for a broadcast link. No re-ingest — the
282
+ // first-party `email.link_clicked` bus event is email-semantic.
283
+ void emitOutbound({
284
+ db,
285
+ hatchet,
286
+ logger,
287
+ event: "link.clicked",
288
+ payload: {
289
+ linkId: link.id,
290
+ source: link.source ?? null,
291
+ userId: link.distinctId ?? null,
292
+ emailSendId: null,
293
+ messageId: null,
294
+ linkUrl: link.originalUrl,
295
+ at: new Date().toISOString(),
296
+ },
297
+ }).catch(logger.warn);
298
+
299
+ // BUS re-ingest: the first-party `link.clicked` event for a NON-email
300
+ // managed link, so journeys can trigger / `ctx.waitForEvent` on a click of
301
+ // a SPECIFIC managed link (filter by `linkId`/`campaign`). GATED on:
302
+ // • `!isBot` — an unfurl/prefetch bot fetched the link, not a human.
303
+ // • `link.distinctId` — a broadcast/public link carries no person, and
304
+ // `resolveOrCreateContact` THROWS on a zero-key event. Personal links
305
+ // only; the resolved subject is the survivor contact (not the raw
306
+ // mint key). Per-second idempotencyKey dedupes the userEvents INSERT on
307
+ // retry only — `entryLimit` is the journey-level throttle.
308
+ if (!isBot && link.distinctId) {
309
+ void pushLinkClickEvent({
310
+ db,
311
+ hatchet,
312
+ registry,
313
+ logger,
314
+ linkId: link.linkId ?? null,
315
+ trackedLinkId: link.id,
316
+ campaign: link.campaign ?? null,
317
+ source: link.source ?? null,
318
+ linkType: link.linkType ?? null,
319
+ linkUrl: link.originalUrl,
320
+ distinctId: link.distinctId,
321
+ idempotencyKey: `link:click:${link.id}:${Math.floor(
322
+ Date.now() / 1000,
323
+ )}`,
324
+ }).catch(logger.warn);
325
+ }
326
+ }
327
+
328
+ return c.redirect(redirectUrl, 302);
329
+ }
@@ -1,17 +1,8 @@
1
- import { emailSends, linkClicks, links, trackedLinks } from "@hogsend/db";
1
+ import { links, trackedLinks } from "@hogsend/db";
2
2
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
- import { and, eq, isNull, sql } from "drizzle-orm";
3
+ import { eq } from "drizzle-orm";
4
4
  import type { AppEnv } from "../../app.js";
5
- import { isBotOrPrefetch } from "../../lib/bot-prefetch.js";
6
- import { generateIdentityToken } from "../../lib/identity-token.js";
7
- import { emitOutbound } from "../../lib/outbound.js";
8
- import { EMAIL_LINK_CLICKED } from "../../lib/tracking-event-names.js";
9
- import {
10
- pushLinkClickEvent,
11
- pushTrackingEvent,
12
- resolveEmailSendContext,
13
- } from "../../lib/tracking-events.js";
14
- import { confirmSemanticClickTask } from "../../workflows/confirm-semantic-click.js";
5
+ import { clickSelection, handleTrackedClick } from "./click-pipeline.js";
15
6
 
16
7
  const clickRoute = createRoute({
17
8
  method: "get",
@@ -36,22 +27,7 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
36
27
  const { db, env } = c.get("container");
37
28
 
38
29
  const rows = await db
39
- .select({
40
- id: trackedLinks.id,
41
- originalUrl: trackedLinks.originalUrl,
42
- emailSendId: trackedLinks.emailSendId,
43
- distinctId: trackedLinks.distinctId,
44
- source: trackedLinks.source,
45
- event: trackedLinks.event,
46
- eventProperties: trackedLinks.eventProperties,
47
- // Managed-link provenance (NULL for email-rewritten links, whose
48
- // `tracked_links.link_id` is NULL). `linkId` is the durable `links.id`
49
- // a journey filters on; it rides ONLY the bus re-ingest (A5), never the
50
- // unchanged outbound payloads which keep `trackedLinks.id` as `linkId`.
51
- linkId: links.id,
52
- campaign: links.campaign,
53
- linkType: links.type,
54
- })
30
+ .select(clickSelection)
55
31
  .from(trackedLinks)
56
32
  .leftJoin(links, eq(trackedLinks.linkId, links.id))
57
33
  .where(eq(trackedLinks.id, id))
@@ -62,247 +38,6 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
62
38
  return c.redirect(env.API_PUBLIC_URL, 302);
63
39
  }
64
40
 
65
- const ip =
66
- c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
67
- c.req.header("x-real-ip") ??
68
- null;
69
- const userAgent = c.req.header("user-agent") ?? null;
70
-
71
- // Unfurl-bot / prefetch detection. A link-preview bot (Discord/Slack/…)
72
- // auto-fetches a DM'd link BEFORE a human clicks; we still record the click
73
- // + 302, but must NOT re-ingest it onto the journey bus (it would phantom
74
- // enroll the recipient). Affects ONLY the non-email bus re-ingest below.
75
- const isBot = isBotOrPrefetch({
76
- userAgent,
77
- purpose: c.req.header("purpose"),
78
- xPurpose: c.req.header("x-purpose"),
79
- xMozPrefetch: c.req.header("x-moz"),
80
- secPurpose: c.req.header("sec-purpose"),
81
- });
82
-
83
- // The linkClicks insert + clickCount increment stay UNCONDITIONAL — every
84
- // tracked link counts clicks, email or not.
85
- //
86
- // First-touch state UPDATE: the `WHERE clickedAt IS NULL` sets `clickedAt`
87
- // exactly once (the first click), which is the row-level state we keep. The
88
- // outbound emit is NO LONGER gated on this — every destination must receive
89
- // EVERY click (owner decision 1), so the emit below fires per-hit. The
90
- // emailSends update is GATED on `emailSendId != null` (MF-6): a non-email
91
- // link has no send row to mark. This was previously safe-by-accident
92
- // (`WHERE id = NULL` matches nothing) — the gate makes it explicit.
93
- const emailSendId = link.emailSendId;
94
- await Promise.all([
95
- db.insert(linkClicks).values({
96
- trackedLinkId: link.id,
97
- ipAddress: ip,
98
- userAgent,
99
- }),
100
- db
101
- .update(trackedLinks)
102
- .set({
103
- clickCount: sql`${trackedLinks.clickCount} + 1`,
104
- updatedAt: new Date(),
105
- })
106
- .where(eq(trackedLinks.id, link.id)),
107
- ...(emailSendId
108
- ? [
109
- db
110
- .update(emailSends)
111
- .set({
112
- clickedAt: new Date(),
113
- updatedAt: new Date(),
114
- })
115
- .where(
116
- and(
117
- eq(emailSends.id, emailSendId),
118
- isNull(emailSends.clickedAt),
119
- ),
120
- ),
121
- ]
122
- : []),
123
- ]);
124
-
125
- const { hatchet, registry, logger } = c.get("container");
126
-
127
- // SEMANTIC link: the click is a PROVISIONAL answer. Confirmation is
128
- // deferred past the scanner-burst window (a Hatchet task) so the gate can
129
- // see the WHOLE burst — an inline check could never suppress a scanner's
130
- // first click. The task claims the send's answer slot (first answer wins)
131
- // and emits the consumer event + email.action outbound. GATED on
132
- // `emailSendId != null` (MF-6): the confirm task is email-semantic (it
133
- // claims a send's answer slot + emits `email.action`), so a non-email
134
- // semantic link would have no send to confirm against.
135
- if (link.event && emailSendId) {
136
- void confirmSemanticClickTask
137
- .runNoWait({
138
- trackedLinkId: link.id,
139
- clickedAt: new Date().toISOString(),
140
- })
141
- .catch((err: unknown) => {
142
- logger.warn("Failed to enqueue semantic click confirmation", {
143
- linkId: link.id,
144
- event: link.event,
145
- error: err instanceof Error ? err.message : String(err),
146
- });
147
- });
148
- }
149
-
150
- // Cross-device identity stitch (opt-in): append a short-lived signed
151
- // `hs_t` token to the destination so the landing site can fold its own anon
152
- // session INTO the subject at `/v1/t/identify`. Two mint sources by link
153
- // type (§6.5): a stitch-bearing NON-email link mints from its own
154
- // `distinct_id` (`src: "<source>:<id>"`); an EMAIL link mints from the
155
- // resolved send context; a BROADCAST link (no `distinct_id`, no send) mints
156
- // nothing. The token is minted at CLICK time only — never stored on the
157
- // shareable `/v1/t/c/:id` artifact (§6.3). The awaited send resolve is
158
- // shared with the async chain below so the read still happens once.
159
- let redirectUrl = link.originalUrl;
160
- let preResolved: Awaited<
161
- ReturnType<typeof resolveEmailSendContext>
162
- > | null = null;
163
- let preResolvedSet = false;
164
- if (env.TRACKING_IDENTITY_TOKEN) {
165
- let tokenDistinctId: string | null = null;
166
- let tokenSrc: string | null = null;
167
- if (link.distinctId) {
168
- // Stitch-bearing non-email link: the subject is the link's own
169
- // `distinct_id` (canonical key). No send resolve needed.
170
- tokenDistinctId = link.distinctId;
171
- tokenSrc = `${link.source ?? "link"}:${link.id}`;
172
- } else if (emailSendId) {
173
- // Email link: resolve the recipient's canonical key from the send row.
174
- preResolved = await resolveEmailSendContext(db, emailSendId);
175
- preResolvedSet = true;
176
- if (preResolved?.userId) {
177
- tokenDistinctId = preResolved.userId;
178
- tokenSrc = `email:${emailSendId}`;
179
- }
180
- }
181
- // else: broadcast link (no distinctId, no send) — mint nothing.
182
-
183
- if (tokenDistinctId && tokenSrc) {
184
- try {
185
- const url = new URL(link.originalUrl);
186
- url.searchParams.set(
187
- "hs_t",
188
- generateIdentityToken({
189
- secret: env.BETTER_AUTH_SECRET,
190
- distinctId: tokenDistinctId,
191
- src: tokenSrc,
192
- emailSendId: emailSendId ?? undefined,
193
- }),
194
- );
195
- redirectUrl = url.toString();
196
- } catch {
197
- // Unparseable destination — redirect untouched rather than break it.
198
- redirectUrl = link.originalUrl;
199
- }
200
- }
201
- }
202
-
203
- // PER-HIT outbound emit, off the response path. EMAIL links re-ingest the
204
- // first-party `email.link_clicked` event (journey routing + userEvents) and
205
- // emit `email.clicked`; NON-email links emit `link.clicked` instead — never
206
- // a malformed `email.clicked` (MF-missing #3). NO `dedupeKey`: a NULL dedupe
207
- // key is distinct in Postgres, so every click creates a fresh delivery to
208
- // every subscribed destination (per-hit, not first-touch).
209
- if (emailSendId) {
210
- void (
211
- preResolvedSet
212
- ? Promise.resolve(preResolved)
213
- : resolveEmailSendContext(db, emailSendId)
214
- )
215
- .then(async (ctx) => {
216
- await pushTrackingEvent({
217
- db,
218
- hatchet,
219
- registry,
220
- logger,
221
- event: EMAIL_LINK_CLICKED,
222
- emailSendId,
223
- properties: { linkUrl: link.originalUrl, linkId: link.id },
224
- resolvedContext: ctx,
225
- }).catch((err) => {
226
- logger.warn("Failed to push click tracking event", {
227
- linkId: link.id,
228
- error: err instanceof Error ? err.message : String(err),
229
- });
230
- });
231
-
232
- // Only emit when the send-context resolved. A missing emailSends row
233
- // (orphaned tracked link / deleted send) has no userId or recipient to
234
- // attribute, and a keyed destination (PostHog) would otherwise receive
235
- // an empty distinct_id. A normal click always resolves a non-null userId.
236
- if (ctx) {
237
- await emitOutbound({
238
- db,
239
- hatchet,
240
- logger,
241
- event: "email.clicked",
242
- payload: {
243
- emailSendId,
244
- messageId: ctx.messageId ?? null,
245
- templateKey: ctx.templateKey ?? null,
246
- userId: ctx.userId ?? null,
247
- to: ctx.to ?? ctx.userEmail ?? "",
248
- at: new Date().toISOString(),
249
- linkUrl: link.originalUrl,
250
- linkId: link.id,
251
- },
252
- });
253
- }
254
- })
255
- .catch(logger.warn);
256
- } else {
257
- // Non-email tracked link: emit the catalogued `link.clicked` (NOT
258
- // `email.clicked`). `userId` is the link's stitch subject when
259
- // identity-bearing, else null for a broadcast link. No re-ingest — the
260
- // first-party `email.link_clicked` bus event is email-semantic.
261
- void emitOutbound({
262
- db,
263
- hatchet,
264
- logger,
265
- event: "link.clicked",
266
- payload: {
267
- linkId: link.id,
268
- source: link.source ?? null,
269
- userId: link.distinctId ?? null,
270
- emailSendId: null,
271
- messageId: null,
272
- linkUrl: link.originalUrl,
273
- at: new Date().toISOString(),
274
- },
275
- }).catch(logger.warn);
276
-
277
- // BUS re-ingest: the first-party `link.clicked` event for a NON-email
278
- // managed link, so journeys can trigger / `ctx.waitForEvent` on a click of
279
- // a SPECIFIC managed link (filter by `linkId`/`campaign`). GATED on:
280
- // • `!isBot` — an unfurl/prefetch bot fetched the link, not a human.
281
- // • `link.distinctId` — a broadcast/public link carries no person, and
282
- // `resolveOrCreateContact` THROWS on a zero-key event. Personal links
283
- // only; the resolved subject is the survivor contact (not the raw
284
- // mint key). Per-second idempotencyKey dedupes the userEvents INSERT on
285
- // retry only — `entryLimit` is the journey-level throttle.
286
- if (!isBot && link.distinctId) {
287
- void pushLinkClickEvent({
288
- db,
289
- hatchet,
290
- registry,
291
- logger,
292
- linkId: link.linkId ?? null,
293
- trackedLinkId: link.id,
294
- campaign: link.campaign ?? null,
295
- source: link.source ?? null,
296
- linkType: link.linkType ?? null,
297
- linkUrl: link.originalUrl,
298
- distinctId: link.distinctId,
299
- idempotencyKey: `link:click:${link.id}:${Math.floor(
300
- Date.now() / 1000,
301
- )}`,
302
- }).catch(logger.warn);
303
- }
304
- }
305
-
306
- return c.redirect(redirectUrl, 302);
41
+ return handleTrackedClick(c, link);
307
42
  },
308
43
  );
@@ -1,6 +1,7 @@
1
1
  import { OpenAPIHono } from "@hono/zod-openapi";
2
2
  import type { AppEnv } from "../../app.js";
3
3
  import { answerRouter } from "./answer.js";
4
+ import { arriveRouter } from "./arrive.js";
4
5
  import { clickRouter } from "./click.js";
5
6
  import { identifyRouter } from "./identify.js";
6
7
  import { openRouter } from "./open.js";
@@ -11,3 +12,4 @@ trackingRouter.route("/", clickRouter);
11
12
  trackingRouter.route("/", openRouter);
12
13
  trackingRouter.route("/", answerRouter);
13
14
  trackingRouter.route("/", identifyRouter);
15
+ trackingRouter.route("/", arriveRouter);