@hogsend/engine 0.46.1 → 0.50.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/README.md +6 -0
  2. package/package.json +13 -10
  3. package/src/connectors/presets/index.ts +8 -2
  4. package/src/container.ts +149 -7
  5. package/src/destinations/presets/posthog.ts +7 -0
  6. package/src/destinations/presets/segment.ts +5 -0
  7. package/src/env.ts +38 -0
  8. package/src/flags/reconcile.ts +195 -0
  9. package/src/index.ts +79 -0
  10. package/src/journeys/authoring.ts +32 -0
  11. package/src/journeys/define-journey.ts +45 -40
  12. package/src/journeys/execute-journey-run.ts +73 -32
  13. package/src/journeys/journey-boundary.ts +76 -0
  14. package/src/journeys/journey-context.ts +128 -70
  15. package/src/journeys/journey-task-factory.ts +31 -0
  16. package/src/journeys/journey-task-runtime.ts +31 -0
  17. package/src/journeys/journey-version.test.ts +236 -0
  18. package/src/journeys/journey-version.ts +158 -0
  19. package/src/journeys/record-once.ts +28 -2
  20. package/src/lib/connector-actions.test.ts +36 -0
  21. package/src/lib/connector-actions.ts +42 -4
  22. package/src/lib/contacts.ts +49 -0
  23. package/src/lib/conversions.test.ts +33 -0
  24. package/src/lib/conversions.ts +8 -0
  25. package/src/lib/email.ts +23 -2
  26. package/src/lib/enrollment-policy.ts +51 -0
  27. package/src/lib/feed.ts +55 -3
  28. package/src/lib/flags-registry.ts +48 -0
  29. package/src/lib/flags.ts +498 -0
  30. package/src/lib/fx.ts +374 -0
  31. package/src/lib/global-control-readout.ts +166 -0
  32. package/src/lib/groups.ts +362 -0
  33. package/src/lib/ingestion.ts +38 -0
  34. package/src/lib/journey-lift.ts +142 -0
  35. package/src/lib/operator-settings.ts +71 -0
  36. package/src/lib/outbound.ts +147 -0
  37. package/src/lib/preferences.ts +6 -80
  38. package/src/lib/recipient-preferences.ts +53 -0
  39. package/src/lib/sms.ts +21 -2
  40. package/src/lib/stable-stringify.test.ts +42 -0
  41. package/src/lib/stable-stringify.ts +23 -0
  42. package/src/lib/variant.ts +99 -0
  43. package/src/lib/webhook-signing.ts +16 -1
  44. package/src/lists/registry.ts +6 -2
  45. package/src/lists/subscription.ts +13 -0
  46. package/src/routes/admin/contacts.ts +53 -4
  47. package/src/routes/admin/conversions.ts +137 -0
  48. package/src/routes/admin/flags.ts +369 -0
  49. package/src/routes/admin/groups.ts +866 -0
  50. package/src/routes/admin/impact-schemas.ts +44 -0
  51. package/src/routes/admin/impact-wire.test.ts +181 -0
  52. package/src/routes/admin/impact.ts +486 -0
  53. package/src/routes/admin/index.ts +12 -0
  54. package/src/routes/admin/journey-impact.ts +446 -0
  55. package/src/routes/admin/journeys.ts +70 -100
  56. package/src/routes/admin/settings.ts +145 -0
  57. package/src/routes/admin/targeting.ts +256 -0
  58. package/src/routes/events/index.ts +11 -0
  59. package/src/routes/flags/index.ts +120 -0
  60. package/src/routes/groups/index.ts +417 -0
  61. package/src/routes/index.ts +23 -1
  62. package/src/testing.ts +25 -0
  63. package/src/webhook-sources/presets/index.ts +5 -1
  64. package/src/webhook-sources/presets/intercom.ts +230 -0
  65. package/src/webhook-sources/presets/segment.ts +56 -4
  66. package/src/worker.ts +3 -0
  67. package/src/workflows/bucket-backfill.ts +1 -14
  68. package/src/workflows/impact-digest.ts +761 -0
  69. package/src/workflows/journey-blueprint-interpreter.ts +18 -1
package/README.md CHANGED
@@ -5,6 +5,12 @@ The Hogsend framework: `createApp`, `createHogsendClient`, `createWorker`,
5
5
  built-in routes, and the registries. This is the public API surface consumers
6
6
  build their lifecycle apps on top of.
7
7
 
8
+ Journey definition modules should import `defineJourney`, duration helpers, and
9
+ outbound journey effects from `@hogsend/engine/journeys`. That authoring subpath
10
+ does not validate production environment variables, so the original module can
11
+ be loaded by `@hogsend/testing`; importing the main `@hogsend/engine` runtime in
12
+ the API or worker still attaches the real Hatchet task.
13
+
8
14
  The engine also re-exports the capability-provider contracts owned by
