@hogsend/engine 0.46.1 → 0.51.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 (88) hide show
  1. package/README.md +6 -0
  2. package/package.json +13 -10
  3. package/src/campaigns/cohort-sql.ts +8 -9
  4. package/src/connectors/presets/index.ts +8 -2
  5. package/src/container.ts +150 -8
  6. package/src/destinations/define-destination.ts +2 -2
  7. package/src/destinations/presets/posthog.ts +7 -0
  8. package/src/destinations/presets/segment.ts +5 -0
  9. package/src/env.ts +38 -0
  10. package/src/flags/reconcile.ts +200 -0
  11. package/src/index.ts +79 -0
  12. package/src/journeys/authoring.ts +32 -0
  13. package/src/journeys/define-journey.ts +45 -40
  14. package/src/journeys/execute-journey-run.ts +73 -32
  15. package/src/journeys/journey-boundary.ts +76 -0
  16. package/src/journeys/journey-context.ts +128 -70
  17. package/src/journeys/journey-task-factory.ts +31 -0
  18. package/src/journeys/journey-task-runtime.ts +31 -0
  19. package/src/journeys/journey-version.test.ts +236 -0
  20. package/src/journeys/journey-version.ts +158 -0
  21. package/src/journeys/record-once.ts +28 -2
  22. package/src/lib/campaign-send-key.ts +9 -18
  23. package/src/lib/connector-actions.test.ts +36 -0
  24. package/src/lib/connector-actions.ts +42 -4
  25. package/src/lib/contacts.ts +49 -0
  26. package/src/lib/conversions.test.ts +33 -0
  27. package/src/lib/conversions.ts +9 -1
  28. package/src/lib/crm-deals.ts +1 -1
  29. package/src/lib/crm-ingest.ts +1 -1
  30. package/src/lib/email.ts +23 -2
  31. package/src/lib/enrollment-policy.ts +51 -0
  32. package/src/lib/event-names.ts +7 -1
  33. package/src/lib/feed.ts +55 -3
  34. package/src/lib/flags-registry.ts +48 -0
  35. package/src/lib/flags.ts +498 -0
  36. package/src/lib/frequency-cap.ts +4 -2
  37. package/src/lib/funnel-progress.ts +1 -1
  38. package/src/lib/fx.ts +374 -0
  39. package/src/lib/global-control-readout.ts +166 -0
  40. package/src/lib/groups.ts +362 -0
  41. package/src/lib/holdout.ts +1 -1
  42. package/src/lib/ingestion.ts +38 -0
  43. package/src/lib/journey-lift.ts +142 -0
  44. package/src/lib/journey-suppress.ts +4 -2
  45. package/src/lib/lift-stats.ts +2 -2
  46. package/src/lib/operator-settings.ts +71 -0
  47. package/src/lib/outbound.ts +147 -0
  48. package/src/lib/preferences.ts +6 -80
  49. package/src/lib/recipient-preferences.ts +53 -0
  50. package/src/lib/sms.ts +21 -2
  51. package/src/lib/stable-stringify.test.ts +42 -0
  52. package/src/lib/stable-stringify.ts +23 -0
  53. package/src/lib/tracked.ts +9 -2
  54. package/src/lib/variant.ts +99 -0
  55. package/src/lib/webhook-signing.ts +16 -1
  56. package/src/lists/registry.ts +6 -2
  57. package/src/lists/subscription.ts +13 -0
  58. package/src/routes/admin/attribution.ts +1 -2
  59. package/src/routes/admin/campaigns.ts +84 -45
  60. package/src/routes/admin/contacts.ts +53 -4
  61. package/src/routes/admin/conversions.ts +138 -1
  62. package/src/routes/admin/deals.ts +43 -34
  63. package/src/routes/admin/emails.ts +4 -6
  64. package/src/routes/admin/events.ts +128 -1
  65. package/src/routes/admin/flags.ts +369 -0
  66. package/src/routes/admin/groups.ts +900 -0
  67. package/src/routes/admin/impact-schemas.ts +44 -0
  68. package/src/routes/admin/impact-wire.test.ts +181 -0
  69. package/src/routes/admin/impact.ts +486 -0
  70. package/src/routes/admin/index.ts +12 -0
  71. package/src/routes/admin/journey-impact.ts +446 -0
  72. package/src/routes/admin/journeys.ts +70 -100
  73. package/src/routes/admin/settings.ts +145 -0
  74. package/src/routes/admin/targeting.ts +259 -0
  75. package/src/routes/events/index.ts +11 -0
  76. package/src/routes/flags/index.ts +120 -0
  77. package/src/routes/groups/index.ts +417 -0
  78. package/src/routes/index.ts +23 -1
  79. package/src/testing.ts +25 -0
  80. package/src/webhook-sources/presets/index.ts +5 -1
  81. package/src/webhook-sources/presets/intercom.ts +230 -0
  82. package/src/webhook-sources/presets/segment.ts +56 -4
  83. package/src/worker.ts +3 -0
  84. package/src/workflows/bucket-backfill.ts +1 -14
  85. package/src/workflows/crm-reconcile.ts +1 -1
  86. package/src/workflows/impact-digest.ts +761 -0
  87. package/src/workflows/journey-blueprint-interpreter.ts +18 -1
  88. package/src/middleware/auth.ts +0 -24
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.51.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.51.0",
57
+ "@hogsend/core": "^0.51.0",
58
+ "@hogsend/db": "^0.51.0",
59
+ "@hogsend/email": "^0.51.0",
60
+ "@hogsend/plugin-posthog": "^0.51.0",
61
+ "@hogsend/plugin-resend": "^0.51.0",
62
+ "@hogsend/sms": "^0.51.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.51.0",
66
+ "@hogsend/plugin-twilio": "^0.51.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
  }
