@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.
Files changed (75) hide show
  1. package/package.json +10 -7
  2. package/src/container.ts +419 -4
  3. package/src/destinations/define-destination.ts +7 -3
  4. package/src/destinations/presets/posthog.ts +31 -0
  5. package/src/env.ts +28 -0
  6. package/src/index.ts +138 -0
  7. package/src/journeys/execute-journey-run.ts +93 -0
  8. package/src/journeys/journey-boundary.ts +5 -1
  9. package/src/journeys/journey-context.ts +30 -0
  10. package/src/lib/attribution-backfill.ts +285 -0
  11. package/src/lib/attribution.ts +239 -0
  12. package/src/lib/contacts.ts +71 -0
  13. package/src/lib/conversion-dispatch.ts +326 -0
  14. package/src/lib/conversions.ts +197 -0
  15. package/src/lib/crm-deals.ts +320 -0
  16. package/src/lib/crm-ingest.ts +341 -0
  17. package/src/lib/crm-provider-registry.ts +41 -0
  18. package/src/lib/crm-registry-singleton.ts +22 -0
  19. package/src/lib/deal-money-events.ts +85 -0
  20. package/src/lib/email-service-types.ts +16 -1
  21. package/src/lib/event-names.ts +1 -1
  22. package/src/lib/funnel-progress.ts +76 -0
  23. package/src/lib/funnel-registry.ts +108 -0
  24. package/src/lib/funnel-transitions.ts +280 -0
  25. package/src/lib/holdout.ts +62 -0
  26. package/src/lib/ingestion.ts +218 -9
  27. package/src/lib/journey-suppress.ts +33 -2
  28. package/src/lib/lift-stats.ts +125 -0
  29. package/src/lib/mailer.ts +1 -0
  30. package/src/lib/operator.ts +31 -0
  31. package/src/lib/outbound.ts +109 -0
  32. package/src/lib/phone.ts +19 -0
  33. package/src/lib/preferences.ts +32 -0
  34. package/src/lib/revenue.ts +116 -0
  35. package/src/lib/sms-frequency-cap.ts +47 -0
  36. package/src/lib/sms-inbound.ts +200 -0
  37. package/src/lib/sms-link-tracking.ts +160 -0
  38. package/src/lib/sms-mailer.ts +338 -0
  39. package/src/lib/sms-provider-registry.ts +35 -0
  40. package/src/lib/sms-providers-from-env.ts +100 -0
  41. package/src/lib/sms-service-types.ts +175 -0
  42. package/src/lib/sms-tracked.ts +625 -0
  43. package/src/lib/sms.ts +117 -0
  44. package/src/lib/tracked.ts +40 -0
  45. package/src/lib/tracking-event-names.ts +6 -0
  46. package/src/lib/tracking-events.ts +133 -1
  47. package/src/lib/tracking.ts +2 -1
  48. package/src/lib/webhook-signing.ts +24 -1
  49. package/src/lists/channels.ts +21 -0
  50. package/src/routes/admin/attribution.ts +414 -0
  51. package/src/routes/admin/contacts.ts +71 -11
  52. package/src/routes/admin/conversions.ts +247 -0
  53. package/src/routes/admin/deals.ts +472 -0
  54. package/src/routes/admin/funnels.ts +228 -0
  55. package/src/routes/admin/index.ts +8 -0
  56. package/src/routes/admin/journeys.ts +158 -1
  57. package/src/routes/admin/readiness.ts +97 -2
  58. package/src/routes/admin/templates.ts +28 -1
  59. package/src/routes/email/unsubscribe.ts +1 -0
  60. package/src/routes/events/index.ts +12 -0
  61. package/src/routes/index.ts +6 -0
  62. package/src/routes/lists/index.ts +54 -7
  63. package/src/routes/tracking/click-pipeline.ts +105 -16
  64. package/src/routes/tracking/short.ts +61 -0
  65. package/src/routes/webhooks/crm-provider.ts +117 -0
  66. package/src/routes/webhooks/index.ts +9 -1
  67. package/src/routes/webhooks/sms-provider.ts +110 -0
  68. package/src/sources/define-contact-source.ts +159 -0
  69. package/src/sources/registry.ts +71 -0
  70. package/src/sources/webhook-source.ts +109 -0
  71. package/src/worker.ts +4 -0
  72. package/src/workflows/crm-reconcile.ts +129 -0
  73. package/src/workflows/dispatch-conversion.ts +31 -0
  74. package/src/workflows/import-contacts.ts +61 -4
  75. 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.42.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/core": "^0.42.0",
