@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.
Files changed (69) hide show
  1. package/package.json +11 -8
  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 +96 -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 +641 -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 +406 -59
  17. package/src/journeys/record-once.ts +110 -0
  18. package/src/lib/blueprint-lock.ts +21 -0
  19. package/src/lib/blueprints.ts +803 -0
  20. package/src/lib/campaign-send-key.ts +58 -0
  21. package/src/lib/connector-actions.ts +203 -19
  22. package/src/lib/contacts.ts +54 -0
  23. package/src/lib/email-service-types.ts +4 -1
  24. package/src/lib/email.ts +13 -2
  25. package/src/lib/event-names.ts +143 -0
  26. package/src/lib/feed.ts +77 -57
  27. package/src/lib/frequency-cap.ts +45 -15
  28. package/src/lib/hatchet-duration.ts +22 -0
  29. package/src/lib/html.ts +1 -0
  30. package/src/lib/ingestion.ts +145 -4
  31. package/src/lib/journey-suppress.ts +87 -0
  32. package/src/lib/links.ts +204 -18
  33. package/src/lib/outbound.ts +20 -0
  34. package/src/lib/preferences.ts +80 -1
  35. package/src/lib/tracked.ts +44 -29
  36. package/src/lib/tracking-event-names.ts +8 -0
  37. package/src/lib/tracking.ts +1 -5
  38. package/src/lib/webhook-signing.ts +6 -1
  39. package/src/lists/channels.ts +75 -0
  40. package/src/lists/define-list.ts +34 -0
  41. package/src/lists/registry.ts +29 -2
  42. package/src/mcp/authoring-guide.ts +160 -0
  43. package/src/mcp/blueprint-tools.ts +390 -0
  44. package/src/middleware/require-admin.ts +13 -0
  45. package/src/routes/admin/api-keys.ts +72 -0
  46. package/src/routes/admin/blueprints.ts +795 -0
  47. package/src/routes/admin/campaigns.ts +179 -3
  48. package/src/routes/admin/emails.ts +13 -0
  49. package/src/routes/admin/events.ts +55 -0
  50. package/src/routes/admin/index.ts +4 -0
  51. package/src/routes/admin/journeys.ts +4 -2
  52. package/src/routes/admin/links.ts +303 -36
  53. package/src/routes/admin/lists.ts +51 -0
  54. package/src/routes/campaigns/index.ts +44 -6
  55. package/src/routes/email/preferences.ts +50 -13
  56. package/src/routes/feed/recipient.ts +2 -43
  57. package/src/routes/index.ts +6 -0
  58. package/src/routes/lists/index.ts +138 -18
  59. package/src/routes/tracking/arrive.ts +260 -0
  60. package/src/routes/tracking/click-pipeline.ts +329 -0
  61. package/src/routes/tracking/click.ts +5 -270
  62. package/src/routes/tracking/index.ts +2 -0
  63. package/src/routes/tracking/vanity.ts +64 -0
  64. package/src/worker.ts +5 -0
  65. package/src/workflows/bucket-backfill.ts +4 -2
  66. package/src/workflows/bucket-reconcile.ts +11 -4
  67. package/src/workflows/check-alerts.ts +130 -1
  68. package/src/workflows/journey-blueprint-interpreter.ts +656 -0
  69. package/src/workflows/send-campaign.ts +574 -180
package/src/lib/links.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { randomUUID } from "node:crypto";
2
2
  import { type Database, links, trackedLinks } from "@hogsend/db";
3
+ import { and, eq, isNull, ne, or, sql } from "drizzle-orm";
3
4
 
4
5
  /**
5
6
  * The channel-agnostic MANAGED tracked-link mint — the counterpart to the email
@@ -31,6 +32,11 @@ export interface MintLinkOptions {
31
32
  type?: LinkType;
32
33
  /** Operator-facing name (Studio list). */
33
34
  label?: string;
35
+ /**
36
+ * Longer operator note — what/where this link or its printed QR actually is
37
+ * ("sticker on the workshop door"), for telling codes apart in bulk.
38
+ */
39
+ description?: string;
34
40
  /** UTM-style campaign grouping (public links). */
