@hogsend/engine 0.40.0 → 0.41.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/package.json +9 -7
  2. package/src/buckets/check-membership.ts +6 -1
  3. package/src/campaigns/cohort-sql.ts +198 -0
  4. package/src/campaigns/define-campaign.ts +207 -28
  5. package/src/campaigns/reconcile.ts +105 -11
  6. package/src/campaigns/steps.ts +48 -0
  7. package/src/connectors/define-action.ts +70 -0
  8. package/src/container.ts +124 -42
  9. package/src/destinations/presets/posthog.ts +7 -1
  10. package/src/index.ts +82 -2
  11. package/src/journeys/constants.ts +10 -0
  12. package/src/journeys/define-journey.ts +14 -405
  13. package/src/journeys/execute-journey-run.ts +608 -0
  14. package/src/journeys/graph/build-graph.ts +212 -56
  15. package/src/journeys/journey-boundary.ts +54 -0
  16. package/src/journeys/journey-context.ts +374 -59
  17. package/src/journeys/record-once.ts +110 -0
  18. package/src/lib/blueprints.ts +576 -0
  19. package/src/lib/campaign-send-key.ts +58 -0
  20. package/src/lib/connector-actions.ts +203 -19
  21. package/src/lib/contacts.ts +54 -0
  22. package/src/lib/email-service-types.ts +4 -1
  23. package/src/lib/email.ts +13 -2
  24. package/src/lib/feed.ts +77 -57
  25. package/src/lib/frequency-cap.ts +45 -15
  26. package/src/lib/hatchet-duration.ts +22 -0
  27. package/src/lib/html.ts +1 -0
  28. package/src/lib/ingestion.ts +145 -4
  29. package/src/lib/journey-suppress.ts +87 -0
  30. package/src/lib/links.ts +204 -18
  31. package/src/lib/outbound.ts +20 -0
  32. package/src/lib/preferences.ts +80 -1
  33. package/src/lib/tracked.ts +44 -29
  34. package/src/lib/tracking-event-names.ts +8 -0
  35. package/src/lib/webhook-signing.ts +6 -1
  36. package/src/lists/channels.ts +75 -0
  37. package/src/lists/define-list.ts +34 -0
  38. package/src/lists/registry.ts +29 -2
  39. package/src/mcp/blueprint-tools.ts +460 -0
  40. package/src/routes/admin/blueprints.ts +711 -0
  41. package/src/routes/admin/campaigns.ts +179 -3
  42. package/src/routes/admin/emails.ts +13 -0
  43. package/src/routes/admin/index.ts +4 -0
  44. package/src/routes/admin/journeys.ts +4 -2
  45. package/src/routes/admin/links.ts +303 -36
  46. package/src/routes/admin/lists.ts +51 -0
  47. package/src/routes/campaigns/index.ts +44 -6
  48. package/src/routes/email/preferences.ts +50 -13
  49. package/src/routes/feed/recipient.ts +2 -43
  50. package/src/routes/index.ts +6 -0
  51. package/src/routes/lists/index.ts +138 -18
  52. package/src/routes/tracking/arrive.ts +260 -0
  53. package/src/routes/tracking/click-pipeline.ts +329 -0
  54. package/src/routes/tracking/click.ts +5 -270
  55. package/src/routes/tracking/index.ts +2 -0
  56. package/src/routes/tracking/vanity.ts +64 -0
  57. package/src/worker.ts +5 -0
  58. package/src/workflows/bucket-backfill.ts +4 -2
  59. package/src/workflows/bucket-reconcile.ts +11 -4
  60. package/src/workflows/check-alerts.ts +130 -1
  61. package/src/workflows/journey-blueprint-interpreter.ts +561 -0
  62. package/src/workflows/send-campaign.ts +574 -180
@@ -1,8 +1,29 @@
1
1
  import { linkClicks, links, trackedLinks } from "@hogsend/db";
2
2
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
- import { and, count, desc, eq, inArray, isNull, sql, sum } from "drizzle-orm";
3
+ import {
4
+ and,
5
+ count,
6
+ desc,
7
+ eq,
8
+ exists,
9
+ inArray,
10
+ isNull,
11
+ sql,
12
+ sum,
13
+ } from "drizzle-orm";
14
+ import QRCode from "qrcode";
4
15
  import type { AppEnv } from "../../app.js";
