@hogsend/engine 0.43.0 → 0.45.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 (58) hide show
  1. package/package.json +12 -9
  2. package/src/container.ts +289 -13
  3. package/src/destinations/define-destination.ts +7 -3
  4. package/src/destinations/presets/posthog.ts +31 -0
  5. package/src/index.ts +99 -0
  6. package/src/journeys/execute-journey-run.ts +93 -0
  7. package/src/journeys/journey-context.ts +4 -0
  8. package/src/lib/analytics-providers-from-env.ts +106 -43
  9. package/src/lib/attribution-backfill.ts +285 -0
  10. package/src/lib/attribution.ts +239 -0
  11. package/src/lib/contacts.ts +71 -0
  12. package/src/lib/conversion-dispatch.ts +326 -0
  13. package/src/lib/conversions.ts +197 -0
  14. package/src/lib/crm-deals.ts +320 -0
  15. package/src/lib/crm-ingest.ts +341 -0
  16. package/src/lib/crm-provider-registry.ts +41 -0
  17. package/src/lib/crm-registry-singleton.ts +22 -0
  18. package/src/lib/deal-money-events.ts +85 -0
  19. package/src/lib/email-service-types.ts +16 -1
  20. package/src/lib/event-names.ts +1 -1
  21. package/src/lib/funnel-progress.ts +76 -0
  22. package/src/lib/funnel-registry.ts +108 -0
  23. package/src/lib/funnel-transitions.ts +280 -0
  24. package/src/lib/holdout.ts +62 -0
  25. package/src/lib/ingestion.ts +218 -9
  26. package/src/lib/lift-stats.ts +125 -0
  27. package/src/lib/mailer.ts +1 -0
  28. package/src/lib/operator.ts +31 -0
  29. package/src/lib/outbound.ts +51 -0
  30. package/src/lib/posthog-scopes.ts +30 -6
  31. package/src/lib/revenue.ts +116 -0
  32. package/src/lib/sms-service-types.ts +7 -1
  33. package/src/lib/sms-tracked.ts +35 -0
  34. package/src/lib/tracked.ts +40 -0
  35. package/src/lib/tracking-events.ts +26 -0
  36. package/src/lib/unconfigured-email-provider.ts +45 -0
  37. package/src/lib/webhook-signing.ts +7 -0
  38. package/src/routes/admin/analytics.ts +14 -5
  39. package/src/routes/admin/attribution.ts +414 -0
  40. package/src/routes/admin/contacts.ts +71 -11
  41. package/src/routes/admin/conversions.ts +247 -0
  42. package/src/routes/admin/deals.ts +472 -0
  43. package/src/routes/admin/funnels.ts +228 -0
  44. package/src/routes/admin/index.ts +8 -0
  45. package/src/routes/admin/journeys.ts +158 -1
  46. package/src/routes/admin/readiness.ts +97 -2
  47. package/src/routes/admin/templates.ts +28 -1
  48. package/src/routes/events/index.ts +12 -0
  49. package/src/routes/tracking/click-pipeline.ts +26 -18
  50. package/src/routes/webhooks/crm-provider.ts +117 -0
  51. package/src/routes/webhooks/index.ts +5 -1
  52. package/src/sources/define-contact-source.ts +159 -0
  53. package/src/sources/registry.ts +71 -0
  54. package/src/sources/webhook-source.ts +109 -0
  55. package/src/worker.ts +4 -0
  56. package/src/workflows/crm-reconcile.ts +129 -0
  57. package/src/workflows/dispatch-conversion.ts +31 -0
  58. package/src/workflows/send-campaign.ts +5 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.43.0",
3
+ "version": "0.45.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,16 +51,17 @@
49
51
  "svix": "^1.95.1",
50
52
  "winston": "^3.19.0",
51
53
  "zod": "^4.4.3",
