@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.
- package/package.json +10 -9
- package/src/container.ts +229 -2
- package/src/destinations/define-destination.ts +7 -3
- package/src/destinations/presets/posthog.ts +31 -0
- package/src/index.ts +99 -0
- package/src/journeys/execute-journey-run.ts +93 -0
- package/src/journeys/journey-context.ts +4 -0
- package/src/lib/attribution-backfill.ts +285 -0
- package/src/lib/attribution.ts +239 -0
- package/src/lib/contacts.ts +71 -0
- package/src/lib/conversion-dispatch.ts +326 -0
- package/src/lib/conversions.ts +197 -0
- package/src/lib/crm-deals.ts +320 -0
- package/src/lib/crm-ingest.ts +341 -0
- package/src/lib/crm-provider-registry.ts +41 -0
- package/src/lib/crm-registry-singleton.ts +22 -0
- package/src/lib/deal-money-events.ts +85 -0
- package/src/lib/email-service-types.ts +16 -1
- package/src/lib/event-names.ts +1 -1
- package/src/lib/funnel-progress.ts +76 -0
- package/src/lib/funnel-registry.ts +108 -0
- package/src/lib/funnel-transitions.ts +280 -0
- package/src/lib/holdout.ts +62 -0
- package/src/lib/ingestion.ts +218 -9
- package/src/lib/lift-stats.ts +125 -0
- package/src/lib/mailer.ts +1 -0
- package/src/lib/operator.ts +31 -0
- package/src/lib/outbound.ts +51 -0
- package/src/lib/revenue.ts +116 -0
- package/src/lib/sms-service-types.ts +7 -1
- package/src/lib/sms-tracked.ts +35 -0
- package/src/lib/tracked.ts +40 -0
- package/src/lib/tracking-events.ts +26 -0
- package/src/lib/webhook-signing.ts +7 -0
- package/src/routes/admin/attribution.ts +414 -0
- package/src/routes/admin/contacts.ts +71 -11
- package/src/routes/admin/conversions.ts +247 -0
- package/src/routes/admin/deals.ts +472 -0
- package/src/routes/admin/funnels.ts +228 -0
- package/src/routes/admin/index.ts +8 -0
- package/src/routes/admin/journeys.ts +158 -1
- package/src/routes/admin/readiness.ts +97 -2
- package/src/routes/admin/templates.ts +28 -1
- package/src/routes/events/index.ts +12 -0
- package/src/routes/tracking/click-pipeline.ts +26 -18
- package/src/routes/webhooks/crm-provider.ts +117 -0
- package/src/routes/webhooks/index.ts +5 -1
- package/src/sources/define-contact-source.ts +159 -0
- package/src/sources/registry.ts +71 -0
- package/src/sources/webhook-source.ts +109 -0
- package/src/worker.ts +4 -0
- package/src/workflows/crm-reconcile.ts +129 -0
- package/src/workflows/dispatch-conversion.ts +31 -0
- 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.
|
|
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/
|
|
53
|
-
"@hogsend/
|
|
54
|
-
"@hogsend/
|
|
55
|
-
"@hogsend/
|
|
56
|
-
"@hogsend/plugin-
|
|
57
|
-
"@hogsend/
|
|
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.
|
|
61
|
-
"@hogsend/plugin-twilio": "^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" ||
|
|
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).
|
|
25
|
-
*
|
|
26
|
-
*
|
|
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),
|