5
- import { assertHttpUrl, mintLink } from "../../lib/links.js";
16
+ import {
17
+ assertHttpUrl,
18
+ canonicalTrackedRowFilter,
19
+ ensureQrTrackedLink,
20
+ isSlugUniqueViolation,
21
+ mintLink,
22
+ normalizeSlug,
23
+ QR_TRACKED_SOURCE,
24
+ SlugTakenError,
25
+ vanityUrlFor,
26
+ } from "../../lib/links.js";
6
27
  import { errorSchema } from "../../lib/schemas.js";
7
28
 
8
29
  // ---------------------------------------------------------------------------
@@ -46,13 +67,24 @@ const linkSchema = z.object({
46
67
  trackedLinkId: z.string().nullable(),
47
68
  originalUrl: z.string(),
48
69
  type: z.enum(["personal", "public"]),
70
+ // Vanity slug (normalized lowercase, unique per instance) + its short URL
71
+ // (`${API_PUBLIC_URL}/l/:slug`). Both null when no slug is set.
72
+ slug: z.string().nullable(),
73
+ vanityUrl: z.string().nullable(),
49
74
  label: z.string().nullable(),
75
+ // Longer operator note for bulk identification ("sticker on the door").
76
+ description: z.string().nullable(),
77
+ // Arrival attribution opt-in: redirects append `hs_ref=<click id>`.
78
+ appendRef: z.boolean(),
50
79
  campaign: z.string().nullable(),
51
80
  source: z.string(),
52
81
  distinctId: z.string().nullable(),
53
82
  createdBy: z.string().nullable(),
54
- // Computed on read (summed across the link's tracked_links rows).
83
+ // Computed on read (summed across the link's tracked_links rows). The total
84
+ // across ALL entry paths — vanity, UUID, and QR scans.
55
85
  clickCount: z.number(),
86
+ // The QR-only subtotal (clicks recorded on the link's `source: "qr"` row).
87
+ scanCount: z.number(),
56
88
  // The short redirect URL: `${API_PUBLIC_URL}/v1/t/c/:trackedLinkId`.
57
89
  url: z.string(),
58
90
  archivedAt: z.string().nullable(),
@@ -66,14 +98,41 @@ const clickSchema = z.object({
66
98
  ipAddress: z.string().nullable(),
67
99
  userAgent: z.string().nullable(),
68
100
  clickedAt: z.string(),
101
+ // Arrival stamp (POST /v1/t/arrive): who landed from THIS hit.
102
+ // `visitorKind` is the trust tier — 'token' = verified userId ("known
103
+ // contact"), 'anon' = the visitor's raw anon id (provenance only).
104
+ visitorDistinctId: z.string().nullable(),
105
+ visitorKind: z.string().nullable(),
106
+ arrivedAt: z.string().nullable(),
107
+ });
108
+
109
+ // Per-destination stats bucket: hits grouped by the destination that was live
110
+ // when they landed (link_clicks.destination_url). `url: null` = hits recorded
111
+ // before provenance stamping existed. `clicks` is the all-paths total for the
112
+ // bucket; `scans` its QR subtotal — mirroring clickCount/scanCount semantics.
113
+ const destinationStatSchema = z.object({
114
+ url: z.string().nullable(),
115
+ clicks: z.number(),
116
+ scans: z.number(),
117
+ firstAt: z.string(),
118
+ lastAt: z.string(),
69
119
  });
70
120
 
71
121
  const linkDetailSchema = linkSchema.extend({
72
122
  clicks: z.array(clickSchema),
123
+ destinations: z.array(destinationStatSchema),
124
+ // Landing-confirmed arrivals (stamped hits). `identifiedArrivalCount` is
125
+ // the token-verified subset — "how many KNOWN contacts arrived".
126
+ arrivalCount: z.number(),
127
+ identifiedArrivalCount: z.number(),
73
128
  });
74
129
 
75
130
  type LinkRow = typeof links.$inferSelect;
76
- type ClickAgg = { clicks: number; trackedLinkId: string | null };
131
+ type ClickAgg = {
132
+ clicks: number;
133
+ scans: number;
134
+ trackedLinkId: string | null;
135
+ };
77
136
 
78
137
  // The short redirect URL for a link's tracked row, or a bare prefix if the link
79
138
  // has no tracked row (should not happen for a minted link, but keep it total).
@@ -93,12 +152,17 @@ function serializeLink(
93
152
  originalUrl: row.originalUrl,
94
153
  // The column is a free text; mintLink only ever writes these two values.
95
154
  type: row.type === "personal" ? "personal" : "public",
155
+ slug: row.slug,
156
+ vanityUrl: row.slug ? vanityUrlFor(baseUrl, row.slug) : null,
96
157
  label: row.label,
158
+ description: row.description,
159
+ appendRef: row.appendRef,
97
160
  campaign: row.campaign,
98
161
  source: row.source,
99
162
  distinctId: row.distinctId,
100
163
  createdBy: row.createdBy,
101
164
  clickCount: agg?.clicks ?? 0,
165
+ scanCount: agg?.scans ?? 0,
102
166
  url: shortUrlFor(baseUrl, trackedLinkId),
103
167
  archivedAt: row.archivedAt ? row.archivedAt.toISOString() : null,
104
168
  createdAt: row.createdAt.toISOString(),
@@ -122,7 +186,12 @@ const createLinkRoute = createRoute({
122
186
  schema: z.object({
123
187
  url: z.string().url(),
124
188
  type: z.enum(["personal", "public"]).default("public"),
189
+ // Optional vanity slug (`/l/:slug`). Normalized lowercase; 409 if
190
+ // already taken.
191
+ slug: z.string().optional(),
125
192
  label: z.string().optional(),
193
+ description: z.string().optional(),
194
+ appendRef: z.boolean().optional(),
126
195
  campaign: z.string().optional(),
127
196
  // Honoured ONLY for personal links (the share-safe invariant in
128
197
  // mintLink drops it for public). A canonical contact key the click
@@ -140,7 +209,11 @@ const createLinkRoute = createRoute({
140
209
  },
141
210
  400: {
142
211
  content: { "application/json": { schema: errorSchema } },
143
- description: "Invalid destination URL",
212
+ description: "Invalid destination URL or slug",
213
+ },
214
+ 409: {
215
+ content: { "application/json": { schema: errorSchema } },
216
+ description: "Slug already taken",
144
217
  },
145
218
  },
146
219
  });
@@ -156,6 +229,11 @@ const listLinksRoute = createRoute({
156
229
  offset: z.coerce.number().min(0).default(0),
157
230
  type: z.enum(["personal", "public"]).optional(),
158
231
  includeArchived: z.coerce.boolean().default(false),
232
+ // true = only links whose QR scan row exists — the "QR codes" lens
233
+ // (a QR code IS a managed link whose QR row has been minted).
234
+ // stringbool, NOT coerce.boolean: coerce turns the string "false" into
235
+ // true (any non-empty string is truthy), inverting ?hasQr=false.
236
+ hasQr: z.stringbool().optional(),
159
237
  }),
160
238
  },
161
239
  responses: {
@@ -207,7 +285,12 @@ const updateLinkRoute = createRoute({
207
285
  // NOT NULL on both tables — omit = no change, provide = re-target
208
286
  // both links.originalUrl and the linked tracked_links row.
209
287
  originalUrl: z.string().url().optional(),
288
+ // omit = no change; string = set/replace (409 if taken); null =
289
+ // clear the slug (frees it for reuse).
290
+ slug: z.string().nullable().optional(),
210
291
  label: z.string().nullable().optional(),
292
+ description: z.string().nullable().optional(),
293
+ appendRef: z.boolean().optional(),
211
294
  campaign: z.string().nullable().optional(),
212
295
  }),
213
296
  },
@@ -221,12 +304,44 @@ const updateLinkRoute = createRoute({
221
304
  },
222
305
  400: {
223
306
  content: { "application/json": { schema: errorSchema } },
224
- description: "Invalid destination URL",
307
+ description: "Invalid destination URL or slug",
225
308
  },
226
309
  404: {
227
310
  content: { "application/json": { schema: errorSchema } },
228
311
  description: "Link not found",
229
312
  },
313
+ 409: {
314
+ content: { "application/json": { schema: errorSchema } },
315
+ description: "Slug already taken",
316
+ },
317
+ },
318
+ });
319
+
320
+ const qrLinkRoute = createRoute({
321
+ method: "get",
322
+ path: "/{id}/qr",
323
+ tags: ["Admin — Links"],
324
+ summary: "Render a link's QR code (lazy-mints its scan row)",
325
+ request: {
326
+ params: z.object({ id: z.string().uuid() }),
327
+ query: z.object({
328
+ format: z.enum(["svg", "png"]).default("svg"),
329
+ // Rendered pixel width. QR content is size-independent (same encoded
330
+ // URL), so this only affects raster/viewport dimensions.
331
+ size: z.coerce.number().min(64).max(2048).default(512),
332
+ // Transparent background (both formats) — for print/overlay use where
333
+ // the artwork supplies its own background. stringbool, NOT
334
+ // coerce.boolean: coerce would turn ?transparent=false into true and
335
+ // ship an invisible-on-white QR.
336
+ transparent: z.stringbool().default(false),
337
+ }),
338
+ },
339
+ responses: {
340
+ 200: { description: "QR image (SVG or PNG) encoding the scan URL" },
341
+ 404: {
342
+ content: { "application/json": { schema: errorSchema } },
343
+ description: "Link not found",
344
+ },
230
345
  },
231
346
  });
232
347
 
@@ -252,9 +367,10 @@ type Db = AppEnv["Variables"]["container"]["db"];
252
367
 
253
368
  // Aggregates each link's tracked_links rows in ONE grouped query: the summed
254
369
  // click_count (computed on read — no denormalized counter on `links`) and the
255
- // link's redirect id (a managed link has exactly one tracked row, minted
256
- // alongside it). Returns a map keyed by link id; links with no tracked rows are
257
- // simply absent (callers default to 0 / a bare prefix).
370
+ // link's redirect id — the CANONICAL tracked row (minted alongside the link),
371
+ // never the per-link QR scan row, via the shared canonical-row predicate.
372
+ // Returns a map keyed by link id; links with no tracked rows are simply absent
373
+ // (callers default to 0 / a bare prefix).
258
374
  async function aggregateFor(
259
375
  db: Db,
260
376
  linkIds: string[],
@@ -267,7 +383,12 @@ async function aggregateFor(
267
383
  clicks: sql<number>`coalesce(${sum(trackedLinks.clickCount)}, 0)`.mapWith(
268
384
  Number,
269
385
  ),
270
- trackedLinkId: sql<string>`min(${trackedLinks.id}::text)`,
386
+ // QR-only subtotal — the complement of the canonical-row predicate.
387
+ scans:
388
+ sql<number>`coalesce(${sum(trackedLinks.clickCount)} filter (where not (${canonicalTrackedRowFilter()})), 0)`.mapWith(
389
+ Number,
390
+ ),
391
+ trackedLinkId: sql<string>`min(${trackedLinks.id}::text) filter (where ${canonicalTrackedRowFilter()})`,
271
392
  })
272
393
  .from(trackedLinks)
273
394
  .where(inArray(trackedLinks.linkId, linkIds))
@@ -276,6 +397,7 @@ async function aggregateFor(
276
397
  if (r.linkId) {
277
398
  map.set(r.linkId, {
278
399
  clicks: r.clicks,
400
+ scans: r.scans,
279
401
  trackedLinkId: r.trackedLinkId ?? null,
280
402
  });
281
403
  }
@@ -295,7 +417,10 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
295
417
  baseUrl: env.API_PUBLIC_URL,
296
418
  source: "studio",
297
419
  type: body.type,
420
+ slug: body.slug,
298
421
  label: body.label,
422
+ description: body.description,
423
+ appendRef: body.appendRef,
299
424
  campaign: body.campaign,
300
425
  distinctId: body.distinctId,
301
426
  createdBy: resolveActor(c) ?? undefined,
@@ -314,23 +439,42 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
314
439
  return c.json(
315
440
  serializeLink(
316
441
  row,
317
- { clicks: 0, trackedLinkId: minted.trackedLinkId },
442
+ { clicks: 0, scans: 0, trackedLinkId: minted.trackedLinkId },
318
443
  env.API_PUBLIC_URL,
319
444
  ),
320
445
  200,
321
446
  );
322
447
  } catch (err) {
448
+ if (err instanceof SlugTakenError) {
449
+ return c.json({ error: err.message }, 409);
450
+ }
323
451
  const message = err instanceof Error ? err.message : "Mint failed";
324
452
  return c.json({ error: message }, 400);
325
453
  }
326
454
  })
