@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
@@ -15,16 +15,24 @@
15
15
  * and warn loudly. A late deploy NEVER fires a surprise blast; bump
16
16
  * `sendAt` (or delete the file) to resolve.
17
17
  * - Row exists and is still `scheduled` → sync mutable fields (name,
18
- * audience, template, props, subject, from, sendAt) so editing the file and
19
- * redeploying updates the pending broadcast — the git-ops loop. A moved
20
- * `sendAt` gets a fresh scheduled run; the stale run no-ops via the send
21
- * task's early-fire guard.
18
+ * audience, template, props, subject, from, sendAt, steps) so editing the
19
+ * file and redeploying updates the pending broadcast — the git-ops loop. A
20
+ * moved `sendAt` gets a fresh scheduled run; the stale run no-ops via the
21
+ * send task's early-fire guard.
22
22
  * - Row exists in any other status (`sent`/`canceled`/`expired`/`failed`/
23
- * in-flight) → no-op. `sent` is the natural "retired" end state; an
24
- * operator `canceled` is never resurrected by a redeploy.
23
+ * in-flight/`waiting`) → no-op. `sent` is the natural "retired" end state;
24
+ * an operator `canceled` is never resurrected by a redeploy. Editing steps
25
+ * mid-flight is deliberately unsupported in v1 — once the campaign leaves
26
+ * `scheduled` (running or waiting between waves), the row is the source of
27
+ * truth.
25
28
  */
29
+ import type { CampaignSendStep } from "@hogsend/core";
26
30
  import { campaigns } from "@hogsend/db";
27
- import { getTemplateNames } from "@hogsend/email";
31
+ import {
32
+ getTemplateDefinition,
33
+ getTemplateNames,
34
+ type TemplateName,
35
+ } from "@hogsend/email";
28
36
  import { and, eq, sql } from "drizzle-orm";
29
37
  import type { HogsendClient } from "../container.js";
30
38
  import { sendCampaignTask } from "../workflows/send-campaign.js";
