@hogsend/engine 0.43.0 → 0.44.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 (54) hide show
  1. package/package.json +10 -9
  2. package/src/container.ts +229 -2
  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/attribution-backfill.ts +285 -0
  9. package/src/lib/attribution.ts +239 -0
  10. package/src/lib/contacts.ts +71 -0
  11. package/src/lib/conversion-dispatch.ts +326 -0
  12. package/src/lib/conversions.ts +197 -0
  13. package/src/lib/crm-deals.ts +320 -0
  14. package/src/lib/crm-ingest.ts +341 -0
  15. package/src/lib/crm-provider-registry.ts +41 -0
  16. package/src/lib/crm-registry-singleton.ts +22 -0
  17. package/src/lib/deal-money-events.ts +85 -0
  18. package/src/lib/email-service-types.ts +16 -1
  19. package/src/lib/event-names.ts +1 -1
  20. package/src/lib/funnel-progress.ts +76 -0
  21. package/src/lib/funnel-registry.ts +108 -0
  22. package/src/lib/funnel-transitions.ts +280 -0
  23. package/src/lib/holdout.ts +62 -0
  24. package/src/lib/ingestion.ts +218 -9
  25. package/src/lib/lift-stats.ts +125 -0
  26. package/src/lib/mailer.ts +1 -0
  27. package/src/lib/operator.ts +31 -0
  28. package/src/lib/outbound.ts +51 -0
  29. package/src/lib/revenue.ts +116 -0
  30. package/src/lib/sms-service-types.ts +7 -1
  31. package/src/lib/sms-tracked.ts +35 -0
  32. package/src/lib/tracked.ts +40 -0
  33. package/src/lib/tracking-events.ts +26 -0
  34. package/src/lib/webhook-signing.ts +7 -0
  35. package/src/routes/admin/attribution.ts +414 -0
  36. package/src/routes/admin/contacts.ts +71 -11
  37. package/src/routes/admin/conversions.ts +247 -0
  38. package/src/routes/admin/deals.ts +472 -0
  39. package/src/routes/admin/funnels.ts +228 -0
  40. package/src/routes/admin/index.ts +8 -0
  41. package/src/routes/admin/journeys.ts +158 -1
  42. package/src/routes/admin/readiness.ts +97 -2
  43. package/src/routes/admin/templates.ts +28 -1
  44. package/src/routes/events/index.ts +12 -0
  45. package/src/routes/tracking/click-pipeline.ts +26 -18
  46. package/src/routes/webhooks/crm-provider.ts +117 -0
  47. package/src/routes/webhooks/index.ts +5 -1
  48. package/src/sources/define-contact-source.ts +159 -0
  49. package/src/sources/registry.ts +71 -0
  50. package/src/sources/webhook-source.ts +109 -0
  51. package/src/worker.ts +4 -0
  52. package/src/workflows/crm-reconcile.ts +129 -0
  53. package/src/workflows/dispatch-conversion.ts +31 -0
  54. 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.44.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -49,16 +49,17 @@
49
49
  "svix": "^1.95.1",
50
50
  "winston": "^3.19.0",
51
51
  "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"
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"
58
59
  },
59
60
  "optionalDependencies": {
60
- "@hogsend/plugin-postmark": "^0.43.0",
61
- "@hogsend/plugin-twilio": "^0.43.0"
61
+ "@hogsend/plugin-postmark": "^0.44.0",
62
+ "@hogsend/plugin-twilio": "^0.44.0"
62
63
  },