9
15
  `@hogsend/core` — `EmailProvider` and `PostHogService` (plus their supporting
10
16
  types) — so `@hogsend/engine` is the **canonical author import** for them when
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.46.1",
3
+ "version": "0.50.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -17,6 +17,8 @@
17
17
  "./create-admin": "./src/lib/create-admin.ts",
18
18
  "./api-key-hash": "./src/lib/api-key-hash.ts",
19
19
  "./posthog-scopes": "./src/lib/posthog-scopes.ts",
20
+ "./journeys": "./src/journeys/authoring.ts",
21
+ "./testing": "./src/testing.ts",
20
22
  "./mcp/authoring-guide": "./src/mcp/authoring-guide.ts",
21
23
  "./package.json": "./package.json"
22
24
  },
@@ -51,17 +53,17 @@
51
53
  "svix": "^1.95.1",
52
54
  "winston": "^3.19.0",
53
55
  "zod": "^4.4.3",
54
- "@hogsend/attribution": "^0.46.1",
55
- "@hogsend/core": "^0.46.1",
56
- "@hogsend/db": "^0.46.1",
57
- "@hogsend/email": "^0.46.1",
58
- "@hogsend/plugin-posthog": "^0.46.1",
59
- "@hogsend/plugin-resend": "^0.46.1",
60
- "@hogsend/sms": "^0.46.1"
56
+ "@hogsend/attribution": "^0.50.0",
57
+ "@hogsend/core": "^0.50.0",
58
+ "@hogsend/db": "^0.50.0",
59
+ "@hogsend/email": "^0.50.0",
60
+ "@hogsend/plugin-posthog": "^0.50.0",
61
+ "@hogsend/plugin-resend": "^0.50.0",
62
+ "@hogsend/sms": "^0.50.0"
61
63
  },
62
64
  "optionalDependencies": {
63
- "@hogsend/plugin-postmark": "^0.46.1",
64
- "@hogsend/plugin-twilio": "^0.46.1"
65
+ "@hogsend/plugin-postmark": "^0.50.0",
66
+ "@hogsend/plugin-twilio": "^0.50.0"
65
67
  },
66
68
  "devDependencies": {
67
69
  "@types/node": "^22.15.3",
@@ -73,6 +75,7 @@
73
75
  },
74
76
  "scripts": {
75
77
  "check-types": "tsc --noEmit",
78
+ "test": "tsx --test src/**/*.test.ts",
76
79
  "lint": "biome check .",
77
80
  "clean": "rm -rf node_modules .turbo"
78
81
  }
@@ -1,5 +1,8 @@
1
1
  import type { env as engineEnv } from "../../env.js";
