@hogsend/engine 0.46.1 → 0.51.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/README.md +6 -0
- package/package.json +13 -10
- package/src/campaigns/cohort-sql.ts +8 -9
- package/src/connectors/presets/index.ts +8 -2
- package/src/container.ts +150 -8
- package/src/destinations/define-destination.ts +2 -2
- package/src/destinations/presets/posthog.ts +7 -0
- package/src/destinations/presets/segment.ts +5 -0
- package/src/env.ts +38 -0
- package/src/flags/reconcile.ts +200 -0
- package/src/index.ts +79 -0
- package/src/journeys/authoring.ts +32 -0
- package/src/journeys/define-journey.ts +45 -40
- package/src/journeys/execute-journey-run.ts +73 -32
- package/src/journeys/journey-boundary.ts +76 -0
- package/src/journeys/journey-context.ts +128 -70
- package/src/journeys/journey-task-factory.ts +31 -0
- package/src/journeys/journey-task-runtime.ts +31 -0
- package/src/journeys/journey-version.test.ts +236 -0
- package/src/journeys/journey-version.ts +158 -0
- package/src/journeys/record-once.ts +28 -2
- package/src/lib/campaign-send-key.ts +9 -18
- package/src/lib/connector-actions.test.ts +36 -0
- package/src/lib/connector-actions.ts +42 -4
- package/src/lib/contacts.ts +49 -0
- package/src/lib/conversions.test.ts +33 -0
- package/src/lib/conversions.ts +9 -1
- package/src/lib/crm-deals.ts +1 -1
- package/src/lib/crm-ingest.ts +1 -1
- package/src/lib/email.ts +23 -2
- package/src/lib/enrollment-policy.ts +51 -0
- package/src/lib/event-names.ts +7 -1
- package/src/lib/feed.ts +55 -3
- package/src/lib/flags-registry.ts +48 -0
- package/src/lib/flags.ts +498 -0
- package/src/lib/frequency-cap.ts +4 -2
- package/src/lib/funnel-progress.ts +1 -1
- package/src/lib/fx.ts +374 -0
- package/src/lib/global-control-readout.ts +166 -0
- package/src/lib/groups.ts +362 -0
- package/src/lib/holdout.ts +1 -1
- package/src/lib/ingestion.ts +38 -0
- package/src/lib/journey-lift.ts +142 -0
- package/src/lib/journey-suppress.ts +4 -2
- package/src/lib/lift-stats.ts +2 -2
- package/src/lib/operator-settings.ts +71 -0
- package/src/lib/outbound.ts +147 -0
- package/src/lib/preferences.ts +6 -80
- package/src/lib/recipient-preferences.ts +53 -0
- package/src/lib/sms.ts +21 -2
- package/src/lib/stable-stringify.test.ts +42 -0
- package/src/lib/stable-stringify.ts +23 -0
- package/src/lib/tracked.ts +9 -2
- package/src/lib/variant.ts +99 -0
- package/src/lib/webhook-signing.ts +16 -1
- package/src/lists/registry.ts +6 -2
- package/src/lists/subscription.ts +13 -0
- package/src/routes/admin/attribution.ts +1 -2
- package/src/routes/admin/campaigns.ts +84 -45
- package/src/routes/admin/contacts.ts +53 -4
- package/src/routes/admin/conversions.ts +138 -1
- package/src/routes/admin/deals.ts +43 -34
- package/src/routes/admin/emails.ts +4 -6
- package/src/routes/admin/events.ts +128 -1
- package/src/routes/admin/flags.ts +369 -0
- package/src/routes/admin/groups.ts +900 -0
- package/src/routes/admin/impact-schemas.ts +44 -0
- package/src/routes/admin/impact-wire.test.ts +181 -0
- package/src/routes/admin/impact.ts +486 -0
- package/src/routes/admin/index.ts +12 -0
- package/src/routes/admin/journey-impact.ts +446 -0
- package/src/routes/admin/journeys.ts +70 -100
- package/src/routes/admin/settings.ts +145 -0
- package/src/routes/admin/targeting.ts +259 -0
- package/src/routes/events/index.ts +11 -0
- package/src/routes/flags/index.ts +120 -0
- package/src/routes/groups/index.ts +417 -0
- package/src/routes/index.ts +23 -1
- package/src/testing.ts +25 -0
- package/src/webhook-sources/presets/index.ts +5 -1
- package/src/webhook-sources/presets/intercom.ts +230 -0
- package/src/webhook-sources/presets/segment.ts +56 -4
- package/src/worker.ts +3 -0
- package/src/workflows/bucket-backfill.ts +1 -14
- package/src/workflows/crm-reconcile.ts +1 -1
- package/src/workflows/impact-digest.ts +761 -0
- package/src/workflows/journey-blueprint-interpreter.ts +18 -1
- package/src/middleware/auth.ts +0 -24
package/README.md
CHANGED
|
@@ -5,6 +5,12 @@ The Hogsend framework: `createApp`, `createHogsendClient`, `createWorker`,
|
|
|
5
5
|
built-in routes, and the registries. This is the public API surface consumers
|
|
6
6
|
build their lifecycle apps on top of.
|
|
7
7
|
|
|
8
|
+
Journey definition modules should import `defineJourney`, duration helpers, and
|
|
9
|
+
outbound journey effects from `@hogsend/engine/journeys`. That authoring subpath
|
|
10
|
+
does not validate production environment variables, so the original module can
|
|
11
|
+
be loaded by `@hogsend/testing`; importing the main `@hogsend/engine` runtime in
|
|
12
|
+
the API or worker still attaches the real Hatchet task.
|
|
13
|
+
|
|
8
14
|
The engine also re-exports the capability-provider contracts owned by
|
|
9
15
|
`@hogsend/core` — `EmailProvider` and `PostHogService` (plus their supporting
|
|
10
16
|
types) — so `@hogsend/engine` is the **canonical author import** for them when
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hogsend/engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.51.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -17,6 +17,8 @@
|
|
|
17
17
|
"./create-admin": "./src/lib/create-admin.ts",
|
|
18
18
|
"./api-key-hash": "./src/lib/api-key-hash.ts",
|
|
19
19
|
"./posthog-scopes": "./src/lib/posthog-scopes.ts",
|
|
20
|
+
"./journeys": "./src/journeys/authoring.ts",
|
|
21
|
+
"./testing": "./src/testing.ts",
|
|
20
22
|
"./mcp/authoring-guide": "./src/mcp/authoring-guide.ts",
|
|
21
23
|
"./package.json": "./package.json"
|
|
22
24
|
},
|
|
@@ -51,17 +53,17 @@
|
|
|
51
53
|
"svix": "^1.95.1",
|
|
52
54
|
"winston": "^3.19.0",
|
|
53
55
|
"zod": "^4.4.3",
|
|
54
|
-
"@hogsend/attribution": "^0.
|
|
55
|
-
"@hogsend/core": "^0.
|
|
56
|
-
"@hogsend/db": "^0.
|
|
57
|
-
"@hogsend/email": "^0.
|
|
58
|
-
"@hogsend/plugin-posthog": "^0.
|
|
59
|
-
"@hogsend/plugin-resend": "^0.
|
|
60
|
-
"@hogsend/sms": "^0.
|
|
56
|
+
"@hogsend/attribution": "^0.51.0",
|
|
57
|
+
"@hogsend/core": "^0.51.0",
|
|
58
|
+
"@hogsend/db": "^0.51.0",
|
|
59
|
+
"@hogsend/email": "^0.51.0",
|
|
60
|
+
"@hogsend/plugin-posthog": "^0.51.0",
|
|
61
|
+
"@hogsend/plugin-resend": "^0.51.0",
|
|
62
|
+
"@hogsend/sms": "^0.51.0"
|
|
61
63
|
},
|
|
62
64
|
"optionalDependencies": {
|
|
63
|
-
"@hogsend/plugin-postmark": "^0.
|
|
64
|
-
"@hogsend/plugin-twilio": "^0.
|
|
65
|
+
"@hogsend/plugin-postmark": "^0.51.0",
|
|
66
|
+
"@hogsend/plugin-twilio": "^0.51.0"
|
|
65
67
|
},
|
|
66
68
|
"devDependencies": {
|
|
67
69
|
"@types/node": "^22.15.3",
|
|
@@ -73,6 +75,7 @@
|
|
|
73
75
|
},
|
|
74
76
|
"scripts": {
|
|
75
77
|
"check-types": "tsc --noEmit",
|
|
78
|
+
"test": "tsx --test src/**/*.test.ts",
|
|
76
79
|
"lint": "biome check .",
|
|
77
80
|
"clean": "rm -rf node_modules .turbo"
|
|
78
81
|
}
|
|
@@ -29,7 +29,6 @@ import {
|
|
|
29
29
|
} from "@hogsend/db";
|
|
30
30
|
import { type SQL, sql } from "drizzle-orm";
|
|
31
31
|
import type { PgColumn } from "drizzle-orm/pg-core";
|
|
32
|
-
import { campaignSendKeyPattern } from "../lib/campaign-send-key.js";
|
|
33
32
|
|
|
34
33
|
/**
|
|
35
34
|
* The v1 linked-identity map: connector id → the `contacts` column that holds
|
|
@@ -107,13 +106,13 @@ export function waveConditionSql(opts: {
|
|
|
107
106
|
}
|
|
108
107
|
|
|
109
108
|
/**
|
|
110
|
-
* Engagement over THIS campaign's prior deliveries
|
|
111
|
-
*
|
|
112
|
-
*
|
|
113
|
-
*
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
*
|
|
109
|
+
* Engagement over THIS campaign's prior deliveries, anchored on the indexed
|
|
110
|
+
* `campaign_id` column (stamped on every campaign-dispatched row regardless
|
|
111
|
+
* of key format; suppressed rows carry it too but have no engagement
|
|
112
|
+
* timestamps, so they can never match positively). Negative checks are NOT
|
|
113
|
+
* EXISTS of the same positive-engagement subquery, so `notOpened()` reads
|
|
114
|
+
* "no opened send of this campaign", including members who received nothing
|
|
115
|
+
* (e.g. suppressed on the prior wave).
|
|
117
116
|
*/
|
|
118
117
|
function engagementSql(
|
|
119
118
|
condition: EmailEngagementCondition,
|
|
@@ -129,7 +128,7 @@ function engagementSql(
|
|
|
129
128
|
: sql.empty();
|
|
130
129
|
const positive = sql`exists (
|
|
131
130
|
select 1 from ${emailSends}
|
|
132
|
-
where ${emailSends.
|
|
131
|
+
where ${emailSends.campaignId} = ${campaignId}
|
|
133
132
|
and ${emailSends.toEmail} = ${campaignRecipients.email}
|
|
134
133
|
and ${engagedAt} is not null${templateFilter}
|
|
135
134
|
)`;
|
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
import type { env as engineEnv } from "../../env.js";
|
|
2
|
-
import {
|
|
2
|
+
import {
|
|
3
|
+
type DefinedWebhookSource,
|
|
4
|
+
webhookSourceToConnector,
|
|
5
|
+
} from "../../webhook-sources/define-webhook-source.js";
|
|
3
6
|
import {
|
|
4
7
|
PRESET_SOURCES,
|
|
5
8
|
presetsFromEnv,
|
|
@@ -14,7 +17,10 @@ import type { DefinedConnector } from "../define-connector.js";
|
|
|
14
17
|
*/
|
|
15
18
|
export const PRESET_CONNECTORS: Record<string, DefinedConnector> =
|
|
16
19
|
Object.fromEntries(
|
|
17
|
-
|
|
20
|
+
// The registry is heterogeneous (`satisfies Record<string,
|
|
21
|
+
// DefinedWebhookSource>`); consume it at that declared type so a new preset
|
|
22
|
+
// whose payload shape diverges can't break union-inference on the lift.
|
|
23
|
+
(Object.values(PRESET_SOURCES) as DefinedWebhookSource[]).map((s) => [
|
|
18
24
|
s.meta.id,
|
|
19
25
|
webhookSourceToConnector(s),
|
|
20
26
|
]),
|
package/src/container.ts
CHANGED
|
@@ -6,9 +6,11 @@ import type {
|
|
|
6
6
|
CrmProvider,
|
|
7
7
|
CrmStageMap,
|
|
8
8
|
DefinedConversion,
|
|
9
|
+
DefinedFlag,
|
|
9
10
|
DefinedFunnel,
|
|
10
11
|
EmailProvider,
|
|
11
12
|
FunnelStageEntry,
|
|
13
|
+
FxRateProvider,
|
|
12
14
|
JourneySourceLocation,
|
|
13
15
|
PostHogService,
|
|
14
16
|
SmsProvider,
|
|
@@ -55,6 +57,7 @@ import {
|
|
|
55
57
|
setDestinationRegistry,
|
|
56
58
|
} from "./destinations/registry-singleton.js";
|
|
57
59
|
import { env } from "./env.js";
|
|
60
|
+
import { reconcileDefinedFlags } from "./flags/reconcile.js";
|
|
58
61
|
import { setClientScheduleDefaults } from "./journeys/client-defaults-singleton.js";
|
|
59
62
|
import type { DefinedJourney } from "./journeys/define-journey.js";
|
|
60
63
|
import { getJourneySourceLocations } from "./journeys/journey-source-locations-singleton.js";
|
|
@@ -97,7 +100,9 @@ import type {
|
|
|
97
100
|
EmailService,
|
|
98
101
|
FrequencyCapConfig,
|
|
99
102
|
} from "./lib/email-service-types.js";
|
|
103
|
+
import { FlagRegistry, setFlagRegistry } from "./lib/flags-registry.js";
|
|
100
104
|
import { FunnelRegistry } from "./lib/funnel-registry.js";
|
|
105
|
+
import { createFxLens, type FxLens, fxProviderFromEnv } from "./lib/fx.js";
|
|
101
106
|
import { hatchet } from "./lib/hatchet.js";
|
|
102
107
|
import {
|
|
103
108
|
createIdentityService,
|
|
@@ -105,6 +110,11 @@ import {
|
|
|
105
110
|
} from "./lib/identity-service.js";
|
|
106
111
|
import { createLogger, type Logger } from "./lib/logger.js";
|
|
107
112
|
import { createTrackedMailer } from "./lib/mailer.js";
|
|
113
|
+
import {
|
|
114
|
+
FX_SETTINGS_KEY,
|
|
115
|
+
type FxSetting,
|
|
116
|
+
getOperatorSetting,
|
|
117
|
+
} from "./lib/operator-settings.js";
|
|
108
118
|
import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
|
|
109
119
|
import { sendResetPasswordEmail } from "./lib/reset-email.js";
|
|
110
120
|
import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
|
|
@@ -210,6 +220,12 @@ export interface HogsendClient {
|
|
|
210
220
|
* (provider, pipeline) claim; admin stats/Studio render per funnel.
|
|
211
221
|
*/
|
|
212
222
|
funnels: FunnelRegistry;
|
|
223
|
+
/**
|
|
224
|
+
* The registry of code-defined feature flags (`defineFlag`), keyed by
|
|
225
|
+
* `meta.key`. Built from `opts.flags`; the boot reconciler + Studio read it.
|
|
226
|
+
* Empty when no flags are defined in code (DB/Studio flags still evaluate).
|
|
227
|
+
*/
|
|
228
|
+
flagRegistry: FlagRegistry;
|
|
213
229
|
/**
|
|
214
230
|
* The container-held registry of analytics providers, keyed by `meta.id` —
|
|
215
231
|
* the analytics sibling of {@link emailProviders}. Built from env presets
|
|
@@ -231,6 +247,15 @@ export interface HogsendClient {
|
|
|
231
247
|
* engine emission ingest uses — never bespoke per-consumer plumbing.
|
|
232
248
|
*/
|
|
233
249
|
identity: IdentityService;
|
|
250
|
+
/**
|
|
251
|
+
* The OPTIONAL base-currency FX lens (docs/groups.md §Base-currency lens):
|
|
252
|
+
* `getBaseCurrency()` resolves the effective reporting currency PER CALL
|
|
253
|
+
* (code pin → Studio operator setting → env `BASE_CURRENCY`; null = lens
|
|
254
|
+
* off) and `getRatesToBase()` is the fail-soft quote→base sheet the admin
|
|
255
|
+
* group revenue views convert through. The per-currency revenue LAW is
|
|
256
|
+
* untouched; this only serves an opt-in converted view on top of it.
|
|
257
|
+
*/
|
|
258
|
+
fx: FxLens;
|
|
234
259
|
registry: JourneyRegistry;
|
|
235
260
|
/**
|
|
236
261
|
* Map of enabled journey id → its captured `run` source string. Populated by
|
|
@@ -419,12 +444,45 @@ export interface HogsendClientOptions {
|
|
|
419
444
|
linkTracking?: boolean;
|
|
420
445
|
linkHost?: string;
|
|
421
446
|
};
|
|
447
|
+
/**
|
|
448
|
+
* The OPTIONAL base-currency FX lens (docs/groups.md §Base-currency lens).
|
|
449
|
+
* OFF unless a base currency resolves — with no `fx.baseCurrency` pin, no
|
|
450
|
+
* Studio operator setting, and no env `BASE_CURRENCY`, nothing anywhere
|
|
451
|
+
* converts.
|
|
452
|
+
*
|
|
453
|
+
* - `provider` — a BYO {@link FxRateProvider} rate source. WINS over the env
|
|
454
|
+
* presets entirely (the same consumer-over-env spirit as `analytics`,
|
|
455
|
+
* minus the registry — exactly one FX source resolves at boot; multiple
|
|
456
|
+
* simultaneous rate sources have no use case). Without it, env resolves:
|
|
457
|
+
* `FX_PROVIDER=frankfurter` → the ECB preset, else a set `FX_RATES` → the
|
|
458
|
+
* sovereign static preset, else no source (lens stays off).
|
|
459
|
+
* - `baseCurrency` — the code-level PIN: wins over BOTH the Studio operator
|
|
460
|
+
* setting and env `BASE_CURRENCY` (the `defaults.timezone` pattern; also
|
|
461
|
+
* the test seam, since `env` is a process singleton). Without it the base
|
|
462
|
+
* resolves per call: Studio setting (explicit null there = lens OFF,
|
|
463
|
+
* beating env) → env `BASE_CURRENCY`.
|
|
464
|
+
*/
|
|
465
|
+
fx?: {
|
|
466
|
+
provider?: FxRateProvider;
|
|
467
|
+
baseCurrency?: string;
|
|
468
|
+
};
|
|
422
469
|
/**
|
|
423
470
|
* Code-first conversion-point definitions (plan §5.1) — `defineConversion`
|
|
424
471
|
* results. Evaluated inside `ingestEvent` after every fresh event insert;
|
|
425
|
-
* fired instances land in the `conversions` table.
|
|
472
|
+
* fired instances land in the `conversions` table. Every journey
|
|
473
|
+
* `meta.goal` is boot-validated against this set (plus the seeded
|
|
474
|
+
* "revenue" definition when active) — an unknown goal throws here.
|
|
426
475
|
*/
|
|
427
476
|
conversions?: DefinedConversion[];
|
|
477
|
+
/**
|
|
478
|
+
* Code-first feature-flag definitions (`defineFlag()` results). Reconciled
|
|
479
|
+
* into `flags` rows at boot (create-if-absent, disabled + rollout 0; contract
|
|
480
|
+
* drift synced on code-origin rows; operator state never clobbered — see
|
|
481
|
+
* `reconcileDefinedFlags`). Only the CONTRACT is expressed here; targeting /
|
|
482
|
+
* rollout / enabling are DB/operator-owned. Wire in BOTH `index.ts` and
|
|
483
|
+
* `worker.ts` so both processes reconcile. Defaults to none.
|
|
484
|
+
*/
|
|
485
|
+
flags?: DefinedFlag[];
|
|
428
486
|
/**
|
|
429
487
|
* Conversion DESTINATIONS (plan §5.2) — ad-platform feedback providers
|
|
430
488
|
* (`defineConversionDestination`; Meta CAPI is the reference). Referenced
|
|
@@ -432,7 +490,7 @@ export interface HogsendClientOptions {
|
|
|
432
490
|
*/
|
|
433
491
|
conversionDestinations?: ConversionDestination[];
|
|
434
492
|
/**
|
|
435
|
-
* CRM sync providers
|
|
493
|
+
* CRM sync providers — the pluggable
|
|
436
494
|
* layer that pushes leads INTO client CRMs and lands pipeline stage changes
|
|
437
495
|
* + deal values back on the event spine as `funnel.stage_changed`. Register
|
|
438
496
|
* one (`provider`) or many (`providers`); each is webhook-served at
|
|
@@ -867,16 +925,26 @@ export function createHogsendClient(
|
|
|
867
925
|
const seedDefaultRevenue =
|
|
868
926
|
process.env.HOGSEND_DEFAULT_REVENUE_CONVERSION !== "false" &&
|
|
869
927
|
!authoredConversions.some((def) => def.meta.id === "revenue");
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
928
|
+
// Hoisted local (impact experiments D3): the meta.goal boot validation
|
|
929
|
+
// below must check THIS registry — the construction is env-sensitive
|
|
930
|
+
// (HOGSEND_DEFAULT_REVENUE_CONVERSION=false or an authored id:"revenue"
|
|
931
|
+
// suppresses the seed), so goal:"revenue" is valid exactly when a
|
|
932
|
+
// "revenue" definition actually exists. That asymmetry is intended.
|
|
933
|
+
const conversionRegistry = new ConversionRegistry(
|
|
934
|
+
seedDefaultRevenue
|
|
935
|
+
? [...authoredConversions, defaultRevenueConversion]
|
|
936
|
+
: authoredConversions,
|
|
876
937
|
);
|
|
938
|
+
setConversionRegistry(conversionRegistry);
|
|
877
939
|
setConversionDestinations(
|
|
878
940
|
new ConversionDestinationRegistry(opts.conversionDestinations ?? []),
|
|
879
941
|
);
|
|
942
|
+
|
|
943
|
+
// Code-defined feature-flag registry (`defineFlag`) — installed on the
|
|
944
|
+
// process singleton for the boot reconciler + Studio. The reconcile itself
|
|
945
|
+
// fires below, near the other fire-and-forget boot effects.
|
|
946
|
+
const flagRegistry = new FlagRegistry(opts.flags ?? [], logger);
|
|
947
|
+
setFlagRegistry(flagRegistry);
|
|
880
948
|
// The durable dispatch task reference (composition root — the lib module
|
|
881
949
|
// cannot import the workflow without a cycle). Left UNSET under a hatchet
|
|
882
950
|
// override so tests never touch real gRPC; dispatch rows stay pending.
|
|
@@ -1036,6 +1104,35 @@ export function createHogsendClient(
|
|
|
1036
1104
|
});
|
|
1037
1105
|
}
|
|
1038
1106
|
|
|
1107
|
+
// Boot-validate every journey's meta.goal against the conversion
|
|
1108
|
+
// registry — fail CLOSED. A typo'd id matches zero conversion rows, so
|
|
1109
|
+
// every default readout would quietly report 0% for both cohorts — a
|
|
1110
|
+
// wrong-but-plausible number, worse than a crash. Validated over DEFINED
|
|
1111
|
+
// journeys (not just ENABLED — the ENABLED_JOURNEYS lesson) against the
|
|
1112
|
+
// ACTUAL registry (the seeded "revenue" conversion counts, and counts
|
|
1113
|
+
// ONLY when actually seeded). Runs identically in the API and worker
|
|
1114
|
+
// processes (both call createHogsendClient). Same posture as the
|
|
1115
|
+
// EMAIL_PROVIDER throw above and validateListCategory: the registry
|
|
1116
|
+
// universe is fully known at boot, so throw — a warn's failure mode is a
|
|
1117
|
+
// permanently-wrong default readout.
|
|
1118
|
+
for (const journey of opts.journeys ?? []) {
|
|
1119
|
+
const goal = journey.meta.goal;
|
|
1120
|
+
if (!goal) continue;
|
|
1121
|
+
if (!conversionRegistry.has(goal)) {
|
|
1122
|
+
const known = conversionRegistry
|
|
1123
|
+
.getAll()
|
|
1124
|
+
.map((def) => def.meta.id)
|
|
1125
|
+
.join(", ");
|
|
1126
|
+
throw new Error(
|
|
1127
|
+
`Journey "${journey.meta.id}" has goal "${goal}", which matches no registered conversion definition (known: ${known || "none"}). ` +
|
|
1128
|
+
`A goal must be a defineConversion id passed to createHogsendClient({ conversions }) — or the built-in "revenue" conversion when it is seeded.` +
|
|
1129
|
+
(goal === "revenue"
|
|
1130
|
+
? ` Remove HOGSEND_DEFAULT_REVENUE_CONVERSION=false or author an id: "revenue" definition if you meant the built-in.`
|
|
1131
|
+
: ""),
|
|
1132
|
+
);
|
|
1133
|
+
}
|
|
1134
|
+
}
|
|
1135
|
+
|
|
1039
1136
|
const emailService =
|
|
1040
1137
|
opts.overrides?.mailer ??
|
|
1041
1138
|
createTrackedMailer(
|
|
@@ -1315,6 +1412,33 @@ export function createHogsendClient(
|
|
|
1315
1412
|
// emission no-ops; the resolve still happens).
|
|
1316
1413
|
const identity = createIdentityService({ db, analytics, logger });
|
|
1317
1414
|
|
|
1415
|
+
// The OPTIONAL base-currency FX lens. A consumer provider wins over the env
|
|
1416
|
+
// presets wholesale; env otherwise resolves frankfurter (opt-in) or the
|
|
1417
|
+
// sovereign static sheet. `fxProviderFromEnv` throws at boot on a malformed
|
|
1418
|
+
// FX_RATES (fail-loud on config, the EMAIL_PROVIDER posture) — but the
|
|
1419
|
+
// LENS itself is fail-soft at request time: no base currency / no provider /
|
|
1420
|
+
// no rates all resolve to null and the per-currency truth serves unchanged.
|
|
1421
|
+
//
|
|
1422
|
+
// The effective BASE resolves PER CALL (a Studio change needs no reboot),
|
|
1423
|
+
// walking: (1) the code-level pin `opts.fx.baseCurrency` (also the test
|
|
1424
|
+
// seam) — wins over everything; (2) the Studio operator setting when its
|
|
1425
|
+
// row exists — an explicit `baseCurrency: null` there means "operator
|
|
1426
|
+
// turned the lens OFF", which BEATS env; (3) env `BASE_CURRENCY`, the
|
|
1427
|
+
// bootstrap default when NO row exists. No cache on the setting read
|
|
1428
|
+
// (lean-first): only low-QPS admin surfaces resolve rates, and a PK lookup
|
|
1429
|
+
// is nothing.
|
|
1430
|
+
const fxPin = opts.fx?.baseCurrency;
|
|
1431
|
+
const fx = createFxLens({
|
|
1432
|
+
resolveBaseCurrency: async () => {
|
|
1433
|
+
if (fxPin !== undefined) return fxPin;
|
|
1434
|
+
const setting = await getOperatorSetting<FxSetting>(db, FX_SETTINGS_KEY);
|
|
1435
|
+
if (setting) return setting.baseCurrency;
|
|
1436
|
+
return env.BASE_CURRENCY ?? null;
|
|
1437
|
+
},
|
|
1438
|
+
provider: opts.fx?.provider ?? fxProviderFromEnv(env, { db, logger }),
|
|
1439
|
+
logger,
|
|
1440
|
+
});
|
|
1441
|
+
|
|
1318
1442
|
// Build + install the outbound DESTINATION registry (Phase 3) the
|
|
1319
1443
|
// self-booting delivery task resolves by `webhook_endpoints.kind`. Order is
|
|
1320
1444
|
// load-bearing: the env-enabled presets come FIRST and the consumer's
|
|
@@ -1445,9 +1569,11 @@ export function createHogsendClient(
|
|
|
1445
1569
|
smsProvider,
|
|
1446
1570
|
crmProviders,
|
|
1447
1571
|
funnels,
|
|
1572
|
+
flagRegistry,
|
|
1448
1573
|
analyticsProviders,
|
|
1449
1574
|
analytics,
|
|
1450
1575
|
identity,
|
|
1576
|
+
fx,
|
|
1451
1577
|
registry,
|
|
1452
1578
|
journeySources: getJourneySources(),
|
|
1453
1579
|
journeyConstants: {
|
|
@@ -1495,5 +1621,21 @@ export function createHogsendClient(
|
|
|
1495
1621
|
.catch(() => {});
|
|
1496
1622
|
}
|
|
1497
1623
|
|
|
1624
|
+
// Reconcile code-defined feature flags into `flags` rows (create-if-absent,
|
|
1625
|
+
// sync contract drift on code-origin rows, never clobber operator state — see
|
|
1626
|
+
// `reconcileDefinedFlags`). Container-level so BOTH the API and worker
|
|
1627
|
+
// reconcile; the idempotent onConflict makes concurrent runs safe. Twin of
|
|
1628
|
+
// the buildStoredPosthogProvider block above: fire-and-forget, best-effort,
|
|
1629
|
+
// never blocks or fails boot. Skipped under NODE_ENV=test so suites stay
|
|
1630
|
+
// hermetic (tests drive the reconciler directly).
|
|
1631
|
+
const definedFlags = opts.flags ?? [];
|
|
1632
|
+
if (definedFlags.length > 0 && env.NODE_ENV !== "test") {
|
|
1633
|
+
void reconcileDefinedFlags({ client, flags: definedFlags }).catch((err) => {
|
|
1634
|
+
logger.warn("flags: reconcile (boot) failed", {
|
|
1635
|
+
error: err instanceof Error ? err.message : String(err),
|
|
1636
|
+
});
|
|
1637
|
+
});
|
|
1638
|
+
}
|
|
1639
|
+
|
|
1498
1640
|
return client;
|
|
1499
1641
|
}
|
|
@@ -23,8 +23,8 @@ import type { OutboundEventName } from "../lib/outbound.js";
|
|
|
23
23
|
* NOTE: `defineDestination` is for event FAN-OUT to product/data tools
|
|
24
24
|
* (PostHog, Segment, Slack, a CRM, a warehouse). Ad-platform conversion
|
|
25
25
|
* forwarding (Meta CAPI, Google Enhanced Conversions) is Hogsend-native but
|
|
26
|
-
* lives in its own sibling layer (`defineConversionDestination
|
|
27
|
-
*
|
|
26
|
+
* lives in its own sibling layer (`defineConversionDestination`) — it needs
|
|
27
|
+
* identifier hashing, click-id
|
|
28
28
|
* joins, and deterministic event_id idempotency this generic pipe deliberately
|
|
29
29
|
* does not have. It is NOT deferred to any third-party CDP: the money path has
|
|
30
30
|
* no external dependency.
|
|
@@ -103,6 +103,13 @@ export const posthogDestination = defineDestination({
|
|
|
103
103
|
}
|
|
104
104
|
const host = config.host ?? "https://us.i.posthog.com";
|
|
105
105
|
|
|
106
|
+
// impact.digest carries NO person identity (no userId/anonymousId/to/
|
|
107
|
+
// userEmail on the payload) — the generic capture below would ship no
|
|
108
|
+
// distinct_id, PostHog would 400, and the delivery would dead-letter
|
|
109
|
+
// as non-retryable every week. A program-level digest has no person to
|
|
110
|
+
// land on: skipping is a successful no-op, not a delivery failure.
|
|
111
|
+
if (envelope.type === "impact.digest") return null;
|
|
112
|
+
|
|
106
113
|
// Person-property propagation: `contact.*` events carry a contact payload
|
|
107
114
|
// (id/externalId/email/properties), NOT the userId/to identity chain the
|
|
108
115
|
// generic capture branch keys on — so they are handled here exclusively
|
|
@@ -47,6 +47,11 @@ export const segmentDestination = defineDestination({
|
|
|
47
47
|
);
|
|
48
48
|
}
|
|
49
49
|
const host = config.host ?? "https://api.segment.io";
|
|
50
|
+
|
|
51
|
+
// impact.digest has no subject identity; the fallback below would emit
|
|
52
|
+
// a junk track keyed on `anonymousId: envelope.id` — noise. Skipping
|
|
53
|
+
// is honest.
|
|
54
|
+
if (envelope.type === "impact.digest") return null;
|
|
50
55
|
const data = envelope.data as {
|
|
51
56
|
userId?: string | null;
|
|
52
57
|
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
|
+
// --- Base-currency FX lens (optional; docs/groups.md §Base-currency lens) ---
|
|
125
|
+
// The operator's reporting currency. UNSET = the lens is OFF everywhere
|
|
126
|
+
// (zero behavior change): no converted figures, no converted ranking. Set
|
|
127
|
+
// it (e.g. "USD") to turn converted `revenueBase` figures + base-ranked
|
|
128
|
+
// `sort=revenue` on wherever a rate source is available. Uppercased so
|
|
129
|
+
// rate-sheet lookups never miss on case.
|
|
130
|
+
BASE_CURRENCY: z
|
|
131
|
+
.string()
|
|
132
|
+
.regex(/^[A-Za-z]{3}$/, "must be a 3-letter ISO-4217 code")
|
|
133
|
+
.transform((v) => v.toUpperCase())
|
|
134
|
+
.optional(),
|
|
135
|
+
// Which rate source serves the lens. "static" (default) is SOVEREIGN —
|
|
136
|
+
// operator-supplied FX_RATES, zero network. "frankfurter" opts into
|
|
137
|
+
// fetching ECB daily reference rates (cached in `fx_rates`, ≤1 outbound
|
|
138
|
+
// call per day, fail-soft to the last cached sheet).
|
|
139
|
+
FX_PROVIDER: z.enum(["static", "frankfurter"]).optional(),
|
|
140
|
+
// The static preset's rate sheet: a JSON object of quote→base rates, e.g.
|
|
141
|
+
// {"JPY":0.0065,"GBP":1.27} = 1 JPY is 0.0065 base units. Quoted against
|
|
142
|
+
// BASE_CURRENCY. Parsed (and failed LOUD on malformed JSON / non-positive
|
|
143
|
+
// values) at boot in `lib/fx.ts` — a typo'd sheet must never silently
|
|
144
|
+
// convert money wrong.
|
|
145
|
+
FX_RATES: z.string().optional(),
|
|
146
|
+
// Optional ISO date the static FX_RATES were taken from — surfaced as the
|
|
147
|
+
// sheet's `asOf` so converted figures can be labeled ("rates as of …").
|
|
148
|
+
FX_RATES_AS_OF: z
|
|
149
|
+
.string()
|
|
150
|
+
.regex(/^\d{4}-\d{2}-\d{2}$/, "must be an ISO date (YYYY-MM-DD)")
|
|
151
|
+
.optional(),
|
|
124
152
|
// --- SMS channel (provider-neutral, BYO SMS provider) ---
|
|
125
153
|
// The active SMS provider id the container resolves from the
|
|
126
154
|
// SmsProviderRegistry. Absent → "twilio" when a provider is registered;
|
|
@@ -226,6 +254,13 @@ export const env = createEnv({
|
|
|
226
254
|
ENABLED_LISTS: z.string().default("*"),
|
|
227
255
|
// Cadence for the engine-owned bucket reconcile cron (time-based leaves).
|
|
228
256
|
BUCKET_RECONCILE_CRON: z.string().default("*/5 * * * *"),
|
|
257
|
+
// Cadence for the engine-owned impact digest cron. Read raw off
|
|
258
|
+
// process.env by onCrons at module load; declared here for the
|
|
259
|
+
// validated-env contract (the OUTBOUND_WEBHOOK_REAPER_CRON stance).
|
|
260
|
+
IMPACT_DIGEST_CRON: z.string().default("0 9 * * 1"),
|
|
261
|
+
// Win-probability crossing threshold for digest "lift" entries; the
|
|
262
|
+
// task clamps to [0.5, 0.999] and defaults to 0.95.
|
|
263
|
+
IMPACT_DIGEST_WIN_PROB: z.coerce.number().min(0.5).max(0.999).optional(),
|
|
229
264
|
// --- Outbound webhooks (Section 1.5/1.8) ---
|
|
230
265
|
// Cadence for the engine-owned outbound-delivery reaper cron (the retry
|
|
231
266
|
// scheduler + orphan-`sending` recovery). Declared for parity with
|
|
@@ -248,6 +283,9 @@ export const env = createEnv({
|
|
|
248
283
|
SUPABASE_WEBHOOK_SECRET: z.string().min(1).optional(),
|
|
249
284
|
STRIPE_WEBHOOK_SECRET: z.string().min(1).optional(),
|
|
250
285
|
SEGMENT_WEBHOOK_SECRET: z.string().min(1).optional(),
|
|
286
|
+
// Intercom app Client Secret — signs `X-Hub-Signature: sha1=<hex>` over the
|
|
287
|
+
// raw body. Auto-enables the Intercom preset at POST /v1/webhooks/intercom.
|
|
288
|
+
INTERCOM_CLIENT_SECRET: z.string().min(1).optional(),
|
|
251
289
|
// Preset enablement override: csv of preset ids, `"*"` (all with a secret),
|
|
252
290
|
// or `"none"`. Absent → auto-enable any preset whose secret is set.
|
|
253
291
|
ENABLED_WEBHOOK_PRESETS: z.string().optional(),
|