@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
@@ -1,11 +1,18 @@
1
1
  import { campaigns } from "@hogsend/db";
2
2
  import { getTemplateNames, type TemplateName } from "@hogsend/email";
3
3
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
4
- import { eq } from "drizzle-orm";
4
+ import { and, desc, eq, inArray, sql } from "drizzle-orm";
5
5
  import type { AppEnv } from "../../app.js";
6
6
  import { errorSchema } from "../../lib/schemas.js";
7
7
  import { sendCampaignTask } from "../../workflows/send-campaign.js";
8
8
 
9
+ /**
10
+ * How far in the past a `sendAt` may lie and still be accepted (treated as an
11
+ * immediate send). Anything staler is a 400 — a client submitting last week's
12
+ * timestamp almost certainly did not mean "blast right now".
13
+ */
14
+ const SEND_AT_PAST_TOLERANCE_MS = 60 * 1000;
15
+
9
16
  const createCampaignSchema = z
10
17
  .object({
11
18
  name: z.string().min(1).optional(),
@@ -15,6 +22,12 @@ const createCampaignSchema = z
15
22
  props: z.record(z.string(), z.unknown()).optional(),
16
23
  from: z.string().optional(),
17
24
  subject: z.string().optional(),
25
+ /**
26
+ * Optional future send instant (ISO 8601). Present → the campaign is
27
+ * created `scheduled` and delivered at that instant (Hatchet scheduled run,
28
+ * with the reaper sweep as backstop). Absent → immediate enqueue.
29
+ */
30
+ sendAt: z.string().datetime({ offset: true }).optional(),
18
31
  /**
19
32
  * Optional client idempotency key. A retried create with the same key
20
33
  * resolves to the EXISTING campaign instead of spawning a second broadcast
@@ -31,31 +44,79 @@ const createCampaignSchema = z
31
44
  const createResponseSchema = z.object({
32
45
  campaignId: z.string(),
33
46
  status: z.string(),
47
+ scheduledAt: z.string().nullable().optional(),
34
48
  });
35
49
 
36
- const campaignSchema = z.object({
50
+ export const campaignSchema = z.object({
37
51
  id: z.string(),
38
52
  name: z.string(),
39
53
  status: z.string(),
40
54
  audienceKind: z.string(),
41
55
  audienceId: z.string(),
42
56
  templateKey: z.string(),
57
+ subject: z.string().nullable(),
58
+ fromEmail: z.string().nullable(),
43
59
  totalRecipients: z.number(),
44
60
  sentCount: z.number(),
45
61
  skippedCount: z.number(),
46
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(),
77
+ scheduledAt: z.string().nullable(),
78
+ canceledAt: z.string().nullable(),
47
79
  startedAt: z.string().nullable(),
48
80
  completedAt: z.string().nullable(),
49
81
  createdAt: z.string(),
50
82
  });
51
83
 
84
+ type CampaignRow = typeof campaigns.$inferSelect;
85
+
86
+ export function serializeCampaign(
87
+ campaign: CampaignRow,
88
+ ): z.infer<typeof campaignSchema> {
89
+ return {
90
+ id: campaign.id,
91
+ name: campaign.name,
92
+ status: campaign.status,
93
+ audienceKind: campaign.audienceKind,
94
+ audienceId: campaign.audienceId,
95
+ templateKey: campaign.templateKey,
96
+ subject: campaign.subject,
97
+ fromEmail: campaign.fromEmail,
98
+ totalRecipients: campaign.totalRecipients,
99
+ sentCount: campaign.sentCount,
100
+ skippedCount: campaign.skippedCount,
101
+ failedCount: campaign.failedCount,
102
+ steps: campaign.steps?.steps ?? null,
103
+ currentStep: campaign.currentStep,
104
+ nextStepAt: campaign.nextStepAt?.toISOString() ?? null,
105
+ scheduledAt: campaign.scheduledAt?.toISOString() ?? null,
106
+ canceledAt: campaign.canceledAt?.toISOString() ?? null,
107
+ startedAt: campaign.startedAt?.toISOString() ?? null,
108
+ completedAt: campaign.completedAt?.toISOString() ?? null,
109
+ createdAt: campaign.createdAt.toISOString(),
110
+ };
111
+ }
112
+
52
113
  const createRouteDef = createRoute({
53
114
  method: "post",
54
115
  path: "/",
55
116
  tags: ["Campaigns"],
56
- summary: "Create + enqueue a campaign",
117
+ summary: "Create + enqueue (or schedule) a campaign",
57
118
  description:
58
- "Sends one template to every subscribed member of a list (or every active member of a bucket). Validates the template + audience, inserts a `queued` campaign, and enqueues the durable `send-campaign` task. Exactly one of `list` or `bucket` is required.",
119
+ "Sends one template to every subscribed member of a list (or every active member of a bucket). Validates the template + audience, inserts the campaign, and either enqueues the durable `send-campaign` task immediately or — when `sendAt` is supplied — schedules it for that instant. Exactly one of `list` or `bucket` is required.",
59
120
  request: {
60
121
  body: {
61
122
  content: {
@@ -103,6 +164,61 @@ const getRouteDef = createRoute({
103
164
  },
104
165
  });
105
166
 
167
+ const listRouteDef = createRoute({
168
+ method: "get",
169
+ path: "/",
170
+ tags: ["Campaigns"],
171
+ summary: "List campaigns",
172
+ description:
173
+ "Newest first. Filter with `status` (comma-separated, e.g. `scheduled,sending`).",
174
+ request: {
175
+ query: z.object({
176
+ status: z.string().optional(),
177
+ limit: z.coerce.number().int().min(1).max(200).default(50),
178
+ offset: z.coerce.number().int().min(0).default(0),
179
+ }),
180
+ },
181
+ responses: {
182
+ 200: {
183
+ content: {
184
+ "application/json": {
185
+ schema: z.object({
186
+ campaigns: z.array(campaignSchema),
187
+ hasMore: z.boolean(),
188
+ }),
189
+ },
190
+ },
191
+ description: "Campaigns, newest first",
192
+ },
193
+ },
194
+ });
195
+
196
+ const cancelRouteDef = createRoute({
197
+ method: "post",
198
+ path: "/{id}/cancel",
199
+ tags: ["Campaigns"],
200
+ summary: "Cancel a campaign",
201
+ description:
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).",
203
+ request: {
204
+ params: z.object({ id: z.string() }),
205
+ },
206
+ responses: {
207
+ 200: {
208
+ content: { "application/json": { schema: campaignSchema } },
209
+ description: "The canceled campaign",
210
+ },
211
+ 404: {
212
+ content: { "application/json": { schema: errorSchema } },
213
+ description: "Unknown campaign id",
214
+ },
215
+ 409: {
216
+ content: { "application/json": { schema: errorSchema } },
217
+ description: "Campaign is in a terminal state and cannot be canceled",
218
+ },
219
+ },
220
+ });
221
+
106
222
  // The campaigns router does NOT re-apply auth internally — the data-plane prefix
107
223
  // guards in `routes/index.ts` (decision #16) apply `requireApiKey` +
108
224
  // `requireScope("ingest")` to `/v1/campaigns` (bare + `/*`) before requests
@@ -113,19 +229,46 @@ export const campaignsRouter = new OpenAPIHono<AppEnv>()
113
229
  c.get("container");
114
230
  const body = c.req.valid("json");
115
231
 
116
- // Enqueue the durable send task, swallowing a transient broker/transport
117
- // failure: the campaign row is already committed in `queued`, so a failed
118
- // enqueue is recovered by the reaper cron re-enqueueing the orphan rather
119
- // than 500-ing the request (which a keyless client would retry into a
120
- // duplicate broadcast).
121
- const enqueue = async (campaignId: string): Promise<void> => {
232
+ // Parse + bound `sendAt` BEFORE any row is written. A stale timestamp is
233
+ // rejected (not "blast right now"); within tolerance it degrades to an
234
+ // immediate send.
235
+ let scheduledAt: Date | null = null;
236
+ if (body.sendAt) {
237
+ const at = new Date(body.sendAt);
238
+ if (at.getTime() < Date.now() - SEND_AT_PAST_TOLERANCE_MS) {
239
+ return c.json({ error: `sendAt is in the past: ${body.sendAt}` }, 400);
240
+ }
241
+ scheduledAt = at;
242
+ }
243
+ const isScheduled =
244
+ scheduledAt !== null && scheduledAt.getTime() > Date.now();
245
+
246
+ // Fire the row's trigger: a punctual Hatchet scheduled run for a future
247
+ // `scheduledAt`, else an immediate enqueue (runNoWait — `.run()` would
248
+ // block this request until the whole blast completes). Best-effort,
249
+ // swallowing a transient broker/transport failure: the campaign row is
250
+ // already committed, so a failed dispatch is recovered by the reaper cron
251
+ // (re-enqueue / due-scheduled promotion) rather than 500-ing the request
252
+ // (which a keyless client would retry into a duplicate broadcast).
253
+ const dispatch = async (row: {
254
+ id: string;
255
+ scheduledAt?: Date | null;
256
+ }): Promise<void> => {
122
257
  try {
123
- await sendCampaignTask.run({ campaignId });
258
+ const at = row.scheduledAt;
259
+ if (at && at.getTime() > Date.now()) {
260
+ await sendCampaignTask.schedule(at, { campaignId: row.id });
261
+ } else {
262
+ await sendCampaignTask.runNoWait({ campaignId: row.id });
263
+ }
124
264
  } catch (err) {
125
- logger.warn("POST /v1/campaigns: enqueue failed (reaper will retry)", {
126
- campaignId,
127
- error: err instanceof Error ? err.message : String(err),
128
- });
265
+ logger.warn(
266
+ "POST /v1/campaigns: dispatch failed (reaper will recover)",
267
+ {
268
+ campaignId: row.id,
269
+ error: err instanceof Error ? err.message : String(err),
270
+ },
271
+ );
129
272
  }
130
273
  };
131
274
 
@@ -141,6 +284,16 @@ export const campaignsRouter = new OpenAPIHono<AppEnv>()
141
284
  if (audienceKind === "list" && !listRegistry.has(audienceId)) {
142
285
  return c.json({ error: `Unknown list: ${audienceId}` }, 404);
143
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
+ }
144
297
  if (audienceKind === "bucket" && !bucketRegistry.has(audienceId)) {
145
298
  return c.json({ error: `Unknown bucket: ${audienceId}` }, 404);
146
299
  }
@@ -154,66 +307,130 @@ export const campaignsRouter = new OpenAPIHono<AppEnv>()
154
307
 
155
308
  if (idempotencyKey) {
156
309
  const existing = await db
157
- .select({ id: campaigns.id, status: campaigns.status })
310
+ .select({
311
+ id: campaigns.id,
312
+ status: campaigns.status,
313
+ scheduledAt: campaigns.scheduledAt,
314
+ })
158
315
  .from(campaigns)
159
316
  .where(eq(campaigns.idempotencyKey, idempotencyKey))
160
317
  .limit(1);
161
318
  const prior = existing[0];
162
319
  if (prior) {
163
- // Re-enqueue is safe (terminal-`sent` short-circuits; the per-send key
164
- // dedups), so an idempotent retry both returns the existing campaign AND
165
- // ensures it is running — covering a first attempt that committed the
166
- // row but failed to enqueue.
167
- await enqueue(prior.id);
168
- return c.json({ campaignId: prior.id, status: prior.status }, 202);
320
+ // Re-dispatch is safe (terminal statuses short-circuit; the per-send
321
+ // key dedups; an early fire of a still-future scheduled row skips), so
322
+ // an idempotent retry both returns the existing campaign AND ensures
323
+ // its trigger exists — covering a first attempt that committed the row
324
+ // but failed to dispatch.
325
+ await dispatch(prior);
326
+ return c.json(
327
+ {
328
+ campaignId: prior.id,
329
+ status: prior.status,
330
+ scheduledAt: prior.scheduledAt?.toISOString() ?? null,
331
+ },
332
+ 202,
333
+ );
169
334
  }
170
335
  }
171
336
 
172
337
  const baseInsert = db.insert(campaigns).values({
173
338
  name: body.name ?? `Campaign to ${audienceKind} ${audienceId}`,
174
- status: "queued",
339
+ status: isScheduled ? "scheduled" : "queued",
175
340
  audienceKind,
176
341
  audienceId,
177
342
  templateKey: body.template,
178
343
  props: (body.props ?? {}) as Record<string, unknown>,
179
344
  fromEmail: body.from ?? null,
180
345
  subject: body.subject ?? null,
346
+ scheduledAt,
181
347
  idempotencyKey,
182
348
  });
183
349
 
184
350
  // With a key, swallow a concurrent-insert collision on the partial-unique
185
351
  // index (the select-then-insert above is not atomic) and resolve the winner.
352
+ // The `targetWhere` predicate must match the PARTIAL unique index
353
+ // (`WHERE idempotency_key IS NOT NULL`) or Postgres cannot infer the
354
+ // conflict arbiter (42P10) and the keyed insert fails outright.
186
355
  const insertRows = idempotencyKey
187
356
  ? await baseInsert
188
- .onConflictDoNothing({ target: campaigns.idempotencyKey })
357
+ .onConflictDoNothing({
358
+ target: campaigns.idempotencyKey,
359
+ where: sql`idempotency_key is not null`,
360
+ })
189
361
  .returning({ id: campaigns.id })
190
362
  : await baseInsert.returning({ id: campaigns.id });
191
363
 
192
364
  const campaignId = insertRows[0]?.id;
193
365
  if (!campaignId && idempotencyKey) {
194
366
  const winner = await db
195
- .select({ id: campaigns.id, status: campaigns.status })
367
+ .select({
368
+ id: campaigns.id,
369
+ status: campaigns.status,
370
+ scheduledAt: campaigns.scheduledAt,
371
+ })
196
372
  .from(campaigns)
197
373
  .where(eq(campaigns.idempotencyKey, idempotencyKey))
198
374
  .limit(1);
199
375
  if (winner[0]) {
200
- await enqueue(winner[0].id);
376
+ await dispatch(winner[0]);
201
377
  return c.json(
202
- { campaignId: winner[0].id, status: winner[0].status },
378
+ {
379
+ campaignId: winner[0].id,
380
+ status: winner[0].status,
381
+ scheduledAt: winner[0].scheduledAt?.toISOString() ?? null,
382
+ },
203
383
  202,
204
384
  );
205
385
  }
206
386
  }
207
387
  if (!campaignId) throw new Error("Failed to create campaign");
208
388
 
209
- // Enqueue the durable task. The campaign row is already committed in
210
- // `queued`, so a transient enqueue failure (broker down) is NON-fatal: we
211
- // still return 202 and the reaper cron re-enqueues the orphaned `queued`
212
- // row. This keeps the request from 500-ing AFTER a committed row, which a
213
- // client would otherwise retry into a duplicate (sans idempotency key).
214
- await enqueue(campaignId);
389
+ // Fire the trigger. The campaign row is already committed, so a transient
390
+ // dispatch failure (broker down) is NON-fatal: we still return 202 and the
391
+ // reaper cron recovers the orphaned row. This keeps the request from
392
+ // 500-ing AFTER a committed row, which a client would otherwise retry into
393
+ // a duplicate (sans idempotency key).
394
+ await dispatch({ id: campaignId, scheduledAt });
215
395
 
216
- return c.json({ campaignId, status: "queued" }, 202);
396
+ return c.json(
397
+ {
398
+ campaignId,
399
+ status: isScheduled ? "scheduled" : "queued",
400
+ scheduledAt: scheduledAt?.toISOString() ?? null,
401
+ },
402
+ 202,
403
+ );
404
+ })
405
+ .openapi(listRouteDef, async (c) => {
406
+ const { db } = c.get("container");
407
+ const { status, limit, offset } = c.req.valid("query");
408
+
409
+ const statuses = status
410
+ ?.split(",")
411
+ .map((s) => s.trim())
412
+ .filter(Boolean);
413
+
414
+ // Fetch one extra row to derive `hasMore` without a COUNT.
415
+ const rows = await db
416
+ .select()
417
+ .from(campaigns)
418
+ .where(
419
+ statuses && statuses.length > 0
420
+ ? inArray(campaigns.status, statuses)
421
+ : undefined,
422
+ )
423
+ .orderBy(desc(campaigns.createdAt))
424
+ .limit(limit + 1)
425
+ .offset(offset);
426
+
427
+ return c.json(
428
+ {
429
+ campaigns: rows.slice(0, limit).map(serializeCampaign),
430
+ hasMore: rows.length > limit,
431
+ },
432
+ 200,
433
+ );
217
434
  })
218
435
  .openapi(getRouteDef, async (c) => {
219
436
  const { db } = c.get("container");
@@ -229,24 +446,54 @@ export const campaignsRouter = new OpenAPIHono<AppEnv>()
229
446
  return c.json({ error: `Unknown campaign: ${id}` }, 404);
230
447
  }
231
448
 
449
+ return c.json(serializeCampaign(campaign), 200);
450
+ })
451
+ .openapi(cancelRouteDef, async (c) => {
452
+ const { db } = c.get("container");
453
+ const { id } = c.req.valid("param");
454
+
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.
461
+ const canceled = await db
462
+ .update(campaigns)
463
+ .set({
464
+ status: "canceled",
465
+ canceledAt: new Date(),
466
+ updatedAt: new Date(),
467
+ })
468
+ .where(
469
+ and(
470
+ eq(campaigns.id, id),
471
+ inArray(campaigns.status, [
472
+ "scheduled",
473
+ "queued",
474
+ "sending",
475
+ "waiting",
476
+ ]),
477
+ ),
478
+ )
479
+ .returning();
480
+ const row = canceled[0];
481
+ if (row) {
482
+ return c.json(serializeCampaign(row), 200);
483
+ }
484
+
485
+ const existing = await db
486
+ .select()
487
+ .from(campaigns)
488
+ .where(eq(campaigns.id, id))
489
+ .limit(1);
490
+ if (!existing[0]) {
491
+ return c.json({ error: `Unknown campaign: ${id}` }, 404);
492
+ }
232
493
  return c.json(
233
494
  {
234
- id: campaign.id,
235
- name: campaign.name,
236
- status: campaign.status,
237
- audienceKind: campaign.audienceKind,
238
- audienceId: campaign.audienceId,
239
- templateKey: campaign.templateKey,
240
- totalRecipients: campaign.totalRecipients,
241
- sentCount: campaign.sentCount,
242
- skippedCount: campaign.skippedCount,
243
- failedCount: campaign.failedCount,
244
- startedAt: campaign.startedAt ? campaign.startedAt.toISOString() : null,
245
- completedAt: campaign.completedAt
246
- ? campaign.completedAt.toISOString()
247
- : null,
248
- createdAt: campaign.createdAt.toISOString(),
495
+ error: `Campaign is ${existing[0].status} and cannot be canceled`,
249
496
  },
250
- 200,
497
+ 409,
251
498
  );
252
499
  });
@@ -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
- // Built-in journey category + every enabled defined list, deduped by id
99
- // (a list MAY NOT reuse a reserved category id, but guard anyway).
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 renderableCategories: { id: string; label: string }[] = [];
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
- renderableCategories.push({ id: cat.id, label: cat.label });
126
+ topicCategories.push({ id: cat.id, label: cat.label });
106
127
  }
107
- for (const list of listRegistry.getEnabled()) {
108
- if (seen.has(list.id)) continue;
109
- seen.add(list.id);
110
- renderableCategories.push({ id: list.id, label: list.name });
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
- let categoryRows = "";
114
- for (const cat of renderableCategories) {
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
- categoryRows += `
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, or } from "drizzle-orm";
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
@@ -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 +