2
- import { webhookSourceToConnector } from "../../webhook-sources/define-webhook-source.js";
2
+ import {
3
+ type DefinedWebhookSource,
4
+ webhookSourceToConnector,
5
+ } from "../../webhook-sources/define-webhook-source.js";
3
6
  import {
4
7
  PRESET_SOURCES,
5
8
  presetsFromEnv,
@@ -14,7 +17,10 @@ import type { DefinedConnector } from "../define-connector.js";
14
17
  */
15
18
  export const PRESET_CONNECTORS: Record<string, DefinedConnector> =
16
19
  Object.fromEntries(
17
- Object.values(PRESET_SOURCES).map((s) => [
20
+ // The registry is heterogeneous (`satisfies Record<string,
21
+ // DefinedWebhookSource>`); consume it at that declared type so a new preset
22
+ // whose payload shape diverges can't break union-inference on the lift.
23
+ (Object.values(PRESET_SOURCES) as DefinedWebhookSource[]).map((s) => [
18
24
  s.meta.id,
19
25
  webhookSourceToConnector(s),
20
26
  ]),
package/src/container.ts CHANGED
@@ -6,9 +6,11 @@ import type {
6
6
  CrmProvider,
7
7
  CrmStageMap,
8
8
  DefinedConversion,
9
+ DefinedFlag,
9
10
  DefinedFunnel,
10
11
  EmailProvider,
11
12
  FunnelStageEntry,
13
+ FxRateProvider,
12
14
  JourneySourceLocation,
13
15
  PostHogService,
14
16
  SmsProvider,
@@ -55,6 +57,7 @@ import {
55
57
  setDestinationRegistry,
56
58
  } from "./destinations/registry-singleton.js";
57
59
  import { env } from "./env.js";
60
+ import { reconcileDefinedFlags } from "./flags/reconcile.js";
58
61
  import { setClientScheduleDefaults } from "./journeys/client-defaults-singleton.js";
59
62
  import type { DefinedJourney } from "./journeys/define-journey.js";
60
63
  import { getJourneySourceLocations } from "./journeys/journey-source-locations-singleton.js";
@@ -97,7 +100,9 @@ import type {
97
100
  EmailService,
98
101
  FrequencyCapConfig,
99
102
  } from "./lib/email-service-types.js";
103
+ import { FlagRegistry, setFlagRegistry } from "./lib/flags-registry.js";
100
104
  import { FunnelRegistry } from "./lib/funnel-registry.js";
105
+ import { createFxLens, type FxLens, fxProviderFromEnv } from "./lib/fx.js";
101
106
  import { hatchet } from "./lib/hatchet.js";
102
107
  import {
103
108
  createIdentityService,
@@ -105,6 +110,11 @@ import {
105
110
  } from "./lib/identity-service.js";
106
111
  import { createLogger, type Logger } from "./lib/logger.js";
107
112
  import { createTrackedMailer } from "./lib/mailer.js";
113
+ import {
114
+ FX_SETTINGS_KEY,
115
+ type FxSetting,
116
+ getOperatorSetting,
117
+ } from "./lib/operator-settings.js";
108
118
  import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
109
119
  import { sendResetPasswordEmail } from "./lib/reset-email.js";
110
120
  import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
@@ -210,6 +220,12 @@ export interface HogsendClient {
210
220
  * (provider, pipeline) claim; admin stats/Studio render per funnel.
211
221
  */
212
222
  funnels: FunnelRegistry;
223
+ /**
224
+ * The registry of code-defined feature flags (`defineFlag`), keyed by
225
+ * `meta.key`. Built from `opts.flags`; the boot reconciler + Studio read it.
226
+ * Empty when no flags are defined in code (DB/Studio flags still evaluate).
227
+ */
228
+ flagRegistry: FlagRegistry;
213
229
  /**
214
230
  * The container-held registry of analytics providers, keyed by `meta.id` —
215
231
  * the analytics sibling of {@link emailProviders}. Built from env presets
@@ -231,6 +247,15 @@ export interface HogsendClient {
231
247
  * engine emission ingest uses — never bespoke per-consumer plumbing.
232
248
  */
233
249
  identity: IdentityService;
250
+ /**
251
+ * The OPTIONAL base-currency FX lens (docs/groups.md §Base-currency lens):
252
+ * `getBaseCurrency()` resolves the effective reporting currency PER CALL
253
+ * (code pin → Studio operator setting → env `BASE_CURRENCY`; null = lens
254
+ * off) and `getRatesToBase()` is the fail-soft quote→base sheet the admin
255
+ * group revenue views convert through. The per-currency revenue LAW is
256
+ * untouched; this only serves an opt-in converted view on top of it.
257
+ */
258
+ fx: FxLens;
234
259
  registry: JourneyRegistry;
235
260
  /**
236
261
  * Map of enabled journey id → its captured `run` source string. Populated by
@@ -419,12 +444,45 @@ export interface HogsendClientOptions {
419
444
  linkTracking?: boolean;
420
445
  linkHost?: string;
421
446
  };
447
+ /**
448
+ * The OPTIONAL base-currency FX lens (docs/groups.md §Base-currency lens).
449
+ * OFF unless a base currency resolves — with no `fx.baseCurrency` pin, no
450
+ * Studio operator setting, and no env `BASE_CURRENCY`, nothing anywhere
451
+ * converts.
452
+ *
453
+ * - `provider` — a BYO {@link FxRateProvider} rate source. WINS over the env
454
+ * presets entirely (the same consumer-over-env spirit as `analytics`,
455
+ * minus the registry — exactly one FX source resolves at boot; multiple
456
+ * simultaneous rate sources have no use case). Without it, env resolves:
457
+ * `FX_PROVIDER=frankfurter` → the ECB preset, else a set `FX_RATES` → the
458
+ * sovereign static preset, else no source (lens stays off).
459
+ * - `baseCurrency` — the code-level PIN: wins over BOTH the Studio operator
460
+ * setting and env `BASE_CURRENCY` (the `defaults.timezone` pattern; also
461
+ * the test seam, since `env` is a process singleton). Without it the base
462
+ * resolves per call: Studio setting (explicit null there = lens OFF,
463
+ * beating env) → env `BASE_CURRENCY`.
464
+ */
465
+ fx?: {
466
+ provider?: FxRateProvider;
467
+ baseCurrency?: string;
468
+ };
422
469
  /**
423
470
  * Code-first conversion-point definitions (plan §5.1) — `defineConversion`
424
471
  * results. Evaluated inside `ingestEvent` after every fresh event insert;
425
- * fired instances land in the `conversions` table.
472
+ * fired instances land in the `conversions` table. Every journey
473
+ * `meta.goal` is boot-validated against this set (plus the seeded
474
+ * "revenue" definition when active) — an unknown goal throws here.
426
475
  */
427
476
  conversions?: DefinedConversion[];
477
+ /**
478
+ * Code-first feature-flag definitions (`defineFlag()` results). Reconciled
479
+ * into `flags` rows at boot (create-if-absent, disabled + rollout 0; contract
480
+ * drift synced on code-origin rows; operator state never clobbered — see
481
+ * `reconcileDefinedFlags`). Only the CONTRACT is expressed here; targeting /
482
+ * rollout / enabling are DB/operator-owned. Wire in BOTH `index.ts` and
483
+ * `worker.ts` so both processes reconcile. Defaults to none.
484
+ */
485
+ flags?: DefinedFlag[];
428
486
  /**
429
487
  * Conversion DESTINATIONS (plan §5.2) — ad-platform feedback providers
430
488
  * (`defineConversionDestination`; Meta CAPI is the reference). Referenced
@@ -867,16 +925,26 @@ export function createHogsendClient(
867
925
  const seedDefaultRevenue =
868
926
  process.env.HOGSEND_DEFAULT_REVENUE_CONVERSION !== "false" &&
869
927
  !authoredConversions.some((def) => def.meta.id === "revenue");
870
- setConversionRegistry(
871
- new ConversionRegistry(
872
- seedDefaultRevenue
873
- ? [...authoredConversions, defaultRevenueConversion]
874
- : authoredConversions,
875
- ),
928
+ // Hoisted local (impact experiments D3): the meta.goal boot validation
929
+ // below must check THIS registry — the construction is env-sensitive
930
+ // (HOGSEND_DEFAULT_REVENUE_CONVERSION=false or an authored id:"revenue"
931
+ // suppresses the seed), so goal:"revenue" is valid exactly when a
932
+ // "revenue" definition actually exists. That asymmetry is intended.
933
+ const conversionRegistry = new ConversionRegistry(
934
+ seedDefaultRevenue
935
+ ? [...authoredConversions, defaultRevenueConversion]
936
+ : authoredConversions,
876
937
  );
938
+ setConversionRegistry(conversionRegistry);
877
939
  setConversionDestinations(
878
940
  new ConversionDestinationRegistry(opts.conversionDestinations ?? []),
879
941
  );
942
+
943
+ // Code-defined feature-flag registry (`defineFlag`) — installed on the
944
+ // process singleton for the boot reconciler + Studio. The reconcile itself
945
+ // fires below, near the other fire-and-forget boot effects.
946
+ const flagRegistry = new FlagRegistry(opts.flags ?? [], logger);
947
+ setFlagRegistry(flagRegistry);
880
948
  // The durable dispatch task reference (composition root — the lib module
881
949
  // cannot import the workflow without a cycle). Left UNSET under a hatchet
882
950
  // override so tests never touch real gRPC; dispatch rows stay pending.
@@ -1036,6 +1104,35 @@ export function createHogsendClient(
1036
1104
  });
1037
1105
  }
1038
1106
 
1107
+ // Boot-validate every journey's meta.goal against the conversion
1108
+ // registry — fail CLOSED. A typo'd id matches zero conversion rows, so
1109
+ // every default readout would quietly report 0% for both cohorts — a
1110
+ // wrong-but-plausible number, worse than a crash. Validated over DEFINED
1111
+ // journeys (not just ENABLED — the ENABLED_JOURNEYS lesson) against the
1112
+ // ACTUAL registry (the seeded "revenue" conversion counts, and counts
1113
+ // ONLY when actually seeded). Runs identically in the API and worker
1114
+ // processes (both call createHogsendClient). Same posture as the
1115
+ // EMAIL_PROVIDER throw above and validateListCategory: the registry
1116
+ // universe is fully known at boot, so throw — a warn's failure mode is a
1117
+ // permanently-wrong default readout.
1118
+ for (const journey of opts.journeys ?? []) {
1119
+ const goal = journey.meta.goal;
1120
+ if (!goal) continue;
1121
+ if (!conversionRegistry.has(goal)) {
1122
+ const known = conversionRegistry
1123
+ .getAll()
1124
+ .map((def) => def.meta.id)
1125
+ .join(", ");
1126
+ throw new Error(
1127
+ `Journey "${journey.meta.id}" has goal "${goal}", which matches no registered conversion definition (known: ${known || "none"}). ` +
1128
+ `A goal must be a defineConversion id passed to createHogsendClient({ conversions }) — or the built-in "revenue" conversion when it is seeded.` +
1129
+ (goal === "revenue"
1130
+ ? ` Remove HOGSEND_DEFAULT_REVENUE_CONVERSION=false or author an id: "revenue" definition if you meant the built-in.`
1131
+ : ""),
1132
+ );
1133
+ }
1134
+ }
1135
+
1039
1136
  const emailService =
1040
1137
  opts.overrides?.mailer ??
1041
1138
  createTrackedMailer(
@@ -1315,6 +1412,33 @@ export function createHogsendClient(
1315
1412
  // emission no-ops; the resolve still happens).
1316
1413
  const identity = createIdentityService({ db, analytics, logger });
1317
1414
 
1415
+ // The OPTIONAL base-currency FX lens. A consumer provider wins over the env
1416
+ // presets wholesale; env otherwise resolves frankfurter (opt-in) or the
1417
+ // sovereign static sheet. `fxProviderFromEnv` throws at boot on a malformed
1418
+ // FX_RATES (fail-loud on config, the EMAIL_PROVIDER posture) — but the
1419
+ // LENS itself is fail-soft at request time: no base currency / no provider /
1420
+ // no rates all resolve to null and the per-currency truth serves unchanged.
1421
+ //
1422
+ // The effective BASE resolves PER CALL (a Studio change needs no reboot),
1423
+ // walking: (1) the code-level pin `opts.fx.baseCurrency` (also the test
1424
+ // seam) — wins over everything; (2) the Studio operator setting when its
1425
+ // row exists — an explicit `baseCurrency: null` there means "operator
1426
+ // turned the lens OFF", which BEATS env; (3) env `BASE_CURRENCY`, the
1427
+ // bootstrap default when NO row exists. No cache on the setting read
1428
+ // (lean-first): only low-QPS admin surfaces resolve rates, and a PK lookup
1429
+ // is nothing.
1430
+ const fxPin = opts.fx?.baseCurrency;
1431
+ const fx = createFxLens({
1432
+ resolveBaseCurrency: async () => {
1433
+ if (fxPin !== undefined) return fxPin;
1434
+ const setting = await getOperatorSetting<FxSetting>(db, FX_SETTINGS_KEY);
1435
+ if (setting) return setting.baseCurrency;
1436
+ return env.BASE_CURRENCY ?? null;
1437
+ },
1438
+ provider: opts.fx?.provider ?? fxProviderFromEnv(env, { db, logger }),
1439
+ logger,
1440
+ });
1441
+
1318
1442
  // Build + install the outbound DESTINATION registry (Phase 3) the
1319
1443
  // self-booting delivery task resolves by `webhook_endpoints.kind`. Order is
1320
1444
  // load-bearing: the env-enabled presets come FIRST and the consumer's
@@ -1445,9 +1569,11 @@ export function createHogsendClient(
1445
1569
  smsProvider,
1446
1570
  crmProviders,
1447
1571
  funnels,
1572
+ flagRegistry,
1448
1573
  analyticsProviders,
1449
1574
  analytics,
1450
1575
  identity,
1576
+ fx,
1451
1577
  registry,
1452
1578
  journeySources: getJourneySources(),
1453
1579
  journeyConstants: {
@@ -1495,5 +1621,21 @@ export function createHogsendClient(
1495
1621
  .catch(() => {});
1496
1622
  }
1497
1623
 
1624
+ // Reconcile code-defined feature flags into `flags` rows (create-if-absent,
1625
+ // sync contract drift on code-origin rows, never clobber operator state — see
1626
+ // `reconcileDefinedFlags`). Container-level so BOTH the API and worker
1627
+ // reconcile; the idempotent onConflict makes concurrent runs safe. Twin of
1628
+ // the buildStoredPosthogProvider block above: fire-and-forget, best-effort,
1629
+ // never blocks or fails boot. Skipped under NODE_ENV=test so suites stay
1630
+ // hermetic (tests drive the reconciler directly).
1631
+ const definedFlags = opts.flags ?? [];
1632
+ if (definedFlags.length > 0 && env.NODE_ENV !== "test") {
1633
+ void reconcileDefinedFlags({ client, flags: definedFlags }).catch((err) => {
1634
+ logger.warn("flags: reconcile (boot) failed", {
1635
+ error: err instanceof Error ? err.message : String(err),
1636
+ });
1637
+ });
1638
+ }
1639
+
1498
1640
  return client;
1499
1641
  }
@@ -103,6 +103,13 @@ export const posthogDestination = defineDestination({
103
103
  }
104
104
  const host = config.host ?? "https://us.i.posthog.com";
105
105
 
106
+ // impact.digest carries NO person identity (no userId/anonymousId/to/
107
+ // userEmail on the payload) — the generic capture below would ship no
108
+ // distinct_id, PostHog would 400, and the delivery would dead-letter
109
+ // as non-retryable every week. A program-level digest has no person to
110
+ // land on: skipping is a successful no-op, not a delivery failure.
111
+ if (envelope.type === "impact.digest") return null;
112
+
106
113
  // Person-property propagation: `contact.*` events carry a contact payload
107
114
  // (id/externalId/email/properties), NOT the userId/to identity chain the
108
115
  // generic capture branch keys on — so they are handled here exclusively
@@ -47,6 +47,11 @@ export const segmentDestination = defineDestination({
47
47
  );
48
48
  }
49
49
  const host = config.host ?? "https://api.segment.io";
50
+
51
+ // impact.digest has no subject identity; the fallback below would emit
52
+ // a junk track keyed on `anonymousId: envelope.id` — noise. Skipping
53
+ // is honest.
54
+ if (envelope.type === "impact.digest") return null;
50
55
  const data = envelope.data as {
51
56
  userId?: string | null;
52
57
  to?: string | null;
package/src/env.ts CHANGED
@@ -121,6 +121,34 @@ export const env = createEnv({
121
121
  POSTMARK_MESSAGE_STREAM: z.string().min(1).optional(),
122
122
  POSTMARK_WEBHOOK_USER: z.string().min(1).optional(),
123
123
  POSTMARK_WEBHOOK_PASS: z.string().min(1).optional(),
124
+ // --- Base-currency FX lens (optional; docs/groups.md §Base-currency lens) ---
125
+ // The operator's reporting currency. UNSET = the lens is OFF everywhere
126
+ // (zero behavior change): no converted figures, no converted ranking. Set
127
+ // it (e.g. "USD") to turn converted `revenueBase` figures + base-ranked
128
+ // `sort=revenue` on wherever a rate source is available. Uppercased so
129
+ // rate-sheet lookups never miss on case.
130
+ BASE_CURRENCY: z
131
+ .string()
132
+ .regex(/^[A-Za-z]{3}$/, "must be a 3-letter ISO-4217 code")
133
+ .transform((v) => v.toUpperCase())
134
+ .optional(),
135
+ // Which rate source serves the lens. "static" (default) is SOVEREIGN —
136
+ // operator-supplied FX_RATES, zero network. "frankfurter" opts into
137
+ // fetching ECB daily reference rates (cached in `fx_rates`, ≤1 outbound
138
+ // call per day, fail-soft to the last cached sheet).
139
+ FX_PROVIDER: z.enum(["static", "frankfurter"]).optional(),
140
+ // The static preset's rate sheet: a JSON object of quote→base rates, e.g.
141
+ // {"JPY":0.0065,"GBP":1.27} = 1 JPY is 0.0065 base units. Quoted against
142
+ // BASE_CURRENCY. Parsed (and failed LOUD on malformed JSON / non-positive
143
+ // values) at boot in `lib/fx.ts` — a typo'd sheet must never silently
144
+ // convert money wrong.
145
+ FX_RATES: z.string().optional(),
146
+ // Optional ISO date the static FX_RATES were taken from — surfaced as the
147
+ // sheet's `asOf` so converted figures can be labeled ("rates as of …").
148
+ FX_RATES_AS_OF: z
149
+ .string()
150
+ .regex(/^\d{4}-\d{2}-\d{2}$/, "must be an ISO date (YYYY-MM-DD)")
151
+ .optional(),
124
152
  // --- SMS channel (provider-neutral, BYO SMS provider) ---
125
153
  // The active SMS provider id the container resolves from the
126
154
  // SmsProviderRegistry. Absent → "twilio" when a provider is registered;
@@ -226,6 +254,13 @@ export const env = createEnv({
226
254
  ENABLED_LISTS: z.string().default("*"),
227
255
  // Cadence for the engine-owned bucket reconcile cron (time-based leaves).
228
256
  BUCKET_RECONCILE_CRON: z.string().default("*/5 * * * *"),
257
+ // Cadence for the engine-owned impact digest cron. Read raw off
258
+ // process.env by onCrons at module load; declared here for the
259
+ // validated-env contract (the OUTBOUND_WEBHOOK_REAPER_CRON stance).
260
+ IMPACT_DIGEST_CRON: z.string().default("0 9 * * 1"),
261
+ // Win-probability crossing threshold for digest "lift" entries; the
262
+ // task clamps to [0.5, 0.999] and defaults to 0.95.
263
+ IMPACT_DIGEST_WIN_PROB: z.coerce.number().min(0.5).max(0.999).optional(),
229
264
  // --- Outbound webhooks (Section 1.5/1.8) ---
230
265
  // Cadence for the engine-owned outbound-delivery reaper cron (the retry
231
266
  // scheduler + orphan-`sending` recovery). Declared for parity with
@@ -248,6 +283,9 @@ export const env = createEnv({
248
283
  SUPABASE_WEBHOOK_SECRET: z.string().min(1).optional(),
249
284
  STRIPE_WEBHOOK_SECRET: z.string().min(1).optional(),
250
285
  SEGMENT_WEBHOOK_SECRET: z.string().min(1).optional(),
286
+ // Intercom app Client Secret — signs `X-Hub-Signature: sha1=<hex>` over the
287
+ // raw body. Auto-enables the Intercom preset at POST /v1/webhooks/intercom.
288
+ INTERCOM_CLIENT_SECRET: z.string().min(1).optional(),
251
289
  // Preset enablement override: csv of preset ids, `"*"` (all with a secret),
252
290
  // or `"none"`. Absent → auto-enable any preset whose secret is set.
253
291
  ENABLED_WEBHOOK_PRESETS: z.string().optional(),
@@ -0,0 +1,195 @@
1
+ /**
2
+ * Boot-time reconciler for code-defined feature flags ({@link defineFlag}).
3
+ *
4
+ * Runs once at container build (in BOTH the API and worker processes),
5
+ * fire-and-forget and best-effort — a single malformed definition warns and is
6
+ * skipped; the reconciler NEVER throws and never fails boot. State stays
7
+ * DB-owned: this only writes the CONTRACT (identity + served shape). Per
8
+ * definition (deduped on key):
9
+ *
10
+ * - No live row → INSERT the contract fields with `origin:"code"`, born OFF
11
+ * (`enabled:false` — the DB column defaults to `true`, so this MUST be set
12
+ * explicitly) and inert (`rollout:0`, `targeting:[]`, `conditionSets:[]`).
13
+ * The insert is `onConflictDoNothing` against the partial-unique live-key
14
+ * index, so two replicas reconciling concurrently is safe.
15
+ * - Live row with `origin:"code"` → sync CONTRACT drift ONLY (name /
16
+ * description / type / variants / defaultValue) via a canonical-JSON diff.
17
+ * Operator STATE (enabled / rollout / targeting / conditionSets) is NEVER
18
+ * touched — an operator who turned the flag on and set a rollout keeps it.
19
+ * - Live row with a non-`code` origin (e.g. a Studio-authored "native" flag
20
+ * that happens to share the key) → LEFT untouched + a warn. Code never
21
+ * steals an operator's flag.
22
+ * - A flag removed from code → not iterated → left exactly as-is (no
23
+ * auto-archive).
24
+ */
25
+ import type { DefinedFlag } from "@hogsend/core";
26
+ import { flags } from "@hogsend/db";
27
+ import { and, eq, isNull, sql } from "drizzle-orm";
28
+ import type { HogsendClient } from "../container.js";
29
+
30
+ export interface FlagReconcileResult {
31
+ created: number;
32
+ updated: number;
33
+ skipped: number;
34
+ }
35
+
36
+ export async function reconcileDefinedFlags(opts: {
37
+ client: HogsendClient;
38
+ flags: DefinedFlag[];
39
+ }): Promise<FlagReconcileResult> {
40
+ const { client } = opts;
41
+ const { db, logger } = client;
42
+ const result: FlagReconcileResult = { created: 0, updated: 0, skipped: 0 };
43
+ const seen = new Set<string>();
44
+
45
+ for (const def of opts.flags) {
46
+ const meta = def.meta;
47
+ const key = meta.key;
48
+
49
+ if (seen.has(key)) {
50
+ logger.warn("flags: duplicate defineFlag key — skipping", { key });
51
+ result.skipped++;
52
+ continue;
53
+ }
54
+ seen.add(key);
55
+
56
+ // The contract projection, resolved once. `defaultValue` defaults to the
57
+ // type's natural empty (false for boolean, null for multivariate) — never
58
+ // relying on the DB column default so the row matches the definition
59
+ // byte-for-byte.
60
+ const variants = [...(meta.variants ?? [])];
61
+ const defaultValue =
62
+ meta.defaultValue ?? (meta.type === "boolean" ? false : null);
63
+ const description = meta.description ?? null;
64
+
65
+ try {
66
+ const existingRows = await db
67
+ .select({
68
+ id: flags.id,
69
+ origin: flags.origin,
70
+ name: flags.name,
71
+ description: flags.description,
72
+ type: flags.type,
73
+ variants: flags.variants,
74
+ defaultValue: flags.defaultValue,
75
+ })
76
+ .from(flags)
77
+ .where(and(eq(flags.key, key), isNull(flags.archivedAt)))
78
+ .limit(1);
79
+ const existing = existingRows[0];
80
+
81
+ if (!existing) {
82
+ const inserted = await db
83
+ .insert(flags)
84
+ .values({
85
+ key,
86
+ name: meta.name,
87
+ description,
88
+ // The DB column defaults to `true`; a defined flag is born OFF
89
+ // (unless the definition seeds `enabled:true`) so a deploy never
90
+ // silently flips live traffic. Explicit by contract.
91
+ enabled: meta.enabled ?? false,
92
+ type: meta.type,
93
+ variants,
94
+ defaultValue,
95
+ targeting: [],
96
+ rollout: 0,
97
+ conditionSets: [],
98
+ origin: "code",
99
+ })
100
+ // The loser of a two-replica insert race defers to the winner. The
101
+ // `where` predicate MUST match the partial-unique index
102
+ // (`flags_key_unique_idx WHERE archived_at IS NULL`) or Postgres
103
+ // cannot infer the conflict arbiter (42P10).
104
+ .onConflictDoNothing({
105
+ target: flags.key,
106
+ where: sql`archived_at is null`,
107
+ })
108
+ .returning({ id: flags.id });
109
+
110
+ if (inserted[0]) {
111
+ logger.info("flags: defined flag created (disabled)", { key });
112
+ result.created++;
113
+ } else {
114
+ result.skipped++;
115
+ }
116
+ continue;
117
+ }
118
+
119
+ // A same-key flag owned by an operator/Studio (origin != "code") is never
120
+ // clobbered by a code definition — leave it and warn.
121
+ if (existing.origin !== "code") {
122
+ logger.warn(
123
+ "flags: key already owned by a non-code flag — leaving it untouched",
124
+ { key, origin: existing.origin },
125
+ );
126
+ result.skipped++;
127
+ continue;
128
+ }
129
+
130
+ const changed =
131
+ existing.name !== meta.name ||
132
+ (existing.description ?? null) !== description ||
133
+ existing.type !== meta.type ||
134
+ canonicalJson(existing.variants ?? []) !== canonicalJson(variants) ||
135
+ canonicalJson(existing.defaultValue ?? null) !==
136
+ canonicalJson(defaultValue);
137
+
138
+ if (!changed) {
139
+ result.skipped++;
140
+ continue;
141
+ }
142
+
143
+ // Contract drift only. STATE columns (enabled / rollout / targeting /
144
+ // conditionSets) are deliberately absent from this SET. The CAS on
145
+ // `origin = "code"` keeps an operator who flipped provenance mid-flight
146
+ // from being overwritten.
147
+ await db
148
+ .update(flags)
149
+ .set({
150
+ name: meta.name,
151
+ description,
152
+ type: meta.type,
153
+ variants,
154
+ defaultValue,
155
+ updatedAt: new Date(),
156
+ })
157
+ .where(and(eq(flags.id, existing.id), eq(flags.origin, "code")));
158
+
159
+ logger.info("flags: defined flag contract synced", { key });
160
+ result.updated++;
161
+ } catch (err) {
162
+ // One bad definition must never take down boot for every other flag.
163
+ logger.warn("flags: reconcile failed for definition — skipping", {
164
+ key,
165
+ error: err instanceof Error ? err.message : String(err),
166
+ });
167
+ result.skipped++;
168
+ }
169
+ }
170
+
171
+ return result;
172
+ }
173
+
174
+ /**
175
+ * Key-order-canonical JSON for the changed-comparison. `existing.variants` /
176
+ * `existing.defaultValue` round-trip through Postgres jsonb, which does NOT
177
+ * preserve object key order, so a plain `JSON.stringify` would report a phantom
178
+ * "changed" for any multi-key object — rewriting (and logging) an unchanged
179
+ * definition on every boot. Arrays keep order; only object keys are sorted.
180
+ */
181
+ function canonicalJson(value: unknown): string {
182
+ return JSON.stringify(sortKeysDeep(value));
183
+ }
184
+
185
+ function sortKeysDeep(value: unknown): unknown {
186
+ if (Array.isArray(value)) return value.map(sortKeysDeep);
187
+ if (value !== null && typeof value === "object") {
188
+ return Object.fromEntries(
189
+ Object.entries(value as Record<string, unknown>)
190
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
191
+ .map(([k, entry]) => [k, sortKeysDeep(entry)]),
192
+ );
193
+ }
194
+ return value;
195
+ }