@hogsend/engine 0.40.0 → 0.42.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 +11 -8
- package/src/buckets/check-membership.ts +6 -1
- package/src/campaigns/cohort-sql.ts +198 -0
- package/src/campaigns/define-campaign.ts +207 -28
- package/src/campaigns/reconcile.ts +105 -11
- package/src/campaigns/steps.ts +48 -0
- package/src/connectors/define-action.ts +70 -0
- package/src/container.ts +124 -42
- package/src/destinations/presets/posthog.ts +7 -1
- package/src/index.ts +96 -2
- package/src/journeys/constants.ts +10 -0
- package/src/journeys/define-journey.ts +14 -405
- package/src/journeys/execute-journey-run.ts +641 -0
- package/src/journeys/graph/build-graph.ts +212 -56
- package/src/journeys/journey-boundary.ts +54 -0
- package/src/journeys/journey-context.ts +406 -59
- package/src/journeys/record-once.ts +110 -0
- package/src/lib/blueprint-lock.ts +21 -0
- package/src/lib/blueprints.ts +803 -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/event-names.ts +143 -0
- 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/tracking.ts +1 -5
- 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/authoring-guide.ts +160 -0
- package/src/mcp/blueprint-tools.ts +390 -0
- package/src/middleware/require-admin.ts +13 -0
- package/src/routes/admin/api-keys.ts +72 -0
- package/src/routes/admin/blueprints.ts +795 -0
- package/src/routes/admin/campaigns.ts +179 -3
- package/src/routes/admin/emails.ts +13 -0
- package/src/routes/admin/events.ts +55 -0
- package/src/routes/admin/index.ts +4 -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 +44 -6
- 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 +5 -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 +656 -0
- package/src/workflows/send-campaign.ts +574 -180
|
@@ -95,27 +95,49 @@ export const preferencesRouter = new OpenAPIHono<AppEnv>().openapi(
|
|
|
95
95
|
return `${env.API_PUBLIC_URL}/v1/email/unsubscribe?token=${encodeURIComponent(actionToken)}`;
|
|
96
96
|
}
|
|
97
97
|
|
|
98
|
-
//
|
|
99
|
-
//
|
|
98
|
+
// Partition the enabled registry lists into engine-synthesized CHANNELS and
|
|
99
|
+
// author-defined TOPICS (`meta.kind ?? "topic"` mirrors every read site).
|
|
100
|
+
// The built-in journey category is always a topic and leads that group.
|
|
101
|
+
// Deduped by id across both groups (a list MAY NOT reuse a reserved category
|
|
102
|
+
// id, but guard anyway).
|
|
100
103
|
const listRegistry = getListRegistry();
|
|
101
104
|
const seen = new Set<string>();
|
|
102
|
-
const
|
|
105
|
+
const channelCategories: { id: string; label: string }[] = [];
|
|
106
|
+
const topicCategories: { id: string; label: string }[] = [];
|
|
107
|
+
|
|
108
|
+
// Single pass: channels are collected in registry order (deduped now);
|
|
109
|
+
// non-channels are buffered and appended AFTER the built-ins. Because every
|
|
110
|
+
// channel id lands in `seen` before any buffered topic is deduped, this is
|
|
111
|
+
// identical to the prior two-pass form (channel pass fully preceding the
|
|
112
|
+
// topic pass, with the built-ins seeded in between).
|
|
113
|
+
const bufferedTopics: { id: string; label: string }[] = [];
|
|
114
|
+
for (const list of listRegistry.getEnabled()) {
|
|
115
|
+
if ((list.kind ?? "topic") === "channel") {
|
|
116
|
+
if (seen.has(list.id)) continue;
|
|
117
|
+
seen.add(list.id);
|
|
118
|
+
channelCategories.push({ id: list.id, label: list.name });
|
|
119
|
+
} else {
|
|
120
|
+
bufferedTopics.push({ id: list.id, label: list.name });
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
|
|
103
124
|
for (const cat of BUILTIN_CATEGORIES) {
|
|
104
125
|
seen.add(cat.id);
|
|
105
|
-
|
|
126
|
+
topicCategories.push({ id: cat.id, label: cat.label });
|
|
106
127
|
}
|
|
107
|
-
for (const
|
|
108
|
-
if (seen.has(
|
|
109
|
-
seen.add(
|
|
110
|
-
|
|
128
|
+
for (const topic of bufferedTopics) {
|
|
129
|
+
if (seen.has(topic.id)) continue;
|
|
130
|
+
seen.add(topic.id);
|
|
131
|
+
topicCategories.push(topic);
|
|
111
132
|
}
|
|
112
133
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
// Registry-driven polarity (§2.6): defined lists honour their
|
|
134
|
+
function renderRow(cat: { id: string; label: string }): string {
|
|
135
|
+
// Registry-driven polarity (§2.6): defined lists/channels honour their
|
|
116
136
|
// `defaultOptIn`; unknown ids (e.g. the built-in `journey`) fall through
|
|
117
137
|
// to opt-in default (blocked only on explicit `false`). A global
|
|
118
|
-
// unsubscribe overrides every per-category state.
|
|
138
|
+
// unsubscribe overrides every per-category state. Flat channel ids pass
|
|
139
|
+
// the unsubscribe route's category pattern, so channel rows reuse the same
|
|
140
|
+
// per-category token action links unchanged.
|
|
119
141
|
const isSubscribed =
|
|
120
142
|
listRegistry.isSubscribed(categories, cat.id) && !globalUnsub;
|
|
121
143
|
const statusClass = isSubscribed ? "subscribed" : "unsubscribed";
|
|
@@ -125,7 +147,7 @@ export const preferencesRouter = new OpenAPIHono<AppEnv>().openapi(
|
|
|
125
147
|
? makeActionUrl("unsubscribe", cat.id)
|
|
126
148
|
: makeActionUrl("resubscribe", cat.id);
|
|
127
149
|
|
|
128
|
-
|
|
150
|
+
return `
|
|
129
151
|
<div class="pref-row">
|
|
130
152
|
<div>
|
|
131
153
|
<div class="pref-label">${cat.label}</div>
|
|
@@ -135,6 +157,21 @@ export const preferencesRouter = new OpenAPIHono<AppEnv>().openapi(
|
|
|
135
157
|
</div>`;
|
|
136
158
|
}
|
|
137
159
|
|
|
160
|
+
// Section headings render ONLY when channels exist. On a channel-less engine
|
|
161
|
+
// BOTH headings are suppressed so the page is byte-identical to the
|
|
162
|
+
// pre-channels layout (bare topic rows, no headings). When channels exist we
|
|
163
|
+
// show `Channels` then `Email topics`.
|
|
164
|
+
const hasChannels = channelCategories.length > 0;
|
|
165
|
+
let categoryRows = "";
|
|
166
|
+
if (hasChannels) {
|
|
167
|
+
categoryRows += `<h2 class="pref-section">Channels</h2>`;
|
|
168
|
+
categoryRows += channelCategories.map(renderRow).join("");
|
|
169
|
+
}
|
|
170
|
+
if (hasChannels && topicCategories.length > 0) {
|
|
171
|
+
categoryRows += `<h2 class="pref-section">Email topics</h2>`;
|
|
172
|
+
}
|
|
173
|
+
categoryRows += topicCategories.map(renderRow).join("");
|
|
174
|
+
|
|
138
175
|
const globalStatusClass = globalUnsub ? "unsubscribed" : "subscribed";
|
|
139
176
|
const globalStatusText = globalUnsub
|
|
140
177
|
? "Unsubscribed from all"
|
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
import { contacts, type Database } from "@hogsend/db";
|
|
2
|
-
import { and, eq, isNull
|
|
2
|
+
import { and, eq, isNull } from "drizzle-orm";
|
|
3
3
|
import type { Context } from "hono";
|
|
4
4
|
import type { AppEnv } from "../../app.js";
|
|
5
5
|
import {
|
|
6
|
+
collidesWithIdentified,
|
|
6
7
|
contactKey,
|
|
7
8
|
normalizeEmail,
|
|
8
9
|
resolveContact,
|
|
@@ -130,48 +131,6 @@ export async function resolveFeedRecipient(
|
|
|
130
131
|
};
|
|
131
132
|
}
|
|
132
133
|
|
|
133
|
-
/**
|
|
134
|
-
* True when `value` is the canonical key of an IDENTIFIED contact — i.e. a live
|
|
135
|
-
* contact's `external_id`, or its `email` when that is its canonical key (no
|
|
136
|
-
* `external_id`). Such a value names an identified person's feed rows, so a
|
|
137
|
-
* token-less publishable caller must NOT be allowed to claim it as an "anon id".
|
|
138
|
-
*
|
|
139
|
-
* A genuine browser anon id only ever matches a contact via `anonymous_id` whose
|
|
140
|
-
* canonical key is that same anon id (the contact has no `external_id`) — that is
|
|
141
|
-
* the caller's OWN anon contact and is allowed (returns false).
|
|
142
|
-
*/
|
|
143
|
-
async function collidesWithIdentified(
|
|
144
|
-
db: Database,
|
|
145
|
-
value: string,
|
|
146
|
-
): Promise<boolean> {
|
|
147
|
-
const rows = await db
|
|
148
|
-
.select({
|
|
149
|
-
externalId: contacts.externalId,
|
|
150
|
-
email: contacts.email,
|
|
151
|
-
anonymousId: contacts.anonymousId,
|
|
152
|
-
})
|
|
153
|
-
.from(contacts)
|
|
154
|
-
.where(
|
|
155
|
-
and(
|
|
156
|
-
or(
|
|
157
|
-
eq(contacts.externalId, value),
|
|
158
|
-
eq(contacts.email, value),
|
|
159
|
-
eq(contacts.anonymousId, value),
|
|
160
|
-
),
|
|
161
|
-
isNull(contacts.deletedAt),
|
|
162
|
-
),
|
|
163
|
-
);
|
|
164
|
-
for (const row of rows) {
|
|
165
|
-
// The supplied value is this contact's `external_id` → its rows are keyed on
|
|
166
|
-
// it (identified). Reject.
|
|
167
|
-
if (row.externalId === value) return true;
|
|
168
|
-
// The supplied value is this contact's `email` AND that email is its
|
|
169
|
-
// canonical key (no external_id) → identified rows are keyed on it. Reject.
|
|
170
|
-
if (row.email === value && !row.externalId) return true;
|
|
171
|
-
}
|
|
172
|
-
return false;
|
|
173
|
-
}
|
|
174
|
-
|
|
175
134
|
/**
|
|
176
135
|
* Canonical key (`external_id ?? anonymous_id ?? id`) for a known contact. Prefer
|
|
177
136
|
* an `email` match (most specific send target), then `userId` (external id or
|
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 { vanityRouter } from "./tracking/vanity.js";
|
|
18
19
|
import { registerWebhookRoutes } from "./webhooks/index.js";
|
|
19
20
|
|
|
20
21
|
export interface RegisterRoutesOptions {
|
|
@@ -135,6 +136,11 @@ export function registerRoutes(
|
|
|
135
136
|
|
|
136
137
|
app.route("/v1", v1);
|
|
137
138
|
|
|
139
|
+
// Vanity link redirect — root-mounted so the operator-facing short URL is
|
|
140
|
+
// `${API_PUBLIC_URL}/l/:slug`. Unauthenticated like the rest of the tracking
|
|
141
|
+
// surface (vanity links land in chats/posts/print).
|
|
142
|
+
app.route("/", vanityRouter);
|
|
143
|
+
|
|
138
144
|
// Generic connector dispatch (oauth/interactions/ingress) — the static
|
|
139
145
|
// `connectors/` prefix is registered BEFORE the `:sourceId` webhook catch-all
|
|
140
146
|
// so it wins path matching. These routes self-authenticate (oauth state +
|
|
@@ -12,7 +12,10 @@ import {
|
|
|
12
12
|
} from "../../lib/contacts.js";
|
|
13
13
|
import type { Logger } from "../../lib/logger.js";
|
|
14
14
|
import { emitOutbound } from "../../lib/outbound.js";
|
|
15
|
-
import {
|
|
15
|
+
import {
|
|
16
|
+
applyListMembership,
|
|
17
|
+
upsertEmailPreference,
|
|
18
|
+
} from "../../lib/preferences.js";
|
|
16
19
|
import { errorSchema } from "../../lib/schemas.js";
|
|
17
20
|
import { getListRegistry } from "../../lists/registry-singleton.js";
|
|
18
21
|
import {
|
|
@@ -26,6 +29,11 @@ const listSummarySchema = z.object({
|
|
|
26
29
|
name: z.string(),
|
|
27
30
|
description: z.string().optional(),
|
|
28
31
|
defaultOptIn: z.boolean(),
|
|
32
|
+
// Whether this is an author-defined `"topic"` or an engine-synthesized
|
|
33
|
+
// delivery `"channel"` (the in-app feed + one per member-directed connector).
|
|
34
|
+
// Always emitted by the server (`meta.kind ?? "topic"`); additive for
|
|
35
|
+
// consumers that ignore it.
|
|
36
|
+
kind: z.enum(["channel", "topic"]),
|
|
29
37
|
// The resolved opt-in state for the identity in the query (`categories[id] ??
|
|
30
38
|
// defaultOptIn`). An anon / publishable / no-identity read degrades to
|
|
31
39
|
// `defaultOptIn` (never leaks another contact's state — mirrors the
|
|
@@ -108,6 +116,54 @@ const preferencesRoute = createRoute({
|
|
|
108
116
|
},
|
|
109
117
|
});
|
|
110
118
|
|
|
119
|
+
// NEW public data-plane write for the email/global master opt-out
|
|
120
|
+
// (`unsubscribedAll`). Until now the ONLY writers of `unsubscribed_all` were the
|
|
121
|
+
// HMAC unsubscribe-token flow and the admin PUT — a browser had no first-party
|
|
122
|
+
// way to set the master toggle. This is the email/global master; per-category
|
|
123
|
+
// channels + topics are managed via the `/{id}/(un)subscribe` endpoints. Static
|
|
124
|
+
// `/preferences` POST is registered adjacent to its GET; it never collides with
|
|
125
|
+
// `/{id}/subscribe` (distinct path shape) so match order is safe.
|
|
126
|
+
const setPreferencesBodySchema = z.object({
|
|
127
|
+
unsubscribedAll: z.boolean(),
|
|
128
|
+
email: z.string().optional(),
|
|
129
|
+
userId: z.string().optional(),
|
|
130
|
+
// Publishable-key identity assertion (§Phase 1). Ignored on the secret path.
|
|
131
|
+
userToken: z.string().optional(),
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
const setPreferencesRoute = createRoute({
|
|
135
|
+
method: "post",
|
|
136
|
+
path: "/preferences",
|
|
137
|
+
tags: ["Lists"],
|
|
138
|
+
summary: "Set a contact's global opt-out (`unsubscribedAll`)",
|
|
139
|
+
description:
|
|
140
|
+
"Writes the email/global master toggle (`unsubscribed_all`) for the resolved contact — the account-wide email opt-out. Per-category channels + topics are managed via `POST /v1/lists/{id}/(un)subscribe`. Behind the publishable gate: a pk_ key must present a verified userToken to act on a concrete identity.",
|
|
141
|
+
request: {
|
|
142
|
+
body: {
|
|
143
|
+
content: { "application/json": { schema: setPreferencesBodySchema } },
|
|
144
|
+
},
|
|
145
|
+
},
|
|
146
|
+
responses: {
|
|
147
|
+
200: {
|
|
148
|
+
content: {
|
|
149
|
+
"application/json": {
|
|
150
|
+
schema: z.object({ unsubscribedAll: z.boolean() }),
|
|
151
|
+
},
|
|
152
|
+
},
|
|
153
|
+
description: "Global opt-out updated",
|
|
154
|
+
},
|
|
155
|
+
400: {
|
|
156
|
+
content: { "application/json": { schema: errorSchema } },
|
|
157
|
+
description: "Missing identity or no resolvable email",
|
|
158
|
+
},
|
|
159
|
+
403: {
|
|
160
|
+
content: { "application/json": { schema: errorSchema } },
|
|
161
|
+
description:
|
|
162
|
+
"Publishable key attempted to act on another identity without a verified userToken",
|
|
163
|
+
},
|
|
164
|
+
},
|
|
165
|
+
});
|
|
166
|
+
|
|
111
167
|
const subscribeRoute = createRoute({
|
|
112
168
|
method: "post",
|
|
113
169
|
path: "/{id}/subscribe",
|
|
@@ -186,6 +242,36 @@ const unsubscribeRoute = createRoute({
|
|
|
186
242
|
},
|
|
187
243
|
});
|
|
188
244
|
|
|
245
|
+
/**
|
|
246
|
+
* INTENT-LAYER `contact.created` emit (decision #3), shared by the list
|
|
247
|
+
* subscribe/unsubscribe path and the master-toggle write. A preference flip is
|
|
248
|
+
* NOT a contact-property delta (so no `contact.updated`); we emit ONLY on the
|
|
249
|
+
* first creation, after a read-back, fire-and-forget so a transient outbound
|
|
250
|
+
* error never fails the preference write. A no-op when `created` is false.
|
|
251
|
+
*/
|
|
252
|
+
function emitContactCreatedIfNew(opts: {
|
|
253
|
+
db: Database;
|
|
254
|
+
hatchet: HatchetClient;
|
|
255
|
+
logger: Logger;
|
|
256
|
+
contactId: string;
|
|
257
|
+
created: boolean;
|
|
258
|
+
}): void {
|
|
259
|
+
const { db, hatchet, logger, contactId, created } = opts;
|
|
260
|
+
if (!created) return;
|
|
261
|
+
void resolveContact({ db, id: contactId })
|
|
262
|
+
.then((row) => {
|
|
263
|
+
if (!row) return;
|
|
264
|
+
return emitOutbound({
|
|
265
|
+
db,
|
|
266
|
+
hatchet,
|
|
267
|
+
logger,
|
|
268
|
+
event: "contact.created",
|
|
269
|
+
payload: serializeContact(row),
|
|
270
|
+
});
|
|
271
|
+
})
|
|
272
|
+
.catch(logger.warn);
|
|
273
|
+
}
|
|
274
|
+
|
|
189
275
|
/**
|
|
190
276
|
* The shared side-effect of subscribe + unsubscribe (identical apart from the
|
|
191
277
|
* boolean polarity): validate the list id, guard identity, then resolve/create
|
|
@@ -231,23 +317,7 @@ async function applyListSubscription(opts: {
|
|
|
231
317
|
email,
|
|
232
318
|
});
|
|
233
319
|
|
|
234
|
-
|
|
235
|
-
// `contact.created` ONLY on first creation (a list flip is not a contact
|
|
236
|
-
// property delta, so no `contact.updated`). Fire-and-forget after a read-back.
|
|
237
|
-
if (created) {
|
|
238
|
-
void resolveContact({ db, id: contactId })
|
|
239
|
-
.then((row) => {
|
|
240
|
-
if (!row) return;
|
|
241
|
-
return emitOutbound({
|
|
242
|
-
db,
|
|
243
|
-
hatchet,
|
|
244
|
-
logger,
|
|
245
|
-
event: "contact.created",
|
|
246
|
-
payload: serializeContact(row),
|
|
247
|
-
});
|
|
248
|
-
})
|
|
249
|
-
.catch(logger.warn);
|
|
250
|
-
}
|
|
320
|
+
emitContactCreatedIfNew({ db, hatchet, logger, contactId, created });
|
|
251
321
|
|
|
252
322
|
await applyListMembership({
|
|
253
323
|
db,
|
|
@@ -303,6 +373,7 @@ export const listsRouter = new OpenAPIHono<AppEnv>()
|
|
|
303
373
|
name: l.name,
|
|
304
374
|
...(l.description !== undefined ? { description: l.description } : {}),
|
|
305
375
|
defaultOptIn: l.defaultOptIn,
|
|
376
|
+
kind: l.kind ?? "topic",
|
|
306
377
|
subscribed: categories[l.id] ?? l.defaultOptIn,
|
|
307
378
|
}));
|
|
308
379
|
|
|
@@ -357,6 +428,55 @@ export const listsRouter = new OpenAPIHono<AppEnv>()
|
|
|
357
428
|
200,
|
|
358
429
|
);
|
|
359
430
|
})
|
|
431
|
+
.openapi(setPreferencesRoute, async (c) => {
|
|
432
|
+
const { db, hatchet, logger, env } = c.get("container");
|
|
433
|
+
const { unsubscribedAll, email, userId, userToken } = c.req.valid("json");
|
|
434
|
+
|
|
435
|
+
// Identical publishable gate to the subscribe handlers: a secret key defers
|
|
436
|
+
// to requireIdentity; a pk_ key needs a verified userToken to act on a
|
|
437
|
+
// concrete identity.
|
|
438
|
+
const guard = gatePublishableIdentity(
|
|
439
|
+
c,
|
|
440
|
+
{ email, userId, userToken },
|
|
441
|
+
env.BETTER_AUTH_SECRET,
|
|
442
|
+
);
|
|
443
|
+
if (guard) return guard;
|
|
444
|
+
|
|
445
|
+
if (!email && !userId) {
|
|
446
|
+
return c.json({ error: "email or userId is required" }, 400);
|
|
447
|
+
}
|
|
448
|
+
|
|
449
|
+
// Resolve/create the contact FIRST (mirroring the subscribe path) so a real
|
|
450
|
+
// row + uuid exists before the preference write keys on `external_id ?? id`.
|
|
451
|
+
const { id: contactId, created } = await resolveOrCreateContact({
|
|
452
|
+
db,
|
|
453
|
+
userId,
|
|
454
|
+
email,
|
|
455
|
+
});
|
|
456
|
+
|
|
457
|
+
emitContactCreatedIfNew({ db, hatchet, logger, contactId, created });
|
|
458
|
+
|
|
459
|
+
// Resolve the deterministic `(external_id ?? contact.id, email)` pair the
|
|
460
|
+
// same way `applyListMembership` does — `email_preferences.email` is NOT
|
|
461
|
+
// NULL, so a contact with no resolvable email 400s (mirrors its error).
|
|
462
|
+
const recipient = await resolveRecipient({ db, userId, email });
|
|
463
|
+
if (!recipient) {
|
|
464
|
+
return c.json(
|
|
465
|
+
{ error: "Contact has no email; cannot manage list membership" },
|
|
466
|
+
400,
|
|
467
|
+
);
|
|
468
|
+
}
|
|
469
|
+
const externalId = recipient.externalId ?? recipient.contactId;
|
|
470
|
+
|
|
471
|
+
await upsertEmailPreference({
|
|
472
|
+
db,
|
|
473
|
+
externalId,
|
|
474
|
+
email: recipient.email,
|
|
475
|
+
update: { unsubscribedAll },
|
|
476
|
+
});
|
|
477
|
+
|
|
478
|
+
return c.json({ unsubscribedAll }, 200);
|
|
479
|
+
})
|
|
360
480
|
.openapi(subscribeRoute, async (c) => {
|
|
361
481
|
const { db, hatchet, logger, env } = c.get("container");
|
|
362
482
|
const { id } = c.req.valid("param");
|
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
import { linkClicks, links, trackedLinks } from "@hogsend/db";
|
|
2
|
+
import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
|
|
3
|
+
import { and, eq, isNull } from "drizzle-orm";
|
|
4
|
+
import type { AppEnv } from "../../app.js";
|
|
5
|
+
import {
|
|
6
|
+
collidesWithIdentified,
|
|
7
|
+
PublishableAnonymousMergeError,
|
|
8
|
+
} from "../../lib/contacts.js";
|
|
9
|
+
import { ingestEvent } from "../../lib/ingestion.js";
|
|
10
|
+
import { emitOutbound } from "../../lib/outbound.js";
|
|
11
|
+
import { LINK_ARRIVED } from "../../lib/tracking-event-names.js";
|
|
12
|
+
import {
|
|
13
|
+
InvalidUserTokenError,
|
|
14
|
+
verifyUserToken,
|
|
15
|
+
} from "../../lib/user-token.js";
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Arrival attribution: the landing page reports "a visitor arrived from
|
|
19
|
+
* tracked hit `ref`" with the visitor's identity evidence. `ref` is the
|
|
20
|
+
* `hs_ref=<link_clicks.id>` the redirect appended (opt-in per link,
|
|
21
|
+
* `links.append_ref`). Joins visitor → that specific scan/click, stamps the
|
|
22
|
+
* click row (first-write-wins), and emits the journey-triggerable
|
|
23
|
+
* `link.arrived` event.
|
|
24
|
+
*
|
|
25
|
+
* TRUST MODEL (mirrors the events route + feed recipient — see
|
|
26
|
+
* `gatePublishableIdentity` and `resolveFeedRecipient`):
|
|
27
|
+
* - `userToken` (HMAC, BETTER_AUTH_SECRET) is the ONLY way a browser asserts
|
|
28
|
+
* a concrete userId. `visitor_kind = 'token'`.
|
|
29
|
+
* - a raw `anonymousId` is PROVENANCE-ONLY: rejected if it collides with an
|
|
30
|
+
* identified contact's canonical key (`collidesWithIdentified`), and the
|
|
31
|
+
* bus ingest runs under `restrictToAnonymous` — it can never attach to /
|
|
32
|
+
* merge into an identified contact. `visitor_kind = 'anon'`.
|
|
33
|
+
* - a bare asserted email/userId is not even in the schema.
|
|
34
|
+
* - INVARIANT: nothing the ref resolves to (above all `links.distinct_id`)
|
|
35
|
+
* ever enters the contact resolver as a subject — identity inputs come
|
|
36
|
+
* ONLY from the token or the clamped anon id.
|
|
37
|
+
*
|
|
38
|
+
* NOTE: with a valid userToken this is the first `/v1/t/*` route that writes
|
|
39
|
+
* journey-triggering events for an identified subject. That authority is the
|
|
40
|
+
* token itself (the same holder could call `/v1/events`); possession of `ref`
|
|
41
|
+
* only selects WHICH click row gets attributed.
|
|
42
|
+
*
|
|
43
|
+
* IDEMPOTENCY: the ingest subject is ALWAYS read from the stamped row, never
|
|
44
|
+
* the current request — so a replayed ref is a self-healing retry (the
|
|
45
|
+
* `link:arrived:<ref>` idempotencyKey caps it at one event ever, for the
|
|
46
|
+
* originally stamped visitor), not a way to re-attribute or double-fire.
|
|
47
|
+
*
|
|
48
|
+
* ANTI-ORACLE: every outcome — success, unknown ref, non-participating link,
|
|
49
|
+
* already stamped, invalid token, collision skip, no identity — returns the
|
|
50
|
+
* SAME `200 {"ok":true}`. An unauthenticated caller learns nothing about
|
|
51
|
+
* contacts or refs. 400 only for a malformed body.
|
|
52
|
+
*/
|
|
53
|
+
const arriveRoute = createRoute({
|
|
54
|
+
method: "post",
|
|
55
|
+
path: "/arrive",
|
|
56
|
+
tags: ["Tracking"],
|
|
57
|
+
summary: "Report a landing-page arrival from a tracked link hit",
|
|
58
|
+
request: {
|
|
59
|
+
body: {
|
|
60
|
+
content: {
|
|
61
|
+
"application/json": {
|
|
62
|
+
schema: z.object({
|
|
63
|
+
// The `hs_ref` value from the landing URL.
|
|
64
|
+
ref: z.string().uuid(),
|
|
65
|
+
// The visitor's OWN browser anon id (`hs_anon_id`) — provenance
|
|
66
|
+
// only, clamped.
|
|
67
|
+
anonymousId: z.string().min(1).max(200).optional(),
|
|
68
|
+
// Server-minted HMAC token binding a userId — the only way a
|
|
69
|
+
// browser asserts an identified visitor. Wins over anonymousId.
|
|
70
|
+
userToken: z.string().min(1).max(2048).optional(),
|
|
71
|
+
}),
|
|
72
|
+
},
|
|
73
|
+
},
|
|
74
|
+
},
|
|
75
|
+
},
|
|
76
|
+
responses: {
|
|
77
|
+
200: {
|
|
78
|
+
description: "Acknowledged (uniform across all outcomes)",
|
|
79
|
+
content: {
|
|
80
|
+
"application/json": { schema: z.object({ ok: z.literal(true) }) },
|
|
81
|
+
},
|
|
82
|
+
},
|
|
83
|
+
400: { description: "Malformed body" },
|
|
84
|
+
},
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
export const arriveRouter = new OpenAPIHono<AppEnv>().openapi(
|
|
88
|
+
arriveRoute,
|
|
89
|
+
async (c) => {
|
|
90
|
+
const { ref, anonymousId, userToken } = c.req.valid("json");
|
|
91
|
+
const { db, env, logger, hatchet, registry, analytics } =
|
|
92
|
+
c.get("container");
|
|
93
|
+
const ok = () => c.json({ ok: true as const }, 200);
|
|
94
|
+
|
|
95
|
+
// Resolve the hit + its link, join-gated on the opt-in: a ref for a
|
|
96
|
+
// non-participating link is only obtainable out-of-band → no-op.
|
|
97
|
+
const rows = await db
|
|
98
|
+
.select({
|
|
99
|
+
visitorDistinctId: linkClicks.visitorDistinctId,
|
|
100
|
+
visitorKind: linkClicks.visitorKind,
|
|
101
|
+
destinationUrl: linkClicks.destinationUrl,
|
|
102
|
+
trackedLinkId: trackedLinks.id,
|
|
103
|
+
source: trackedLinks.source,
|
|
104
|
+
linkId: links.id,
|
|
105
|
+
campaign: links.campaign,
|
|
106
|
+
})
|
|
107
|
+
.from(linkClicks)
|
|
108
|
+
.innerJoin(trackedLinks, eq(linkClicks.trackedLinkId, trackedLinks.id))
|
|
109
|
+
.innerJoin(
|
|
110
|
+
links,
|
|
111
|
+
and(eq(trackedLinks.linkId, links.id), eq(links.appendRef, true)),
|
|
112
|
+
)
|
|
113
|
+
.where(eq(linkClicks.id, ref))
|
|
114
|
+
.limit(1);
|
|
115
|
+
const hit = rows[0];
|
|
116
|
+
if (!hit) return ok();
|
|
117
|
+
|
|
118
|
+
// Resolve the visitor evidence. INVARIANT: identity comes ONLY from here —
|
|
119
|
+
// never from anything the ref resolved to.
|
|
120
|
+
let claimId: string | null = null;
|
|
121
|
+
let claimKind: "token" | "anon" | null = null;
|
|
122
|
+
if (userToken) {
|
|
123
|
+
try {
|
|
124
|
+
claimId = verifyUserToken({
|
|
125
|
+
token: userToken,
|
|
126
|
+
secret: env.BETTER_AUTH_SECRET,
|
|
127
|
+
}).userId;
|
|
128
|
+
claimKind = "token";
|
|
129
|
+
} catch (err) {
|
|
130
|
+
if (err instanceof InvalidUserTokenError) {
|
|
131
|
+
// Background beacon — nothing for the caller to do differently, and
|
|
132
|
+
// a distinguishable failure would add oracle surface.
|
|
133
|
+
logger.info("arrive: invalid userToken (no-op)", { ref });
|
|
134
|
+
return ok();
|
|
135
|
+
}
|
|
136
|
+
throw err;
|
|
137
|
+
}
|
|
138
|
+
} else if (anonymousId) {
|
|
139
|
+
// The stamp guard: an "anon id" that is really an identified contact's
|
|
140
|
+
// canonical key would forge "that person arrived here" in the stamp
|
|
141
|
+
// even though the clamped ingest would suppress the event.
|
|
142
|
+
if (await collidesWithIdentified(db, anonymousId)) {
|
|
143
|
+
logger.info("arrive: anonymousId collides with identified (no-op)", {
|
|
144
|
+
ref,
|
|
145
|
+
});
|
|
146
|
+
return ok();
|
|
147
|
+
}
|
|
148
|
+
claimId = anonymousId;
|
|
149
|
+
claimKind = "anon";
|
|
150
|
+
} else {
|
|
151
|
+
return ok();
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
// First-write-wins stamp; on a replay, read back the ORIGINAL stamp — the
|
|
155
|
+
// ingest below always runs with the stamped identity, never the current
|
|
156
|
+
// request's, so a replay is a self-healing retry, not a re-attribution.
|
|
157
|
+
const [fresh] = await db
|
|
158
|
+
.update(linkClicks)
|
|
159
|
+
.set({
|
|
160
|
+
visitorDistinctId: claimId,
|
|
161
|
+
visitorKind: claimKind,
|
|
162
|
+
arrivedAt: new Date(),
|
|
163
|
+
})
|
|
164
|
+
.where(and(eq(linkClicks.id, ref), isNull(linkClicks.visitorDistinctId)))
|
|
165
|
+
.returning({
|
|
166
|
+
visitorDistinctId: linkClicks.visitorDistinctId,
|
|
167
|
+
visitorKind: linkClicks.visitorKind,
|
|
168
|
+
});
|
|
169
|
+
|
|
170
|
+
const stamp =
|
|
171
|
+
fresh ??
|
|
172
|
+
(hit.visitorDistinctId
|
|
173
|
+
? {
|
|
174
|
+
visitorDistinctId: hit.visitorDistinctId,
|
|
175
|
+
visitorKind: hit.visitorKind,
|
|
176
|
+
}
|
|
177
|
+
: // Raced another arrive between our select and update — re-read.
|
|
178
|
+
(
|
|
179
|
+
await db
|
|
180
|
+
.select({
|
|
181
|
+
visitorDistinctId: linkClicks.visitorDistinctId,
|
|
182
|
+
visitorKind: linkClicks.visitorKind,
|
|
183
|
+
})
|
|
184
|
+
.from(linkClicks)
|
|
185
|
+
.where(eq(linkClicks.id, ref))
|
|
186
|
+
.limit(1)
|
|
187
|
+
)[0]);
|
|
188
|
+
if (!stamp?.visitorDistinctId) return ok();
|
|
189
|
+
const isToken = stamp.visitorKind === "token";
|
|
190
|
+
|
|
191
|
+
// Bus ingest from the STAMPED identity. `link:arrived:<ref>` (no time
|
|
192
|
+
// bucket — once per ref forever): the user_events unique index +
|
|
193
|
+
// compensating delete make replays converge on exactly one event.
|
|
194
|
+
try {
|
|
195
|
+
const result = await ingestEvent({
|
|
196
|
+
db,
|
|
197
|
+
registry,
|
|
198
|
+
hatchet,
|
|
199
|
+
logger,
|
|
200
|
+
analytics,
|
|
201
|
+
restrictToAnonymous: !isToken,
|
|
202
|
+
event: {
|
|
203
|
+
event: LINK_ARRIVED,
|
|
204
|
+
...(isToken
|
|
205
|
+
? { userId: stamp.visitorDistinctId }
|
|
206
|
+
: { anonymousId: stamp.visitorDistinctId }),
|
|
207
|
+
eventProperties: {
|
|
208
|
+
linkId: hit.linkId,
|
|
209
|
+
trackedLinkId: hit.trackedLinkId,
|
|
210
|
+
ref,
|
|
211
|
+
source: hit.source,
|
|
212
|
+
campaign: hit.campaign,
|
|
213
|
+
linkUrl: hit.destinationUrl,
|
|
214
|
+
visitorKind: stamp.visitorKind,
|
|
215
|
+
},
|
|
216
|
+
source: "tracking",
|
|
217
|
+
idempotencyKey: `link:arrived:${ref}`,
|
|
218
|
+
},
|
|
219
|
+
});
|
|
220
|
+
|
|
221
|
+
// Outbound only on the FRESH store — outbound has no dedupe of its own,
|
|
222
|
+
// so this is what keeps webhooks at one delivery per ref.
|
|
223
|
+
if (result.stored) {
|
|
224
|
+
void emitOutbound({
|
|
225
|
+
db,
|
|
226
|
+
hatchet,
|
|
227
|
+
logger,
|
|
228
|
+
event: "link.arrived",
|
|
229
|
+
payload: {
|
|
230
|
+
linkId: hit.linkId,
|
|
231
|
+
trackedLinkId: hit.trackedLinkId,
|
|
232
|
+
ref,
|
|
233
|
+
source: hit.source,
|
|
234
|
+
campaign: hit.campaign,
|
|
235
|
+
userId: isToken ? stamp.visitorDistinctId : null,
|
|
236
|
+
anonymousId: isToken ? null : stamp.visitorDistinctId,
|
|
237
|
+
visitorKind: isToken ? "token" : "anon",
|
|
238
|
+
linkUrl: hit.destinationUrl,
|
|
239
|
+
at: new Date().toISOString(),
|
|
240
|
+
},
|
|
241
|
+
}).catch(logger.warn);
|
|
242
|
+
}
|
|
243
|
+
} catch (err) {
|
|
244
|
+
if (err instanceof PublishableAnonymousMergeError) {
|
|
245
|
+
// The anon id became identified between the stamp guard and the
|
|
246
|
+
// clamped resolve (race) — suppress the event, keep the stamp, 200.
|
|
247
|
+
logger.info("arrive: clamped anon ingest suppressed", { ref });
|
|
248
|
+
return ok();
|
|
249
|
+
}
|
|
250
|
+
// Transient ingest failure — the stamp is durable and a replayed ref
|
|
251
|
+
// self-heals, so never fail the beacon.
|
|
252
|
+
logger.warn("arrive: ingest failed (stamp kept; replay heals)", {
|
|
253
|
+
ref,
|
|
254
|
+
error: err instanceof Error ? err.message : String(err),
|
|
255
|
+
});
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
return ok();
|
|
259
|
+
},
|
|
260
|
+
);
|