327
455
  .openapi(listLinksRoute, async (c) => {
328
456
  const { db, env } = c.get("container");
329
- const { limit, offset, type, includeArchived } = c.req.valid("query");
457
+ const { limit, offset, type, includeArchived, hasQr } =
458
+ c.req.valid("query");
330
459
 
331
460
  const where = and(
332
461
  includeArchived ? undefined : isNull(links.archivedAt),
333
462
  type ? eq(links.type, type) : undefined,
463
+ // The QR lens: membership = the QR scan row exists (lazily minted on
464
+ // first QR render), not "has been scanned".
465
+ hasQr
466
+ ? exists(
467
+ db
468
+ .select({ one: sql`1` })
469
+ .from(trackedLinks)
470
+ .where(
471
+ and(
472
+ eq(trackedLinks.linkId, links.id),
473
+ eq(trackedLinks.source, QR_TRACKED_SOURCE),
474
+ ),
475
+ ),
476
+ )
477
+ : undefined,
334
478
  );
335
479
 
336
480
  const [rows, totalRows] = await Promise.all([
@@ -376,8 +520,11 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
376
520
  }
377
521
 
378
522
  // Recent clicks joined via the link's tracked_links rows, newest first,
379
- // capped. The aggregate gives the summed count + the redirect id.
380
- const [agg, clickRows] = await Promise.all([
523
+ // capped. The aggregate gives the summed count + the redirect id. The
524
+ // destination buckets group EVERY hit by the target that was live when it
525
+ // landed (per-hit provenance) — most-recent activity first, so the current
526
+ // destination leads.
527
+ const [agg, clickRows, destinationRows, arrivalAgg] = await Promise.all([
381
528
  aggregateFor(db, [id]),
382
529
  db
383
530
  .select({
@@ -386,12 +533,45 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
386
533
  ipAddress: linkClicks.ipAddress,
387
534
  userAgent: linkClicks.userAgent,
388
535
  clickedAt: linkClicks.clickedAt,
536
+ visitorDistinctId: linkClicks.visitorDistinctId,
537
+ visitorKind: linkClicks.visitorKind,
538
+ arrivedAt: linkClicks.arrivedAt,
389
539
  })
390
540
  .from(linkClicks)
391
541
  .innerJoin(trackedLinks, eq(linkClicks.trackedLinkId, trackedLinks.id))
392
542
  .where(eq(trackedLinks.linkId, id))
393
543
  .orderBy(desc(linkClicks.clickedAt))
394
544
  .limit(50),
545
+ db
546
+ .select({
547
+ url: linkClicks.destinationUrl,
548
+ clicks: count().mapWith(Number),
549
+ scans:
550
+ sql<number>`count(*) filter (where not (${canonicalTrackedRowFilter()}))`.mapWith(
551
+ Number,
552
+ ),
553
+ firstAt: sql<string>`min(${linkClicks.clickedAt})`,
554
+ lastAt: sql<string>`max(${linkClicks.clickedAt})`,
555
+ })
556
+ .from(linkClicks)
557
+ .innerJoin(trackedLinks, eq(linkClicks.trackedLinkId, trackedLinks.id))
558
+ .where(eq(trackedLinks.linkId, id))
559
+ .groupBy(linkClicks.destinationUrl)
560
+ .orderBy(desc(sql`max(${linkClicks.clickedAt})`)),
561
+ db
562
+ .select({
563
+ arrivals:
564
+ sql<number>`count(*) filter (where ${linkClicks.visitorDistinctId} is not null)`.mapWith(
565
+ Number,
566
+ ),
567
+ identified:
568
+ sql<number>`count(*) filter (where ${linkClicks.visitorKind} = 'token')`.mapWith(
569
+ Number,
570
+ ),
571
+ })
572
+ .from(linkClicks)
573
+ .innerJoin(trackedLinks, eq(linkClicks.trackedLinkId, trackedLinks.id))
574
+ .where(eq(trackedLinks.linkId, id)),
395
575
  ]);
396
576
 
397
577
  return c.json(
@@ -403,7 +583,19 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
403
583
  ipAddress: cl.ipAddress,
404
584
  userAgent: cl.userAgent,
405
585
  clickedAt: cl.clickedAt.toISOString(),
586
+ visitorDistinctId: cl.visitorDistinctId,
587
+ visitorKind: cl.visitorKind,
588
+ arrivedAt: cl.arrivedAt ? cl.arrivedAt.toISOString() : null,
589
+ })),
590
+ destinations: destinationRows.map((d) => ({
591
+ url: d.url,
592
+ clicks: d.clicks,
593
+ scans: d.scans,
594
+ firstAt: new Date(d.firstAt).toISOString(),
595
+ lastAt: new Date(d.lastAt).toISOString(),
406
596
  })),
597
+ arrivalCount: arrivalAgg[0]?.arrivals ?? 0,
598
+ identifiedArrivalCount: arrivalAgg[0]?.identified ?? 0,
407
599
  },
408
600
  200,
409
601
  );
@@ -427,39 +619,72 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
427
619
  }