63
64
  "devDependencies": {
64
65
  "@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 {
@@ -59,6 +71,18 @@ import {
59
71
  setAnalyticsEventMirror,
60
72
  } from "./lib/analytics-singleton.js";
61
73
  import { type Auth, createAuth } from "./lib/auth.js";
74
+ import {
75
+ ConversionDestinationRegistry,
76
+ setConversionDestinations,
77
+ setConversionDispatchTask,
78
+ } from "./lib/conversion-dispatch.js";
79
+ import {
80
+ ConversionRegistry,
81
+ defaultRevenueConversion,
82
+ setConversionRegistry,
83
+ } from "./lib/conversions.js";
84
+ import { CrmProviderRegistry } from "./lib/crm-provider-registry.js";
85
+ import { setCrmSyncConfig } from "./lib/crm-registry-singleton.js";
62
86
  import {
63
87
  createDomainStatusService,
64
88
  type DomainStatusService,
@@ -70,6 +94,7 @@ import type {
70
94
  EmailService,
71
95
  FrequencyCapConfig,
72
96
  } from "./lib/email-service-types.js";
97
+ import { FunnelRegistry } from "./lib/funnel-registry.js";
73
98
  import { hatchet } from "./lib/hatchet.js";
74
99
  import {
75
100
  createIdentityService,
@@ -93,10 +118,19 @@ import {
93
118
  RESERVED_LIST_IDS,
94
119
  } from "./lists/define-list.js";
95
120
  import { buildListRegistry, type ListRegistry } from "./lists/registry.js";
121
+ import {
122
+ contactSourceToWebhookSource,
123
+ type DefinedContactSource,
124
+ } from "./sources/define-contact-source.js";
125
+ import {
126
+ buildContactSourceRegistry,
127
+ type ContactSourceRegistry,
128
+ } from "./sources/registry.js";
96
129
  import {
97
130
  type DefinedWebhookSource,
98
131
  webhookSourceToConnector,
99
132
  } from "./webhook-sources/define-webhook-source.js";
133
+ import { dispatchConversionTask } from "./workflows/dispatch-conversion.js";
100
134
 
101
135
  export interface HogsendDefaults {
102
136
  /** Global fallback IANA timezone for scheduling. Defaults to "UTC". */
@@ -158,6 +192,20 @@ export interface HogsendClient {
158
192
  * Undefined when no SMS provider is configured.
159
193
  */
160
194
  smsProvider?: SmsProvider;
195
+ /**
196
+ * The container-held registry of CRM providers, keyed by `meta.id`. The
197
+ * `POST /v1/webhooks/crm/:providerId` route resolves the verifying provider
198
+ * out of this and the reconciliation poll walks it. Unlike email/SMS there
199
+ * is no single "active" CRM — many sync concurrently; `pushLead` callers
200
+ * name the provider. Empty when none configured.
201
+ */
202
+ crmProviders: CrmProviderRegistry;
203
+ /**
204
+ * The funnel registry (§5b.4): every `defineFunnel` plus the synthesized
205
+ * `"default"` carrying the crm sugar. Routes stage events by
206
+ * (provider, pipeline) claim; admin stats/Studio render per funnel.
207
+ */
208
+ funnels: FunnelRegistry;
161
209
  /**
162
210
  * The container-held registry of analytics providers, keyed by `meta.id` —
163
211
  * the analytics sibling of {@link emailProviders}. Built from env presets
@@ -223,6 +271,13 @@ export interface HogsendClient {
223
271
  * `/v1/connectors/:id/*` routes read `get(id).handlers`.
224
272
  */
225
273
  connectorRegistry: ConnectorRegistry;
274
+ /**
275
+ * The contact-source registry (Clay/Attio/generic-webhook origins), keyed by
276
+ * `meta.id`. `isProspectSource()` classifies a contact's `contacts.source` as
277
+ * a cold prospect origin; the cold posture + write-back travel with each
278
+ * entry. Installed as the process singleton in BOTH the API and worker.
279
+ */
280
+ contactSourceRegistry: ContactSourceRegistry;
226
281
  /**
227
282
  * The connector OUTBOUND ACTION registry, keyed by `${connectorId}:${name}`.
228
283
  * Holds the journey-callable imperative actions (Discord post / broadcast /
@@ -338,6 +393,57 @@ export interface HogsendClientOptions {
338
393
  linkTracking?: boolean;
339
394
  linkHost?: string;
340
395
  };
396
+ /**
397
+ * Code-first conversion-point definitions (plan §5.1) — `defineConversion`
398
+ * results. Evaluated inside `ingestEvent` after every fresh event insert;
399
+ * fired instances land in the `conversions` table.
400
+ */
401
+ conversions?: DefinedConversion[];
402
+ /**
403
+ * Conversion DESTINATIONS (plan §5.2) — ad-platform feedback providers
404
+ * (`defineConversionDestination`; Meta CAPI is the reference). Referenced
405
+ * by id from `defineConversion({ destinations })`.
406
+ */
407
+ conversionDestinations?: ConversionDestination[];
408
+ /**
409
+ * CRM sync providers (docs/revenue-attribution-plan.md §4) — the pluggable
410
+ * layer that pushes leads INTO client CRMs and lands pipeline stage changes
411
+ * + deal values back on the event spine as `funnel.stage_changed`. Register
412
+ * one (`provider`) or many (`providers`); each is webhook-served at
413
+ * `POST /v1/webhooks/crm/:providerId` and polled for reconciliation where
414
+ * it implements `poll`. No "active" selection — many CRMs sync at once.
415
+ */
416
+ crm?: {
417
+ provider?: CrmProvider;
418
+ providers?: CrmProvider[];
419
+ /**
420
+ * Per-provider stage maps: native `(pipelineId|'*') → stageId → canonical
421
+ * stage` — the one-CRM-no-funnels 3-liner. Desugars into `crmPipeline`
422
+ * bindings on the synthesized `"default"` funnel. Unmapped stages record
423
+ * native ids and warn (the provider's won/lost status hint still resolves
424
+ * sold/lost). Every mapped value must be a ladder stage or `"lost"` —
425
+ * validated at boot.
426
+ */
427
+ stageMaps?: Record<string, CrmStageMap>;
428
+ /**
429
+ * YOUR canonical funnel's stages, in rank order — replaces the built-in
430
+ * `lead → contacted → survey_booked → quoted → sold`. Same entries as
431
+ * `defineFunnel`: plain strings, or objects carrying `milestone` (and
432
+ * `on` event triggers). All-string arrays get the legacy money defaults
433
+ * (soldStage = last stage, quotedStage = a stage literally named
434
+ * "quoted"); any object entry makes milestones explicit-only. `"lost"`
435
+ * stays the implicit terminal. Zero migration: only new stage events
436
+ * re-rank.
437
+ */
438
+ stages?: FunnelStageEntry[];
439
+ };
440
+ /**
441
+ * Funnels as code-first primitives (§5b.4) — `defineFunnel` results. Each
442
+ * claims CRM traffic via its `bindings` (provider, pipeline) pairs;
443
+ * overlapping claims throw at boot. The `crm.{stages,stageMaps}` group
444
+ * above is sugar for a single `"default"` funnel and composes with these.
445
+ */
446
+ funnels?: DefinedFunnel[];
341
447
  /**
342
448
  * The analytics provider(s) — provider-neutral since the
343
449
  * `AnalyticsProvider` contract (the analytics sibling of `EmailProvider`;
@@ -412,6 +518,15 @@ export interface HogsendClientOptions {
412
518
  * Still also accepted by `createApp({ webhookSources })`.
413
519
  */
414
520
  webhookSources?: DefinedWebhookSource[];
521
+ /**
522
+ * Code-defined CONTACT SOURCES (`defineContactSource()`) — Clay/Attio/generic
523
+ * webhook origins of cold "prospects". Each is lifted onto the webhook-source
524
+ * umbrella (served at `POST /v1/webhooks/:sourceId`, provenance-stamped from
525
+ * `meta.id`) AND registered in the {@link ContactSourceRegistry} so the engine
526
+ * can classify sourced contacts + resolve their cold posture / write-back.
527
+ * Wire in BOTH `index.ts` and `worker.ts`. Defaults to none.
528
+ */
529
+ contactSources?: DefinedContactSource[];
415
530
  /**
416
531
  * Auto-register the shipped webhook-source PRESETS (Clerk, Supabase, Stripe,
417
532
  * Segment) for every preset whose env secret is configured (gated further by
@@ -665,6 +780,84 @@ export function createHogsendClient(
665
780
  ]);
666
781
  const smsConfigured = smsProviders.count() > 0;
667
782
 
783
+ // CRM sync providers (§Phase 4). No env presets yet — CRM credentials are
784
+ // per-deployment enough that construction stays consumer-side; the single
785
+ // `provider` merges LAST (wins an id collision with `providers`).
786
+ const crmProviders = new CrmProviderRegistry([
787
+ ...(opts.crm?.providers ?? []),
788
+ ...(opts.crm?.provider ? [opts.crm.provider] : []),
789
+ ]);
790
+ // Funnels (§5b.4): authored `defineFunnel`s plus a synthesized "default"
791
+ // carrying the crm.{stages,stageMaps} sugar — unless the consumer authored
792
+ // their own default. The sugar desugars THROUGH defineFunnel itself (one
793
+ // normalization + validation path: ladder rules, milestone rules, binding
794
+ // targets). The registry ctor throws on overlapping pipeline claims and
795
+ // duplicate ids.
796
+ const authoredFunnels = opts.funnels ?? [];
797
+ const authoredDefault = authoredFunnels.some(
798
+ (f) => f.meta.id === DEFAULT_FUNNEL_ID,
799
+ );
800
+ const crmSugarPresent = Boolean(opts.crm?.stages || opts.crm?.stageMaps);
801
+ if (authoredDefault && crmSugarPresent) {
802
+ logger.warn(
803
+ 'crm.{stages,stageMaps} are IGNORED because a funnel with id "default" is authored — move that config into the funnel',
804
+ );
805
+ }
806
+ const defaultFunnel = authoredDefault
807
+ ? undefined
808
+ : defineFunnel({
809
+ id: DEFAULT_FUNNEL_ID,
810
+ stages: opts.crm?.stages ?? [...DEFAULT_PIPELINE_LADDER.stages],
811
+ bindings: Object.entries(opts.crm?.stageMaps ?? {}).flatMap(
812
+ ([providerId, map]) =>
813
+ Object.entries(map).map(([pipelineId, stages]) =>
814
+ crmPipeline({
815
+ provider: providerId,
816
+ pipeline: pipelineId,
817
+ stages,
818
+ }),
819
+ ),
820
+ ),
821
+ });
822
+ const funnels = new FunnelRegistry([
823
+ ...authoredFunnels,
824
+ ...(defaultFunnel ? [defaultFunnel] : []),
825
+ ]);
826
+
827
+ // Process singleton for the crm-reconcile cron (runs in BOTH API and worker;
828
+ // the cron reads it because task fns have no client reference).
829
+ setCrmSyncConfig({
830
+ registry: crmProviders,
831
+ funnels,
832
+ });
833
+
834
+ // Conversion-point registry (plan §5.1) — evaluated on every ingest in BOTH
835
+ // the API and worker processes.
836
+ // Zero-config revenue conversion (impact plan §5.2) — seeded unless the
837
+ // consumer authors their own `id: "revenue"` definition or opts out via
838
+ // HOGSEND_DEFAULT_REVENUE_CONVERSION=false (the seeded-PostHog-destination
839
+ // opt-out pattern).
840
+ const authoredConversions = opts.conversions ?? [];
841
+ const seedDefaultRevenue =
842
+ process.env.HOGSEND_DEFAULT_REVENUE_CONVERSION !== "false" &&
843
+ !authoredConversions.some((def) => def.meta.id === "revenue");
844
+ setConversionRegistry(
845
+ new ConversionRegistry(
846
+ seedDefaultRevenue
847
+ ? [...authoredConversions, defaultRevenueConversion]
848
+ : authoredConversions,
849
+ ),
850
+ );
851
+ setConversionDestinations(
852
+ new ConversionDestinationRegistry(opts.conversionDestinations ?? []),
853
+ );
854
+ // The durable dispatch task reference (composition root — the lib module
855
+ // cannot import the workflow without a cycle). Left UNSET under a hatchet
856
+ // override so tests never touch real gRPC; dispatch rows stay pending.
857
+ if (!opts.overrides?.hatchet) {
858
+ setConversionDispatchTask(dispatchConversionTask);
859
+ }
860
+
668
861
  const channelLists = synthesizeChannelLists(opts.connectorActions ?? [], {
669
862
  sms: smsConfigured,
670
863
  });
@@ -1108,16 +1301,23 @@ export function createHogsendClient(
1108
1301
  const connectorList = [
1109
1302
  ...(enablePresets ? connectorsFromEnv(env) : []),
1110
1303
  ...(opts.webhookSources ?? []).map(webhookSourceToConnector),
1304
+ // Contact sources ride the SAME webhook path (provenance stamped from
1305
+ // meta.id); lift to a webhook source, then onto the connector umbrella.
1306
+ ...(opts.contactSources ?? [])
1307
+ .map(contactSourceToWebhookSource)
1308
+ .map(webhookSourceToConnector),
1111
1309
  ...(opts.connectors ?? []),
1112
1310
  ];
1113
1311
  for (const connector of connectorList) {
1114
1312
  if (
1115
1313
  (connector.meta.transport ?? "webhook") === "webhook" &&
1116
- (connector.meta.id === "email" || connector.meta.id === "sms")
1314
+ (connector.meta.id === "email" ||
1315
+ connector.meta.id === "sms" ||
1316
+ connector.meta.id === "crm")
1117
1317
  ) {
1118
1318
  throw new Error(
1119
1319
  `Connector id "${connector.meta.id}" is reserved for the ` +
1120
- "email/SMS-provider routes (POST /v1/webhooks/{email,sms}/:providerId). " +
1320
+ "email/SMS/CRM-provider routes (POST /v1/webhooks/{email,sms,crm}/:providerId). " +
1121
1321
  "Rename the connector.",
1122
1322
  );
1123
1323
  }
@@ -1128,6 +1328,30 @@ export function createHogsendClient(
1128
1328
  `Connector registry loaded: ${connectorRegistry.count()} connectors`,
1129
1329
  );
1130
1330
 
1331
+ // Build + install the contact-source registry (prospect classification + cold
1332
+ // posture + write-back), keyed by meta.id. Runs in BOTH the API and worker.
1333
+ const contactSourceRegistry = buildContactSourceRegistry(
1334
+ opts.contactSources ?? [],
1335
+ );
1336
+
1337
+ // Fail-loud at boot on a contact source with no secret: a `match` auth is OPEN
1338
+ // when the env value is empty, which for a contact source means an
1339
+ // UNAUTHENTICATED identity-write endpoint (it mints/enriches contacts and can
1340
+ // trigger outbound journeys). Warn so the operator catches the omission before
1341
+ // it ships. Mirrors the webhook route's secret resolution (env ?? process.env).
1342
+ for (const src of opts.contactSources ?? []) {
1343
+ if (src.auth.type !== "match") continue;
1344
+ const secret =
1345
+ (env[src.auth.envKey as keyof typeof env] as string | undefined) ??
1346
+ process.env[src.auth.envKey];
1347
+ if (!secret) {
1348
+ logger.warn(
1349
+ `Contact source "${src.meta.id}" has no secret set (env ${src.auth.envKey}) — ` +
1350
+ "its webhook currently accepts UNAUTHENTICATED contact writes. Set the secret.",
1351
+ );
1352
+ }
1353
+ }
1354
+
1131
1355
  // Build + install the connector ACTION registry (outbound imperative actions),
1132
1356
  // the action sibling of the connector registry above. Runs in BOTH the API and
1133
1357
  // worker (both call createHogsendClient), so `sendConnectorAction()` resolves
@@ -1179,6 +1403,8 @@ export function createHogsendClient(
1179
1403
  smsService,
1180
1404
  smsProviders,
1181
1405
  smsProvider,
1406
+ crmProviders,
1407
+ funnels,
1182
1408
  analyticsProviders,
1183
1409
  analytics,
1184
1410
  identity,
@@ -1189,6 +1415,7 @@ export function createHogsendClient(
1189
1415
  listRegistry,
1190
1416
  campaigns: opts.campaigns ?? [],
1191
1417
  connectorRegistry,
1418
+ contactSourceRegistry,
1192
1419
  connectorActionRegistry,
1193
1420
  hatchet: opts.overrides?.hatchet ?? hatchet,
1194
1421
  clientJournal: opts.clientJournal ?? { entries: [] },
@@ -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;
package/src/index.ts CHANGED
@@ -367,11 +367,51 @@ export {
367
367
  } from "./lib/connector-state.js";
368
368
  // --- Contacts identity (resolve/create — used by connector member-link) ---
369
369
  export { resolveOrCreateContact } from "./lib/contacts.js";
370
+ // --- Conversion dispatch (plan §5.2): destinations registry + delivery ---
371
+ export {
372
+ ConversionDestinationRegistry,
373
+ conversionEventId,
374
+ createConversionDispatches,
375
+ deliverConversionDispatch,
376
+ enqueueConversionDispatches,
377
+ getConversionDestinations,
378
+ recoverClickContext,
379
+ resetConversionDestinations,
380
+ setConversionDestinations,
381
+ } from "./lib/conversion-dispatch.js";
382
+ // --- Conversion points (plan §5.1): registry + ingest-time evaluation ---
383
+ export {
384
+ ConversionRegistry,
385
+ evaluateConversionsAtIngest,
386
+ type FiredConversion,
387
+ getConversionRegistry,
388
+ resetConversionRegistry,
389
+ setConversionRegistry,
390
+ } from "./lib/conversions.js";
370
391
  export {
371
392
  AdminAlreadyExistsError,
372
393
  type CreatedAdmin,
373
394
  createAdminUser,
374
395
  } from "./lib/create-admin.js";
396
+ // --- CRM sync (provider registry + the stage-event spine sink) ---
397
+ export {
398
+ type AppliedStageChange,
399
+ applyCrmStageEvent,
400
+ ensureCrmLinks,
401
+ resolveCrmLinkedContact,
402
+ } from "./lib/crm-deals.js";
403
+ export {
404
+ DEAL_QUOTED,
405
+ DEAL_SOLD,
406
+ FUNNEL_STAGE_CHANGED,
407
+ ingestCrmStageEvents,
408
+ } from "./lib/crm-ingest.js";
409
+ export { CrmProviderRegistry } from "./lib/crm-provider-registry.js";
410
+ export {
411
+ getCrmSyncConfig,
412
+ resetCrmSyncConfig,
413
+ setCrmSyncConfig,
414
+ } from "./lib/crm-registry-singleton.js";
375
415
  // --- Infrastructure singletons ---
376
416
  export { getDb } from "./lib/db.js";
377
417
  // --- Discord gateway-worker liveness heartbeat (Studio status) ---
@@ -420,7 +460,14 @@ export {
420
460
  } from "./lib/feed.js";
421
461
  export { countRecentSends, isFrequencyCapped } from "./lib/frequency-cap.js";
422
462
  export { addrSpecOf, hostOfFromAddress } from "./lib/from-address.js";
463
+ export { FunnelRegistry } from "./lib/funnel-registry.js";
423
464
  export { hatchet } from "./lib/hatchet.js";
465
+ export {
466
+ globalControlPercent,
467
+ holdoutBucket,
468
+ isGlobalControl,
469
+ isHeldOut,
470
+ } from "./lib/holdout.js";
424
471
  // --- Identity service (resolve/merge + analytics merge propagation, §7) ---
425
472
  export {
426
473
  createIdentityService,
@@ -448,6 +495,14 @@ export {
448
495
  releaseLeaderLease,
449
496
  renewLeaderLease,
450
497
  } from "./lib/leader-lease.js";
498
+ // --- Holdout lift statistics (impact plan §4.2) ---
499
+ export {
500
+ betaWinProbability,
501
+ computeLift,
502
+ type LiftVerdict,
503
+ MIN_COMBINED_CONVERSIONS,
504
+ SMALL_SAMPLE_FLOOR,
505
+ } from "./lib/lift-stats.js";
451
506
  // --- Managed tracked links (channel-agnostic mint — Studio/Discord/share) ---
452
507
  // NOTE: the QR scan-row plumbing (ensureQrTrackedLink, the canonical-row
453
508
  // filter, the 'qr' source marker) is deliberately NOT exported — it is
@@ -516,6 +571,12 @@ export {
516
571
  } from "./lib/redis.js";
517
572
  // --- Self-service password reset (engine-owned, self-contained email) ---
518
573
  export { sendResetPasswordEmail } from "./lib/reset-email.js";
574
+ // --- Revenue rollups (the event spine's value/currency columns) ---
575
+ export {
576
+ type ContactRevenue,
577
+ type ContactRevenueTotal,
578
+ getContactRevenue,
579
+ } from "./lib/revenue.js";
519
580
  // --- PostHog destination seed (idempotent; ENABLE_POSTHOG_DESTINATION) ---
520
581
  export { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
521
582
  export {
@@ -583,6 +644,14 @@ export {
583
644
  prepareTrackedHtml,
584
645
  rewriteLinks,
585
646
  } from "./lib/tracking.js";
647
+ // --- First-party tracking event names (touchpoint-classed in @hogsend/core) ---
648
+ export {
649
+ EMAIL_LINK_CLICKED,
650
+ EMAIL_OPENED,
651
+ LINK_ARRIVED,
652
+ LINK_CLICKED,
653
+ SMS_LINK_CLICKED,
654
+ } from "./lib/tracking-event-names.js";
586
655
  export {
587
656
  pushSmsTrackingEvent,
588
657
  pushTrackingEvent,
@@ -677,6 +746,32 @@ export {
677
746
  } from "./middleware/rate-limit.js";
678
747
  // --- Middleware (consumer-mounted routes, e.g. the @hogsend/mcp hosted route) ---
679
748
  export { requireAdmin } from "./middleware/require-admin.js";
749
+ // --- Contact sources (Clay/Attio/generic-webhook → cold prospects) ---
750
+ export {
751
+ type ColdChannelPosture,
752
+ type ColdPosture,
753
+ type ContactSourceMeta,
754
+ type ContactWriteBack,
755
+ contactSourceToWebhookSource,
756
+ type DefinedContactSource,
757
+ defaultColdPosture,
758
+ defineContactSource,
759
+ isColdChannelAllowed,
760
+ resolveColdPosture,
761
+ } from "./sources/define-contact-source.js";
762
+ export {
763
+ buildContactSourceRegistry,
764
+ ContactSourceRegistry,
765
+ getContactSourceRegistry,
766
+ setContactSourceRegistry,
767
+ } from "./sources/registry.js";
768
+ export {
769
+ normalizeWebhookContactEvent,
770
+ type WebhookContactPayload,
771
+ type WebhookContactSourceOptions,
772
+ webhookContactPayloadSchema,
773
+ webhookContactSource,
774
+ } from "./sources/webhook-source.js";
680
775
  // --- Webhook sources ---
681
776
  export {
682
777
  type DefinedWebhookSource,
@@ -717,6 +812,10 @@ export {
717
812
  checkAlertsTask,
718
813
  surfaceStrandedWaiting,
719
814
  } from "./workflows/check-alerts.js";
815
+ export {
816
+ crmReconcileTask,
817
+ runCrmReconcile,
818
+ } from "./workflows/crm-reconcile.js";
720
819
  // --- Outbound webhooks: durable delivery task + reaper (Section 1.5) ---
721
820
  export {
722
821
  deliverWebhookTask,
@@ -25,6 +25,8 @@ import {
25
25
  checkEntryLimit,
26
26
  } from "../lib/enrollment-guards.js";
27
27
  import { hatchet } from "../lib/hatchet.js";
28
+ import { isHeldOut } from "../lib/holdout.js";
29
+ import { ingestEvent } from "../lib/ingestion.js";
28
30
  import { createLogger } from "../lib/logger.js";
29
31
  import { emitOutbound } from "../lib/outbound.js";
30
32
  import { resolveTimezoneWithSource } from "../lib/timezone.js";
@@ -303,6 +305,97 @@ export async function executeJourneyRun(
303
305
  return { status: "skipped", reason: "user_unsubscribed" };
304
306
  }
305
307
 
308
+ // HOLDOUT DIVERSION (impact plan §4.1) — deliberately LAST in the guard
309
+ // chain: a contact who'd have been blocked by any gate above is never
310
+ // counted as held out (intent-to-treat — the control must mirror the
311
+ // would-have-entered population, not the triggered one). Assignment is a
312
+ // deterministic hash (replay law: no RNG in durable paths), so the same
313
+ // contact diverts identically on every trigger AND every replay. One
314
+ // held_out row per (user, journey), ever; the spine event's idempotency
315
+ // key carries the same once-ever semantics for fan-out/analytics.
316
+ if (meta.holdout && meta.holdout.percent > 0) {
317
+ const diverted = isHeldOut({
318
+ userId,
319
+ journeyId: meta.id,
320
+ percent: meta.holdout.percent,
321
+ salt: meta.holdout.salt,
322
+ });
323
+ if (diverted) {
324
+ const priorHoldout = await db.query.journeyStates.findFirst({
325
+ where: and(
326
+ eq(journeyStates.userId, userId),
327
+ eq(journeyStates.journeyId, meta.id),
328
+ eq(journeyStates.status, "held_out"),
329
+ ),
330
+ });
331
+ if (!priorHoldout) {
332
+ const heldOutAt = new Date();
333
+ const inserted = await db
334
+ .insert(journeyStates)
335
+ .values({
336
+ userId,
337
+ userEmail,
338
+ journeyId: meta.id,
339
+ currentNodeId: "held-out",
340
+ status: "held_out",
341
+ context: properties,
342
+ exitedAt: heldOutAt,
343
+ })
344
+ .returning({ id: journeyStates.id });
345
+ const holdoutStateId = inserted[0]?.id;
346
+ if (holdoutStateId) {
347
+ // The counterfactual as data (the Iterable Send Skip pattern):
348
+ // queryable on the spine, fan-out-able to journeys/destinations.
349
+ // Once-ever per (user, journey) via the idempotency key — a
350
+ // concurrent double-diversion dedups here even if it raced the
351
+ // row existence check above.
352
+ try {
353
+ await ingestEvent({
354
+ db,
355
+ registry: getJourneyRegistrySingleton(),
356
+ hatchet,
357
+ logger,
358
+ event: {
359
+ event: "journey.heldout",
360
+ userId,
361
+ userEmail,
362
+ eventProperties: {
363
+ journeyId: meta.id,
364
+ journeyName: meta.name,
365
+ holdoutPercent: meta.holdout.percent,
366
+ },
367
+ source: "journey",
368
+ idempotencyKey: `journey:heldout:${meta.id}:${userId}`,
369
+ },
370
+ });
371
+ } catch (err) {
372
+ logger.warn("journey.heldout ingest failed", {
373
+ journeyId: meta.id,
374
+ userId,
375
+ error: err instanceof Error ? err.message : String(err),
376
+ });
377
+ }
378
+ void emitOutbound({
379
+ db,
380
+ hatchet,
381
+ logger,
382
+ event: "journey.heldout",
383
+ dedupeKey: `journey.heldout:${holdoutStateId}`,
384
+ payload: {
385
+ journeyId: meta.id,
386
+ journeyName: meta.name,
387
+ stateId: holdoutStateId,
388
+ userId,
389
+ userEmail,
390
+ heldOutAt: heldOutAt.toISOString(),
391
+ },
392
+ }).catch(logger.warn);
393
+ }
394
+ }
395
+ return { status: "skipped", reason: "held_out" };
396
+ }
397
+ }
398
+
306
399
  const activeState = await db.query.journeyStates.findFirst({
307
400
  where: and(
308
401
  eq(journeyStates.userId, userId),