@hogsend/engine 0.39.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.
- package/package.json +9 -7
- package/src/buckets/check-membership.ts +6 -1
- package/src/campaigns/cohort-sql.ts +198 -0
- package/src/campaigns/define-campaign.ts +301 -0
- package/src/campaigns/reconcile.ts +391 -0
- package/src/campaigns/steps.ts +48 -0
- package/src/connectors/define-action.ts +70 -0
- package/src/container.ts +144 -42
- package/src/destinations/presets/posthog.ts +7 -1
- package/src/env.ts +14 -0
- package/src/index.ts +98 -3
- package/src/journeys/constants.ts +10 -0
- package/src/journeys/define-journey.ts +14 -405
- package/src/journeys/execute-journey-run.ts +608 -0
- package/src/journeys/graph/build-graph.ts +212 -56
- package/src/journeys/journey-boundary.ts +54 -0
- package/src/journeys/journey-context.ts +374 -59
- package/src/journeys/record-once.ts +110 -0
- package/src/lib/auth.ts +33 -1
- package/src/lib/blueprints.ts +576 -0
- package/src/lib/campaign-send-key.ts +58 -0
- package/src/lib/connector-actions.ts +203 -19
- package/src/lib/contacts.ts +54 -0
- package/src/lib/email-service-types.ts +4 -1
- package/src/lib/email.ts +13 -2
- package/src/lib/feed.ts +77 -57
- package/src/lib/frequency-cap.ts +45 -15
- package/src/lib/hatchet-duration.ts +22 -0
- package/src/lib/html.ts +1 -0
- package/src/lib/ingestion.ts +145 -4
- package/src/lib/journey-suppress.ts +87 -0
- package/src/lib/links.ts +204 -18
- package/src/lib/outbound.ts +20 -0
- package/src/lib/preferences.ts +80 -1
- package/src/lib/tracked.ts +44 -29
- package/src/lib/tracking-event-names.ts +8 -0
- package/src/lib/webhook-signing.ts +6 -1
- package/src/lists/channels.ts +75 -0
- package/src/lists/define-list.ts +34 -0
- package/src/lists/registry.ts +29 -2
- package/src/mcp/blueprint-tools.ts +460 -0
- package/src/routes/admin/blueprints.ts +711 -0
- package/src/routes/admin/campaigns.ts +341 -0
- package/src/routes/admin/emails.ts +13 -0
- package/src/routes/admin/index.ts +6 -0
- package/src/routes/admin/journeys.ts +4 -2
- package/src/routes/admin/links.ts +303 -36
- package/src/routes/admin/lists.ts +51 -0
- package/src/routes/campaigns/index.ts +297 -50
- package/src/routes/email/preferences.ts +50 -13
- package/src/routes/feed/recipient.ts +2 -43
- package/src/routes/index.ts +6 -0
- package/src/routes/lists/index.ts +138 -18
- package/src/routes/tracking/arrive.ts +260 -0
- package/src/routes/tracking/click-pipeline.ts +329 -0
- package/src/routes/tracking/click.ts +5 -270
- package/src/routes/tracking/index.ts +2 -0
- package/src/routes/tracking/vanity.ts +64 -0
- package/src/worker.ts +27 -0
- package/src/workflows/bucket-backfill.ts +4 -2
- package/src/workflows/bucket-reconcile.ts +11 -4
- package/src/workflows/check-alerts.ts +130 -1
- package/src/workflows/journey-blueprint-interpreter.ts +561 -0
- package/src/workflows/send-campaign.ts +673 -127
|
@@ -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 {
|
|
1
|
+
import { links, trackedLinks } from "@hogsend/db";
|
|
2
2
|
import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
|
|
3
|
-
import {
|
|
3
|
+
import { eq } from "drizzle-orm";
|
|
4
4
|
import type { AppEnv } from "../../app.js";
|
|
5
|
-
import {
|
|
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
|
-
|
|
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);
|