428
620
 
429
621
  const patch: Partial<
430
- Pick<LinkRow, "label" | "campaign" | "originalUrl">
622
+ Pick<
623
+ LinkRow,
624
+ | "label"
625
+ | "description"
626
+ | "appendRef"
627
+ | "campaign"
628
+ | "originalUrl"
629
+ | "slug"
630
+ >
431
631
  > & {
432
632
  updatedAt: Date;
433
633
  } = { updatedAt: new Date() };
434
634
  if (body.label !== undefined) patch.label = body.label;
635
+ if (body.description !== undefined) patch.description = body.description;
636
+ if (body.appendRef !== undefined) patch.appendRef = body.appendRef;
435
637
  if (body.campaign !== undefined) patch.campaign = body.campaign;
436
638
  if (body.originalUrl !== undefined) patch.originalUrl = body.originalUrl;
639
+ // Slug: string = set/replace (normalized, 409 on conflict below); null =
640
+ // clear, freeing it for reuse.
641
+ if (body.slug !== undefined) {
642
+ if (body.slug === null) {
643
+ patch.slug = null;
644
+ } else {
645
+ try {
646
+ patch.slug = normalizeSlug(body.slug);
647
+ } catch (err) {
648
+ const message = err instanceof Error ? err.message : "Invalid slug";
649
+ return c.json({ error: message }, 400);
650
+ }
651
+ }
652
+ }
437
653
 