53
- "@hogsend/db": "^0.42.0",
54
- "@hogsend/email": "^0.42.0",
55
- "@hogsend/plugin-posthog": "^0.42.0",
56
- "@hogsend/plugin-resend": "^0.42.0"
52
+ "@hogsend/attribution": "^0.44.0",
53
+ "@hogsend/core": "^0.44.0",
54
+ "@hogsend/db": "^0.44.0",
55
+ "@hogsend/email": "^0.44.0",
56
+ "@hogsend/plugin-posthog": "^0.44.0",
57
+ "@hogsend/plugin-resend": "^0.44.0",
58
+ "@hogsend/sms": "^0.44.0"
57
59
  },
58
60
  "optionalDependencies": {
59
- "@hogsend/plugin-postmark": "^0.42.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
- const channelLists = synthesizeChannelLists(opts.connectorActions ?? []);
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
- 'Connector id "email" is reserved for the email-provider route ' +
936
- "(POST /v1/webhooks/email/:providerId). Rename the connector.",
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). It is NOT the home for
25
- * ad-platform conversion forwarding (CAPI) — that stays deferred to PostHog CDP;
26
- * Hogsend just fires the events.
24
+ * (PostHog, Segment, Slack, a CRM, a warehouse). Ad-platform conversion
25
+ * forwarding (Meta CAPI, Google Enhanced Conversions) is Hogsend-native but
26
+ * lives in its own sibling layer (`defineConversionDestination`, per
27
+ * docs/revenue-attribution-plan.md) — it needs identifier hashing, click-id
28
+ * joins, and deterministic event_id idempotency this generic pipe deliberately
29
+ * does not have. It is NOT deferred to any third-party CDP: the money path has
30
+ * no external dependency.
27
31
  */
28
32
 
29
33
  /** A live `webhook_endpoints` row, as read by the delivery task. */
@@ -153,11 +153,42 @@ export const posthogDestination = defineDestination({
153
153
  return setCapture(data.externalId, { [flag]: true });
154
154
  }
155
155
 
156
+ if (envelope.type === "contact.control_group") {
157
+ // Global control group membership (impact plan §4.4): a person flag
158
+ // so PostHog insights/experiments can slice program-level lift. The
159
+ // engine owns assignment (deterministic, durable-path); PostHog gets
160
+ // the raw material. Identity-less sends carry no addressable key.
161
+ const data =
162
+ envelope.data as unknown as OutboundPayloads["contact.control_group"];
163
+ if (!data.userId) return null;
164
+ return setCapture(data.userId, { hogsend_control_group: true });
165
+ }
166
+
156
167
  // contact.deleted: PostHog person deletion is a private-API operation,
157
168
  // not a capture — out of scope for this rail.
158
169
  return null;
159
170
  }
160
171
 
172
+ // Holdout membership as a person property (impact plan §4.4): when
173
+ // person sync is on, journey.heldout becomes a per-journey $set flag
174
+ // (`hogsend_holdout_<journeyId>: true`) so PostHog can slice any insight
175
+ // by holdout membership. With sync off it falls through to the generic
176
+ // event capture below — the event stream alone still records diversion.
177
+ if (envelope.type === "journey.heldout" && config.syncPersons === true) {
178
+ const heldout =
179
+ envelope.data as unknown as OutboundPayloads["journey.heldout"];
180
+ return captureRequest({
181
+ host,
182
+ apiKey: config.apiKey,
183
+ event: "$set",
184
+ distinctId: heldout.userId,
185
+ timestamp: envelope.timestamp,
186
+ properties: {
187
+ $set: { [`hogsend_holdout_${heldout.journeyId}`]: true },
188
+ },
189
+ });
190
+ }
191
+
161
192
  const data = envelope.data as {
162
193
  userId?: string | null;
163
194
  to?: string | null;
package/src/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