@@ -29,7 +29,6 @@ import {
29
29
  } from "@hogsend/db";
30
30
  import { type SQL, sql } from "drizzle-orm";
31
31
  import type { PgColumn } from "drizzle-orm/pg-core";
32
- import { campaignSendKeyPattern } from "../lib/campaign-send-key.js";
33
32
 
34
33
  /**
35
34
  * The v1 linked-identity map: connector id → the `contacts` column that holds
@@ -107,13 +106,13 @@ export function waveConditionSql(opts: {
107
106
  }
108
107
 
109
108
  /**
110
- * Engagement over THIS campaign's prior deliveries. The campaign-level LIKE
111
- * (`campaign:<escaped-id>:%`) is a correct superset of BOTH key formats
112
- * (legacy and step-scoped), so an absent `templateKey` — "any prior send of
113
- * this campaign" — and a template-filtered check both anchor on it. Negative
114
- * checks are NOT EXISTS of the same positive-engagement subquery, so
115
- * `notOpened()` reads "no opened send of this campaign", including members
116
- * who received nothing (e.g. suppressed on the prior wave).
109
+ * Engagement over THIS campaign's prior deliveries, anchored on the indexed
110
+ * `campaign_id` column (stamped on every campaign-dispatched row regardless
111
+ * of key format; suppressed rows carry it too but have no engagement
112
+ * timestamps, so they can never match positively). Negative checks are NOT
113
+ * EXISTS of the same positive-engagement subquery, so `notOpened()` reads
114
+ * "no opened send of this campaign", including members who received nothing
115
+ * (e.g. suppressed on the prior wave).
117
116
  */
118
117
  function engagementSql(
119
118
  condition: EmailEngagementCondition,
@@ -129,7 +128,7 @@ function engagementSql(
129
128
  : sql.empty();
130
129
  const positive = sql`exists (
131
130
  select 1 from ${emailSends}
132
- where ${emailSends.idempotencyKey} like ${campaignSendKeyPattern(campaignId)}
131
+ where ${emailSends.campaignId} = ${campaignId}
133
132
  and ${emailSends.toEmail} = ${campaignRecipients.email}
134
133
  and ${engagedAt} is not null${templateFilter}
135
134
  )`;
@@ -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
@@ -432,7 +490,7 @@ export interface HogsendClientOptions {
432
490
  */
433
491
  conversionDestinations?: ConversionDestination[];
434
492
  /**
435
- * CRM sync providers (docs/revenue-attribution-plan.md §4) — the pluggable
493
+ * CRM sync providers — the pluggable
436
494
  * layer that pushes leads INTO client CRMs and lands pipeline stage changes
437
495
  * + deal values back on the event spine as `funnel.stage_changed`. Register
438
496
  * one (`provider`) or many (`providers`); each is webhook-served at
@@ -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
  }
@@ -23,8 +23,8 @@ import type { OutboundEventName } from "../lib/outbound.js";
23
23
  * NOTE: `defineDestination` is for event FAN-OUT to product/data tools
24
24
  * (PostHog, Segment, Slack, a CRM, a warehouse). Ad-platform conversion
25
25
  * forwarding (Meta CAPI, Google Enhanced Conversions) is Hogsend-native but
26
- * lives in its own sibling layer (`defineConversionDestination`, per
27
- * docs/revenue-attribution-plan.md) — it needs identifier hashing, click-id
26
+ * lives in its own sibling layer (`defineConversionDestination`) — it needs
27
+ * identifier hashing, click-id
28
28
  * joins, and deterministic event_id idempotency this generic pipe deliberately
29
29
  * does not have. It is NOT deferred to any third-party CDP: the money path has
30
30
  * no external dependency.
@@ -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(),