@@ -100,15 +108,72 @@ export async function reconcileDefinedCampaigns(opts: {
100
108
  result.skipped++;
101
109
  continue;
102
110
  }
103
- if (!templateNames.has(meta.template)) {
111
+ // A list-audience campaign resolves recipients by SUBSCRIPTION. A channel
112
+ // preference list (`kind:"channel"`) gates a delivery transport (the in-app
113
+ // feed, a connector), not an email topic — a channel audience would EMAIL
114
+ // everyone not opted out of e.g. the discord channel. Mirror the unknown-
115
+ // audience config-error path: warn + skip, never throw (one bad definition
116
+ // must not take down worker boot for every campaign).
117
+ if (audienceKind === "list" && listRegistry.isChannel(audienceId)) {
118
+ logger.error(
119
+ "campaigns: channel-list audience — skipping definition (a channel preference list cannot be a campaign audience)",
120
+ { campaignId: meta.id, audienceId },
121
+ );
122
+ result.skipped++;
123
+ continue;
124
+ }
125
+ // Validate EVERY send step's template, not just the mirrored first-step
126
+ // `meta.template` — a broken template on step 3 must be caught at deploy
127
+ // time, not mid-campaign two days into a wait.
128
+ const sendSteps = meta.steps.filter(
129
+ (s): s is CampaignSendStep => s.kind === "send",
130
+ );
131
+ const unknownTemplates = sendSteps
132
+ .map((s) => s.template)
133
+ .filter((t) => !templateNames.has(t));
134
+ if (unknownTemplates.length > 0) {
104
135
  logger.error("campaigns: unknown template — skipping definition", {
105
136
  campaignId: meta.id,
106
- template: meta.template,
137
+ templates: unknownTemplates,
107
138
  });
108
139
  result.skipped++;
109
140
  continue;
110
141
  }
111
142
 
143
+ // A bucket campaign borrows consent from each template's declared
144
+ // category (a bucket is behavior, not consent — docs/audience-model.md).
145
+ // A categoryless template leaves suppression + List-Unsubscribe with
146
+ // nothing beyond unsubscribedAll/suppressed, so its compliance story is
147
+ // only as good as the template's category. Warn, don't skip — the send is
148
+ // legal-by-default, just weaker than it should be.
149
+ if (audienceKind === "bucket") {
150
+ for (const s of sendSteps) {
151
+ const definition = getTemplateDefinition({
152
+ key: s.template as TemplateName,
153
+ registry: templates,
154
+ });
155
+ if (!definition.category) {
156
+ logger.warn(
157
+ "campaigns: bucket-audience campaign template has no category — consent/unsubscribe fall back to the global opt-out only",
158
+ { campaignId: meta.id, template: s.template },
159
+ );
160
+ }
161
+ }
162
+ }
163
+
164
+ // The stored steps blob: multi-step definitions persist `{ v: 1, steps }`;
165
+ // a single-step definition stores NULL — the legacy row shape — so its
166
+ // per-send idempotency keys stay byte-for-byte legacy (campaignSendKey
167
+ // contract). The cast crosses the db package's opaque element type (db
168
+ // cannot import @hogsend/core; the engine narrows at read time).
169
+ const stepsBlob =
170
+ meta.steps.length > 1
171
+ ? {
172
+ v: 1 as const,
173
+ steps: meta.steps as unknown as Array<Record<string, unknown>>,
174
+ }
175
+ : null;
176
+
112
177
  const idempotencyKey = `${DEFINED_CAMPAIGN_KEY_PREFIX}${meta.id}`;
113
178
  const existingRows = await db
114
179
  .select({
@@ -121,6 +186,7 @@ export async function reconcileDefinedCampaigns(opts: {
121
186
  props: campaigns.props,
122
187
  fromEmail: campaigns.fromEmail,
123
188
  subject: campaigns.subject,
189
+ steps: campaigns.steps,
124
190
  scheduledAt: campaigns.scheduledAt,
125
191
  })
126
192
  .from(campaigns)
@@ -143,6 +209,7 @@ export async function reconcileDefinedCampaigns(opts: {
143
209
  props: meta.props ?? {},
144
210
  fromEmail: meta.from ?? null,
145
211
  subject: meta.subject ?? null,
212
+ steps: stepsBlob,
146
213
  scheduledAt: meta.sendAt,
147
214
  idempotencyKey,
148
215
  });
@@ -169,6 +236,7 @@ export async function reconcileDefinedCampaigns(opts: {
169
236
  props: meta.props ?? {},
170
237
  fromEmail: meta.from ?? null,
171
238
  subject: meta.subject ?? null,
239
+ steps: stepsBlob,
172
240
  scheduledAt: meta.sendAt,
173
241
  idempotencyKey,
174
242
  })
@@ -210,10 +278,10 @@ export async function reconcileDefinedCampaigns(opts: {
210
278
  existing.audienceKind !== audienceKind ||
211
279
  existing.audienceId !== audienceId ||
212
280
  existing.templateKey !== meta.template ||
213
- JSON.stringify(existing.props ?? {}) !==
214
- JSON.stringify(meta.props ?? {}) ||
281
+ canonicalJson(existing.props ?? {}) !== canonicalJson(meta.props ?? {}) ||
215
282
  (existing.fromEmail ?? null) !== (meta.from ?? null) ||
216
283
  (existing.subject ?? null) !== (meta.subject ?? null) ||
284
+ canonicalJson(existing.steps ?? null) !== canonicalJson(stepsBlob) ||
217
285
  existing.scheduledAt?.getTime() !== meta.sendAt.getTime();
218
286
 
219
287
  if (!changed) {
@@ -236,6 +304,7 @@ export async function reconcileDefinedCampaigns(opts: {
236
304
  props: meta.props ?? {},
237
305
  fromEmail: meta.from ?? null,
238
306
  subject: meta.subject ?? null,
307
+ steps: stepsBlob,
239
308
  scheduledAt: meta.sendAt,
240
309
  updatedAt: new Date(),
241
310
  })
@@ -266,6 +335,31 @@ export async function reconcileDefinedCampaigns(opts: {
266
335
  return result;
267
336
  }
268
337
 
338
+ /**
339
+ * Key-order-canonical JSON for the changed-comparison. `existing.props` /
340
+ * `existing.steps` round-trip through Postgres jsonb, which does NOT preserve
341
+ * object key order (jsonb canonicalizes it), so a plain `JSON.stringify`
342
+ * comparison against the freshly-authored definition would report a permanent
343
+ * phantom "changed" for any multi-key object — an unchanged definition
344
+ * rewritten (and logged as updated) on every worker boot. Arrays keep their
345
+ * order; only object keys are sorted.
346
+ */
347
+ function canonicalJson(value: unknown): string {
348
+ return JSON.stringify(sortKeysDeep(value));
349
+ }
350
+
351
+ function sortKeysDeep(value: unknown): unknown {
352
+ if (Array.isArray(value)) return value.map(sortKeysDeep);
353
+ if (value !== null && typeof value === "object") {
354
+ return Object.fromEntries(
355
+ Object.entries(value as Record<string, unknown>)
356
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
357
+ .map(([key, entry]) => [key, sortKeysDeep(entry)]),
358
+ );
359
+ }
360
+ return value;
361
+ }
362
+
269
363
  /**
270
364
  * Create the punctual trigger for a scheduled row: a Hatchet scheduled run at
271
365
  * `sendAt`, or an immediate enqueue when already due (within grace).
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Authoring sugar for campaign steps ({@link defineCampaign} `steps:`).
3
+ * Each helper returns the plain stored POJO ({@link CampaignStep} —
4
+ * `campaigns.steps` blob entries): `step.send` normalizes a `where` builder
5
+ * to `ConditionEval[]` HERE, at authoring time (the same
6
+ * normalize-at-definition pattern as `trigger.where` in `defineJourney`), so
7
+ * the stored form is always introspectable data. Channel steps
8
+ * (`step.discord.post` / `.dm`, …) are phase 2.
9
+ */
10
+ import {
11
+ type CampaignSendStep,
12
+ type CampaignWaitStep,
13
+ type CampaignWhere,
14
+ type DurationObject,
15
+ normalizeCampaignWhere,
16
+ } from "@hogsend/core";
17
+ import type { TemplateName } from "@hogsend/email";
18
+
19
+ export const step = {
20
+ /**
21
+ * A per-recipient email wave. `where` filters the campaign's cohort
22
+ * (builder or declarative conditions — engagement terminals with no
23
+ * template scope to "any prior send of this campaign"); only valid on
24
+ * steps after the first (validated by `defineCampaign`).
25
+ */
26
+ send(opts: {
27
+ template: TemplateName;
28
+ props?: Record<string, unknown>;
29
+ subject?: string;
30
+ from?: string;
31
+ where?: CampaignWhere;
32
+ }): CampaignSendStep {
33
+ const where = normalizeCampaignWhere(opts.where);
34
+ return {
35
+ kind: "send",
36
+ template: opts.template,
37
+ ...(opts.props !== undefined ? { props: opts.props } : {}),
38
+ ...(opts.subject !== undefined ? { subject: opts.subject } : {}),
39
+ ...(opts.from !== undefined ? { from: opts.from } : {}),
40
+ ...(where !== undefined ? { where } : {}),
41
+ };
42
+ },
43
+
44
+ /** A durable gap between waves. Minimum 5 minutes (validated). */
45
+ wait(duration: DurationObject): CampaignWaitStep {
46
+ return { kind: "wait", duration };
47
+ },
48
+ };
@@ -36,6 +36,27 @@ export interface ConnectorActionCtx {
36
36
  resolveContact(ref: string): Promise<ResolvedActionContact | null>;
37
37
  }
38
38
 
39
+ /**
40
+ * Declares an action MEMBER-DIRECTED — aimed at an individual recipient rather
41
+ * than a channel/ops surface. Its presence gates the action on the recipient's
42
+ * channel preferences (the auto-registered per-connector opt-out list) before
43
+ * the plugin runs; enforcement lands in a later phase. Absent audience =
44
+ * ops/channel-directed = never gated.
45
+ */
46
+ export interface MemberAudience<A = unknown> {
47
+ kind: "member";
48
+ /**
49
+ * Candidate recipient refs (email | externalId | platform id | namespaced key
50
+ * like "telegram:<chatId>"), tried in order; first resolving contact wins.
51
+ * Returning undefined (or throwing) fails OPEN — the send proceeds.
52
+ *
53
+ * Method shorthand (bivariant) so a `DefinedConnectorAction<DmArgs, …>` stays
54
+ * assignable to the erased `DefinedConnectorAction[]` the registry/plugin
55
+ * index files use (same reason `run` is method shorthand).
56
+ */
57
+ ref(args: A): string | string[] | undefined;
58
+ }
59
+
39
60
  export interface DefinedConnectorAction<A = unknown, R = unknown> {
40
61
  /** The connector this action belongs to (e.g. "discord"). Keys the registry. */
41
62
  connectorId: string;
@@ -43,6 +64,12 @@ export interface DefinedConnectorAction<A = unknown, R = unknown> {
43
64
  name: string;
44
65
  /** Optional human description (Studio enumeration / docs). */
45
66
  description?: string;
67
+ /**
68
+ * When set, declares the action member-directed: the engine will gate it on
69
+ * the recipient's channel preferences before the plugin runs (enforcement
70
+ * lands in a later phase). Absent = ops/channel-directed = never gated.
71
+ */
72
+ audience?: MemberAudience<A>;
46
73
  /** Perform the outbound action. Single-object-in, result-out. */
47
74
  run(args: A, ctx: ConnectorActionCtx): Promise<R>;
48
75
  }
@@ -53,3 +80,46 @@ export function defineConnectorAction<A, R>(
53
80
  ): DefinedConnectorAction<A, R> {
54
81
  return def;
55
82
  }
83
+
84
+ /**
85
+ * The verdict returned when the engine SKIPS a member-directed connector action
86
+ * because the resolved recipient opted out — either the global master opt-out
87
+ * (`unsubscribed_all`) or the per-connector channel list (`channel_unsubscribed`).
88
+ *
89
+ * A plain JSON-safe POJO so it is memo-recordable and replays VERBATIM through
90
+ * both the Hatchet durable `memo` (Layer 1) AND the `connector_deliveries.result`
91
+ * jsonb round-trip (Layer 2) — although a skip in practice NEVER writes a
92
+ * delivery row (the gate runs BEFORE the ledger claim), so a skip is observable
93
+ * only via logs + this returned value.
94
+ *
95
+ * The shape DELIBERATELY does NOT mimic per-action result shapes (it carries no
96
+ * `messageId`/`delivered`): the `skipped: true` discriminant must be
97
+ * unambiguous. An existing consumer reading `result.delivered` gets `undefined`
98
+ * (falsy) on a skip — which degrades in the correct direction (treated as "not
99
+ * delivered").
100
+ */
101
+ export interface ConnectorActionSkipped {
102
+ skipped: true;
103
+ reason: "unsubscribed_all" | "channel_unsubscribed";
104
+ connectorId: string;
105
+ action: string;
106
+ }
107
+
108
+ /**
109
+ * Narrow an outbound-action result to a {@link ConnectorActionSkipped} verdict.
110
+ * Checks a non-null object with `skipped === true` plus string
111
+ * `reason`/`connectorId`/`action` — enough to disambiguate from every per-action
112
+ * result shape.
113
+ */
114
+ export function isConnectorActionSkipped(
115
+ r: unknown,
116
+ ): r is ConnectorActionSkipped {
117
+ if (typeof r !== "object" || r === null) return false;
118
+ const v = r as Record<string, unknown>;
119
+ return (
120
+ v.skipped === true &&
121
+ typeof v.reason === "string" &&
122
+ typeof v.connectorId === "string" &&
123
+ typeof v.action === "string"
124
+ );
125
+ }
package/src/container.ts CHANGED
@@ -79,6 +79,7 @@ import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
79
79
  import { sendResetPasswordEmail } from "./lib/reset-email.js";
80
80
  import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
81
81
  import { prepareTrackedHtml } from "./lib/tracking.js";
82
+ import { synthesizeChannelLists } from "./lists/channels.js";
82
83
  import {
83
84
  type DefinedList,
84
85
  isReservedListId,
@@ -407,6 +408,96 @@ export interface HogsendClientOptions {
407
408
  };
408
409
  }
409
410
 
411
+ /**
412
+ * Boot-validate ONE email-preference `category` against the resolvable list
413
+ * namespace — shared by both the template loop and the journey loop below so a
414
+ * category typo/consent-flip is caught fail-CLOSED wherever a category is
415
+ * declared. `owner` is the human-readable prefix naming the offending
416
+ * declaration (e.g. `Email template "welcome"` / `Journey "my-journey"`), so the
417
+ * throw/warn messages read naturally for either source.
418
+ *
419
+ * A `category` IS the `email_preferences.categories` key: at send time
420
+ * `lib/tracked.ts` resolves the effective category and `checkSuppression` gates
421
+ * it through `ListRegistry.isSubscribed`, whose legacy fallback is
422
+ * `this.get(id)?.defaultOptIn ?? true`. So an UNKNOWN/typo'd id resolves to the
423
+ * `?? true` opt-in default → treated as subscribed → NOT suppressed → an opt-in/
424
+ * consent email delivered to everyone (CAN-SPAM/GDPR-grade). This guard makes a
425
+ * mismatched category a loud boot failure so it can never reach that fallback.
426
+ *
427
+ * Branch semantics (preserved from the original inline template loop):
428
+ * - CHANNEL list (`kind:"channel"`) → THROW. A channel gates a delivery
429
+ * transport, not an email topic; using one as an email category is a category
430
+ * error (it would also opt-out-gate the send by the connector's channel).
431
+ * - reserved built-in (`transactional`/`journey`) → OK.
432
+ * - registered topic list → OK.
433
+ * - DEFINED but registry-EXCLUDED (ENABLED_LISTS) → THROW for an opt-in list
434
+ * (excluding it un-gates consent), WARN for an opt-out list (behavior-
435
+ * preserving, but the preference-center entry is hidden while excluded).
436
+ * - unknown → THROW.
437
+ */
438
+ function validateListCategory(opts: {
439
+ owner: string;
440
+ category: string;
441
+ listRegistry: ListRegistry;
442
+ /** id → `defaultOptIn` for every DEFINED list (`opts.lists`), enabled or not. */
443
+ definedLists: Map<string, boolean>;
444
+ logger: Logger;
445
+ }): void {
446
+ const { owner, category, listRegistry, definedLists, logger } = opts;
447
+
448
+ // A channel list is a registered list (so `has()`/`isSubscribed` treat it as
449
+ // known), which means the reserved/registered OK branches below would wave it
450
+ // through. Reject it FIRST: a channel gates a delivery transport (the in-app
451
+ // feed, a connector), never an email topic.
452
+ if (listRegistry.isChannel(category)) {
453
+ throw new Error(
454
+ `${owner} uses category "${category}": a channel preference list gates a delivery transport, not an email topic — pick a topic list or a built-in category.`,
455
+ );
456
+ }
457
+ // Reserved built-in category (transactional / journey) — never a list, but a
458
+ // legitimate `email_preferences.categories` key. OK.
459
+ if (isReservedListId(category)) return;
460
+ // Category names a REGISTERED topic list ⇒ suppression/preferences gate
461
+ // correctly. (A `defineList({ enabled:false })` is STILL registered — the
462
+ // registry filters on ENABLED_LISTS only, never `meta.enabled` — so it lands
463
+ // here, not in the excluded branch below.)
464
+ if (listRegistry.has(category)) return;
465
+ // Category names a DEFINED list that is EXCLUDED from the registry by an
466
+ // ENABLED_LISTS allowlist that doesn't name it. Excluding it makes the
467
+ // send-time check fall back to the legacy `?? true` opt-in default, which
468
+ // FLIPS the gate by polarity:
469
+ // • opt-IN list (`defaultOptIn:false`, consent required): enabled →
470
+ // `categories[id] === true` (never-consented = NOT subscribed =
471
+ // suppressed); excluded → `categories[id] !== false` (never-consented =
472
+ // SUBSCRIBED = NOT suppressed) → the consent email SHIPS to someone who
473
+ // never opted in. Disabling un-gates consent → THROW (fail closed).
474
+ // • opt-OUT list (`defaultOptIn:true`): both enabled and excluded compute
475
+ // `categories[id] !== false` — IDENTICAL, behavior-preserving → WARN.
476
+ const definedOptIn = definedLists.get(category);
477
+ if (definedOptIn !== undefined) {
478
+ if (definedOptIn === false) {
479
+ throw new Error(
480
+ `${owner} has category "${category}", an OPT-IN email list (defaultOptIn:false) that is DEFINED but EXCLUDED from the active registry by ENABLED_LISTS. At send time an excluded list falls back to the legacy opt-in default, which UN-GATES consent — the opt-in email would ship to recipients who never subscribed. Re-enable the list in ENABLED_LISTS (or change the category) — disabling an opt-in list must not silently flip its consent gate open.`,
481
+ );
482
+ }
483
+ logger.warn(
484
+ `${owner} has category "${category}", a DEFINED email list EXCLUDED from the active registry by ENABLED_LISTS. It is an opt-out list (defaultOptIn:true), so send-time gating is behavior-preserving — but its preference center entry is hidden while excluded. Re-enable the list in ENABLED_LISTS or change the category.`,
485
+ );
486
+ return;
487
+ }
488
+ // Unknown category: neither a reserved built-in nor a defined list. At send
489
+ // time this resolves to the `?? true` opt-in default, bypassing suppression/
490
+ // consent. Fail CLOSED with an actionable message.
491
+ const knownLists = [...definedLists.keys()];
492
+ throw new Error(
493
+ `${owner} has category "${category}", which is neither a reserved built-in category (${[
494
+ ...RESERVED_LIST_IDS,
495
+ ].join(", ")}) nor a defined email list (${
496
+ knownLists.length ? knownLists.join(", ") : "none"
497
+ }). A category is its email-preferences list key, so it MUST match a list id (defineList) or a reserved built-in — otherwise an unknown/typo'd category silently defaults to opt-in and un-gates suppression/consent. Fix the category or define the list.`,
498
+ );
499
+ }
500
+
410
501
  export function createHogsendClient(
411
502
  opts: HogsendClientOptions = {},
412
503
  ): HogsendClient {
@@ -466,9 +557,17 @@ export function createHogsendClient(
466
557
  // worker (both call createHogsendClient), so `getListRegistry()` resolves the
467
558
  // wired lists in the mailer's suppression check and the preference center in
468
559
  // either process. `buildListRegistry` installs the process singleton.
560
+ //
561
+ // Channel lists (the in-app feed + one per connector exposing member-directed
562
+ // actions) are synthesized from the raw `opts.connectorActions` array — which
563
+ // is available here before the connector-action registry is built, and is
564
+ // identical in both the API and worker processes — then registered
565
+ // unconditionally (bypassing ENABLED_LISTS) after the user lists.
566
+ const channelLists = synthesizeChannelLists(opts.connectorActions ?? []);
469
567
  const listRegistry = buildListRegistry(
470
568
  opts.lists ?? [],
471
569
  opts.enabledLists ?? env.ENABLED_LISTS,
570
+ channelLists,
472
571
  );
473
572
 
474
573
  // Build the email provider registry, then resolve the single active provider
@@ -573,48 +672,31 @@ export function createHogsendClient(
573
672
  const category = (def as TemplateDefinition | undefined)?.category;
574
673
  // No category ⇒ no per-list gating for this template; nothing to validate.
575
674
  if (!category) continue;
576
- // Reserved built-in category (transactional / journey) — never a list, but
577
- // a legitimate `email_preferences.categories` key. OK.
578
- if (isReservedListId(category)) continue;
579
- // Category names a REGISTERED list ⇒ suppression/preferences gate correctly.
580
- // (Note: a `defineList({ enabled:false })` is STILL registered — the
581
- // registry filters on ENABLED_LISTS only, never `meta.enabled` — so it
582
- // lands here, not in the excluded branch below.)
583
- if (listRegistry.has(category)) continue;
584
- // Category names a DEFINED list that is EXCLUDED from the registry by an
585
- // ENABLED_LISTS allowlist that doesn't name it. Excluding it makes the
586
- // send-time check fall back to the legacy `?? true` opt-in default, which
587
- // FLIPS the gate by polarity:
588
- // • opt-IN list (`defaultOptIn:false`, consent required): enabled →
589
- // `categories[id] === true` (never-consented = NOT subscribed =
590
- // suppressed); excluded → `categories[id] !== false` (never-consented =
591
- // SUBSCRIBED = NOT suppressed) → the consent email SHIPS to someone who
592
- // never opted in. Disabling un-gates consent → THROW (fail closed).
593
- // • opt-OUT list (`defaultOptIn:true`): both enabled and excluded compute
594
- // `categories[id] !== false` — IDENTICAL, behavior-preserving → WARN.
595
- const definedOptIn = definedLists.get(category);
596
- if (definedOptIn !== undefined) {
597
- if (definedOptIn === false) {
598
- throw new Error(
599
- `Email template "${templateKey}" has category "${category}", an OPT-IN email list (defaultOptIn:false) that is DEFINED but EXCLUDED from the active registry by ENABLED_LISTS. At send time an excluded list falls back to the legacy opt-in default, which UN-GATES consent — the opt-in email would ship to recipients who never subscribed. Re-enable the list in ENABLED_LISTS (or change the template's category) — disabling an opt-in list must not silently flip its consent gate open.`,
600
- );
601
- }
602
- logger.warn(
603
- `Email template "${templateKey}" has category "${category}", a DEFINED email list EXCLUDED from the active registry by ENABLED_LISTS. It is an opt-out list (defaultOptIn:true), so send-time gating is behavior-preserving — but its preference center entry is hidden while excluded. Re-enable the list in ENABLED_LISTS or change the template's category.`,
604
- );
605
- continue;
606
- }
607
- // Unknown category: neither a reserved built-in nor a defined list. At send
608
- // time this resolves to the `?? true` opt-in default, bypassing
609
- // suppression/consent. Fail CLOSED with an actionable message.
610
- const knownLists = [...definedLists.keys()];
611
- throw new Error(
612
- `Email template "${templateKey}" has category "${category}", which is neither a reserved built-in category (${[
613
- ...RESERVED_LIST_IDS,
614
- ].join(", ")}) nor a defined email list (${
615
- knownLists.length ? knownLists.join(", ") : "none"
616
- }). A template's category is its email-preferences list key, so it MUST match a list id (defineList) or a reserved built-in — otherwise an unknown/typo'd category silently defaults to opt-in and un-gates suppression/consent. Fix the category or define the list.`,
617
- );
675
+ validateListCategory({
676
+ owner: `Email template "${templateKey}"`,
677
+ category,
678
+ listRegistry,
679
+ definedLists,
680
+ logger,
681
+ });
682
+ }
683
+
684
+ // Boot-validate every journey's `meta.category` through the SAME helper (same
685
+ // fail-closed branch semantics as templates). A journey stamps its category on
686
+ // every `sendEmail` at send time (overriding the template's own category), so
687
+ // a typo/channel/consent-flip here is exactly as dangerous as on a template.
688
+ // Bucket-reaction journeys never carry a `category`, so `opts.journeys` is the
689
+ // complete set to check. Placed right beside the template loop.
690
+ for (const journey of opts.journeys ?? []) {
691
+ const category = journey.meta.category;
692
+ if (!category) continue;
693
+ validateListCategory({
694
+ owner: `Journey "${journey.meta.id}"`,
695
+ category,
696
+ listRegistry,
697
+ definedLists,
698
+ logger,
699
+ });
618
700
  }
619
701
 
620
702
  const emailService =
@@ -162,8 +162,14 @@ export const posthogDestination = defineDestination({
162
162
  userId?: string | null;
163
163
  to?: string | null;
164
164
  userEmail?: string | null;
165
+ anonymousId?: string | null;
165
166
  };
166
- const distinctId = data.userId ?? data.to ?? data.userEmail ?? undefined;
167
+ // `anonymousId` covers anon-tier arrivals (`link.arrived`): a raw browser
168
+ // anon id IS a legitimate PostHog distinct_id, and without it the capture
169
+ // would ship no distinct_id at all — PostHog 400s and the delivery
170
+ // dead-letters (<500 = non-retryable).
171
+ const distinctId =
172
+ data.userId ?? data.anonymousId ?? data.to ?? data.userEmail ?? undefined;
167
173
  // `email.action` is the semantic-link envelope: the CONSUMER's event name
168
174
  // (data.event, e.g. "nps.submitted") is what PostHog should capture, with
169
175
  // the author's properties flattened to the top level. Other catalog events