@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.
- package/package.json +12 -9
- package/src/container.ts +289 -13
- 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/analytics-providers-from-env.ts +106 -43
- 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/posthog-scopes.ts +30 -6
- 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/unconfigured-email-provider.ts +45 -0
- package/src/lib/webhook-signing.ts +7 -0
- package/src/routes/admin/analytics.ts +14 -5
- 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.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/
|
|
53
|
-
"@hogsend/
|
|
54
|
-
"@hogsend/
|
|
55
|
-
"@hogsend/
|
|
56
|
-
"@hogsend/plugin-
|
|
57
|
-
"@hogsend/
|
|
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.
|
|
61
|
-
"@hogsend/plugin-twilio": "^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 {
|
|
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
|
|
697
|
-
|
|
698
|
-
|
|
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
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
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
|
-
}
|
|
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" ||
|
|
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
|
-
|
|
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).
|
|
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;
|