35
41
  campaign?: string;
36
42
  /**
@@ -40,6 +46,19 @@ export interface MintLinkOptions {
40
46
  distinctId?: string;
41
47
  /** The admin actor who minted it (Studio). */
42
48
  createdBy?: string;
49
+ /**
50
+ * Optional vanity slug — the `/l/:slug` short path layered over the UUID
51
+ * redirect. Normalized lowercase; unique per instance (SlugTakenError on
52
+ * conflict). Managed links only — email's per-send links stay UUID.
53
+ */
54
+ slug?: string;
55
+ /**
56
+ * Arrival attribution opt-in: append `hs_ref=<click id>` to every redirect
57
+ * from this link so the landing page can report the visitor back to
58
+ * `POST /v1/t/arrive`. Off by default — an appended param breaks strict
59
+ * OAuth redirect_uri destinations.
60
+ */
61
+ appendRef?: boolean;
43
62
  }
44
63
 
45
64
  export interface MintedLink {
@@ -49,6 +68,157 @@ export interface MintedLink {
49
68
  trackedLinkId: string;
50
69
  /** The short redirect URL: `${baseUrl}/v1/t/c/:id`. */
51
70
  url: string;
71
+ /** The normalized vanity slug, if one was minted. */
72
+ slug: string | null;
73
+ /** The vanity short URL (`${baseUrl}/l/:slug`), if a slug was minted. */
74
+ vanityUrl: string | null;
75
+ }
76
+
77
+ // ---------------------------------------------------------------------------
78
+ // Vanity slugs
79
+ // ---------------------------------------------------------------------------
80
+
81
+ /** 1–64 chars of lowercase [a-z0-9-], no leading/trailing hyphen. */
82
+ const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
83
+
84
+ /** Thrown when a requested slug is already held by another link → HTTP 409. */
85
+ export class SlugTakenError extends Error {
86
+ constructor(slug: string) {
87
+ super(`Slug "${slug}" is already taken`);
88
+ this.name = "SlugTakenError";
89
+ }
90
+ }
91
+
92
+ /**
93
+ * Lowercase-normalize + validate a requested vanity slug. Throws on an
94
+ * invalid shape (→ HTTP 400). Case-insensitivity comes from normalizing at
95
+ * every write — the DB unique index then only ever sees lowercase.
96
+ */
97
+ export function normalizeSlug(raw: string): string {
98
+ const slug = raw.trim().toLowerCase();
99
+ if (!SLUG_RE.test(slug)) {
100
+ throw new Error(
101
+ `Invalid slug "${raw}": 1-64 lowercase letters/digits/hyphens, no leading/trailing hyphen`,
102
+ );
103
+ }
104
+ return slug;
105
+ }
106
+
107
+ /**
108
+ * True when a DB error is the Postgres unique_violation on the slug index.
109
+ * Walks the cause chain — drizzle wraps the driver's PostgresError in a
110
+ * DrizzleQueryError whose `cause` carries the actual code/constraint.
111
+ */
112
+ export function isSlugUniqueViolation(err: unknown): boolean {
113
+ for (let e = err, depth = 0; e && depth < 5; depth++) {
114
+ const candidate = e as {
115
+ code?: string;
116
+ constraint_name?: string;
117
+ message?: string;
118
+ cause?: unknown;
119
+ };
120
+ if (
121
+ candidate.code === "23505" &&
122
+ (candidate.constraint_name === "links_slug_unique" ||
123
+ (candidate.message?.includes("links_slug_unique") ?? false))
124
+ ) {
125
+ return true;
126
+ }
127
+ e = candidate.cause;
128
+ }
129
+ return false;
130
+ }
131
+
132
+ export function vanityUrlFor(baseUrl: string, slug: string): string {
133
+ return `${baseUrl}/l/${slug}`;
134
+ }
135
+
136
+ /** The `tracked_links.source` marker of a link's per-link QR scan row. */
137
+ export const QR_TRACKED_SOURCE = "qr";
138
+
139
+ /**
140
+ * Lazily mint (or fetch) a managed link's QR scan row — the SECOND
141
+ * `tracked_links` row for the link, `source: "qr"`. The QR code encodes
142
+ * `/v1/t/c/<this row>` (the durable UID URL, never the slug), so scans are
143
+ * attributable separately from link clicks while a PATCH re-target (which
144
+ * updates every tracked row scoped by `link_id`) keeps a printed code
145
+ * pointing at the current destination.
146
+ *
147
+ * Race-safe via the partial unique index `tracked_links(link_id) WHERE
148
+ * source = 'qr'`: a concurrent double-mint loses the insert cleanly and
149
+ * re-reads the winner's row. Returns null when the link doesn't exist.
150
+ */
151
+ export async function ensureQrTrackedLink(opts: {
152
+ db: Database;
153
+ linkId: string;
154
+ }): Promise<{ trackedLinkId: string; created: boolean } | null> {
155
+ const { db, linkId } = opts;
156
+
157
+ const qrRowFilter = and(
158
+ eq(trackedLinks.linkId, linkId),
159
+ eq(trackedLinks.source, QR_TRACKED_SOURCE),
160
+ );
161
+
162
+ const [existing] = await db
163
+ .select({ id: trackedLinks.id })
164
+ .from(trackedLinks)
165
+ .where(qrRowFilter)
166
+ .limit(1);
167
+ if (existing) return { trackedLinkId: existing.id, created: false };
168
+
169
+ const [link] = await db
170
+ .select({
171
+ originalUrl: links.originalUrl,
172
+ distinctId: links.distinctId,
173
+ })
174
+ .from(links)
175
+ .where(eq(links.id, linkId))
176
+ .limit(1);
177
+ if (!link) return null;
178
+
179
+ // distinctId copied from the link so a PERSONAL link's scans stitch the same
180
+ // subject as its clicks; public links stay identity-free (NULL).
181
+ const [inserted] = await db
182
+ .insert(trackedLinks)
183
+ .values({
184
+ id: randomUUID(),
185
+ linkId,
186
+ emailSendId: null,
187
+ distinctId: link.distinctId,
188
+ source: QR_TRACKED_SOURCE,
189
+ originalUrl: link.originalUrl,
190
+ })
191
+ .onConflictDoNothing({
192
+ target: [trackedLinks.linkId],
193
+ // The arbiter predicate matching the partial unique index
194
+ // `tracked_links_qr_per_link_unique` (… WHERE source = 'qr').
195
+ where: sql`${trackedLinks.source} = ${QR_TRACKED_SOURCE}`,
196
+ })
197
+ .returning({ id: trackedLinks.id });
198
+
199
+ if (inserted) return { trackedLinkId: inserted.id, created: true };
200
+
201
+ // Lost the race — the concurrent mint's row is the QR row.
202
+ const [winner] = await db
203
+ .select({ id: trackedLinks.id })
204
+ .from(trackedLinks)
205
+ .where(qrRowFilter)
206
+ .limit(1);
207
+ return winner ? { trackedLinkId: winner.id, created: false } : null;
208
+ }
209
+
210
+ /**
211
+ * SQL predicate selecting a link's CANONICAL tracked row — the redirect row
212
+ * minted alongside the link, as opposed to the lazily-minted per-link QR scan
213
+ * row (`source = 'qr'`). The ONE definition of "which tracked row is the
214
+ * link's redirect row"; every consumer (vanity resolver, admin aggregates)
215
+ * must use it rather than re-deriving QR-awareness.
216
+ */
217
+ export function canonicalTrackedRowFilter() {
218
+ return or(
219
+ isNull(trackedLinks.source),
220
+ ne(trackedLinks.source, QR_TRACKED_SOURCE),
221
+ );
52
222
  }
53
223
 
54
224
  /**
@@ -75,32 +245,48 @@ export async function mintLink(opts: MintLinkOptions): Promise<MintedLink> {
75
245
  const type: LinkType = opts.type ?? "public";
76
246
  // A public link must NEVER carry a person token — drop any distinctId.
77
247
  const distinctId = type === "personal" ? (opts.distinctId ?? null) : null;
248
+ const slug = opts.slug !== undefined ? normalizeSlug(opts.slug) : null;
78
249
 
79
250
  const linkId = randomUUID();
80
251
  const trackedLinkId = randomUUID();
81
252
 
82
- await opts.db.insert(links).values({
83
- id: linkId,
84
- originalUrl: opts.url,
85
- type,
86
- label: opts.label ?? null,
87
- campaign: opts.campaign ?? null,
88
- source: opts.source,
89
- distinctId,
90
- createdBy: opts.createdBy ?? null,
91
- });
92
- await opts.db.insert(trackedLinks).values({
93
- id: trackedLinkId,
94
- linkId,
95
- emailSendId: null,
96
- distinctId,
97
- source: opts.source,
98
- originalUrl: opts.url,
99
- });
253
+ // ONE transaction: a half-failed mint would otherwise strand a `links` row
254
+ // that reserves a globally-unique slug with no tracked row — `/l/<slug>`
255
+ // dead (inner join misses) yet the slug 409s every re-mint.
256
+ try {
257
+ await opts.db.transaction(async (tx) => {
258
+ await tx.insert(links).values({
259
+ id: linkId,
260
+ originalUrl: opts.url,
261
+ type,
262
+ slug,
263
+ label: opts.label ?? null,
264
+ description: opts.description ?? null,
265
+ appendRef: opts.appendRef ?? false,
266
+ campaign: opts.campaign ?? null,
267
+ source: opts.source,
268
+ distinctId,
269
+ createdBy: opts.createdBy ?? null,
270
+ });
271
+ await tx.insert(trackedLinks).values({
272
+ id: trackedLinkId,
273
+ linkId,
274
+ emailSendId: null,
275
+ distinctId,
276
+ source: opts.source,
277
+ originalUrl: opts.url,
278
+ });
279
+ });
280
+ } catch (err) {
281
+ if (slug && isSlugUniqueViolation(err)) throw new SlugTakenError(slug);
282
+ throw err;
283
+ }
100
284
 
101
285
  return {
102
286
  linkId,
103
287
  trackedLinkId,
104
288
  url: `${opts.baseUrl}/v1/t/c/${trackedLinkId}`,
289
+ slug,
290
+ vanityUrl: slug ? vanityUrlFor(opts.baseUrl, slug) : null,
105
291
  };
106
292
  }
@@ -107,6 +107,26 @@ export interface OutboundPayloads {
107
107
  linkUrl: string;
108
108
  at: string;
109
109
  };
110
+ /**
111
+ * A visitor CONFIRMED landing from a tracked hit (opt-in `hs_ref` +
112
+ * POST /v1/t/arrive). Subset of `link.clicked` — fires only when the link
113
+ * opts in AND the landing page reports back. Unlike `link.clicked`, `linkId`
114
+ * here is the MANAGED `links.id` (`trackedLinkId` rides separately — no
115
+ * legacy split), and the identity fields are the VISITOR's: `userId` only
116
+ * when token-verified, `anonymousId` for a clamped anon arrival.
117
+ */
118
+ "link.arrived": {
119
+ linkId: string;
120
+ trackedLinkId: string;
121
+ ref: string;
122
+ source: string | null;
123
+ campaign: string | null;
124
+ userId: string | null;
125
+ anonymousId: string | null;
126
+ visitorKind: "token" | "anon";
127
+ linkUrl: string | null;
128
+ at: string;
129
+ };
110
130
  /**
111
131
  * A SEMANTIC link answered — the in-email action event (consumer-named, e.g.
112
132
  * "nps.submitted"). Emitted at most once per (send, event name): first
@@ -1,6 +1,6 @@
1
1
  import type { Database } from "@hogsend/db";
2
2
  import { emailPreferences } from "@hogsend/db";
3
- import { sql } from "drizzle-orm";
3
+ import { eq, or, sql } from "drizzle-orm";
4
4
  import { resolveRecipient } from "./contacts.js";
5
5
  import { hatchet } from "./hatchet.js";
6
6
  import { createLogger } from "./logger.js";
@@ -121,6 +121,85 @@ export async function upsertEmailPreference(opts: {
121
121
  }
122
122
  }
123
123
 
124
+ /**
125
+ * Aggregated preference verdict for a recipient, folded across EVERY matching
126
+ * `email_preferences` row. See {@link readRecipientPreferences}.
127
+ */
128
+ export interface RecipientPreferences {
129
+ /** true when ANY matching row has unsubscribed_all (global master opt-out). */
130
+ unsubscribedAll: boolean;
131
+ /**
132
+ * true when ANY matching row is suppressed (hard bounce / complaint).
133
+ * Email-transport-specific — channel checks must NOT consume this.
134
+ */
135
+ suppressed: boolean;
136
+ /** Category map merged across ALL matching rows, explicit false winning. */
137
+ categories: Record<string, boolean>;
138
+ }
139
+
140
+ /**
141
+ * The ONE aggregated preference READ shared by the email mailer (checkSuppression),
142
+ * the in-app feed, and connector-send gating. Selects EVERY `email_preferences`
143
+ * row matching the given identity keys and folds them into a single verdict.
144
+ *
145
+ * An address can legitimately have MORE THAN ONE row: the `(user_id, email)`
146
+ * composite PK means a suppression imported before the contact existed is keyed
147
+ * (email, email) while later interactive writes key (external_id, email). We
148
+ * aggregate across ALL matching rows — any suppression signal on ANY row must
149
+ * win — so an imported unsubscribe/bounce can never be shadowed by a newer clean
150
+ * row for the same address.
151
+ *
152
+ * Rows are selected `WHERE email = keys.email OR user_id = keys.userId`, each leg
153
+ * included ONLY when its key is a non-empty string. With NEITHER key provided we
154
+ * do NOT query and return the empty/clean default.
155
+ *
156
+ * Category maps are merged with explicit FALSE winning: `categories[key] =
157
+ * (categories[key] ?? true) && value` over every row's map — an opt-out recorded
158
+ * on any row blocks, matching the conservative aggregation above. (In the common
159
+ * single-row case this is identical to reading the row's map directly.)
160
+ */
161
+ export async function readRecipientPreferences(
162
+ db: Database,
163
+ keys: { email?: string | null; userId?: string | null },
164
+ ): Promise<RecipientPreferences> {
165
+ // Build the OR legs conditionally — an empty/absent key contributes NO leg, so
166
+ // a `{ email }`-only read never matches every `user_id = ''` row and vice versa.
167
+ const legs = [];
168
+ if (typeof keys.email === "string" && keys.email.length > 0) {
169
+ legs.push(eq(emailPreferences.email, keys.email));
170
+ }
171
+ if (typeof keys.userId === "string" && keys.userId.length > 0) {
172
+ legs.push(eq(emailPreferences.userId, keys.userId));
173
+ }
174
+
175
+ // Neither key: do NOT query — a bare `.where()`/`or()` with no legs would match
176
+ // the whole table. Return the clean default instead.
177
+ if (legs.length === 0) {
178
+ return { unsubscribedAll: false, suppressed: false, categories: {} };
179
+ }
180
+
181
+ const rows = await db
182
+ .select()
183
+ .from(emailPreferences)
184
+ .where(or(...legs));
185
+
186
+ // Merge category maps across rows with explicit FALSE winning (see JSDoc). This
187
+ // always runs — an absent/empty map contributes nothing, so the result is `{}`.
188
+ const categories: Record<string, boolean> = {};
189
+ for (const prefs of rows) {
190
+ const map = (prefs.categories ?? {}) as Record<string, boolean>;
191
+ for (const [key, value] of Object.entries(map)) {
192
+ categories[key] = (categories[key] ?? true) && value;
193
+ }
194
+ }
195
+
196
+ return {
197
+ unsubscribedAll: rows.some((r) => r.unsubscribedAll),
198
+ suppressed: rows.some((r) => r.suppressed),
199
+ categories,
200
+ };
201
+ }
202
+
124
203
  /**
125
204
  * D3 list-membership write. Resolves the caller's identity to the deterministic
126
205
  * `(externalId | contactId fallback, email)` pair via `resolveRecipient`, then
@@ -1,6 +1,6 @@
1
1
  import type { EmailProvider } from "@hogsend/core";
2
2
  import type { Database } from "@hogsend/db";
3
- import { emailPreferences, emailSends } from "@hogsend/db";
3
+ import { emailSends } from "@hogsend/db";
4
4
  import type {
5
5
  EmailSuppressionError,
6
6
  RetryOptions,
@@ -30,8 +30,10 @@ import {
30
30
  } from "./email-service-types.js";
31
31
  import { isFrequencyCapped } from "./frequency-cap.js";
32
32
  import { hatchet } from "./hatchet.js";
33
+ import { checkJourneySuppress } from "./journey-suppress.js";
33
34
  import { createLogger, type Logger } from "./logger.js";
34
35
  import { emitOutbound } from "./outbound.js";
36
+ import { readRecipientPreferences } from "./preferences.js";
35
37
  import {
36
38
  buildRedirect,
37
39
  isUnaddressable,
@@ -257,6 +259,38 @@ async function sendTrackedEmailInner<K extends TemplateName>(
257
259
  });
258
260
  }
259
261
  }
262
+
263
+ // Journey suppress (`meta.suppress`) — a per-recipient min-gap flooding
264
+ // guard, enforced ONLY for journey-bound sends (a JourneyBoundary is
265
+ // present) whose journey sets suppress > 0. Slotted ADJACENT to the
266
+ // frequency cap so the skip mirrors it exactly: on a hit there is no
267
+ // provider call, no `email_sends` row, and no throw — the journey run
268
+ // continues. It MUST run AFTER the idempotency short-circuit above: a replay
269
+ // of an already-dispatched send has to return that dup (from its prior
270
+ // `sent` row) BEFORE any suppress evaluation, or the second drive would
271
+ // wrongly re-evaluate suppression for a send that already went out. The
272
+ // verdict itself is RECORDED set-once (see checkJourneySuppress) so it is
273
+ // replay-stable. Non-journey sends (no boundary: transactional API /
274
+ // password-reset flows) are inert here.
275
+ const boundary = getJourneyBoundary();
276
+ const suppress = await checkJourneySuppress({
277
+ db,
278
+ boundary,
279
+ to: options.to,
280
+ idempotencyKey: options.idempotencyKey,
281
+ });
282
+ if (suppress.suppressed) {
283
+ logger?.info("send skipped: journey_suppressed", {
284
+ to: options.to,
285
+ journeyId: boundary?.journeyId,
286
+ });
287
+ return trackedSendResult({
288
+ emailSendId: "",
289
+ messageId: "",
290
+ status: "skipped",
291
+ reason: "journey_suppressed",
292
+ });
293
+ }
260
294
  }
261
295
 
262
296
  // Unsubscribe surface (RFC 8058 / CAN-SPAM): generate the per-recipient
@@ -553,19 +587,13 @@ async function checkSuppression(
553
587
  email: string,
554
588
  category?: string,
555
589
  ): Promise<SuppressionReason> {
556
- // An address can legitimately have MORE THAN ONE `email_preferences` row:
557
- // the PK is (user_id, email), and a suppression imported before the contact
558
- // existed is keyed (email, email) while later interactive writes key
559
- // (external_id, email). Aggregate across ALL rows — any suppression signal
560
- // on any row blocks the send — so an imported unsubscribe/bounce can never
561
- // be shadowed by a newer clean row for the same address.
562
- const rows = await db
563
- .select()
564
- .from(emailPreferences)
565
- .where(eq(emailPreferences.email, email));
566
-
567
- if (rows.some((prefs) => prefs.suppressed)) return "suppressed";
568
- if (rows.some((prefs) => prefs.unsubscribedAll)) return "unsubscribed";
590
+ // Aggregated across ALL `email_preferences` rows for this address by the shared
591
+ // reader — an address can legitimately have MORE THAN ONE row (multi-row
592
+ // (user_id, email) aggregation rationale lives in readRecipientPreferences).
593
+ const prefs = await readRecipientPreferences(db, { email });
594
+
595
+ if (prefs.suppressed) return "suppressed";
596
+ if (prefs.unsubscribedAll) return "unsubscribed";
569
597
 
570
598
  // Registry-aware polarity (§2.6, D3) — applied through the SINGLE source of
571
599
  // truth `ListRegistry.isSubscribed` so it matches the preference center EXACTLY
@@ -575,21 +603,8 @@ async function checkSuppression(
575
603
  // so absence-of-true (the common "never opted in" case) MUST block — otherwise
576
604
  // a contact the preference center shows as "Unsubscribed" would still receive
577
605
  // the mail (the two surfaces would disagree, which §2.6 forbids).
578
- // Category maps are merged across rows with explicit FALSE winning: an
579
- // opt-out recorded on any row blocks, matching the conservative aggregation
580
- // above. (In the common single-row case this is identical to reading the
581
- // row's map directly.)
582
- if (category) {
583
- const categories: Record<string, boolean> = {};
584
- for (const prefs of rows) {
585
- const map = (prefs.categories ?? {}) as Record<string, boolean>;
586
- for (const [key, value] of Object.entries(map)) {
587
- categories[key] = (categories[key] ?? true) && value;
588
- }
589
- }
590
- if (!getListRegistry().isSubscribed(categories, category)) {
591
- return "category_unsubscribed";
592
- }
606
+ if (category && !getListRegistry().isSubscribed(prefs.categories, category)) {
607
+ return "category_unsubscribed";
593
608
  }
594
609
 
595
610
  return null;
@@ -12,3 +12,11 @@ export const EMAIL_LINK_CLICKED = "email.link_clicked" as const;
12
12
  // raw mint distinctId; the BUS event carries the MANAGED `links.id` as `linkId`
13
13
  // + the RESOLVED survivor contact key (see `pushLinkClickEvent`).
14
14
  export const LINK_CLICKED = "link.clicked" as const;
15
+
16
+ // A visitor CONFIRMED landing from a tracked hit (POST /v1/t/arrive, opt-in
17
+ // `hs_ref`). Subset of `link.clicked`: fires only when the link opts in AND
18
+ // the landing page integrates. Unlike `link.clicked`, it carries the VISITOR's
19
+ // identity (token-verified userId or clamped anon id) — which is what answers
20
+ // "did a known user scan this QR?". Bus + outbound both define `linkId` as the
21
+ // managed `links.id` and carry `trackedLinkId` separately (no legacy split).
22
+ export const LINK_ARRIVED = "link.arrived" as const;
@@ -1,4 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
+ import { RESERVED_EVENT_NAME_RE } from "@hogsend/core";
2
3
  import type { Database } from "@hogsend/db";
3
4
  import { trackedLinks } from "@hogsend/db";
4
5
  import {
@@ -25,11 +26,6 @@ const STRIP_SEMANTIC_ATTRS_RE = new RegExp(
25
26
 
26
27
  const SKIP_PATTERNS = ["/v1/email/unsubscribe", "/v1/email/preferences"];
27
28
 
28
- // Engine-owned event vocabularies (both `email.opened` dot-style and
29
- // `journey:completed` colon-style exist) — a consumer semantic event in these
30
- // namespaces would corrupt insights or trigger engine-internal logic.
31
- const RESERVED_EVENT_NAME_RE = /^(?:email|journey|bucket|contact)[.:]/;
32
-
33
29
  // Semantic payloads re-emit on every answer and persist indefinitely — keep
34
30
  // them small and scalar (non-scalars don't survive the Hatchet wire anyway).
35
31
  const MAX_PROPS_JSON_LENGTH = 2048;
@@ -25,7 +25,7 @@ import { Webhook } from "svix";
25
25
  */
26
26
 
27
27
  /**
28
- * The 15-event catalog — the SINGLE source of truth (schema, routes, client,
28
+ * The 16-event catalog — the SINGLE source of truth (schema, routes, client,
29
29
  * CLI all derive from this). The `webhook.test` sentinel is intentionally NOT a
30
30
  * member (it is delivered out-of-band regardless of an endpoint's `eventTypes`).
31
31
  *
@@ -33,6 +33,10 @@ import { Webhook } from "svix";
33
33
  * has no email send (Discord/referral/ad-hoc `createTrackedLink`). It is the
34
34
  * deliberate counterpart to `email.clicked` so a non-email click never fires a
35
35
  * malformed `email.clicked` (MF-missing #3).
36
+ *
37
+ * `link.arrived` is the landing-confirmed subset of `link.clicked`: the
38
+ * visitor reported back from the destination (opt-in `hs_ref` +
39
+ * POST /v1/t/arrive) with identity evidence.
36
40
  */
37
41
  export const WEBHOOK_EVENT_TYPES = [
38
42
  "contact.created",
@@ -50,6 +54,7 @@ export const WEBHOOK_EVENT_TYPES = [
50
54
  "bucket.entered",
51
55
  "bucket.left",
52
56
  "link.clicked",
57
+ "link.arrived",
53
58
  ] as const;
54
59
 
55
60
  export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
@@ -0,0 +1,75 @@
1
+ /**
2
+ * Channel lists — engine-synthesized delivery channels layered on the SAME
3
+ * `email_preferences.categories` JSONB namespace as author-defined lists (D3).
4
+ * A channel is an auto-registered opt-out list: `in_app` (the notification
5
+ * feed) plus one per connector that exposes member-directed actions (discord,
6
+ * telegram). There is no new table and no authoring surface — channels are
7
+ * derived from the registered connector actions at container build time.
8
+ *
9
+ * POLARITY (zero behaviour flip): every channel is `defaultOptIn: true`, so
10
+ * `ListRegistry.isSubscribed(categories, id)` returns `categories[id] !== false`
11
+ * — subscribed unless the recipient explicitly set the category to `false`.
12
+ * That is EXACTLY the unknown-id fallback an UNregistered channel already
13
+ * resolved to (`isSubscribedByDefault` → `?? true`), so registering these lists
14
+ * flips zero existing behaviour; it only makes the channels visible in the
15
+ * catalog and (in a later phase) enforceable in `sendConnectorAction`.
16
+ */
17
+ import type { DefinedConnectorAction } from "../connectors/define-action.js";
18
+ import type { ListMeta } from "./define-list.js";
19
+
20
+ /**
21
+ * Reserved list id for the engine's in-app channel (the notification feed).
22
+ * Always synthesized first by {@link synthesizeChannelLists}; also the
23
+ * suppression key consulted by `sendFeedItem`.
24
+ */
25
+ export const IN_APP_LIST_ID = "in_app";
26
+
27
+ /** Uppercase the first character of a connector id for the channel's display name. */
28
+ function capitalize(id: string): string {
29
+ return id.length === 0 ? id : id.charAt(0).toUpperCase() + id.slice(1);
30
+ }
31
+
32
+ /**
33
+ * Synthesize the engine-owned channel {@link ListMeta}s from the registered
34
+ * connector actions.
35
+ *
36
+ * Always yields the `in_app` channel first. Then one channel per DISTINCT
37
+ * `connectorId` among actions declaring a member audience
38
+ * (`action.audience?.kind === "member"`), de-duplicated via a `Set` in stable
39
+ * first-appearance order. Actions WITHOUT a member audience (ops/channel-
40
+ * directed) never mint a channel. Channel display name = the connector id with
41
+ * its first letter capitalized ("discord" → "Discord").
42
+ *
43
+ * Every channel shares the opt-out polarity shape `{ defaultOptIn: true,
44
+ * enabled: true, kind: "channel" }` — see the module docblock for why this
45
+ * flips no existing behaviour.
46
+ */
47
+ export function synthesizeChannelLists(
48
+ actions: DefinedConnectorAction[],
49
+ ): ListMeta[] {
50
+ const channels: ListMeta[] = [
51
+ {
52
+ id: IN_APP_LIST_ID,
53
+ name: "In-app feed",
54
+ defaultOptIn: true,
55
+ enabled: true,
56
+ kind: "channel",
57
+ },
58
+ ];
59
+
60
+ const seen = new Set<string>();
61
+ for (const action of actions) {
62
+ if (action.audience?.kind !== "member") continue;
63
+ if (seen.has(action.connectorId)) continue;
64
+ seen.add(action.connectorId);
65
+ channels.push({
66
+ id: action.connectorId,
67
+ name: capitalize(action.connectorId),
68
+ defaultOptIn: true,
69
+ enabled: true,
70
+ kind: "channel",
71
+ });
72
+ }
73
+
74
+ return channels;
75
+ }