@hogsend/engine 0.44.0 → 0.46.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.44.0",
3
+ "version": "0.46.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -15,6 +15,8 @@
15
15
  "./worker": "./src/worker.ts",
16
16
  "./auth": "./src/lib/auth.ts",
17
17
  "./create-admin": "./src/lib/create-admin.ts",
18
+ "./api-key-hash": "./src/lib/api-key-hash.ts",
19
+ "./posthog-scopes": "./src/lib/posthog-scopes.ts",
18
20
  "./mcp/authoring-guide": "./src/mcp/authoring-guide.ts",
19
21
  "./package.json": "./package.json"
20
22
  },
@@ -49,17 +51,17 @@
49
51
  "svix": "^1.95.1",
50
52
  "winston": "^3.19.0",
51
53
  "zod": "^4.4.3",
52
- "@hogsend/attribution": "^0.44.0",
53
- "@hogsend/core": "^0.44.0",
54
- "@hogsend/db": "^0.44.0",
55
- "@hogsend/email": "^0.44.0",
56
- "@hogsend/plugin-posthog": "^0.44.0",
57
- "@hogsend/plugin-resend": "^0.44.0",
58
- "@hogsend/sms": "^0.44.0"
54
+ "@hogsend/attribution": "^0.46.0",
55
+ "@hogsend/core": "^0.46.0",
56
+ "@hogsend/db": "^0.46.0",
57
+ "@hogsend/email": "^0.46.0",
58
+ "@hogsend/plugin-posthog": "^0.46.0",
59
+ "@hogsend/plugin-resend": "^0.46.0",
60
+ "@hogsend/sms": "^0.46.0"
59
61
  },
60
62
  "optionalDependencies": {
61
- "@hogsend/plugin-postmark": "^0.44.0",
62
- "@hogsend/plugin-twilio": "^0.44.0"
63
+ "@hogsend/plugin-postmark": "^0.46.0",
64
+ "@hogsend/plugin-twilio": "^0.46.0"
63
65
  },
