@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.
Files changed (64) hide show
  1. package/package.json +9 -7
  2. package/src/buckets/check-membership.ts +6 -1
  3. package/src/campaigns/cohort-sql.ts +198 -0
  4. package/src/campaigns/define-campaign.ts +301 -0
  5. package/src/campaigns/reconcile.ts +391 -0
  6. package/src/campaigns/steps.ts +48 -0
  7. package/src/connectors/define-action.ts +70 -0
  8. package/src/container.ts +144 -42
  9. package/src/destinations/presets/posthog.ts +7 -1
  10. package/src/env.ts +14 -0
  11. package/src/index.ts +98 -3
  12. package/src/journeys/constants.ts +10 -0
  13. package/src/journeys/define-journey.ts +14 -405
  14. package/src/journeys/execute-journey-run.ts +608 -0
  15. package/src/journeys/graph/build-graph.ts +212 -56
  16. package/src/journeys/journey-boundary.ts +54 -0
  17. package/src/journeys/journey-context.ts +374 -59
  18. package/src/journeys/record-once.ts +110 -0
  19. package/src/lib/auth.ts +33 -1
  20. package/src/lib/blueprints.ts +576 -0
  21. package/src/lib/campaign-send-key.ts +58 -0
  22. package/src/lib/connector-actions.ts +203 -19
  23. package/src/lib/contacts.ts +54 -0
  24. package/src/lib/email-service-types.ts +4 -1
  25. package/src/lib/email.ts +13 -2
  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/webhook-signing.ts +6 -1
  38. package/src/lists/channels.ts +75 -0
  39. package/src/lists/define-list.ts +34 -0
  40. package/src/lists/registry.ts +29 -2
  41. package/src/mcp/blueprint-tools.ts +460 -0
  42. package/src/routes/admin/blueprints.ts +711 -0
  43. package/src/routes/admin/campaigns.ts +341 -0
  44. package/src/routes/admin/emails.ts +13 -0
  45. package/src/routes/admin/index.ts +6 -0
  46. package/src/routes/admin/journeys.ts +4 -2
  47. package/src/routes/admin/links.ts +303 -36
  48. package/src/routes/admin/lists.ts +51 -0
  49. package/src/routes/campaigns/index.ts +297 -50
  50. package/src/routes/email/preferences.ts +50 -13
  51. package/src/routes/feed/recipient.ts +2 -43
  52. package/src/routes/index.ts +6 -0
  53. package/src/routes/lists/index.ts +138 -18
  54. package/src/routes/tracking/arrive.ts +260 -0
  55. package/src/routes/tracking/click-pipeline.ts +329 -0
  56. package/src/routes/tracking/click.ts +5 -270
  57. package/src/routes/tracking/index.ts +2 -0
  58. package/src/routes/tracking/vanity.ts +64 -0
  59. package/src/worker.ts +27 -0
  60. package/src/workflows/bucket-backfill.ts +4 -2
  61. package/src/workflows/bucket-reconcile.ts +11 -4
  62. package/src/workflows/check-alerts.ts +130 -1
  63. package/src/workflows/journey-blueprint-interpreter.ts +561 -0
  64. package/src/workflows/send-campaign.ts +673 -127
