@hogsend/engine 0.42.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 -7
- package/src/container.ts +419 -4
- package/src/destinations/define-destination.ts +7 -3
- package/src/destinations/presets/posthog.ts +31 -0
- package/src/env.ts +28 -0
- package/src/index.ts +138 -0
- package/src/journeys/execute-journey-run.ts +93 -0
- package/src/journeys/journey-boundary.ts +5 -1
- package/src/journeys/journey-context.ts +30 -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/journey-suppress.ts +33 -2
- 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 +109 -0
- package/src/lib/phone.ts +19 -0
- package/src/lib/preferences.ts +32 -0
- package/src/lib/revenue.ts +116 -0
- package/src/lib/sms-frequency-cap.ts +47 -0
- package/src/lib/sms-inbound.ts +200 -0
- package/src/lib/sms-link-tracking.ts +160 -0
- package/src/lib/sms-mailer.ts +338 -0
- package/src/lib/sms-provider-registry.ts +35 -0
- package/src/lib/sms-providers-from-env.ts +100 -0
- package/src/lib/sms-service-types.ts +175 -0
- package/src/lib/sms-tracked.ts +625 -0
- package/src/lib/sms.ts +117 -0
- package/src/lib/tracked.ts +40 -0
- package/src/lib/tracking-event-names.ts +6 -0
- package/src/lib/tracking-events.ts +133 -1
- package/src/lib/tracking.ts +2 -1
- package/src/lib/webhook-signing.ts +24 -1
- package/src/lists/channels.ts +21 -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/email/unsubscribe.ts +1 -0
- package/src/routes/events/index.ts +12 -0
- package/src/routes/index.ts +6 -0
- package/src/routes/lists/index.ts +54 -7
- package/src/routes/tracking/click-pipeline.ts +105 -16
- package/src/routes/tracking/short.ts +61 -0
- package/src/routes/webhooks/crm-provider.ts +117 -0
- package/src/routes/webhooks/index.ts +9 -1
- package/src/routes/webhooks/sms-provider.ts +110 -0
- 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/import-contacts.ts +61 -4
- 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,14 +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-
|
|
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"
|
|
57
59
|
},
|
|
58
60
|
"optionalDependencies": {
|
|
59
|
-
"@hogsend/plugin-postmark": "^0.
|
|
61
|
+
"@hogsend/plugin-postmark": "^0.44.0",
|
|
62
|
+
"@hogsend/plugin-twilio": "^0.44.0"
|
|
60
63
|
},
|
|
61
64
|
"devDependencies": {
|
|
62
65
|
"@types/node": "^22.15.3",
|
package/src/container.ts
CHANGED
|
@@ -2,11 +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,
|
|
14
|
+
SmsProvider,
|
|
8
15
|
TimeZone,
|
|
9
16
|
} from "@hogsend/core";
|
|
17
|
+
import {
|
|
18
|
+
crmPipeline,
|
|
19
|
+
DEFAULT_FUNNEL_ID,
|
|
20
|
+
DEFAULT_PIPELINE_LADDER,
|
|
21
|
+
defineFunnel,
|
|
22
|
+
} from "@hogsend/core";
|
|
10
23
|
import type { BucketRegistry, JourneyRegistry } from "@hogsend/core/registry";
|
|
11
24
|
import type { SendWindow } from "@hogsend/core/schedule";
|
|
12
25
|
import {
|
|
@@ -16,6 +29,7 @@ import {
|
|
|
16
29
|
type JournalShape,
|
|
17
30
|
} from "@hogsend/db";
|
|
18
31
|
import type { TemplateDefinition, TemplateRegistry } from "@hogsend/email";
|
|
32
|
+
import type { SmsTemplateDefinition, SmsTemplateRegistry } from "@hogsend/sms";
|
|
19
33
|
import { createBucketAccessor } from "./buckets/bucket-access.js";
|
|
20
34
|
import type { DefinedBucket } from "./buckets/define-bucket.js";
|
|
21
35
|
import {
|
|
@@ -57,6 +71,18 @@ import {
|
|
|
57
71
|
setAnalyticsEventMirror,
|
|
58
72
|
} from "./lib/analytics-singleton.js";
|
|
59
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";
|
|
60
86
|
import {
|
|
61
87
|
createDomainStatusService,
|
|
62
88
|
type DomainStatusService,
|
|
@@ -68,6 +94,7 @@ import type {
|
|
|
68
94
|
EmailService,
|
|
69
95
|
FrequencyCapConfig,
|
|
70
96
|
} from "./lib/email-service-types.js";
|
|
97
|
+
import { FunnelRegistry } from "./lib/funnel-registry.js";
|
|
71
98
|
import { hatchet } from "./lib/hatchet.js";
|
|
72
99
|
import {
|
|
73
100
|
createIdentityService,
|
|
@@ -78,6 +105,11 @@ import { createTrackedMailer } from "./lib/mailer.js";
|
|
|
78
105
|
import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
|
|
79
106
|
import { sendResetPasswordEmail } from "./lib/reset-email.js";
|
|
80
107
|
import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
|
|
108
|
+
import { setSmsService } from "./lib/sms.js";
|
|
109
|
+
import { createTrackedSmsSender } from "./lib/sms-mailer.js";
|
|
110
|
+
import { SmsProviderRegistry } from "./lib/sms-provider-registry.js";
|
|
111
|
+
import { smsProvidersFromEnv } from "./lib/sms-providers-from-env.js";
|
|
112
|
+
import type { SmsService } from "./lib/sms-service-types.js";
|
|
81
113
|
import { prepareTrackedHtml } from "./lib/tracking.js";
|
|
82
114
|
import { synthesizeChannelLists } from "./lists/channels.js";
|
|
83
115
|
import {
|
|
@@ -86,10 +118,19 @@ import {
|
|
|
86
118
|
RESERVED_LIST_IDS,
|
|
87
119
|
} from "./lists/define-list.js";
|
|
88
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";
|
|
89
129
|
import {
|
|
90
130
|
type DefinedWebhookSource,
|
|
91
131
|
webhookSourceToConnector,
|
|
92
132
|
} from "./webhook-sources/define-webhook-source.js";
|
|
133
|
+
import { dispatchConversionTask } from "./workflows/dispatch-conversion.js";
|
|
93
134
|
|
|
94
135
|
export interface HogsendDefaults {
|
|
95
136
|
/** Global fallback IANA timezone for scheduling. Defaults to "UTC". */
|
|
@@ -134,6 +175,37 @@ export interface HogsendClient {
|
|
|
134
175
|
* templates without going through a send. Empty when no templates are wired.
|
|
135
176
|
*/
|
|
136
177
|
templates: TemplateRegistry;
|
|
178
|
+
/**
|
|
179
|
+
* The engine-owned tracked SMS sender (the SMS sibling of {@link emailService}).
|
|
180
|
+
* When no SMS provider is configured this is an inert stub whose `send` throws
|
|
181
|
+
* an actionable error — so an existing deploy without Twilio creds boots clean.
|
|
182
|
+
*/
|
|
183
|
+
smsService: SmsService;
|
|
184
|
+
/**
|
|
185
|
+
* The container-held registry of SMS providers, keyed by `meta.id`. The
|
|
186
|
+
* `POST /v1/webhooks/sms/:providerId` route resolves the verifying provider
|
|
187
|
+
* out of this. Empty when no SMS provider is configured.
|
|
188
|
+
*/
|
|
189
|
+
smsProviders: SmsProviderRegistry;
|
|
190
|
+
/**
|
|
191
|
+
* The single resolved active SMS provider the tracked sender delivers through.
|
|
192
|
+
* Undefined when no SMS provider is configured.
|
|
193
|
+
*/
|
|
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;
|
|
137
209
|
/**
|
|
138
210
|
* The container-held registry of analytics providers, keyed by `meta.id` —
|
|
139
211
|
* the analytics sibling of {@link emailProviders}. Built from env presets
|
|
@@ -199,6 +271,13 @@ export interface HogsendClient {
|
|
|
199
271
|
* `/v1/connectors/:id/*` routes read `get(id).handlers`.
|
|
200
272
|
*/
|
|
201
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;
|
|
202
281
|
/**
|
|
203
282
|
* The connector OUTBOUND ACTION registry, keyed by `${connectorId}:${name}`.
|
|
204
283
|
* Holds the journey-callable imperative actions (Discord post / broadcast /
|
|
@@ -274,6 +353,97 @@ export interface HogsendClientOptions {
|
|
|
274
353
|
defaultProvider?: string;
|
|
275
354
|
templates?: TemplateRegistry;
|
|
276
355
|
};
|
|
356
|
+
/**
|
|
357
|
+
* SMS is a first-class channel (the SMS sibling of {@link email}). Its config
|
|
358
|
+
* is grouped here; the engine owns the cohesive SMS pipeline (templates →
|
|
359
|
+
* render → preference/suppression checks → `sms_sends` write → STOP handling),
|
|
360
|
+
* and the {@link SmsProvider} (Twilio, …) is only the swappable wire.
|
|
361
|
+
*
|
|
362
|
+
* - `provider` — a single SMS provider. Merged LAST (after env presets and
|
|
363
|
+
* `providers`), so it wins on id collision.
|
|
364
|
+
* - `providers` — register MANY providers into the {@link SmsProviderRegistry}
|
|
365
|
+
* so `POST /v1/webhooks/sms/:providerId` can verify each one's webhooks.
|
|
366
|
+
* - `defaultProvider` — the active provider id the tracked sender delivers
|
|
367
|
+
* through. Resolves as `defaultProvider ?? SMS_PROVIDER ?? "twilio"`. If it
|
|
368
|
+
* names an unregistered provider, the container throws at boot.
|
|
369
|
+
* - `templates` — the app's SMS template registry (key → component +
|
|
370
|
+
* category), threaded into the tracked SMS sender.
|
|
371
|
+
* - `from` — the E.164 default sender (overrides env `SMS_FROM`).
|
|
372
|
+
* - `stopFooter` — the compliance footer appended to non-transactional
|
|
373
|
+
* bodies; `false` disables it, a string overrides the default text.
|
|
374
|
+
* - `optOutReplies` — send STOP/START/HELP confirmation replies (default off;
|
|
375
|
+
* the carrier already replies and a post-STOP send is blocked).
|
|
376
|
+
* - `linkTracking` — rewrite bare URLs in rendered bodies to first-party
|
|
377
|
+
* short tracked links (`/s/:code`). Default true (overrides env
|
|
378
|
+
* `SMS_LINK_TRACKING`).
|
|
379
|
+
* - `linkHost` — the full origin short links are minted under (overrides
|
|
380
|
+
* env `SMS_LINK_HOST`; falls back to `API_PUBLIC_URL`).
|
|
381
|
+
*
|
|
382
|
+
* Omitting `sms` entirely (or configuring no provider) installs an inert stub
|
|
383
|
+
* SMS service — an existing deploy without Twilio creds boots unchanged.
|
|
384
|
+
*/
|
|
385
|
+
sms?: {
|
|
386
|
+
provider?: SmsProvider;
|
|
387
|
+
providers?: SmsProvider[];
|
|
388
|
+
defaultProvider?: string;
|
|
389
|
+
templates?: SmsTemplateRegistry;
|
|
390
|
+
from?: string;
|
|
391
|
+
stopFooter?: string | false;
|
|
392
|
+
optOutReplies?: boolean;
|
|
393
|
+
linkTracking?: boolean;
|
|
394
|
+
linkHost?: string;
|
|
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[];
|
|
277
447
|
/**
|
|
278
448
|
* The analytics provider(s) — provider-neutral since the
|
|
279
449
|
* `AnalyticsProvider` contract (the analytics sibling of `EmailProvider`;
|
|
@@ -348,6 +518,15 @@ export interface HogsendClientOptions {
|
|
|
348
518
|
* Still also accepted by `createApp({ webhookSources })`.
|
|
349
519
|
*/
|
|
350
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[];
|
|
351
530
|
/**
|
|
352
531
|
* Auto-register the shipped webhook-source PRESETS (Clerk, Supabase, Stripe,
|
|
353
532
|
* Segment) for every preset whose env secret is configured (gated further by
|
|
@@ -498,6 +677,33 @@ function validateListCategory(opts: {
|
|
|
498
677
|
);
|
|
499
678
|
}
|
|
500
679
|
|
|
680
|
+
/**
|
|
681
|
+
* The inert SMS service installed when no SMS provider is configured. `render`
|
|
682
|
+
* still works (templates need no provider); `send` throws an actionable error;
|
|
683
|
+
* `handleWebhook` is a no-op (a stray webhook can't dispatch without a provider).
|
|
684
|
+
*/
|
|
685
|
+
function createStubSmsService(): SmsService {
|
|
686
|
+
const notConfigured = () => {
|
|
687
|
+
throw new Error(
|
|
688
|
+
"No SMS provider configured. Set TWILIO_ACCOUNT_SID/TWILIO_AUTH_TOKEN and SMS_FROM, or pass sms.provider to createHogsendClient.",
|
|
689
|
+
);
|
|
690
|
+
};
|
|
691
|
+
return {
|
|
692
|
+
async send() {
|
|
693
|
+
return notConfigured();
|
|
694
|
+
},
|
|
695
|
+
async sendRaw() {
|
|
696
|
+
return notConfigured();
|
|
697
|
+
},
|
|
698
|
+
async render() {
|
|
699
|
+
return notConfigured();
|
|
700
|
+
},
|
|
701
|
+
async handleWebhook(event) {
|
|
702
|
+
return { type: event.type, handled: false };
|
|
703
|
+
},
|
|
704
|
+
};
|
|
705
|
+
}
|
|
706
|
+
|
|
501
707
|
export function createHogsendClient(
|
|
502
708
|
opts: HogsendClientOptions = {},
|
|
503
709
|
): HogsendClient {
|
|
@@ -563,7 +769,98 @@ export function createHogsendClient(
|
|
|
563
769
|
// is available here before the connector-action registry is built, and is
|
|
564
770
|
// identical in both the API and worker processes — then registered
|
|
565
771
|
// unconditionally (bypassing ENABLED_LISTS) after the user lists.
|
|
566
|
-
|
|
772
|
+
// Build the SMS provider registry early (before channel synthesis) so the
|
|
773
|
+
// `sms` opt-out channel is minted iff an SMS provider is actually configured.
|
|
774
|
+
// Same merge order as email: env presets FIRST, then `providers`, then the
|
|
775
|
+
// single `provider` LAST (last-writer-wins).
|
|
776
|
+
const smsProviders = new SmsProviderRegistry([
|
|
777
|
+
...smsProvidersFromEnv(env),
|
|
778
|
+
...(opts.sms?.providers ?? []),
|
|
779
|
+
...(opts.sms?.provider ? [opts.sms.provider] : []),
|
|
780
|
+
]);
|
|
781
|
+
const smsConfigured = smsProviders.count() > 0;
|
|
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
|
+
|
|
861
|
+
const channelLists = synthesizeChannelLists(opts.connectorActions ?? [], {
|
|
862
|
+
sms: smsConfigured,
|
|
863
|
+
});
|
|
567
864
|
const listRegistry = buildListRegistry(
|
|
568
865
|
opts.lists ?? [],
|
|
569
866
|
opts.enabledLists ?? env.ENABLED_LISTS,
|
|
@@ -724,6 +1021,86 @@ export function createHogsendClient(
|
|
|
724
1021
|
|
|
725
1022
|
setEmailService(emailService);
|
|
726
1023
|
|
|
1024
|
+
// --- SMS channel (parallel to the email pipeline above) -------------------
|
|
1025
|
+
// Resolve the active SMS provider: `defaultProvider ?? SMS_PROVIDER ?? "twilio"`.
|
|
1026
|
+
// An EXPLICITLY-requested id that isn't registered throws (mirrors email's
|
|
1027
|
+
// "never silently fall back"). When nothing is configured the registry is
|
|
1028
|
+
// empty and `smsProvider` stays undefined — the tracked sender below becomes
|
|
1029
|
+
// an inert stub so an existing deploy without Twilio creds boots unchanged.
|
|
1030
|
+
const smsTemplates = opts.sms?.templates ?? ({} as SmsTemplateRegistry);
|
|
1031
|
+
const smsActiveId = opts.sms?.defaultProvider ?? env.SMS_PROVIDER ?? "twilio";
|
|
1032
|
+
const smsExplicit = Boolean(opts.sms?.defaultProvider ?? env.SMS_PROVIDER);
|
|
1033
|
+
let smsProvider = smsProviders.get(smsActiveId);
|
|
1034
|
+
// DX: when the active id wasn't explicitly requested and the default "twilio"
|
|
1035
|
+
// isn't registered but EXACTLY ONE provider is, use that one — so a consumer
|
|
1036
|
+
// passing a single `sms.provider` (any id) never has to also set
|
|
1037
|
+
// `defaultProvider`. An explicit id that misses still throws below.
|
|
1038
|
+
if (!smsProvider && !smsExplicit && smsProviders.count() === 1) {
|
|
1039
|
+
smsProvider = smsProviders.getAll()[0];
|
|
1040
|
+
}
|
|
1041
|
+
if (smsExplicit && !smsProvider) {
|
|
1042
|
+
throw new Error(
|
|
1043
|
+
`SMS provider "${smsActiveId}" is not registered (registered: ${
|
|
1044
|
+
smsProviders
|
|
1045
|
+
.getAll()
|
|
1046
|
+
.map((p) => p.meta.id)
|
|
1047
|
+
.join(", ") || "none"
|
|
1048
|
+
}). Set TWILIO_ACCOUNT_SID/TWILIO_AUTH_TOKEN and SMS_FROM, or pass sms.provider.`,
|
|
1049
|
+
);
|
|
1050
|
+
}
|
|
1051
|
+
|
|
1052
|
+
// Boot-validate SMS template categories through the SAME fail-closed helper as
|
|
1053
|
+
// email templates (a channel/typo/consent-flip category is as dangerous here).
|
|
1054
|
+
for (const [templateKey, def] of Object.entries(smsTemplates)) {
|
|
1055
|
+
const category = (def as SmsTemplateDefinition | undefined)?.category;
|
|
1056
|
+
if (!category) continue;
|
|
1057
|
+
validateListCategory({
|
|
1058
|
+
owner: `SMS template "${templateKey}"`,
|
|
1059
|
+
category,
|
|
1060
|
+
listRegistry,
|
|
1061
|
+
definedLists,
|
|
1062
|
+
logger,
|
|
1063
|
+
});
|
|
1064
|
+
}
|
|
1065
|
+
|
|
1066
|
+
const smsService: SmsService = smsProvider
|
|
1067
|
+
? createTrackedSmsSender(
|
|
1068
|
+
{
|
|
1069
|
+
defaultFrom: opts.sms?.from ?? env.SMS_FROM,
|
|
1070
|
+
templates: smsTemplates,
|
|
1071
|
+
db,
|
|
1072
|
+
frequencyCap: defaults.frequencyCap,
|
|
1073
|
+
logger,
|
|
1074
|
+
stopFooter: opts.sms?.stopFooter,
|
|
1075
|
+
optOutReplies: opts.sms?.optOutReplies,
|
|
1076
|
+
// Deploy-wide test-mode coherence: HOGSEND_TEST_MODE is channel-
|
|
1077
|
+
// neutral. "true" forces SMS test mode directly; "auto" arms it
|
|
1078
|
+
// whenever the EMAIL side's test mode is armed (unverified domain),
|
|
1079
|
+
// so a staging deploy that redirects email never live-texts real
|
|
1080
|
+
// numbers. SMS has no domain-verification analog of its own, so
|
|
1081
|
+
// "auto" with email test mode off keeps live sends (PR behavior).
|
|
1082
|
+
testMode: () =>
|
|
1083
|
+
env.HOGSEND_TEST_MODE === "true" ||
|
|
1084
|
+
(env.HOGSEND_TEST_MODE === "auto" &&
|
|
1085
|
+
domainStatus.testModeCached().active),
|
|
1086
|
+
testPhone: env.HOGSEND_TEST_PHONE,
|
|
1087
|
+
// First-party short-link rewriting (ON by default, mirrors email's
|
|
1088
|
+
// always-on tracking). SMS_LINK_HOST swaps in a branded short
|
|
1089
|
+
// domain; API_PUBLIC_URL serves out of the box.
|
|
1090
|
+
linkTracking:
|
|
1091
|
+
opts.sms?.linkTracking ?? env.SMS_LINK_TRACKING !== "false",
|
|
1092
|
+
linkHost: (
|
|
1093
|
+
opts.sms?.linkHost ??
|
|
1094
|
+
env.SMS_LINK_HOST ??
|
|
1095
|
+
env.API_PUBLIC_URL
|
|
1096
|
+
).replace(/\/+$/, ""),
|
|
1097
|
+
},
|
|
1098
|
+
{ provider: smsProvider },
|
|
1099
|
+
)
|
|
1100
|
+
: createStubSmsService();
|
|
1101
|
+
|
|
1102
|
+
setSmsService(smsService);
|
|
1103
|
+
|
|
727
1104
|
// Wire better-auth's secondary storage to the SHARED engine Redis (the same
|
|
728
1105
|
// singleton backing the PostHog cache + worker heartbeat — never a second
|
|
729
1106
|
// pool). Passing `secondaryStorage` flips better-auth's rate-limit store from
|
|
@@ -924,16 +1301,24 @@ export function createHogsendClient(
|
|
|
924
1301
|
const connectorList = [
|
|
925
1302
|
...(enablePresets ? connectorsFromEnv(env) : []),
|
|
926
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),
|
|
927
1309
|
...(opts.connectors ?? []),
|
|
928
1310
|
];
|
|
929
1311
|
for (const connector of connectorList) {
|
|
930
1312
|
if (
|
|
931
1313
|
(connector.meta.transport ?? "webhook") === "webhook" &&
|
|
932
|
-
connector.meta.id === "email"
|
|
1314
|
+
(connector.meta.id === "email" ||
|
|
1315
|
+
connector.meta.id === "sms" ||
|
|
1316
|
+
connector.meta.id === "crm")
|
|
933
1317
|
) {
|
|
934
1318
|
throw new Error(
|
|
935
|
-
|
|
936
|
-
"(POST /v1/webhooks/email/:providerId).
|
|
1319
|
+
`Connector id "${connector.meta.id}" is reserved for the ` +
|
|
1320
|
+
"email/SMS/CRM-provider routes (POST /v1/webhooks/{email,sms,crm}/:providerId). " +
|
|
1321
|
+
"Rename the connector.",
|
|
937
1322
|
);
|
|
938
1323
|
}
|
|
939
1324
|
}
|
|
@@ -943,6 +1328,30 @@ export function createHogsendClient(
|
|
|
943
1328
|
`Connector registry loaded: ${connectorRegistry.count()} connectors`,
|
|
944
1329
|
);
|
|
945
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
|
+
|
|
946
1355
|
// Build + install the connector ACTION registry (outbound imperative actions),
|
|
947
1356
|
// the action sibling of the connector registry above. Runs in BOTH the API and
|
|
948
1357
|
// worker (both call createHogsendClient), so `sendConnectorAction()` resolves
|
|
@@ -991,6 +1400,11 @@ export function createHogsendClient(
|
|
|
991
1400
|
emailProvider: provider,
|
|
992
1401
|
domainStatus,
|
|
993
1402
|
templates,
|
|
1403
|
+
smsService,
|
|
1404
|
+
smsProviders,
|
|
1405
|
+
smsProvider,
|
|
1406
|
+
crmProviders,
|
|
1407
|
+
funnels,
|
|
994
1408
|
analyticsProviders,
|
|
995
1409
|
analytics,
|
|
996
1410
|
identity,
|
|
@@ -1001,6 +1415,7 @@ export function createHogsendClient(
|
|
|
1001
1415
|
listRegistry,
|
|
1002
1416
|
campaigns: opts.campaigns ?? [],
|
|
1003
1417
|
connectorRegistry,
|
|
1418
|
+
contactSourceRegistry,
|
|
1004
1419
|
connectorActionRegistry,
|
|
1005
1420
|
hatchet: opts.overrides?.hatchet ?? hatchet,
|
|
1006
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/env.ts
CHANGED
|
@@ -121,6 +121,34 @@ export const env = createEnv({
|
|
|
121
121
|
POSTMARK_MESSAGE_STREAM: z.string().min(1).optional(),
|
|
122
122
|
POSTMARK_WEBHOOK_USER: z.string().min(1).optional(),
|
|
123
123
|
POSTMARK_WEBHOOK_PASS: z.string().min(1).optional(),
|
|
124
|
+
// --- SMS channel (provider-neutral, BYO SMS provider) ---
|
|
125
|
+
// The active SMS provider id the container resolves from the
|
|
126
|
+
// SmsProviderRegistry. Absent → "twilio" when a provider is registered;
|
|
127
|
+
// with no provider configured the SMS service is an inert throwing stub.
|
|
128
|
+
SMS_PROVIDER: z.string().optional(),
|
|
129
|
+
// Neutral E.164 default-from number the tracked SMS sender uses when a send
|
|
130
|
+
// omits `from` and no messaging-service is pinned.
|
|
131
|
+
SMS_FROM: z.string().optional(),
|
|
132
|
+
// The safe phone every redirected SMS is delivered to under
|
|
133
|
+
// HOGSEND_TEST_MODE=true. When unset while test mode is active, the send is
|
|
134
|
+
// BLOCKED (recorded, never delivered to the real recipient).
|
|
135
|
+
HOGSEND_TEST_PHONE: z.string().optional(),
|
|
136
|
+
// SMS link shortening/tracking is ON by default when SMS is configured.
|
|
137
|
+
// An enum, NOT z.coerce.boolean — an explicit "false" must actually
|
|
138
|
+
// disable (coerce treats the string "false" as true; HOGSEND_TEST_MODE
|
|
139
|
+
// precedent).
|
|
140
|
+
SMS_LINK_TRACKING: z.enum(["true", "false"]).default("true"),
|
|
141
|
+
// Full origin short links are minted under (e.g. https://hs.example.com —
|
|
142
|
+
// a branded short domain routed to this app). Falls back to
|
|
143
|
+
// API_PUBLIC_URL; the /s/:code route serves either way.
|
|
144
|
+
SMS_LINK_HOST: z.string().url().optional(),
|
|
145
|
+
// --- Twilio (default SMS provider, opt-in) ---
|
|
146
|
+
// A preset provider is built only when BOTH SID + token are present (the
|
|
147
|
+
// guarded dynamic import in sms-providers-from-env.ts). One of SMS_FROM /
|
|
148
|
+
// TWILIO_MESSAGING_SERVICE_SID must also be set for sends to succeed.
|
|
149
|
+
TWILIO_ACCOUNT_SID: z.string().min(1).optional(),
|
|
150
|
+
TWILIO_AUTH_TOKEN: z.string().min(1).optional(),
|
|
151
|
+
TWILIO_MESSAGING_SERVICE_SID: z.string().min(1).optional(),
|
|
124
152
|
// Hatchet connection contract. The @hatchet-dev SDK also reads these straight
|
|
125
153
|
// from process.env via its own config-loader, so this schema is a presence /
|
|
126
154
|
// shape check that keeps the contract in one place — the values still flow to
|