64
66
  "devDependencies": {
65
67
  "@types/node": "^22.15.3",
package/src/container.ts CHANGED
@@ -65,7 +65,10 @@ import {
65
65
  wrapLegacyAnalyticsService,
66
66
  } from "./lib/analytics-adapter.js";
67
67
  import { AnalyticsProviderRegistry } from "./lib/analytics-provider-registry.js";
68
- import { analyticsProvidersFromEnv } from "./lib/analytics-providers-from-env.js";
68
+ import {
69
+ analyticsProvidersFromEnv,
70
+ buildStoredPosthogProvider,
71
+ } from "./lib/analytics-providers-from-env.js";
69
72
  import {
70
73
  setAnalytics,
71
74
  setAnalyticsEventMirror,
@@ -111,6 +114,7 @@ import { SmsProviderRegistry } from "./lib/sms-provider-registry.js";
111
114
  import { smsProvidersFromEnv } from "./lib/sms-providers-from-env.js";
112
115
  import type { SmsService } from "./lib/sms-service-types.js";
113
116
  import { prepareTrackedHtml } from "./lib/tracking.js";
117
+ import { createUnconfiguredEmailProvider } from "./lib/unconfigured-email-provider.js";
114
118
  import { synthesizeChannelLists } from "./lists/channels.js";
115
119
  import {
116
120
  type DefinedList,
@@ -235,6 +239,16 @@ export interface HogsendClient {
235
239
  * with acorn to derive a visual workflow. Empty when no journeys are wired.
236
240
  */
237
241
  journeySources: Map<string, string>;
242
+ /**
243
+ * The consumer's `Templates`/`Events` `as const` maps, normalized to always
244
+ * be present (`{ templates: {}, events: {} }` when unwired). Consumed by the
245
+ * Studio journey-graph route to resolve `Templates.X` / `Events.X` member
246
+ * expressions to their real values, for exact previews + stable node ids.
247
+ */
248
+ journeyConstants: {
249
+ templates: Record<string, string>;
250
+ events: Record<string, string>;
251
+ };
238
252
  /**
239
253
  * Map of enabled journey id → its `defineJourney` call-site `{ path, line }`.
240
254
  * Populated by `buildJourneyRegistry`. Consumed by the Studio journey-graph
@@ -304,6 +318,18 @@ export interface HogsendClient {
304
318
  export interface HogsendClientOptions {
305
319
  /** Journeys to register in the {@link JourneyRegistry}. Defaults to none. */
306
320
  journeys?: DefinedJourney[];
321
+ /**
322
+ * The consumer's `Templates`/`Events` `as const` maps (each a
323
+ * `CONST_NAME -> "value"` record). Threaded into the Studio journey-graph
324
+ * route so `Templates.X` / `Events.X` member expressions in a journey's `run`
325
+ * source resolve to their real runtime values — yielding exact email-template
326
+ * previews and stable, join-safe `wait-event:${value}` / `digest:${value}`
327
+ * node ids (instead of positional `unstable` synthetics). Defaults to none.
328
+ */
329
+ journeyConstants?: {
330
+ templates?: Record<string, string>;
331
+ events?: Record<string, string>;
332
+ };
307
333
  /** Buckets to register in the {@link BucketRegistry}. Defaults to none. */
308
334
  buckets?: DefinedBucket[];
309
335
  /**
@@ -886,16 +912,30 @@ export function createHogsendClient(
886
912
  // SINGLE place Resend is constructed from env — so resolution is just a
887
913
  // registry lookup that throws if the active id resolves to nothing. NEVER
888
914
  // silently fall back for a non-resend id.
889
- const activeId =
890
- opts.email?.defaultProvider ?? env.EMAIL_PROVIDER ?? "resend";
891
- const provider = emailProviders.get(activeId);
915
+ const explicitId = opts.email?.defaultProvider ?? env.EMAIL_PROVIDER;
916
+ const activeId = explicitId ?? "resend";
917
+ let provider = emailProviders.get(activeId);
892
918
 
893
919
  if (!provider) {
894
- throw new Error(
895
- `email provider "${activeId}" is not registered (registered: ${emailProviders
896
- .getAll()
897
- .map((p) => p.meta?.id ?? "resend")
898
- .join(", ")})`,
920
+ // An EXPLICITLY requested id that resolves to nothing is a config error —
921
+ // throw (typo safety). So is an implicit default when OTHER providers are
922
+ // registered (e.g. Postmark-only without EMAIL_PROVIDER=postmark).
923
+ if (explicitId !== undefined || emailProviders.count() > 0) {
924
+ throw new Error(
925
+ `email provider "${activeId}" is not registered (registered: ${emailProviders
926
+ .getAll()
927
+ .map((p) => p.meta?.id ?? "resend")
928
+ .join(", ")})`,
929
+ );
930
+ }
931
+ // Zero providers + nothing requested = a fresh app without email creds
932
+ // yet. Boot INERT instead of crashing (mirrors the SMS channel's
933
+ // operator-opt-in stub): Studio, ingest and non-email journeys all work;
934
+ // each send fails per-call with an actionable message. The stub is NOT
935
+ // registered in the registry, so no webhook route resolves it.
936
+ provider = createUnconfiguredEmailProvider();
937
+ logger.warn(
938
+ "no email provider configured — email sends will fail until RESEND_API_KEY (or POSTMARK_SERVER_TOKEN with EMAIL_PROVIDER=postmark) is set. Everything else works without one.",
899
939
  );
900
940
  }
901
941
 
@@ -909,7 +949,7 @@ export function createHogsendClient(
909
949
  logger.warn(
910
950
  `provider ${
911
951
  provider.meta?.id ?? "resend"
912
- } reports account-level native tracking ON; disable it in the dashboard — first-party tracking is Hogsend's source of truth.`,
952
+ } can't disable its native open/click tracking per-send (account-level setting) — if it's enabled in the provider dashboard, turn it off there; first-party tracking is Hogsend's source of truth.`,
913
953
  );
914
954
  }
915
955
 
@@ -1389,7 +1429,7 @@ export function createHogsendClient(
1389
1429
  `Destination registry loaded: ${destinationRegistry.count()} destinations`,
1390
1430
  );
1391
1431
 
1392
- return {
1432
+ const client: HogsendClient = {
1393
1433
  env,
1394
1434
  logger,
1395
1435
  db,
@@ -1410,6 +1450,10 @@ export function createHogsendClient(
1410
1450
  identity,
1411
1451
  registry,
1412
1452
  journeySources: getJourneySources(),
1453
+ journeyConstants: {
1454
+ templates: opts.journeyConstants?.templates ?? {},
1455
+ events: opts.journeyConstants?.events ?? {},
1456
+ },
1413
1457
  journeySourceLocations: getJourneySourceLocations(),
1414
1458
  bucketRegistry,
1415
1459
  listRegistry,
@@ -1421,4 +1465,35 @@ export function createHogsendClient(
1421
1465
  clientJournal: opts.clientJournal ?? { entries: [] },
1422
1466
  defaults,
1423
1467
  };
1468
+
1469
+ // Boot-time reader for `hogsend connect posthog`'s persisted phc_: when no
1470
+ // provider resolved AND no POSTHOG_API_KEY is set, activate PostHog from the
1471
+ // stored derived credential (async, fire-and-forget — the container is built
1472
+ // synchronously; a failure leaves the container exactly as booted). ALL
1473
+ // activation effects live here, in one block, so "who mutates what" has a
1474
+ // single answer. Skipped under NODE_ENV=test so suites stay hermetic.
1475
+ if (!analytics && !env.POSTHOG_API_KEY && env.NODE_ENV !== "test") {
1476
+ void buildStoredPosthogProvider({ env, db, logger })
1477
+ .then((provider) => {
1478
+ if (!provider) return;
1479
+ // Someone claimed the slot while we read (consumer provider, race).
1480
+ if (client.analytics || analyticsProviders.get("posthog")) return;
1481
+ analyticsProviders.register(provider);
1482
+ client.analytics = provider;
1483
+ setAnalytics(provider);
1484
+ // Rebuild the boot closure that captured `analytics: undefined` so
1485
+ // identity merges propagate to the newly-live provider too.
1486
+ client.identity = createIdentityService({
1487
+ db,
1488
+ analytics: provider,
1489
+ logger,
1490
+ });
1491
+ logger.info(
1492
+ 'analytics provider "posthog" activated from the stored `hogsend connect posthog` credential — outbound capture is live without POSTHOG_API_KEY.',
1493
+ );
1494
+ })
1495
+ .catch(() => {});
1496
+ }
1497
+
1498
+ return client;
1424
1499
  }
@@ -120,8 +120,12 @@ interface Raw {
120
120
  timeout?: Record<string, number>;
121
121
  eventLiteral?: string;
122
122
  eventIdent?: string;
123
+ /** OBJECT qualifier of an `X.PROP` event member-expr (`Events.NPS` → "Events"). */
124
+ eventObject?: string;
123
125
  templateLiteral?: string;
124
126
  templateIdent?: string;
127
+ /** OBJECT qualifier of an `X.PROP` template member-expr (`Templates.WELCOME` → "Templates"). */
128
+ templateObject?: string;
125
129
  connectorId?: string;
126
130
  action?: string;
127
131
  idempotencyLabel?: string;
@@ -129,16 +133,31 @@ interface Raw {
129
133
  calleeName?: string;
130
134
  }
131
135
 
136
+ /**
137
+ * The consumer's `Templates`/`Events` `as const` maps (`CONST_NAME -> "value"`),
138
+ * threaded through so `Templates.X` / `Events.X` member expressions in a
139
+ * journey's source resolve to their REAL runtime values. This is what makes the
140
+ * derived node ids deterministic (stable `wait-event:${value}` / `digest:${value}`
141
+ * ids that join to `journeyStates.currentNodeId`) and populates `meta.template` /
142
+ * `meta.event` for exact previews — with NO other extraction changes.
143
+ */
144
+ export interface JourneyGraphConsts {
145
+ templates?: Record<string, string>;
146
+ events?: Record<string, string>;
147
+ }
148
+
132
149
  export function buildJourneyGraph({
133
150
  runSource,
134
151
  meta,
152
+ consts,
135
153
  }: {
136
154
  runSource?: string;
137
155
  meta: JourneyMeta;
156
+ consts?: JourneyGraphConsts;
138
157
  }): JourneyGraph {
139
158
  if (!runSource) return degradedGraphFromMeta(meta);
140
159
  try {
141
- return extract(runSource, meta);
160
+ return extract(runSource, meta, consts);
142
161
  } catch {
143
162
  return degradedGraphFromMeta(meta);
144
163
  }
@@ -165,7 +184,57 @@ export function degradedGraphFromMeta(meta: JourneyMeta): JourneyGraph {
165
184
  };
166
185
  }
167
186
 
168
- function extract(runSource: string, meta: JourneyMeta): JourneyGraph {
187
+ /**
188
+ * Deterministic const-resolution pass: for each raw whose template/event slot
189
+ * is a member-expr IDENTIFIER (`Templates.DOCS_WELCOME` → ident `DOCS_WELCOME`)
190
+ * but has no literal, fill the literal from the matching const map value. Only
191
+ * fills from the ident (never overwrites an existing literal) and only for own,
192
+ * non-empty-string entries — so prototype keys can't leak in. Filling the
193
+ * literal is enough: the node builders already prefer the literal for the id,
194
+ * `meta`, subtitle, and the `unstable` flag, so everything downstream becomes
195
+ * deterministic with no other change.
196
+ *
197
+ * The fill is GATED on the OBJECT qualifier being the conventional const-object
198
+ * name — `Templates` for templates, `Events` for events (the documented
199
+ * consumer convention: CLAUDE.md's `Templates`/`Events` `as const` maps + the
200
+ * create-hogsend scaffold). This prevents a property-name collision — e.g. an
201
+ * unrelated `SomeEnum.SUBMITTED` whose `SUBMITTED` key also lives in the events
202
+ * map but maps to a different value — from confidently resolving to a WRONG
203
+ * literal. An aliased/non-conventional object name degrades gracefully to the
204
+ * pre-fill fallback (positional id / heuristic) instead of risking a wrong value.
205
+ */
206
+ function resolveRawConsts(raws: Raw[], consts?: JourneyGraphConsts): void {
207
+ if (!consts) return;
208
+ const fill = (
209
+ map: Record<string, string> | undefined,
210
+ ident: string | undefined,
211
+ ): string | undefined => {
212
+ if (!map || ident === undefined || !Object.hasOwn(map, ident)) {
213
+ return undefined;
214
+ }
215
+ const value = map[ident];
216
+ return typeof value === "string" && value.length > 0 ? value : undefined;
217
+ };
218
+ for (const raw of raws) {
219
+ if (
220
+ raw.templateLiteral === undefined &&
221
+ raw.templateObject === "Templates"
222
+ ) {
223
+ const value = fill(consts.templates, raw.templateIdent);
224
+ if (value !== undefined) raw.templateLiteral = value;
225
+ }
226
+ if (raw.eventLiteral === undefined && raw.eventObject === "Events") {
227
+ const value = fill(consts.events, raw.eventIdent);
228
+ if (value !== undefined) raw.eventLiteral = value;
229
+ }
230
+ }
231
+ }
232
+
233
+ function extract(
234
+ runSource: string,
235
+ meta: JourneyMeta,
236
+ consts?: JourneyGraphConsts,
237
+ ): JourneyGraph {
169
238
  const wrapped = `(${runSource})`;
170
239
  const ast = acorn.parse(wrapped, {
171
240
  ecmaVersion: "latest",
@@ -190,6 +259,11 @@ function extract(runSource: string, meta: JourneyMeta): JourneyGraph {
190
259
  });
191
260
  raws.sort((a, b) => a.start - b.start);
192
261
 
262
+ // Resolve `Templates.X` / `Events.X` member-expr idents to their real runtime
263
+ // values from the consumer's const maps BEFORE id assignment, so the node
264
+ // builders (which already prefer the literal) mint deterministic ids + meta.
265
+ resolveRawConsts(raws, consts);
266
+
193
267
  // --- Pass B: assign ids (A2 join-key rules) ---
194
268
  const emitted = assignNodes(raws, meta.trigger.event);
195
269
  dedupeIds(emitted);
@@ -316,6 +390,21 @@ function lastIdentOf(node: Node | undefined): string | undefined {
316
390
  return undefined;
317
391
  }
318
392
 
393
+ /**
394
+ * The OBJECT identifier of a simple `Object.PROP` member expression
395
+ * (`Templates.DOCS_WELCOME` → "Templates", `Events.NPS_SUBMITTED` → "Events").
396
+ * Returns undefined for anything that isn't `<plain Identifier>.<prop>` —
397
+ * nested member exprs (`Foo.Bar.BAZ`), computed access (`Map[k]`), or a bare
398
+ * identifier. Used to gate const resolution on the CONVENTIONAL object name so a
399
+ * property-name collision on an unrelated enum can't resolve to a wrong value.
400
+ */
401
+ function objectIdentOf(node: Node | undefined): string | undefined {
402
+ if (!node || node.type !== "MemberExpression" || node.computed) {
403
+ return undefined;
404
+ }
405
+ return node.object.type === "Identifier" ? node.object.name : undefined;
406
+ }
407
+
319
408
  function objectProp(
320
409
  obj: acorn.ObjectExpression,
321
410
  key: string,
@@ -536,6 +625,7 @@ function ctxNodeFields(
536
625
  labelUnstable: label?.unstable,
537
626
  eventLiteral: stringLiteral(eventNode),
538
627
  eventIdent: lastIdentOf(eventNode),
628
+ eventObject: objectIdentOf(eventNode),
539
629
  timeout: arg ? extractDuration(objectProp(arg, "timeout")) : undefined,
540
630
  };
541
631
  }
@@ -549,6 +639,7 @@ function ctxNodeFields(
549
639
  labelUnstable: label?.unstable,
550
640
  eventLiteral: stringLiteral(eventNode),
551
641
  eventIdent: lastIdentOf(eventNode),
642
+ eventObject: objectIdentOf(eventNode),
552
643
  duration: arg ? extractDuration(objectProp(arg, "window")) : undefined,
553
644
  };
554
645
  }
@@ -558,6 +649,7 @@ function ctxNodeFields(
558
649
  kind,
559
650
  eventLiteral: stringLiteral(eventNode),
560
651
  eventIdent: lastIdentOf(eventNode),
652
+ eventObject: objectIdentOf(eventNode),
561
653
  };
562
654
  }
563
655
 
@@ -568,6 +660,7 @@ function sendFields(arg: acorn.ObjectExpression): ClassifiedFields {
568
660
  kind: "send",
569
661
  templateLiteral: stringLiteral(templateNode),
570
662
  templateIdent: lastIdentOf(templateNode),
663
+ templateObject: objectIdentOf(templateNode),
571
664
  // Only a literal idempotencyLabel is a stable id "site".
572
665
  idempotencyLabel: idem && !idem.unstable ? idem.value : undefined,
573
666
  };
@@ -2,11 +2,13 @@ import type { AnalyticsProvider } from "@hogsend/core";
2
2
  import type { Database } from "@hogsend/db";
3
3
  import {
4
4
  createPostHogProvider,
5
+ deriveIngestHost,
5
6
  type PostHogAuthTokenAccessor,
6
7
  } from "@hogsend/plugin-posthog";
7
8
  import type { env as envSchema } from "../env.js";
8
9
  import type { Logger } from "./logger.js";
9
10
  import { createTokenManager } from "./oauth-token-manager.js";
11
+ import { getDerivedCredential } from "./provider-credentials.js";
10
12
  import { getRedis } from "./redis.js";
11
13
 
12
14
  /**
@@ -28,52 +30,113 @@ export function analyticsProvidersFromEnv(
28
30
  const providers: AnalyticsProvider[] = [];
29
31
 
30
32
  if (env.POSTHOG_API_KEY) {
31
- // Token-manager-backed accessor: the manager re-checks the DB (30s
32
- // negative cache), so a credential stored at RUNTIME via
33
- // `hogsend connect posthog` comes alive without a restart.
34
- let authToken: PostHogAuthTokenAccessor | undefined;
35
- if (deps?.db) {
36
- const tokenManager = createTokenManager({
37
- db: deps.db,
38
- providerId: "posthog",
39
- logger: deps.logger,
40
- });
41
- // Load-only warm-up (no refresh, never blocks construction). The
42
- // person-reads nudge logs HERE, after the load settles — the container
43
- // can't log it truthfully at boot because capabilities resolve async
44
- // for OAuth-capable providers (a connected instance would otherwise
45
- // log "DISABLED" once on every boot).
46
- const personalKeySet = Boolean(env.POSTHOG_PERSONAL_API_KEY);
47
- void tokenManager
48
- .prime()
49
- .then(() => {
50
- if (!personalKeySet && tokenManager.credentialState() !== "present") {
51
- deps.logger?.info(
52
- 'analytics provider "posthog" has person reads DISABLED — ' +
53
- "timezone resolution falls back to contact properties. Set " +
54
- "POSTHOG_PERSONAL_API_KEY or run `hogsend connect posthog`. " +
55
- "Docs: https://hogsend.com/docs/guides/analytics-access",
56
- );
57
- }
58
- })
59
- .catch(() => {});
60
- authToken = {
61
- getToken: () => tokenManager.getAccessToken(),
62
- isAvailable: () => tokenManager.credentialState() === "present",
63
- };
64
- }
65
33
  providers.push(
66
- createPostHogProvider({
67
- apiKey: env.POSTHOG_API_KEY,
68
- host: env.POSTHOG_HOST,
69
- personalApiKey: env.POSTHOG_PERSONAL_API_KEY,
70
- projectId: env.POSTHOG_PROJECT_ID,
71
- privateHost: env.POSTHOG_PRIVATE_HOST,
72
- redis: getRedis(),
73
- authToken,
74
- }),
34
+ buildPosthogProvider(env, deps, { apiKey: env.POSTHOG_API_KEY }),
75
35
  );
76
36
  }
77
37
 
78
38
  return providers;
79
39
  }
40
+
41
+ /**
42
+ * Construct the PostHog provider with the token-manager-backed OAuth accessor.
43
+ * Shared by the env preset above (`POSTHOG_API_KEY`) and the stored-credential
44
+ * activation below (`hogsend connect posthog`'s persisted phc_). Env values
45
+ * win over `source` overrides so a hand-set var still takes precedence.
46
+ */
47
+ function buildPosthogProvider(
48
+ env: typeof envSchema,
49
+ deps: { db?: Database; logger?: Logger } | undefined,
50
+ source: {
51
+ apiKey: string;
52
+ host?: string;
53
+ projectId?: string;
54
+ privateHost?: string;
55
+ },
56
+ ): AnalyticsProvider {
57
+ // Token-manager-backed accessor: the manager re-checks the DB (30s
58
+ // negative cache), so a credential stored at RUNTIME via
59
+ // `hogsend connect posthog` comes alive without a restart.
60
+ let authToken: PostHogAuthTokenAccessor | undefined;
61
+ if (deps?.db) {
62
+ const tokenManager = createTokenManager({
63
+ db: deps.db,
64
+ providerId: "posthog",
65
+ logger: deps.logger,
66
+ });
67
+ // Load-only warm-up (no refresh, never blocks construction). The
68
+ // person-reads nudge logs HERE, after the load settles — the container
69
+ // can't log it truthfully at boot because capabilities resolve async
70
+ // for OAuth-capable providers (a connected instance would otherwise
71
+ // log "DISABLED" once on every boot).
72
+ const personalKeySet = Boolean(env.POSTHOG_PERSONAL_API_KEY);
73
+ void tokenManager
74
+ .prime()
75
+ .then(() => {
76
+ if (!personalKeySet && tokenManager.credentialState() !== "present") {
77
+ deps.logger?.info(
78
+ 'analytics provider "posthog" has person reads DISABLED — ' +
79
+ "timezone resolution falls back to contact properties. Set " +
80
+ "POSTHOG_PERSONAL_API_KEY or run `hogsend connect posthog`. " +
81
+ "Docs: https://hogsend.com/docs/guides/analytics-access",
82
+ );
83
+ }
84
+ })
85
+ .catch(() => {});
86
+ authToken = {
87
+ getToken: () => tokenManager.getAccessToken(),
88
+ isAvailable: () => tokenManager.credentialState() === "present",
89
+ };
90
+ }
91
+ return createPostHogProvider({
92
+ apiKey: source.apiKey,
93
+ host: env.POSTHOG_HOST ?? source.host,
94
+ personalApiKey: env.POSTHOG_PERSONAL_API_KEY,
95
+ projectId: env.POSTHOG_PROJECT_ID ?? source.projectId,
96
+ privateHost: env.POSTHOG_PRIVATE_HOST ?? source.privateHost,
97
+ redis: getRedis(),
98
+ authToken,
99
+ });
100
+ }
101
+
102
+ /**
103
+ * Boot-time reader for the phc_ persisted by `hogsend connect posthog`
104
+ * (provider_credentials kind="derived", `projectApiKey`): a PURE builder —
105
+ * reads the stored credential and constructs the PostHog provider from it, or
106
+ * resolves null when there is nothing stored (or it can't be decrypted, which
107
+ * must behave exactly like "unconfigured"). ALL activation side effects
108
+ * (registry, `client.analytics`, the module singleton, identity rebind) live
109
+ * at the single call site in `container.ts`. Without this reader the
110
+ * persisted key is dead weight and outbound capture silently keeps requiring
111
+ * a hand-pasted env var.
112
+ *
113
+ * The capture host resolves env-first, then the ingestion host derived from
114
+ * the stored PRIVATE host (`eu.posthog.com` → `eu.i.posthog.com`) so an
115
+ * EU-connected instance never captures to the US default.
116
+ */
117
+ export async function buildStoredPosthogProvider(opts: {
118
+ env: typeof envSchema;
119
+ db: Database;
120
+ logger: Logger;
121
+ }): Promise<AnalyticsProvider | null> {
122
+ let derived: Awaited<ReturnType<typeof getDerivedCredential>>;
123
+ try {
124
+ derived = await getDerivedCredential(opts.db, "posthog");
125
+ } catch {
126
+ return null;
127
+ }
128
+ if (!derived?.projectApiKey) return null;
129
+
130
+ return buildPosthogProvider(
131
+ opts.env,
132
+ { db: opts.db, logger: opts.logger },
133
+ {
134
+ apiKey: derived.projectApiKey,
135
+ projectId: derived.projectId,
136
+ privateHost: derived.privateHost,
137
+ host: derived.privateHost
138
+ ? deriveIngestHost(derived.privateHost)
139
+ : undefined,
140
+ },
141
+ );
142
+ }
@@ -5,12 +5,14 @@
5
5
  * so future read/write features activate without forcing a reconnect. Every
6
6
  * name is validated against PostHog's published `scopes_supported`.
7
7
  *
8
- * LOCKSTEP (3 places — no single importable source of truth, the CLI has no
9
- * engine dependency): this constant, the CLI's `POSTHOG_SCOPES`
10
- * (`packages/cli/src/lib/oauth.ts`), and the `scope` field of the hosted CIMD
11
- * document (`apps/docs/public/.well-known/hogsend-posthog-client.json`).
12
- * PostHog gates the scopes it will grant by the CIMD doc, so grep all three
13
- * and keep them identical before changing any of them.
8
+ * LOCKSTEP (3 places): this constant, the CLI's `POSTHOG_SCOPES`
9
+ * (`packages/cli/src/lib/oauth.ts` — the CLI avoids the engine ROOT import
10
+ * because the barrel does import-time env validation, but this module is
11
+ * dependency-free and exported as the `@hogsend/engine/posthog-scopes`
12
+ * subpath), and the `scope` field of the hosted CIMD document
13
+ * (`apps/docs/public/.well-known/hogsend-posthog-client.json`) — that one is
14
+ * genuinely un-importable. PostHog gates the scopes it will grant by the CIMD
15
+ * doc, so grep all three and keep them identical before changing any of them.
14
16
  */
15
17
  export const EXPECTED_POSTHOG_SCOPES: string[] = [
16
18
  "person:read",
@@ -27,3 +29,25 @@ export const EXPECTED_POSTHOG_SCOPES: string[] = [
27
29
  "event_definition:read",
28
30
  "property_definition:read",
29
31
  ];
32
+
33
+ /**
34
+ * PostHog's scope model is hierarchical — `X:write` implies `X:read` — and
35
+ * the grant NORMALIZES a request for both halves down to `X:write` alone. A
36
+ * literal set-difference against the requested list therefore reports the
37
+ * implied `:read` halves as "missing" on every fully-successful consent
38
+ * (e.g. person:read, hog_function:read, cohort:read). Treat a requested
39
+ * `X:read` as satisfied when the grant carries `X:write`.
40
+ *
41
+ * The CLI imports this via the `@hogsend/engine/posthog-scopes` subpath —
42
+ * single implementation, no mirror.
43
+ */
44
+ export function posthogScopeSatisfied(
45
+ granted: string[],
46
+ scope: string,
47
+ ): boolean {
48
+ return (
49
+ granted.includes(scope) ||
50
+ (scope.endsWith(":read") &&
51
+ granted.includes(scope.replace(/:read$/, ":write")))
52
+ );
53
+ }
@@ -46,8 +46,21 @@ export interface ProvisionPostHogLoopOptions {
46
46
  logger: Logger;
47
47
  /** Display name for a NEWLY created function. Default: MANAGED_NAME. */
48
48
  name?: string;
49
+ /**
50
+ * Placeholder mode (local instances PostHog can't reach): provision the
51
+ * destination DISABLED, pointing at the obvious stand-in
52
+ * `https://CHANGEME.yourdomain.com/...` instead of `apiPublicUrl`. The
53
+ * destination then EXISTS in PostHog — name, filters, secret header, all
54
+ * inspectable — with zero failed deliveries. Going live after deploy is one
55
+ * re-run WITHOUT this flag (`--provision-only --url https://real`): the
56
+ * reconciler swaps the URL and re-enables in a single PATCH.
57
+ */
58
+ placeholder?: boolean;
49
59
  }
50
60
 
61
+ /** The stand-in base URL placeholder mode provisions against. */
62
+ export const PLACEHOLDER_PUBLIC_URL = "https://CHANGEME.yourdomain.com";
63
+
51
64
  export interface ProvisionPostHogLoopResult {
52
65
  action: "created" | "updated" | "unchanged";
53
66
  /** Hog function UUID. */
@@ -64,6 +77,8 @@ export interface ProvisionPostHogLoopResult {
64
77
  projectApiKey?: string;
65
78
  /** Best-effort deep link (pattern unverified — cosmetic, confirm in e2e). */
66
79
  dashboardUrl: string;
80
+ /** false ⇒ placeholder mode: disabled destination, CHANGEME URL. */
81
+ enabled: boolean;
67
82
  }
68
83
 
69
84
  export type ProvisionPostHogLoopErrorCode =
@@ -243,6 +258,8 @@ interface HogFunctionDetail {
243
258
  interface DesiredLoop {
244
259
  webhookUrl: string;
245
260
  webhookSecret: string;
261
+ /** false only in placeholder mode — see ProvisionPostHogLoopOptions. */
262
+ enabled: boolean;
246
263
  }
247
264
 
248
265
  /**
@@ -266,7 +283,11 @@ export async function provisionPostHogLoop(
266
283
  });
267
284
  }
268
285
 
269
- const webhookUrl = joinUrl(apiPublicUrl, HOGSEND_LOOP_PATH);
286
+ const placeholder = opts.placeholder === true;
287
+ const webhookUrl = joinUrl(
288
+ placeholder ? PLACEHOLDER_PUBLIC_URL : apiPublicUrl,
289
+ HOGSEND_LOOP_PATH,
290
+ );
270
291
  const hostname = tryParseUrl(webhookUrl)?.hostname;
271
292
  if (hostname === "localhost" || hostname === "127.0.0.1") {
272
293
  logger.warn(
@@ -282,7 +303,11 @@ export async function provisionPostHogLoop(
282
303
  });
283
304
 
284
305
  const basePath = `/api/environments/${projectId}/hog_functions/`;
285
- const desired: DesiredLoop = { webhookUrl, webhookSecret };
306
+ const desired: DesiredLoop = {
307
+ webhookUrl,
308
+ webhookSecret,
309
+ enabled: !placeholder,
310
+ };
286
311
 
287
312
  const found = await findLoopFunction({ privateHost, accessToken, basePath });
288
313
 
@@ -339,6 +364,7 @@ export async function provisionPostHogLoop(
339
364
  dashboardUrl:
340
365
  `${privateHost.replace(/\/+$/, "")}/project/${projectId}` +
341
366
  `/pipeline/destinations/hog-${functionId}/configuration`,
367
+ enabled: desired.enabled,
342
368
  };
343
369
  }
344
370
 
@@ -562,7 +588,7 @@ async function findLoopFunction(opts: {
562
588
 
563
589
  /** true ⇒ no PATCH needed. */
564
590
  function isCompliant(fn: HogFunctionDetail, desired: DesiredLoop): boolean {
565
- if (fn.enabled !== true) return false;
591
+ if (fn.enabled !== desired.enabled) return false;
566
592
  if (inputValue(fn.inputs, "url") !== desired.webhookUrl) return false;
567
593
  if (inputValue(fn.inputs, "method") !== "POST") return false;
568
594
  if (!deepEquals(inputValue(fn.inputs, "body"), CANONICAL_BODY)) return false;
@@ -614,7 +640,7 @@ function buildCreatePayload(
614
640
  name: name ?? MANAGED_NAME,
615
641
  description: MANAGED_DESCRIPTION,
616
642
  template_id: "template-webhook",
617
- enabled: true,
643
+ enabled: desired.enabled,
618
644
  inputs: {
619
645
  url: { value: desired.webhookUrl },
620
646
  method: { value: "POST" },
@@ -636,11 +662,12 @@ function buildCreatePayload(
636
662
 
637
663
  /**
638
664
  * Reconciled PATCH body: enforce what we manage, preserve the rest.
639
- * `enabled: true` always — connect is an explicit operator action, so
640
- * re-enabling a paused loop is the expected outcome. PostHog replaces
641
- * `inputs` WHOLESALE on PATCH (verified), so all five keys are always
642
- * sent. `name`/`description` are never touched on adopt — the operator
643
- * may have renamed deliberately.
665
+ * `enabled` follows `desired` — true on a real provision (connect is an
666
+ * explicit operator action, so re-enabling a paused loop is the expected
667
+ * outcome), false in placeholder mode (a CHANGEME URL must never receive
668
+ * deliveries). PostHog replaces `inputs` WHOLESALE on PATCH (verified), so
669
+ * all five keys are always sent. `name`/`description` are never touched on
670
+ * adopt — the operator may have renamed deliberately.
644
671
  */
645
672
  function buildUpdatePayload(
646
673
  fn: HogFunctionDetail,
@@ -665,7 +692,7 @@ function buildUpdatePayload(
665
692
  filters.properties = properties;
666
693
 
667
694
  const payload: Record<string, unknown> = {
668
- enabled: true,
695
+ enabled: desired.enabled,
669
696
  inputs: {
670
697
  url: { value: desired.webhookUrl },
671
698
  method: { value: "POST" },
@@ -0,0 +1,45 @@
1
+ import { defineEmailProvider } from "@hogsend/core";
2
+
3
+ /**
4
+ * The inert email provider a container boots with when NO provider is
5
+ * configured and none was explicitly requested (mirrors the SMS channel's
6
+ * operator-opt-in posture: unconfigured ⇒ inert stub, not a boot crash).
7
+ *
8
+ * A fresh scaffold has no RESEND_API_KEY yet — it should still boot, serve
9
+ * Studio, ingest events and run non-email journeys. Every email send fails
10
+ * per-call with this actionable message instead; the container logs one boot
11
+ * warning. Never registered in the provider registry, so no webhook route
12
+ * resolves it.
13
+ *
14
+ * DELIBERATE seam choice (vs SMS's service-level stub): the stub is the WIRE
15
+ * inside the real tracked mailer, so an unconfigured send still runs the
16
+ * pipeline (preferences → render → tracking → `email_sends` write) and fails
17
+ * at dispatch — leaving a failed-send row visible in Studio, which is exactly
18
+ * the operator-facing breadcrumb a "why didn't my email go out?" moment needs.
19
+ */
20
+ export const UNCONFIGURED_EMAIL_MESSAGE =
21
+ "no email provider configured — set RESEND_API_KEY (or POSTMARK_SERVER_TOKEN " +
22
+ "with EMAIL_PROVIDER=postmark), or pass `email: { provider }` to " +
23
+ "createHogsendClient().";
24
+
25
+ export function createUnconfiguredEmailProvider() {
26
+ return defineEmailProvider({
27
+ meta: {
28
+ id: "unconfigured",
29
+ name: "No email provider configured",
30
+ },
31
+ capabilities: {},
32
+ async send() {
33
+ throw new Error(UNCONFIGURED_EMAIL_MESSAGE);
34
+ },
35
+ async sendBatch() {
36
+ throw new Error(UNCONFIGURED_EMAIL_MESSAGE);
37
+ },
38
+ verifyWebhook() {
39
+ throw new Error(UNCONFIGURED_EMAIL_MESSAGE);
40
+ },
41
+ parseWebhook() {
42
+ throw new Error(UNCONFIGURED_EMAIL_MESSAGE);
43
+ },
44
+ });
45
+ }
@@ -3,7 +3,10 @@ import { DEFAULT_HOST, derivePrivateHost } from "@hogsend/plugin-posthog";
3
3
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
4
4
  import type { AppEnv } from "../../app.js";
5
5
  import { createTokenManager } from "../../lib/oauth-token-manager.js";
6
- import { EXPECTED_POSTHOG_SCOPES } from "../../lib/posthog-scopes.js";
6
+ import {
7
+ EXPECTED_POSTHOG_SCOPES,
8
+ posthogScopeSatisfied,
9
+ } from "../../lib/posthog-scopes.js";
7
10
  import {
8
11
  getDerivedCredential,
9
12
  getProviderCredential,
@@ -120,6 +123,8 @@ const provisionLoopResponseSchema = z.object({
120
123
  hogFunctionId: z.string(),
121
124
  webhookUrl: z.string(),
122
125
  dashboardUrl: z.string(),
126
+ /** false ⇒ placeholder mode: destination is DISABLED with a CHANGEME URL. */
127
+ enabled: z.boolean(),
123
128
  });
124
129
 
125
130
  const provisionFailureSchema = z.object({
@@ -154,6 +159,12 @@ const provisionLoopRoute = createRoute({
154
159
  path: "/provision-loop",
155
160
  tags: ["Admin — Analytics"],
156
161
  summary: "Provision the PostHog → Hogsend event loop (webhook destination)",
162
+ request: {
163
+ // `?placeholder=true` — pre-create the destination DISABLED with the
164
+ // CHANGEME stand-in URL (for local instances PostHog can't reach). A
165
+ // query param (not a body) keeps older CLIs' bare POST byte-compatible.
166
+ query: z.object({ placeholder: z.enum(["true", "false"]).optional() }),
167
+ },
157
168
  responses: {
158
169
  200: {
159
170
  content: {
@@ -202,8 +213,12 @@ export const analyticsAdminRouter = new OpenAPIHono<AppEnv>()
202
213
  try {
203
214
  const oauth = await getProviderCredential(db, "posthog");
204
215
  if (oauth) {
216
+ // Hierarchical scopes: a granted `X:write` satisfies `X:read` (the
217
+ // grant normalizes both-halves requests down to write-only).
205
218
  const granted = oauth.payload.scopes;
206
- scopeGap = EXPECTED_POSTHOG_SCOPES.filter((s) => !granted.includes(s));
219
+ scopeGap = EXPECTED_POSTHOG_SCOPES.filter(
220
+ (s) => !posthogScopeSatisfied(granted, s),
221
+ );
207
222
  }
208
223
  } catch {
209
224
  scopeGap = [];
@@ -217,6 +232,7 @@ export const analyticsAdminRouter = new OpenAPIHono<AppEnv>()
217
232
  .openapi(provisionLoopRoute, async (c) => {
218
233
  const { db, env, logger } = c.get("container");
219
234
  const info = resolveConnectInfo(env);
235
+ const placeholder = c.req.valid("query").placeholder === "true";
220
236
 
221
237
  // Credential check FIRST (M3), secret refusal second (enforced by the
222
238
  // provisioner itself). The container does NOT expose the token manager
@@ -245,7 +261,9 @@ export const analyticsAdminRouter = new OpenAPIHono<AppEnv>()
245
261
  // PostHog Cloud cannot deliver webhooks to a loopback address — and a
246
262
  // local instance with a misconfigured API_PUBLIC_URL must never repoint
247
263
  // a production destination at localhost. Refuse BEFORE any PostHog call.
248
- if (isLoopbackPublicUrl(info.apiPublicUrl)) {
264
+ // Placeholder mode is exempt: it never uses apiPublicUrl (the destination
265
+ // is created DISABLED against the CHANGEME stand-in URL).
266
+ if (!placeholder && isLoopbackPublicUrl(info.apiPublicUrl)) {
249
267
  return c.json(
250
268
  {
251
269
  error: "api_public_url_unreachable",
@@ -290,12 +308,15 @@ export const analyticsAdminRouter = new OpenAPIHono<AppEnv>()
290
308
  apiPublicUrl: info.apiPublicUrl,
291
309
  webhookSecret,
292
310
  logger,
311
+ placeholder,
293
312
  });
294
313
 
295
314
  // Opportunistically persist the phc_ (project api_token) the provisioner
296
- // read on its way through — it powers the OPTIONAL outbound capture path
297
- // and activates on the next deploy (no lazy boot-time seam). Re-read the
298
- // stored payload to merge over the just-persisted webhook secret.
315
+ // read on its way through — it powers the OPTIONAL outbound capture path.
316
+ // `activateStoredPosthogAnalytics` (container boot) reads it back, so
317
+ // capture comes alive on the next boot with NO hand-pasted
318
+ // POSTHOG_API_KEY. Re-read the stored payload to merge over the
319
+ // just-persisted webhook secret.
299
320
  if (result.projectApiKey) {
300
321
  const cur = (await getDerivedCredential(db, "posthog")) ?? {};
301
322
  await saveDerivedCredential(db, "posthog", {
@@ -316,6 +337,7 @@ export const analyticsAdminRouter = new OpenAPIHono<AppEnv>()
316
337
  hogFunctionId: result.functionId,
317
338
  webhookUrl: result.webhookUrl,
318
339
  dashboardUrl: result.dashboardUrl,
340
+ enabled: result.enabled,
319
341
  },
320
342
  200,
321
343
  );
@@ -2,6 +2,7 @@ import { contacts, userEvents } from "@hogsend/db";
2
2
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
3
  import { and, count, desc, eq, gte, isNull, lte, or, sql } from "drizzle-orm";
4
4
  import type { AppEnv } from "../../app.js";
5
+ import type { HogsendClient } from "../../container.js";
5
6
  import {
6
7
  eventNameEntrySchema,
7
8
  listEventNameVocabulary,
@@ -16,8 +17,8 @@ const eventSchema = z.object({
16
17
  occurredAt: z.string(),
17
18
  // Where the event entered the pipeline ("posthog", "api", "studio", …).
18
19
  source: z.string().nullable(),
19
- // Resolved from the matching live contact (user_events.userId ==
20
- // contacts.externalId), so the Events feed can show WHO an event is from.
20
+ // Resolved from THE live contact whose key (externalId, anonymousId, or
21
+ // id) matches user_events.userId — shows WHO an event is from.
21
22
  userEmail: z.string().nullable(),
22
23
  contactId: z.string().nullable(),
23
24
  });
@@ -45,21 +46,36 @@ function serializeEvent(row: JoinedEvent) {
45
46
  }
46
47
 
47
48
  /**
48
- * LEFT JOIN to the live contact for the userId. `userEvents.userId` holds the
49
- * resolved canonical key (`external_id ?? anonymous_id ?? id`), so match all
50
- * three — covering email-only/anonymous contacts, not just externalId-keyed
51
- * ones. Each key is partial-unique among live rows, and the three namespaces
52
- * don't overlap in practice, so at most one live contact matches per userId.
49
+ * LATERAL pick of THE live contact for an event's userId. `userEvents.userId`
50
+ * holds the resolved canonical key (`external_id ?? anonymous_id ?? id`), so
51
+ * match all three — covering email-only/anonymous contacts, not just
52
+ * externalId-keyed ones. Each column is partial-unique among live rows, but
53
+ * the three namespaces are NOT guaranteed disjoint across contacts: a
54
+ * mis-keyed emitter can park one contact's key in another contact's
55
+ * anonymous_id, and a bare OR-join then matches BOTH — fanning every event
56
+ * out into one display row per matching contact. The lateral picks exactly
57
+ * one, by the same precedence ingest resolves keys with.
53
58
  */
54
- const contactJoin = and(
55
- or(
56
- eq(contacts.externalId, userEvents.userId),
57
- eq(contacts.anonymousId, userEvents.userId),
58
- eq(sql`${contacts.id}::text`, userEvents.userId),
59
- ),
60
- isNull(contacts.deletedAt),
61
- );
62
- const contactCols = { id: contacts.id, email: contacts.email };
59
+ function liveContactFor(db: HogsendClient["db"]) {
60
+ return db
61
+ .select({ id: contacts.id, email: contacts.email })
62
+ .from(contacts)
63
+ .where(
64
+ and(
65
+ or(
66
+ eq(contacts.externalId, userEvents.userId),
67
+ eq(contacts.anonymousId, userEvents.userId),
68
+ eq(sql`${contacts.id}::text`, userEvents.userId),
69
+ ),
70
+ isNull(contacts.deletedAt),
71
+ ),
72
+ )
73
+ .orderBy(
74
+ sql`case when ${contacts.externalId} = ${userEvents.userId} then 0 when ${contacts.anonymousId} = ${userEvents.userId} then 1 else 2 end`,
75
+ )
76
+ .limit(1)
77
+ .as("live_contact");
78
+ }
63
79
 
64
80
  const listRoute = createRoute({
65
81
  method: "get",
@@ -234,11 +250,15 @@ export const eventsRouter = new OpenAPIHono<AppEnv>()
234
250
 
235
251
  const where = conditions.length > 0 ? and(...conditions) : undefined;
236
252
 
253
+ const liveContact = liveContactFor(db);
237
254
  const [rows, totalRows] = await Promise.all([
238
255
  db
239
- .select({ event: userEvents, contact: contactCols })
256
+ .select({
257
+ event: userEvents,
258
+ contact: { id: liveContact.id, email: liveContact.email },
259
+ })
240
260
  .from(userEvents)
241
- .leftJoin(contacts, contactJoin)
261
+ .leftJoinLateral(liveContact, sql`true`)
242
262
  .where(where)
243
263
  .orderBy(desc(userEvents.occurredAt))
244
264
  .limit(limit)
@@ -276,10 +296,14 @@ export const eventsRouter = new OpenAPIHono<AppEnv>()
276
296
  const { db } = c.get("container");
277
297
  const { id } = c.req.valid("param");
278
298
 
299
+ const liveContact = liveContactFor(db);
279
300
  const rows = await db
280
- .select({ event: userEvents, contact: contactCols })
301
+ .select({
302
+ event: userEvents,
303
+ contact: { id: liveContact.id, email: liveContact.email },
304
+ })
281
305
  .from(userEvents)
282
- .leftJoin(contacts, contactJoin)
306
+ .leftJoinLateral(liveContact, sql`true`)
283
307
  .where(eq(userEvents.id, id))
284
308
  .limit(1);
285
309
 
@@ -1,4 +1,8 @@
1
- import { type JourneyGraph, journeyGraphSchema } from "@hogsend/core";
1
+ import {
2
+ type JourneyGraph,
3
+ journeyGraphSchema,
4
+ resolveTemplateKeyFromConst,
5
+ } from "@hogsend/core";
2
6
  import {
3
7
  type Database,
4
8
  emailSends,
@@ -900,8 +904,14 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
900
904
  );
901
905
  })
902
906
  .openapi(graphRoute, async (c) => {
903
- const { db, registry, journeySources, journeySourceLocations, templates } =
904
- c.get("container");
907
+ const {
908
+ db,
909
+ registry,
910
+ journeySources,
911
+ journeySourceLocations,
912
+ journeyConstants,
913
+ templates,
914
+ } = c.get("container");
905
915
  const { id } = c.req.valid("param");
906
916
 
907
917
  const meta = registry.get(id);
@@ -914,7 +924,11 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
914
924
  // call-site (also static per process) is baked into the cached graph.
915
925
  let graph = journeyGraphCache.get(id);
916
926
  if (!graph) {
917
- graph = buildJourneyGraph({ runSource: journeySources.get(id), meta });
927
+ graph = buildJourneyGraph({
928
+ runSource: journeySources.get(id),
929
+ meta,
930
+ consts: journeyConstants,
931
+ });
918
932
  const source = journeySourceLocations.get(id);
919
933
  if (source) graph.source = source;
920
934
  journeyGraphCache.set(id, graph);
@@ -972,13 +986,13 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
972
986
  // the React Email component — no send data), so STATIC resolution is the
973
987
  // primary mechanism and a never-sent journey still previews. Priority:
974
988
  // (1) literal `meta.template` — already the registry key.
975
- // (2) STATIC exact: the node's `subtitle` is the Templates const name for
976
- // member-expr sends (`FEEDBACK_NPS_SURVEY`); lowercase + `_`→`-`
977
- // (`feedback-nps-survey`) and use it IFF that key is in the registry.
978
- // (2b) STATIC prefix: else the single LONGEST registry key that is a
979
- // segment-prefix of the kebab'd const name (`activation-nudge-series`
980
- // → `activation-nudge`). Only when that longest prefix is unique — a
981
- // wrong preview is worse than none, so an ambiguous tie stays unresolved.
989
+ // (2) STATIC segment match (`resolveTemplateKeyFromConst`): the node's
990
+ // `subtitle` is the Templates const name for member-expr sends
991
+ // (`FEEDBACK_NPS_SURVEY`, `DOCS_WELCOME`). Split it and each registry
992
+ // key on any of `/ _ -` and compare SEGMENTS, so slash-namespaced keys
993
+ // (`docs/welcome`) resolve too — else the unique longest segment-prefix
994
+ // key (`activation-nudge-series` → `activation-nudge`). Ambiguous ties
995
+ // stay unresolved — a wrong preview is worse than none.
982
996
  // (3) journey_logs rows (action='send') whose `to_node_id` is this send
983
997
  // node's site id (`send:<site>`), reading `detail.template` — site-
984
998
  // keyed, so two sends of one template on different branches stay
@@ -1010,31 +1024,12 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
1010
1024
  }
1011
1025
 
1012
1026
  // (2/2b) static const-name → registry key (no runtime data needed):
1013
- // exact kebab match, else the unique longest segment-prefix key.
1027
+ // separator-agnostic SEGMENT match, so slash-namespaced keys
1028
+ // (`docs/welcome`) resolve from `DOCS_WELCOME` just as hyphen ones do.
1014
1029
  const registryKeys = getTemplateNames(templates) as string[];
1015
- const registeredKeys = new Set<string>(registryKeys);
1016
- const resolveStatic = (constName: string): string | undefined => {
1017
- const kebab = constName.toLowerCase().replace(/_/g, "-");
1018
- if (registeredKeys.has(kebab)) return kebab;
1019
- // Longest registry key that is a segment-prefix of the kebab'd name.
1020
- let best: string | undefined;
1021
- let bestLen = -1;
1022
- let ambiguous = false;
1023
- for (const key of registryKeys) {
1024
- if (!kebab.startsWith(`${key}-`)) continue;
1025
- if (key.length > bestLen) {
1026
- best = key;
1027
- bestLen = key.length;
1028
- ambiguous = false;
1029
- } else if (key.length === bestLen) {
1030
- ambiguous = true;
1031
- }
1032
- }
1033
- return ambiguous ? undefined : best;
1034
- };
1035
1030
  for (const node of sendNodes) {
1036
1031
  if (nodeMetrics[node.id]?.templateKey || !node.subtitle) continue;
1037
- const key = resolveStatic(node.subtitle);
1032
+ const key = resolveTemplateKeyFromConst(node.subtitle, registryKeys);
1038
1033
  if (key) setTemplate(node.id, key);
1039
1034
  }
1040
1035