package/src/lib/html.ts CHANGED
@@ -12,6 +12,7 @@ export function htmlPage(opts: { title: string; body: string }): string {
12
12
  p { color: #555; line-height: 1.6; }
13
13
  a { color: #2563eb; text-decoration: none; }
14
14
  a:hover { text-decoration: underline; }
15
+ .pref-section { font-size: 0.75rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.06em; color: #6b7280; margin: 28px 0 4px; }
15
16
  .pref-row { display: flex; justify-content: space-between; align-items: center; padding: 12px 0; border-bottom: 1px solid #e5e7eb; }
16
17
  .pref-label { font-weight: 500; }
17
18
  .pref-status { font-size: 0.875rem; }
@@ -2,12 +2,20 @@ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
2
  import type {
3
3
  AnalyticsEventMirrorConfig,
4
4
  AnalyticsProvider,
5
+ PropertyCondition,
5
6
  } from "@hogsend/core";
6
7
  import { evaluatePropertyConditions } from "@hogsend/core";
7
8
  import type { JourneyRegistry } from "@hogsend/core/registry";
8
- import { type Database, journeyStates, userEvents } from "@hogsend/db";
9
+ import type { JourneyMeta } from "@hogsend/core/types";
10
+ import {
11
+ type Database,
12
+ journeyBlueprints,
13
+ journeyStates,
14
+ userEvents,
15
+ } from "@hogsend/db";
9
16
  import { and, eq, inArray, isNull } from "drizzle-orm";
10
17
  import { checkBucketMembership } from "../buckets/check-membership.js";
18
+ import { BLUEPRINT_RUN_EVENT } from "../journeys/constants.js";
11
19
  import { logTransition } from "../journeys/journey-log.js";
12
20
  import {
13
21
  logResidualTwins,
@@ -157,6 +165,80 @@ function shouldMirrorEvent(
157
165
  return true;
158
166
  }
159
167
 
168
+ /**
169
+ * Blueprint dispatch (spec §5) — the DB-lookup counterpart of the static
170
+ * `onEvents` registration code journeys get at boot. Code journeys can't gain
171
+ * a trigger without a worker redeploy; a blueprint row created at 3pm must
172
+ * fire at 3:01. So on every ingested event this queries the enabled
173
+ * `journey_blueprints` whose `triggerEvent` matches (served by the
174
+ * `(trigger_event, status)` index), applies `triggerWhere` with the SAME
175
+ * `evaluatePropertyConditions` the interpreter's enrollment guard re-checks
176
+ * with (dispatch and guard must agree, and both see the serializable-scalar
177
+ * payload), and pushes one `blueprint:run` per match to the single
178
+ * statically-registered `journey-blueprint-interpreter` task.
179
+ *
180
+ * Returns the number of dispatched enrollment attempts.
181
+ */
182
+ export async function checkBlueprintTriggers(opts: {
183
+ db: Database;
184
+ hatchet: HatchetClient;
185
+ logger: Logger;
186
+ event: {
187
+ name: string;
188
+ userId: string;
189
+ userEmail: string;
190
+ /** The serializable-scalar subset that will reach the interpreter. */
191
+ properties: Record<string, string | number | boolean | null>;
192
+ };
193
+ }): Promise<number> {
194
+ const { db, hatchet, logger, event } = opts;
195
+
196
+ const candidates = await db
197
+ .select({
198
+ id: journeyBlueprints.id,
199
+ version: journeyBlueprints.version,
200
+ triggerWhere: journeyBlueprints.triggerWhere,
201
+ })
202
+ .from(journeyBlueprints)
203
+ .where(
204
+ and(
205
+ eq(journeyBlueprints.triggerEvent, event.name),
206
+ eq(journeyBlueprints.status, "enabled"),
207
+ ),
208
+ );
209
+
210
+ let dispatched = 0;
211
+ for (const bp of candidates) {
212
+ const where = (bp.triggerWhere ?? []) as unknown as PropertyCondition[];
213
+ if (
214
+ where.length > 0 &&
215
+ !evaluatePropertyConditions({
216
+ conditions: where,
217
+ properties: event.properties,
218
+ })
219
+ ) {
220
+ continue;
221
+ }
222
+ await hatchet.events.push(BLUEPRINT_RUN_EVENT, {
223
+ blueprintId: bp.id,
224
+ blueprintVersion: bp.version,
225
+ userId: event.userId,
226
+ userEmail: event.userEmail,
227
+ triggerProperties: event.properties,
228
+ });
229
+ dispatched += 1;
230
+ }
231
+
232
+ if (dispatched > 0) {
233
+ logger.info("Blueprint runs dispatched", {
234
+ event: event.name,
235
+ userId: event.userId,
236
+ dispatched,
237
+ });
238
+ }
239
+ return dispatched;
240
+ }
241
+
160
242
  export async function ingestEvent(opts: {
161
243
  db: Database;
162
244
  registry: JourneyRegistry;
@@ -402,6 +484,34 @@ export async function ingestEvent(opts: {
402
484
  }
403
485
  const exits = exitsResult.value;
404
486
 
487
+ // (5b) Blueprint dispatch (spec §5) — the DB-driven twin of the Hatchet
488
+ // push in (4): one `blueprint:run` per enabled matching blueprint. Runs
489
+ // AFTER the main push settled, so a dispatched blueprint never observes an
490
+ // event code journeys were not notified of. Best-effort by design: the
491
+ // event row + code-journey push are already committed, so throwing here
492
+ // could not be retried into a redelivery (the idempotency claim survives) —
493
+ // it would only fail the caller for work that half-happened. Mirrors the
494
+ // bucket-membership stance below.
495
+ try {
496
+ await checkBlueprintTriggers({
497
+ db,
498
+ hatchet,
499
+ logger,
500
+ event: {
501
+ name: event.event,
502
+ userId: resolvedKey,
503
+ userEmail: event.userEmail ?? "",
504
+ properties: serializableProperties,
505
+ },
506
+ });
507
+ } catch (err) {
508
+ logger.warn("Blueprint trigger dispatch failed", {
509
+ event: event.event,
510
+ userId: resolvedKey,
511
+ error: err instanceof Error ? err.message : String(err),
512
+ });
513
+ }
514
+
405
515
  // (6) Real-time bucket membership re-evaluation (Section 6.1). NOT part of the
406
516
  // Promise.all above: its property eval reads contact state ⊕ this-ingest
407
517
  // contactProperties patch, and its bucket:entered/left emissions recurse back
@@ -458,14 +568,45 @@ async function checkExits(
458
568
  ),
459
569
  });
460
570
 
571
+ // Blueprint enrollments share journeyStates but are NOT in the code-journey
572
+ // registry — their exitOn lives on the journey_blueprints row (spec §4).
573
+ // Resolve exitOn for any active state whose journeyId the registry doesn't
574
+ // know, in one batched read. Deliberately status-agnostic: disabling a
575
+ // blueprint stops NEW enrollments, but an in-flight run keeps honoring its
576
+ // exit rules (spec §10/§12).
577
+ const unregisteredIds = [
578
+ ...new Set(
579
+ activeStates
580
+ .map((state) => state.journeyId)
581
+ .filter((journeyId) => !registry.get(journeyId)),
582
+ ),
583
+ ];
584
+ const blueprintExitOn = new Map<string, NonNullable<JourneyMeta["exitOn"]>>();
585
+ if (unregisteredIds.length > 0) {
586
+ const rows = await db
587
+ .select({ id: journeyBlueprints.id, exitOn: journeyBlueprints.exitOn })
588
+ .from(journeyBlueprints)
589
+ .where(inArray(journeyBlueprints.id, unregisteredIds));
590
+ for (const row of rows) {
591
+ if (row.exitOn?.length) {
592
+ blueprintExitOn.set(
593
+ row.id,
594
+ row.exitOn as NonNullable<JourneyMeta["exitOn"]>,
595
+ );
596
+ }
597
+ }
598
+ }
599
+
461
600
  const statesToExit: string[] = [];
462
601
  const runIdsToCancel: string[] = [];
463
602
 
464
603
  for (const state of activeStates) {
465
- const journey = registry.get(state.journeyId);
466
- if (!journey?.exitOn) continue;
604
+ const exitOn =
605
+ registry.get(state.journeyId)?.exitOn ??
606
+ blueprintExitOn.get(state.journeyId);
607
+ if (!exitOn) continue;
467
608
 
468
- const shouldExit = journey.exitOn.some((exitCondition) => {
609
+ const shouldExit = exitOn.some((exitCondition) => {
469
610
  if (exitCondition.event !== event.eventName) return false;
470
611
  if (!exitCondition.where?.length) return true;
471
612
  return evaluatePropertyConditions({
@@ -0,0 +1,87 @@
1
+ import type { Database } from "@hogsend/db";
2
+ import { emailSends, journeyStates } from "@hogsend/db";
3
+ import { and, eq, gte, ne } from "drizzle-orm";
4
+ import type { JourneyBoundary } from "../journeys/journey-boundary.js";
5
+ import { recordOnce } from "../journeys/record-once.js";
6
+
7
+ /**
8
+ * True if a non-failed `email_sends` row exists for THIS journey — across ALL
9
+ * of its enrollments — to THIS recipient within the suppress window. The
10
+ * INNER JOIN to `journey_states` on `journey_state_id`, filtered by
11
+ * `journey_id`, is what crosses enrollments: `meta.suppress` is a per-JOURNEY
12
+ * min-gap, not per-enrollment, so a re-enrollment inside the window is still
13
+ * gapped. Failed rows (`status = 'failed'`, never dispatched) are excluded,
14
+ * mirroring {@link countRecentSends}. EXISTS semantics only — `limit(1)`, no
15
+ * count needed.
16
+ */
17
+ export async function hasRecentJourneySend(opts: {
18
+ db: Database;
19
+ journeyId: string;
20
+ to: string;
21
+ since: Date;
22
+ }): Promise<boolean> {
23
+ const rows = await opts.db
24
+ .select({ id: emailSends.id })
25
+ .from(emailSends)
26
+ .innerJoin(journeyStates, eq(emailSends.journeyStateId, journeyStates.id))
27
+ .where(
28
+ and(
29
+ eq(journeyStates.journeyId, opts.journeyId),
30
+ eq(emailSends.toEmail, opts.to),
31
+ gte(emailSends.createdAt, opts.since),
32
+ ne(emailSends.status, "failed"),
33
+ ),
34
+ )
35
+ .limit(1);
36
+ return rows.length > 0;
37
+ }
38
+
39
+ /**
40
+ * The RECORDED-once journey-suppress verdict for a boundary send. Returns
41
+ * `{ suppressed }` — `true` means the tracked mailer must skip the send
42
+ * (`journey_suppressed`, no provider call, no `email_sends` row).
43
+ *
44
+ * REPLAY STABILITY (non-negotiable): the live EXISTS check diverges on replay —
45
+ * the run's OWN send lands in the window, so an originally-ALLOWED send would
46
+ * re-check as suppressed (a late duplicate), and an originally-SUPPRESSED send
47
+ * could re-check as allowed if the blocking row was purged. So the verdict is
48
+ * frozen set-once under `context.__throttle__` keyed by the send's resolved
49
+ * idempotency key (already per-run-unique via `registerKey`, so it needs no
50
+ * extra registration) and replayed verbatim thereafter — durable on ANY engine.
51
+ *
52
+ * The guard is INERT (returns `{ suppressed: false }` without touching the DB)
53
+ * when there is no boundary, no `journeyId`, a zero `suppressMs`, or no resolved
54
+ * idempotency key — i.e. every non-journey / transactional send is unaffected.
55
+ */
56
+ export async function checkJourneySuppress(opts: {
57
+ db: Database;
58
+ boundary: JourneyBoundary | undefined;
59
+ to: string;
60
+ idempotencyKey: string | undefined;
61
+ /** Injectable clock for tests; defaults to the live wall clock. */
62
+ now?: number;
63
+ }): Promise<{ suppressed: boolean }> {
64
+ const { db, boundary, to, idempotencyKey } = opts;
65
+ if (
66
+ !boundary?.journeyId ||
67
+ !boundary.suppressMs ||
68
+ boundary.suppressMs <= 0 ||
69
+ !idempotencyKey
70
+ ) {
71
+ return { suppressed: false };
72
+ }
73
+
74
+ const { journeyId, suppressMs, stateId } = boundary;
75
+ return recordOnce<{ suppressed: boolean }>({
76
+ db,
77
+ stateId,
78
+ namespace: "__throttle__",
79
+ key: `suppress:${idempotencyKey}`,
80
+ compute: async () => {
81
+ const since = new Date((opts.now ?? Date.now()) - suppressMs);
82
+ return {
83
+ suppressed: await hasRecentJourneySend({ db, journeyId, to, since }),
84
+ };
85
+ },
86
+ });
87
+ }
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