52
- "@hogsend/core": "^0.43.0",
53
- "@hogsend/db": "^0.43.0",
54
- "@hogsend/email": "^0.43.0",
55
- "@hogsend/plugin-posthog": "^0.43.0",
56
- "@hogsend/plugin-resend": "^0.43.0",
57
- "@hogsend/sms": "^0.43.0"
54
+ "@hogsend/attribution": "^0.45.0",
55
+ "@hogsend/core": "^0.45.0",
56
+ "@hogsend/db": "^0.45.0",
57
+ "@hogsend/email": "^0.45.0",
58
+ "@hogsend/plugin-posthog": "^0.45.0",
59
+ "@hogsend/plugin-resend": "^0.45.0",
60
+ "@hogsend/sms": "^0.45.0"
58
61
  },
59
62
  "optionalDependencies": {
60
- "@hogsend/plugin-postmark": "^0.43.0",
61
- "@hogsend/plugin-twilio": "^0.43.0"
63
+ "@hogsend/plugin-postmark": "^0.45.0",
64
+ "@hogsend/plugin-twilio": "^0.45.0"
62
65
  },
63
66
  "devDependencies": {
64
67
  "@types/node": "^22.15.3",
package/src/container.ts CHANGED
@@ -2,12 +2,24 @@ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
2
  import type {
3
3
  AnalyticsEventMirrorConfig,
4
4
  AnalyticsProvider,
5
+ ConversionDestination,
6
+ CrmProvider,
7
+ CrmStageMap,
8
+ DefinedConversion,
9
+ DefinedFunnel,
5
10
  EmailProvider,
11
+ FunnelStageEntry,
6
12
  JourneySourceLocation,
7
13
  PostHogService,
8
14
  SmsProvider,
9
15
  TimeZone,
10
16
  } from "@hogsend/core";
17
+ import {
18
+ crmPipeline,
19
+ DEFAULT_FUNNEL_ID,
20
+ DEFAULT_PIPELINE_LADDER,
21
+ defineFunnel,
22
+ } from "@hogsend/core";
11
23
  import type { BucketRegistry, JourneyRegistry } from "@hogsend/core/registry";
12
24
  import type { SendWindow } from "@hogsend/core/schedule";
13
25
  import {
@@ -53,12 +65,27 @@ import {
53
65
  wrapLegacyAnalyticsService,
54
66
  } from "./lib/analytics-adapter.js";
55
67
  import { AnalyticsProviderRegistry } from "./lib/analytics-provider-registry.js";
56
- import { analyticsProvidersFromEnv } from "./lib/analytics-providers-from-env.js";
68
+ import {
69
+ analyticsProvidersFromEnv,
70
+ buildStoredPosthogProvider,
71
+ } from "./lib/analytics-providers-from-env.js";
57
72
  import {
58
73
  setAnalytics,
59
74
  setAnalyticsEventMirror,
60
75
  } from "./lib/analytics-singleton.js";
61
76
  import { type Auth, createAuth } from "./lib/auth.js";
77
+ import {
78
+ ConversionDestinationRegistry,
79
+ setConversionDestinations,
80
+ setConversionDispatchTask,
81
+ } from "./lib/conversion-dispatch.js";
82
+ import {
83
+ ConversionRegistry,
84
+ defaultRevenueConversion,
85
+ setConversionRegistry,
86
+ } from "./lib/conversions.js";
87
+ import { CrmProviderRegistry } from "./lib/crm-provider-registry.js";
88
+ import { setCrmSyncConfig } from "./lib/crm-registry-singleton.js";
62
89
  import {
63
90
  createDomainStatusService,
64
91
  type DomainStatusService,
@@ -70,6 +97,7 @@ import type {
70
97
  EmailService,
71
98
  FrequencyCapConfig,
72
99
  } from "./lib/email-service-types.js";
100
+ import { FunnelRegistry } from "./lib/funnel-registry.js";
73
101
  import { hatchet } from "./lib/hatchet.js";
74
102
  import {
75
103
  createIdentityService,
@@ -86,6 +114,7 @@ import { SmsProviderRegistry } from "./lib/sms-provider-registry.js";
86
114
  import { smsProvidersFromEnv } from "./lib/sms-providers-from-env.js";
87
115
  import type { SmsService } from "./lib/sms-service-types.js";
88
116
  import { prepareTrackedHtml } from "./lib/tracking.js";
117
+ import { createUnconfiguredEmailProvider } from "./lib/unconfigured-email-provider.js";
89
118
  import { synthesizeChannelLists } from "./lists/channels.js";
90
119
  import {
91
120
  type DefinedList,
@@ -93,10 +122,19 @@ import {
93
122
  RESERVED_LIST_IDS,
94
123
  } from "./lists/define-list.js";
95
124
  import { buildListRegistry, type ListRegistry } from "./lists/registry.js";
125
+ import {
126
+ contactSourceToWebhookSource,
127
+ type DefinedContactSource,
128
+ } from "./sources/define-contact-source.js";
129
+ import {
130
+ buildContactSourceRegistry,
131
+ type ContactSourceRegistry,
132
+ } from "./sources/registry.js";
96
133
  import {
97
134
  type DefinedWebhookSource,
98
135
  webhookSourceToConnector,
99
136
  } from "./webhook-sources/define-webhook-source.js";
137
+ import { dispatchConversionTask } from "./workflows/dispatch-conversion.js";
100
138
 
101
139
  export interface HogsendDefaults {
102
140
  /** Global fallback IANA timezone for scheduling. Defaults to "UTC". */
@@ -158,6 +196,20 @@ export interface HogsendClient {
158
196
  * Undefined when no SMS provider is configured.
159
197
  */
160
198
  smsProvider?: SmsProvider;
199
+ /**
200
+ * The container-held registry of CRM providers, keyed by `meta.id`. The
201
+ * `POST /v1/webhooks/crm/:providerId` route resolves the verifying provider
202
+ * out of this and the reconciliation poll walks it. Unlike email/SMS there
203
+ * is no single "active" CRM — many sync concurrently; `pushLead` callers
204
+ * name the provider. Empty when none configured.
205
+ */
206
+ crmProviders: CrmProviderRegistry;
207
+ /**
208
+ * The funnel registry (§5b.4): every `defineFunnel` plus the synthesized
209
+ * `"default"` carrying the crm sugar. Routes stage events by
210
+ * (provider, pipeline) claim; admin stats/Studio render per funnel.
211
+ */
212
+ funnels: FunnelRegistry;
161
213
  /**
162
214
  * The container-held registry of analytics providers, keyed by `meta.id` —
163
215
  * the analytics sibling of {@link emailProviders}. Built from env presets
@@ -223,6 +275,13 @@ export interface HogsendClient {
223
275
  * `/v1/connectors/:id/*` routes read `get(id).handlers`.
224
276
  */
225
277
  connectorRegistry: ConnectorRegistry;
278
+ /**
279
+ * The contact-source registry (Clay/Attio/generic-webhook origins), keyed by
280
+ * `meta.id`. `isProspectSource()` classifies a contact's `contacts.source` as
281
+ * a cold prospect origin; the cold posture + write-back travel with each
282
+ * entry. Installed as the process singleton in BOTH the API and worker.
283
+ */
284
+ contactSourceRegistry: ContactSourceRegistry;
226
285
  /**
227
286
  * The connector OUTBOUND ACTION registry, keyed by `${connectorId}:${name}`.
228
287
  * Holds the journey-callable imperative actions (Discord post / broadcast /
@@ -338,6 +397,57 @@ export interface HogsendClientOptions {
338
397
  linkTracking?: boolean;
339
398
  linkHost?: string;
340
399
  };
400
+ /**
401
+ * Code-first conversion-point definitions (plan §5.1) — `defineConversion`
402
+ * results. Evaluated inside `ingestEvent` after every fresh event insert;
403
+ * fired instances land in the `conversions` table.
404
+ */
405
+ conversions?: DefinedConversion[];
406
+ /**
407
+ * Conversion DESTINATIONS (plan §5.2) — ad-platform feedback providers
408
+ * (`defineConversionDestination`; Meta CAPI is the reference). Referenced
409
+ * by id from `defineConversion({ destinations })`.
410
+ */
411
+ conversionDestinations?: ConversionDestination[];
412
+ /**
413
+ * CRM sync providers (docs/revenue-attribution-plan.md §4) — the pluggable
414
+ * layer that pushes leads INTO client CRMs and lands pipeline stage changes
415
+ * + deal values back on the event spine as `funnel.stage_changed`. Register
416
+ * one (`provider`) or many (`providers`); each is webhook-served at
417
+ * `POST /v1/webhooks/crm/:providerId` and polled for reconciliation where
418
+ * it implements `poll`. No "active" selection — many CRMs sync at once.
419
+ */
420
+ crm?: {
421
+ provider?: CrmProvider;
422
+ providers?: CrmProvider[];
423
+ /**
424
+ * Per-provider stage maps: native `(pipelineId|'*') → stageId → canonical
425
+ * stage` — the one-CRM-no-funnels 3-liner. Desugars into `crmPipeline`
426
+ * bindings on the synthesized `"default"` funnel. Unmapped stages record
427
+ * native ids and warn (the provider's won/lost status hint still resolves
428
+ * sold/lost). Every mapped value must be a ladder stage or `"lost"` —
429
+ * validated at boot.
430
+ */
431
+ stageMaps?: Record<string, CrmStageMap>;
432
+ /**
433
+ * YOUR canonical funnel's stages, in rank order — replaces the built-in
434
+ * `lead → contacted → survey_booked → quoted → sold`. Same entries as
435
+ * `defineFunnel`: plain strings, or objects carrying `milestone` (and
436
+ * `on` event triggers). All-string arrays get the legacy money defaults
437
+ * (soldStage = last stage, quotedStage = a stage literally named
438
+ * "quoted"); any object entry makes milestones explicit-only. `"lost"`
439
+ * stays the implicit terminal. Zero migration: only new stage events
440
+ * re-rank.
441
+ */
442
+ stages?: FunnelStageEntry[];
443
+ };
444
+ /**
445
+ * Funnels as code-first primitives (§5b.4) — `defineFunnel` results. Each
446
+ * claims CRM traffic via its `bindings` (provider, pipeline) pairs;
447
+ * overlapping claims throw at boot. The `crm.{stages,stageMaps}` group
448
+ * above is sugar for a single `"default"` funnel and composes with these.
449
+ */
450
+ funnels?: DefinedFunnel[];
341
451
  /**
342
452
  * The analytics provider(s) — provider-neutral since the
343
453
  * `AnalyticsProvider` contract (the analytics sibling of `EmailProvider`;
@@ -412,6 +522,15 @@ export interface HogsendClientOptions {
412
522
  * Still also accepted by `createApp({ webhookSources })`.
413
523
  */
414
524
  webhookSources?: DefinedWebhookSource[];
525
+ /**
526
+ * Code-defined CONTACT SOURCES (`defineContactSource()`) — Clay/Attio/generic
527
+ * webhook origins of cold "prospects". Each is lifted onto the webhook-source
528
+ * umbrella (served at `POST /v1/webhooks/:sourceId`, provenance-stamped from
529
+ * `meta.id`) AND registered in the {@link ContactSourceRegistry} so the engine
530
+ * can classify sourced contacts + resolve their cold posture / write-back.
531
+ * Wire in BOTH `index.ts` and `worker.ts`. Defaults to none.
532
+ */
533
+ contactSources?: DefinedContactSource[];
415
534
  /**
416
535
  * Auto-register the shipped webhook-source PRESETS (Clerk, Supabase, Stripe,
417
536
  * Segment) for every preset whose env secret is configured (gated further by
@@ -665,6 +784,84 @@ export function createHogsendClient(
665
784
  ]);
666
785
  const smsConfigured = smsProviders.count() > 0;
667
786
 
787
+ // CRM sync providers (§Phase 4). No env presets yet — CRM credentials are
788
+ // per-deployment enough that construction stays consumer-side; the single
789
+ // `provider` merges LAST (wins an id collision with `providers`).
790
+ const crmProviders = new CrmProviderRegistry([
791
+ ...(opts.crm?.providers ?? []),
792
+ ...(opts.crm?.provider ? [opts.crm.provider] : []),
793
+ ]);
794
+ // Funnels (§5b.4): authored `defineFunnel`s plus a synthesized "default"
795
+ // carrying the crm.{stages,stageMaps} sugar — unless the consumer authored
796
+ // their own default. The sugar desugars THROUGH defineFunnel itself (one
797
+ // normalization + validation path: ladder rules, milestone rules, binding
798
+ // targets). The registry ctor throws on overlapping pipeline claims and
799
+ // duplicate ids.
800
+ const authoredFunnels = opts.funnels ?? [];
801
+ const authoredDefault = authoredFunnels.some(
802
+ (f) => f.meta.id === DEFAULT_FUNNEL_ID,
803
+ );
804
+ const crmSugarPresent = Boolean(opts.crm?.stages || opts.crm?.stageMaps);
805
+ if (authoredDefault && crmSugarPresent) {
806
+ logger.warn(
807
+ 'crm.{stages,stageMaps} are IGNORED because a funnel with id "default" is authored — move that config into the funnel',
808
+ );
809
+ }
810
+ const defaultFunnel = authoredDefault
811
+ ? undefined
812
+ : defineFunnel({
813
+ id: DEFAULT_FUNNEL_ID,
814
+ stages: opts.crm?.stages ?? [...DEFAULT_PIPELINE_LADDER.stages],
815
+ bindings: Object.entries(opts.crm?.stageMaps ?? {}).flatMap(
816
+ ([providerId, map]) =>
817
+ Object.entries(map).map(([pipelineId, stages]) =>
818
+ crmPipeline({
819
+ provider: providerId,
820
+ pipeline: pipelineId,
821
+ stages,
822
+ }),
823
+ ),
824
+ ),
825
+ });
826
+ const funnels = new FunnelRegistry([
827
+ ...authoredFunnels,
828
+ ...(defaultFunnel ? [defaultFunnel] : []),
829
+ ]);
830
+
831
+ // Process singleton for the crm-reconcile cron (runs in BOTH API and worker;
832
+ // the cron reads it because task fns have no client reference).
833
+ setCrmSyncConfig({
834
+ registry: crmProviders,
835
+ funnels,
836
+ });
837
+
838
+ // Conversion-point registry (plan §5.1) — evaluated on every ingest in BOTH
839
+ // the API and worker processes.
840
+ // Zero-config revenue conversion (impact plan §5.2) — seeded unless the
841
+ // consumer authors their own `id: "revenue"` definition or opts out via
842
+ // HOGSEND_DEFAULT_REVENUE_CONVERSION=false (the seeded-PostHog-destination
843
+ // opt-out pattern).
844
+ const authoredConversions = opts.conversions ?? [];
845
+ const seedDefaultRevenue =
846
+ process.env.HOGSEND_DEFAULT_REVENUE_CONVERSION !== "false" &&
847
+ !authoredConversions.some((def) => def.meta.id === "revenue");
848
+ setConversionRegistry(
849
+ new ConversionRegistry(
850
+ seedDefaultRevenue
851
+ ? [...authoredConversions, defaultRevenueConversion]
852
+ : authoredConversions,
853
+ ),
854
+ );
855
+ setConversionDestinations(
856
+ new ConversionDestinationRegistry(opts.conversionDestinations ?? []),
857
+ );
858
+ // The durable dispatch task reference (composition root — the lib module
859
+ // cannot import the workflow without a cycle). Left UNSET under a hatchet
860
+ // override so tests never touch real gRPC; dispatch rows stay pending.
861
+ if (!opts.overrides?.hatchet) {
862
+ setConversionDispatchTask(dispatchConversionTask);
863
+ }
864
+
668
865
  const channelLists = synthesizeChannelLists(opts.connectorActions ?? [], {
669
866
  sms: smsConfigured,
670
867
  });
@@ -693,16 +890,30 @@ export function createHogsendClient(
693
890
  // SINGLE place Resend is constructed from env — so resolution is just a
694
891
  // registry lookup that throws if the active id resolves to nothing. NEVER
695
892
  // silently fall back for a non-resend id.
696
- const activeId =
697
- opts.email?.defaultProvider ?? env.EMAIL_PROVIDER ?? "resend";
698
- const provider = emailProviders.get(activeId);
893
+ const explicitId = opts.email?.defaultProvider ?? env.EMAIL_PROVIDER;
894
+ const activeId = explicitId ?? "resend";
895
+ let provider = emailProviders.get(activeId);
699
896
 
700
897
  if (!provider) {
701
- throw new Error(
702
- `email provider "${activeId}" is not registered (registered: ${emailProviders
703
- .getAll()
704
- .map((p) => p.meta?.id ?? "resend")
705
- .join(", ")})`,
898
+ // An EXPLICITLY requested id that resolves to nothing is a config error —
899
+ // throw (typo safety). So is an implicit default when OTHER providers are
900
+ // registered (e.g. Postmark-only without EMAIL_PROVIDER=postmark).
901
+ if (explicitId !== undefined || emailProviders.count() > 0) {
902
+ throw new Error(
903
+ `email provider "${activeId}" is not registered (registered: ${emailProviders
904
+ .getAll()
905
+ .map((p) => p.meta?.id ?? "resend")
906
+ .join(", ")})`,
907
+ );
908
+ }
909
+ // Zero providers + nothing requested = a fresh app without email creds
910
+ // yet. Boot INERT instead of crashing (mirrors the SMS channel's
911
+ // operator-opt-in stub): Studio, ingest and non-email journeys all work;
912
+ // each send fails per-call with an actionable message. The stub is NOT
913
+ // registered in the registry, so no webhook route resolves it.
914
+ provider = createUnconfiguredEmailProvider();
915
+ logger.warn(
916
+ "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.",
706
917
  );
707
918
  }
708
919
 
@@ -716,7 +927,7 @@ export function createHogsendClient(
716
927
  logger.warn(
717
928
  `provider ${
718
929
  provider.meta?.id ?? "resend"
719
- } reports account-level native tracking ON; disable it in the dashboard — first-party tracking is Hogsend's source of truth.`,
930
+ } 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.`,
720
931
  );
721
932
  }
722
933
 
@@ -1108,16 +1319,23 @@ export function createHogsendClient(
1108
1319
  const connectorList = [
1109
1320
  ...(enablePresets ? connectorsFromEnv(env) : []),
1110
1321
  ...(opts.webhookSources ?? []).map(webhookSourceToConnector),
1322
+ // Contact sources ride the SAME webhook path (provenance stamped from
1323
+ // meta.id); lift to a webhook source, then onto the connector umbrella.
1324
+ ...(opts.contactSources ?? [])
1325
+ .map(contactSourceToWebhookSource)
1326
+ .map(webhookSourceToConnector),
1111
1327
  ...(opts.connectors ?? []),
1112
1328
  ];
1113
1329
  for (const connector of connectorList) {
1114
1330
  if (
1115
1331
  (connector.meta.transport ?? "webhook") === "webhook" &&
1116
- (connector.meta.id === "email" || connector.meta.id === "sms")
1332
+ (connector.meta.id === "email" ||
1333
+ connector.meta.id === "sms" ||
1334
+ connector.meta.id === "crm")
1117
1335
  ) {
1118
1336
  throw new Error(
1119
1337
  `Connector id "${connector.meta.id}" is reserved for the ` +
1120
- "email/SMS-provider routes (POST /v1/webhooks/{email,sms}/:providerId). " +
1338
+ "email/SMS/CRM-provider routes (POST /v1/webhooks/{email,sms,crm}/:providerId). " +
1121
1339
  "Rename the connector.",
1122
1340
  );
1123
1341
  }
@@ -1128,6 +1346,30 @@ export function createHogsendClient(
1128
1346
  `Connector registry loaded: ${connectorRegistry.count()} connectors`,
1129
1347
  );
1130
1348
 
1349
+ // Build + install the contact-source registry (prospect classification + cold
1350
+ // posture + write-back), keyed by meta.id. Runs in BOTH the API and worker.
1351
+ const contactSourceRegistry = buildContactSourceRegistry(
1352
+ opts.contactSources ?? [],
1353
+ );
1354
+
1355
+ // Fail-loud at boot on a contact source with no secret: a `match` auth is OPEN
1356
+ // when the env value is empty, which for a contact source means an
1357
+ // UNAUTHENTICATED identity-write endpoint (it mints/enriches contacts and can
1358
+ // trigger outbound journeys). Warn so the operator catches the omission before
1359
+ // it ships. Mirrors the webhook route's secret resolution (env ?? process.env).
1360
+ for (const src of opts.contactSources ?? []) {
1361
+ if (src.auth.type !== "match") continue;
1362
+ const secret =
1363
+ (env[src.auth.envKey as keyof typeof env] as string | undefined) ??
1364
+ process.env[src.auth.envKey];
1365
+ if (!secret) {
1366
+ logger.warn(
1367
+ `Contact source "${src.meta.id}" has no secret set (env ${src.auth.envKey}) — ` +
1368
+ "its webhook currently accepts UNAUTHENTICATED contact writes. Set the secret.",
1369
+ );
1370
+ }
1371
+ }
1372
+
1131
1373
  // Build + install the connector ACTION registry (outbound imperative actions),
1132
1374
  // the action sibling of the connector registry above. Runs in BOTH the API and
1133
1375
  // worker (both call createHogsendClient), so `sendConnectorAction()` resolves
@@ -1165,7 +1407,7 @@ export function createHogsendClient(
1165
1407
  `Destination registry loaded: ${destinationRegistry.count()} destinations`,
1166
1408
  );
1167
1409
 
1168
- return {
1410
+ const client: HogsendClient = {
1169
1411
  env,
1170
1412
  logger,
1171
1413
  db,
@@ -1179,6 +1421,8 @@ export function createHogsendClient(
1179
1421
  smsService,
1180
1422
  smsProviders,
1181
1423
  smsProvider,
1424
+ crmProviders,
1425
+ funnels,
1182
1426
  analyticsProviders,
1183
1427
  analytics,
1184
1428
  identity,
@@ -1189,9 +1433,41 @@ export function createHogsendClient(
1189
1433
  listRegistry,
1190
1434
  campaigns: opts.campaigns ?? [],
1191
1435
  connectorRegistry,
1436
+ contactSourceRegistry,
1192
1437
  connectorActionRegistry,
1193
1438
  hatchet: opts.overrides?.hatchet ?? hatchet,
1194
1439
  clientJournal: opts.clientJournal ?? { entries: [] },
1195
1440
  defaults,
1196
1441
  };
1442
+
1443
+ // Boot-time reader for `hogsend connect posthog`'s persisted phc_: when no
1444
+ // provider resolved AND no POSTHOG_API_KEY is set, activate PostHog from the
1445
+ // stored derived credential (async, fire-and-forget — the container is built
1446
+ // synchronously; a failure leaves the container exactly as booted). ALL
1447
+ // activation effects live here, in one block, so "who mutates what" has a
1448
+ // single answer. Skipped under NODE_ENV=test so suites stay hermetic.
1449
+ if (!analytics && !env.POSTHOG_API_KEY && env.NODE_ENV !== "test") {
1450
+ void buildStoredPosthogProvider({ env, db, logger })
1451
+ .then((provider) => {
1452
+ if (!provider) return;
1453
+ // Someone claimed the slot while we read (consumer provider, race).
1454
+ if (client.analytics || analyticsProviders.get("posthog")) return;
1455
+ analyticsProviders.register(provider);
1456
+ client.analytics = provider;
1457
+ setAnalytics(provider);
1458
+ // Rebuild the boot closure that captured `analytics: undefined` so
1459
+ // identity merges propagate to the newly-live provider too.
1460
+ client.identity = createIdentityService({
1461
+ db,
1462
+ analytics: provider,
1463
+ logger,
1464
+ });
1465
+ logger.info(
1466
+ 'analytics provider "posthog" activated from the stored `hogsend connect posthog` credential — outbound capture is live without POSTHOG_API_KEY.',
1467
+ );
1468
+ })
1469
+ .catch(() => {});
1470
+ }
1471
+
1472
+ return client;
1197
1473
  }
@@ -21,9 +21,13 @@ import type { OutboundEventName } from "../lib/outbound.js";
21
21
  * into the process {@link getDestinationRegistry} the delivery task reads.
22
22
  *
23
23
  * NOTE: `defineDestination` is for event FAN-OUT to product/data tools
24
- * (PostHog, Segment, Slack, a CRM, a warehouse). It is NOT the home for
25
- * ad-platform conversion forwarding (CAPI) — that stays deferred to PostHog CDP;
26
- * Hogsend just fires the events.
24
+ * (PostHog, Segment, Slack, a CRM, a warehouse). Ad-platform conversion
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
28
+ * joins, and deterministic event_id idempotency this generic pipe deliberately
29
+ * does not have. It is NOT deferred to any third-party CDP: the money path has
30
+ * no external dependency.
27
31
  */
28
32
 
29
33
  /** A live `webhook_endpoints` row, as read by the delivery task. */
@@ -153,11 +153,42 @@ export const posthogDestination = defineDestination({
153
153
  return setCapture(data.externalId, { [flag]: true });
154
154
  }
155
155
 
156
+ if (envelope.type === "contact.control_group") {
157
+ // Global control group membership (impact plan §4.4): a person flag
158
+ // so PostHog insights/experiments can slice program-level lift. The
159
+ // engine owns assignment (deterministic, durable-path); PostHog gets
160
+ // the raw material. Identity-less sends carry no addressable key.
161
+ const data =
162
+ envelope.data as unknown as OutboundPayloads["contact.control_group"];
163
+ if (!data.userId) return null;
164
+ return setCapture(data.userId, { hogsend_control_group: true });
165
+ }
166
+
156
167
  // contact.deleted: PostHog person deletion is a private-API operation,
157
168
  // not a capture — out of scope for this rail.
158
169
  return null;
159
170
  }
160
171
 
172
+ // Holdout membership as a person property (impact plan §4.4): when
173
+ // person sync is on, journey.heldout becomes a per-journey $set flag
174
+ // (`hogsend_holdout_<journeyId>: true`) so PostHog can slice any insight
175
+ // by holdout membership. With sync off it falls through to the generic
176
+ // event capture below — the event stream alone still records diversion.
177
+ if (envelope.type === "journey.heldout" && config.syncPersons === true) {
178
+ const heldout =
179
+ envelope.data as unknown as OutboundPayloads["journey.heldout"];
180
+ return captureRequest({
181
+ host,
182
+ apiKey: config.apiKey,
183
+ event: "$set",
184
+ distinctId: heldout.userId,
185
+ timestamp: envelope.timestamp,
186
+ properties: {
187
+ $set: { [`hogsend_holdout_${heldout.journeyId}`]: true },
188
+ },
189
+ });
190
+ }
191
+
161
192
  const data = envelope.data as {
162
193
  userId?: string | null;
163
194
  to?: string | null;