438
654
  // Both writes in ONE transaction so the two originalUrls can never diverge.
439
655
  // CRITICAL: the click redirect reads tracked_links.originalUrl fresh per
440
656
  // hit (no cache), NOT links.originalUrl — so re-targeting MUST also update
441
- // the 1:1 tracked_links row (scoped by link_id, which can only ever be the
442
- // managed tracked row). The links row is the display/source of truth.
443
- const updated = await db.transaction(async (tx) => {
444
- const [row] = await tx
445
- .update(links)
446
- .set(patch)
447
- .where(eq(links.id, id))
448
- .returning();
449
-
450
- // Signal 404 to the caller; returning null (vs throwing) commits an empty
451
- // tx and avoids bubbling as a 500.
452
- if (!row) return null;
453
-
454
- if (body.originalUrl !== undefined) {
455
- await tx
456
- .update(trackedLinks)
457
- .set({ originalUrl: body.originalUrl, updatedAt: new Date() })
458
- .where(eq(trackedLinks.linkId, id));
657
+ // the link's tracked_links rows (scoped by link_id — the managed redirect
658
+ // row, plus the QR scan row once one is minted). The links row is the
659
+ // display/source of truth.
660
+ let updated: LinkRow | null;
661
+ try {
662
+ updated = await db.transaction(async (tx) => {
663
+ const [row] = await tx
664
+ .update(links)
665
+ .set(patch)
666
+ .where(eq(links.id, id))
667
+ .returning();
668
+
669
+ // Signal 404 to the caller; returning null (vs throwing) commits an
670
+ // empty tx and avoids bubbling as a 500.
671
+ if (!row) return null;
672
+
673
+ if (body.originalUrl !== undefined) {
674
+ await tx
675
+ .update(trackedLinks)
676
+ .set({ originalUrl: body.originalUrl, updatedAt: new Date() })
677
+ .where(eq(trackedLinks.linkId, id));
678
+ }
679
+
680
+ return row;
681
+ });
682
+ } catch (err) {
683
+ if (patch.slug && isSlugUniqueViolation(err)) {
684
+ return c.json({ error: new SlugTakenError(patch.slug).message }, 409);
459
685
  }
460
-
461
- return row;
462
- });
686
+ throw err;
687
+ }
463
688
 
464
689
  if (!updated) {
465
690
  return c.json({ error: "Link not found" }, 404);
@@ -471,6 +696,48 @@ export const linksRouter = new OpenAPIHono<AppEnv>()
471
696
  200,
472
697
  );
473
698
  })
699
+ .openapi(qrLinkRoute, async (c) => {
700
+ const { db, env } = c.get("container");
701
+ const { id } = c.req.valid("param");
702
+ const { format, size, transparent } = c.req.valid("query");
703
+
704
+ // Lazy-mints the link's QR scan row on first render (race-safe via the
705
+ // partial unique index). An archived link still renders — archive never
706
+ // kills distributed artifacts, and a printed code is the most distributed
707
+ // artifact there is.
708
+ const qr = await ensureQrTrackedLink({ db, linkId: id });
709
+ if (!qr) {
710
+ return c.json({ error: "Link not found" }, 404);
711
+ }
712
+
713
+ // The QR encodes the DURABLE UID redirect — never the vanity slug — so a
714
+ // printed code survives slug changes AND re-targeting (PATCH updates the
715
+ // scan row's destination alongside the canonical row).
716
+ const scanUrl = `${env.API_PUBLIC_URL}/v1/t/c/${qr.trackedLinkId}`;
717
+
718
+ // Same-content caching: the encoded URL is immutable for the link's
719
+ // lifetime, so clients (the Studio <img>) may cache; private because the
720
+ // endpoint is admin-authed.
721
+ c.header("Cache-Control", "private, max-age=3600");
722
+
723
+ const render = {
724
+ width: size,
725
+ errorCorrectionLevel: "M" as const,
726
+ // "#0000" = fully transparent light modules; default is opaque white.
727
+ ...(transparent ? { color: { light: "#0000" } } : {}),
728
+ };
729
+
730
+ if (format === "png") {
731
+ const png = await QRCode.toBuffer(scanUrl, render);
732
+ c.header("Content-Type", "image/png");
733
+ // Re-wrap: hono's `c.body` Data type doesn't accept Node's Buffer.
734
+ return c.body(new Uint8Array(png));
735
+ }
736
+
737
+ const svg = await QRCode.toString(scanUrl, { ...render, type: "svg" });
738
+ c.header("Content-Type", "image/svg+xml");
739
+ return c.body(svg);
740
+ })
474
741
  .openapi(archiveLinkRoute, async (c) => {
475
742
  const { db, env } = c.get("container");
476
743
  const { id } = c.req.valid("param");
@@ -0,0 +1,51 @@
1
+ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
2
+ import type { AppEnv } from "../../app.js";
3
+ import { getListRegistry } from "../../lists/registry-singleton.js";
4
+
5
+ const listSchema = z.object({
6
+ id: z.string(),
7
+ name: z.string(),
8
+ description: z.string().optional(),
9
+ defaultOptIn: z.boolean(),
10
+ enabled: z.boolean(),
11
+ // `"topic"` = author-defined (`defineList`); `"channel"` = engine-synthesized
12
+ // delivery channel (the in-app feed + one per member-directed connector).
13
+ kind: z.enum(["channel", "topic"]),
14
+ });
15
+
16
+ const listRoute = createRoute({
17
+ method: "get",
18
+ path: "/",
19
+ tags: ["Admin — Lists"],
20
+ summary: "List all registered lists",
21
+ description:
22
+ "Returns EVERY registered list — author-defined topics AND engine-synthesized channels — with its `kind`. Reads the process `ListRegistry` directly (no DB); mirrors the catalog the mailer and preference center resolve against.",
23
+ responses: {
24
+ 200: {
25
+ content: {
26
+ "application/json": {
27
+ schema: z.object({ lists: z.array(listSchema) }),
28
+ },
29
+ },
30
+ description: "All registered lists (topics + channels)",
31
+ },
32
+ },
33
+ });
34
+
35
+ export const adminListsRouter = new OpenAPIHono<AppEnv>().openapi(
36
+ listRoute,
37
+ (c) => {
38
+ const lists = getListRegistry()
39
+ .getAll()
40
+ .map((l) => ({
41
+ id: l.id,
42
+ name: l.name,
43
+ ...(l.description !== undefined ? { description: l.description } : {}),
44
+ defaultOptIn: l.defaultOptIn,
45
+ enabled: l.enabled,
46
+ kind: l.kind ?? "topic",
47
+ }));
48
+
49
+ return c.json({ lists }, 200);
50
+ },
51
+ );
@@ -54,10 +54,26 @@ export const campaignSchema = z.object({
54
54
  audienceKind: z.string(),
55
55
  audienceId: z.string(),
56
56
  templateKey: z.string(),
57
+ subject: z.string().nullable(),
58
+ fromEmail: z.string().nullable(),
57
59
  totalRecipients: z.number(),
58
60
  sentCount: z.number(),
59
61
  skippedCount: z.number(),
60
62
  failedCount: z.number(),
63
+ /**
64
+ * Multi-step wave definition — the stored blob's steps array verbatim
65
+ * (`docs/campaign-steps-spec.md`; elements are `CampaignStep` data). NULL =
66
+ * legacy single-send campaign (templateKey/subject/fromEmail are the whole
67
+ * send).
68
+ */
69
+ steps: z.array(z.record(z.string(), z.unknown())).nullable(),
70
+ /** The next step to execute — the wave runtime's sole resume cursor. */
71
+ currentStep: z.number(),
72
+ /**
73
+ * When a `waiting` campaign's pending wait elapses (ISO 8601). Mirror of
74
+ * `scheduledAt`; null unless a wait is pending.
75
+ */
76
+ nextStepAt: z.string().nullable(),
61
77
  scheduledAt: z.string().nullable(),
62
78
  canceledAt: z.string().nullable(),
63
79
  startedAt: z.string().nullable(),
@@ -77,10 +93,15 @@ export function serializeCampaign(
77
93
  audienceKind: campaign.audienceKind,
78
94
  audienceId: campaign.audienceId,
79
95
  templateKey: campaign.templateKey,
96
+ subject: campaign.subject,
97
+ fromEmail: campaign.fromEmail,
80
98
  totalRecipients: campaign.totalRecipients,
81
99
  sentCount: campaign.sentCount,
82
100
  skippedCount: campaign.skippedCount,
83
101
  failedCount: campaign.failedCount,
102
+ steps: campaign.steps?.steps ?? null,
103
+ currentStep: campaign.currentStep,
104
+ nextStepAt: campaign.nextStepAt?.toISOString() ?? null,
84
105
  scheduledAt: campaign.scheduledAt?.toISOString() ?? null,
85
106
  canceledAt: campaign.canceledAt?.toISOString() ?? null,
86
107
  startedAt: campaign.startedAt?.toISOString() ?? null,
@@ -178,7 +199,7 @@ const cancelRouteDef = createRoute({
178
199
  tags: ["Campaigns"],
179
200
  summary: "Cancel a campaign",
180
201
  description:
181
- "Cancels a `scheduled`, `queued`, or `sending` campaign. A mid-send cancel stops the blast at the next chunk boundary — recipients not yet dispatched are spared; already-dispatched sends are not recalled.",
202
+ "Cancels a `scheduled`, `queued`, `sending`, or `waiting` campaign. A mid-send cancel stops the blast at the next chunk boundary — recipients not yet dispatched are spared; already-dispatched sends are not recalled. Canceling a `waiting` multi-step campaign spares every remaining wave (its pending next-step run no-ops on the terminal guard).",
182
203
  request: {
183
204
  params: z.object({ id: z.string() }),
184
205
  },
@@ -263,6 +284,16 @@ export const campaignsRouter = new OpenAPIHono<AppEnv>()
263
284
  if (audienceKind === "list" && !listRegistry.has(audienceId)) {
264
285
  return c.json({ error: `Unknown list: ${audienceId}` }, 404);
265
286
  }
287
+ // A list-audience campaign resolves recipients by SUBSCRIPTION. A channel
288
+ // preference list (`kind:"channel"`) gates a delivery transport (the in-app
289
+ // feed, a connector), not an email topic — a channel audience would EMAIL
290
+ // everyone not opted out of e.g. the discord channel. Reject it.
291
+ if (audienceKind === "list" && listRegistry.isChannel(audienceId)) {
292
+ return c.json(
293
+ { error: `a channel preference list cannot be a campaign audience` },
294
+ 400,
295
+ );
296
+ }
266
297
  if (audienceKind === "bucket" && !bucketRegistry.has(audienceId)) {
267
298
  return c.json({ error: `Unknown bucket: ${audienceId}` }, 404);
268
299
  }
@@ -421,10 +452,12 @@ export const campaignsRouter = new OpenAPIHono<AppEnv>()
421
452
  const { db } = c.get("container");
422
453
  const { id } = c.req.valid("param");
423
454
 
424
- // CAS: only a cancelable status transitions, so a concurrent completion
425
- // (or a second cancel) is never overwritten. The punctual Hatchet
426
- // scheduled run for a canceled campaign still fires but no-ops on the
427
- // terminal guard; a `sending` blast stops at its next chunk boundary.
455
+ // CAS: only a cancelable status transitions (allowed from
456
+ // scheduled/queued/sending/waiting), so a concurrent completion (or a
457
+ // second cancel) is never overwritten. The punctual Hatchet scheduled run
458
+ // for a canceled campaign — a `scheduled` row's send or a `waiting` row's
459
+ // pending next-step — still fires but no-ops on the terminal guard; a
460
+ // `sending` blast stops at its next chunk boundary.
428
461
  const canceled = await db
429
462
  .update(campaigns)
430
463
  .set({
@@ -435,7 +468,12 @@ export const campaignsRouter = new OpenAPIHono<AppEnv>()
435
468
  .where(
436
469
  and(
437
470
  eq(campaigns.id, id),
438
- inArray(campaigns.status, ["scheduled", "queued", "sending"]),
471
+ inArray(campaigns.status, [
472
+ "scheduled",
473
+ "queued",
474
+ "sending",
475
+ "waiting",
476
+ ]),
439
477
  ),
440
478
  )
441
479
  .returning();