@hogsend/engine 0.46.0 → 0.50.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/connectors/presets/index.ts +8 -2
- package/src/container.ts +149 -7
- 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 +195 -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/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 +8 -0
- package/src/lib/email.ts +23 -2
- package/src/lib/enrollment-policy.ts +51 -0
- 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/fx.ts +374 -0
- package/src/lib/global-control-readout.ts +166 -0
- package/src/lib/groups.ts +362 -0
- package/src/lib/ingestion.ts +38 -0
- package/src/lib/journey-lift.ts +142 -0
- 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/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/contacts.ts +53 -4
- package/src/routes/admin/conversions.ts +137 -0
- package/src/routes/admin/flags.ts +369 -0
- package/src/routes/admin/groups.ts +866 -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/readiness.ts +8 -8
- package/src/routes/admin/settings.ts +145 -0
- package/src/routes/admin/targeting.ts +256 -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/impact-digest.ts +761 -0
- package/src/workflows/journey-blueprint-interpreter.ts +18 -1
package/src/lib/fx.ts
ADDED
|
@@ -0,0 +1,374 @@
|
|
|
1
|
+
import type { FxRateProvider, FxRateSheet } from "@hogsend/core";
|
|
2
|
+
import { defineFxRateProvider } from "@hogsend/core";
|
|
3
|
+
import type { Database } from "@hogsend/db";
|
|
4
|
+
import { fxRates } from "@hogsend/db";
|
|
5
|
+
import { eq, sql } from "drizzle-orm";
|
|
6
|
+
import type { env as envSchema } from "../env.js";
|
|
7
|
+
import type { Logger } from "./logger.js";
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* The base-currency FX lens (docs/groups.md §Base-currency lens) — an OPT-IN
|
|
11
|
+
* converted VIEW layered on top of the revenue spine's per-currency truth.
|
|
12
|
+
* The law (`lib/revenue.ts`) is untouched: currencies are never summed
|
|
13
|
+
* together; the lens converts each per-currency total through an operator-
|
|
14
|
+
* sanctioned quote→base rate and sums the CONVERSIONS. Off by default — the
|
|
15
|
+
* effective base resolves per call (Studio operator setting → env
|
|
16
|
+
* `BASE_CURRENCY`; see the container's resolver); when neither is set the
|
|
17
|
+
* lens resolves null everywhere and nothing changes.
|
|
18
|
+
*
|
|
19
|
+
* Two shipped presets, mirroring how analytics builds from env
|
|
20
|
+
* (`analyticsProvidersFromEnv`), except there is deliberately NO registry:
|
|
21
|
+
* exactly one rate source is resolved at boot (lean-first — multiple
|
|
22
|
+
* simultaneous FX sources have no use case). A consumer-supplied provider
|
|
23
|
+
* (`fx.provider`) wins over both presets.
|
|
24
|
+
*
|
|
25
|
+
* - `static` (the DEFAULT) — sovereign, zero network: the operator supplies
|
|
26
|
+
* the rates (`FX_RATES` JSON) and optionally their date (`FX_RATES_AS_OF`).
|
|
27
|
+
* - `frankfurter` (OPT-IN via `FX_PROVIDER=frankfurter`) — ECB daily
|
|
28
|
+
* reference rates, cached in `fx_rates` so conversions are pinned to a
|
|
29
|
+
* recorded sheet and the API is hit at most once per staleness window.
|
|
30
|
+
*/
|
|
31
|
+
|
|
32
|
+
/** How long a fetched sheet serves before the network source is re-asked. */
|
|
33
|
+
const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
|
|
34
|
+
|
|
35
|
+
// ---------------------------------------------------------------------------
|
|
36
|
+
// Static preset (the default — operator-supplied rates, zero network)
|
|
37
|
+
// ---------------------------------------------------------------------------
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Parse the `FX_RATES` env JSON into a quote→rate map. THROWS on anything
|
|
41
|
+
* malformed (bad JSON, non-object, non-finite or non-positive rates) — a
|
|
42
|
+
* typo'd rate sheet must fail the boot loudly, never silently convert money
|
|
43
|
+
* wrong (the same fail-loud posture as an unresolvable `EMAIL_PROVIDER`).
|
|
44
|
+
* Keys are uppercased so lookups never miss on case.
|
|
45
|
+
*/
|
|
46
|
+
export function parseFxRatesEnv(raw: string): Record<string, number> {
|
|
47
|
+
let parsed: unknown;
|
|
48
|
+
try {
|
|
49
|
+
parsed = JSON.parse(raw);
|
|
50
|
+
} catch {
|
|
51
|
+
throw new Error(
|
|
52
|
+
'FX_RATES is not valid JSON — expected e.g. {"JPY":0.0065,"GBP":1.27}',
|
|
53
|
+
);
|
|
54
|
+
}
|
|
55
|
+
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
|
|
56
|
+
throw new Error(
|
|
57
|
+
'FX_RATES must be a JSON object of quote→base rates, e.g. {"JPY":0.0065}',
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
const rates: Record<string, number> = {};
|
|
61
|
+
for (const [code, rate] of Object.entries(parsed)) {
|
|
62
|
+
if (typeof rate !== "number" || !Number.isFinite(rate) || rate <= 0) {
|
|
63
|
+
throw new Error(
|
|
64
|
+
`FX_RATES["${code}"] must be a positive number (got ${JSON.stringify(rate)})`,
|
|
65
|
+
);
|
|
66
|
+
}
|
|
67
|
+
rates[code.toUpperCase()] = rate;
|
|
68
|
+
}
|
|
69
|
+
return rates;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* The sovereign default rate source: a fixed operator-supplied sheet, which
|
|
74
|
+
* is exactly the sovereignty trade: no network, no drift, rates change only
|
|
75
|
+
* when the operator changes them.
|
|
76
|
+
*
|
|
77
|
+
* THE HONESTY RULE: a static sheet is only meaningful against the ONE base
|
|
78
|
+
* it was quoted in (`quotedBase` — the env `BASE_CURRENCY` the operator's
|
|
79
|
+
* `FX_RATES` were written for). `getRates(base)` serves the sheet ONLY when
|
|
80
|
+
* `base === quotedBase` and resolves null for any other base — a USD-quoted
|
|
81
|
+
* sheet must never silently convert into EUR just because the effective base
|
|
82
|
+
* changed (e.g. via the Studio setting). A `quotedBase` of null (FX_RATES
|
|
83
|
+
* with no BASE_CURRENCY) is a base-less sheet: it serves null for EVERY
|
|
84
|
+
* base — inert, warned at boot in {@link fxProviderFromEnv}.
|
|
85
|
+
*/
|
|
86
|
+
export function createStaticFxProvider(opts: {
|
|
87
|
+
rates: Record<string, number>;
|
|
88
|
+
asOf?: string | null;
|
|
89
|
+
/** The base the sheet's rates are quoted against (null = base-less/inert). */
|
|
90
|
+
quotedBase: string | null;
|
|
91
|
+
}): FxRateProvider {
|
|
92
|
+
const rates = Object.fromEntries(
|
|
93
|
+
Object.entries(opts.rates).map(([code, rate]) => [
|
|
94
|
+
code.toUpperCase(),
|
|
95
|
+
rate,
|
|
96
|
+
]),
|
|
97
|
+
);
|
|
98
|
+
const asOf = opts.asOf ?? null;
|
|
99
|
+
const quotedBase = opts.quotedBase?.toUpperCase() ?? null;
|
|
100
|
+
return defineFxRateProvider({
|
|
101
|
+
meta: {
|
|
102
|
+
id: "static",
|
|
103
|
+
name: "Static (operator-supplied rates)",
|
|
104
|
+
},
|
|
105
|
+
async getRates(base) {
|
|
106
|
+
if (!quotedBase || base.toUpperCase() !== quotedBase) return null;
|
|
107
|
+
return { rates: { ...rates }, asOf };
|
|
108
|
+
},
|
|
109
|
+
});
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
// ---------------------------------------------------------------------------
|
|
113
|
+
// Frankfurter preset (opt-in — ECB daily reference rates, DB-cached)
|
|
114
|
+
// ---------------------------------------------------------------------------
|
|
115
|
+
|
|
116
|
+
/** The subset of Frankfurter's `/latest` response the provider reads. */
|
|
117
|
+
interface FrankfurterLatest {
|
|
118
|
+
date?: string;
|
|
119
|
+
rates?: Record<string, unknown>;
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* ECB daily reference rates via frankfurter.app, opt-in
|
|
124
|
+
* (`FX_PROVIDER=frankfurter`). ONE request serves every quote:
|
|
125
|
+
* `latest?from=<base>` returns base→quote rates (1 base = N quote) for all
|
|
126
|
+
* supported currencies, which we INVERT (quote→base = 1/N) — there is no
|
|
127
|
+
* `latest?to=<base>` batch form.
|
|
128
|
+
*
|
|
129
|
+
* Every successful fetch is upserted into `fx_rates`, and the cache is
|
|
130
|
+
* authoritative until it goes stale, so the API sees at most one call per
|
|
131
|
+
* staleness window and a day's conversions are pinned to one recorded sheet.
|
|
132
|
+
* Staleness is measured from `fetched_at`, NOT `as_of`: the ECB reference
|
|
133
|
+
* date legitimately freezes over weekends/holidays, so keying the refetch off
|
|
134
|
+
* `as_of` would re-hit the API on every request all weekend for rates that
|
|
135
|
+
* cannot have changed.
|
|
136
|
+
*
|
|
137
|
+
* FAIL-SOFT throughout: a failed/malformed fetch serves the last cached sheet
|
|
138
|
+
* when one exists, else resolves null. Nothing here ever throws into a
|
|
139
|
+
* request path.
|
|
140
|
+
*/
|
|
141
|
+
export function createFrankfurterFxProvider(opts: {
|
|
142
|
+
db: Database;
|
|
143
|
+
logger?: Logger;
|
|
144
|
+
/** Test seam — injected fetch. Defaults to the global. */
|
|
145
|
+
fetchImpl?: typeof fetch;
|
|
146
|
+
/** Refetch window in ms. Defaults to 24h (ECB publishes daily). */
|
|
147
|
+
maxAgeMs?: number;
|
|
148
|
+
}): FxRateProvider {
|
|
149
|
+
const fetchImpl = opts.fetchImpl ?? fetch;
|
|
150
|
+
const maxAgeMs = opts.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
|
|
151
|
+
|
|
152
|
+
const sheetFromRows = (
|
|
153
|
+
rows: (typeof fxRates.$inferSelect)[],
|
|
154
|
+
): FxRateSheet => ({
|
|
155
|
+
rates: Object.fromEntries(rows.map((r) => [r.quote, Number(r.rate)])),
|
|
156
|
+
// Rows are upserted as one batch, but be defensive: label the sheet with
|
|
157
|
+
// the newest date present.
|
|
158
|
+
asOf: rows.reduce<string | null>(
|
|
159
|
+
(max, r) => (max === null || r.asOf > max ? r.asOf : max),
|
|
160
|
+
null,
|
|
161
|
+
),
|
|
162
|
+
});
|
|
163
|
+
|
|
164
|
+
return defineFxRateProvider({
|
|
165
|
+
meta: {
|
|
166
|
+
id: "frankfurter",
|
|
167
|
+
name: "Frankfurter (ECB daily reference rates)",
|
|
168
|
+
},
|
|
169
|
+
async getRates(base) {
|
|
170
|
+
const baseCode = base.toUpperCase();
|
|
171
|
+
let cached: (typeof fxRates.$inferSelect)[] = [];
|
|
172
|
+
try {
|
|
173
|
+
cached = await opts.db
|
|
174
|
+
.select()
|
|
175
|
+
.from(fxRates)
|
|
176
|
+
.where(eq(fxRates.base, baseCode));
|
|
177
|
+
|
|
178
|
+
const newestFetch = cached.reduce<number>(
|
|
179
|
+
(max, r) => Math.max(max, r.fetchedAt.getTime()),
|
|
180
|
+
0,
|
|
181
|
+
);
|
|
182
|
+
if (cached.length > 0 && Date.now() - newestFetch < maxAgeMs) {
|
|
183
|
+
return sheetFromRows(cached);
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
const res = await fetchImpl(
|
|
187
|
+
`https://api.frankfurter.app/latest?from=${encodeURIComponent(baseCode)}`,
|
|
188
|
+
);
|
|
189
|
+
if (!res.ok) {
|
|
190
|
+
throw new Error(`frankfurter responded ${res.status}`);
|
|
191
|
+
}
|
|
192
|
+
const body = (await res.json()) as FrankfurterLatest;
|
|
193
|
+
const asOf = body.date;
|
|
194
|
+
// 1 base = N quote on the wire; the lens wants quote→base, so 1/N.
|
|
195
|
+
const entries = Object.entries(body.rates ?? {}).filter(
|
|
196
|
+
(pair): pair is [string, number] =>
|
|
197
|
+
typeof pair[1] === "number" &&
|
|
198
|
+
Number.isFinite(pair[1]) &&
|
|
199
|
+
pair[1] > 0,
|
|
200
|
+
);
|
|
201
|
+
if (!asOf || entries.length === 0) {
|
|
202
|
+
throw new Error("frankfurter returned no usable rates");
|
|
203
|
+
}
|
|
204
|
+
const fetchedAt = new Date();
|
|
205
|
+
const rows = entries.map(([quote, perBase]) => ({
|
|
206
|
+
base: baseCode,
|
|
207
|
+
quote: quote.toUpperCase(),
|
|
208
|
+
rate: 1 / perBase,
|
|
209
|
+
asOf,
|
|
210
|
+
fetchedAt,
|
|
211
|
+
}));
|
|
212
|
+
await opts.db
|
|
213
|
+
.insert(fxRates)
|
|
214
|
+
.values(rows)
|
|
215
|
+
.onConflictDoUpdate({
|
|
216
|
+
target: [fxRates.base, fxRates.quote],
|
|
217
|
+
set: {
|
|
218
|
+
rate: sql`excluded.rate`,
|
|
219
|
+
asOf: sql`excluded.as_of`,
|
|
220
|
+
fetchedAt: sql`excluded.fetched_at`,
|
|
221
|
+
},
|
|
222
|
+
});
|
|
223
|
+
return {
|
|
224
|
+
rates: Object.fromEntries(rows.map((r) => [r.quote, r.rate])),
|
|
225
|
+
asOf,
|
|
226
|
+
};
|
|
227
|
+
} catch (error) {
|
|
228
|
+
// Fail-soft: a stale sheet labeled with its true asOf beats no sheet;
|
|
229
|
+
// no sheet beats an invented one. Never throw into a request path.
|
|
230
|
+
opts.logger?.warn(
|
|
231
|
+
`frankfurter FX rates unavailable${
|
|
232
|
+
cached.length > 0 ? " — serving the last cached sheet" : ""
|
|
233
|
+
}`,
|
|
234
|
+
{ error: error instanceof Error ? error.message : String(error) },
|
|
235
|
+
);
|
|
236
|
+
return cached.length > 0 ? sheetFromRows(cached) : null;
|
|
237
|
+
}
|
|
238
|
+
},
|
|
239
|
+
});
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
// ---------------------------------------------------------------------------
|
|
243
|
+
// Env resolution + the lens (what the container holds)
|
|
244
|
+
// ---------------------------------------------------------------------------
|
|
245
|
+
|
|
246
|
+
/**
|
|
247
|
+
* Resolve the ONE env-configured rate source, mirroring the env-preset spirit
|
|
248
|
+
* of `analyticsProvidersFromEnv` without the registry: `FX_PROVIDER=
|
|
249
|
+
* frankfurter` opts into the network source; otherwise a set `FX_RATES`
|
|
250
|
+
* builds the sovereign static sheet (throwing at boot on a malformed one);
|
|
251
|
+
* otherwise there is no source. A consumer `fx.provider` wins over this
|
|
252
|
+
* entirely (checked at the container call site).
|
|
253
|
+
*/
|
|
254
|
+
export function fxProviderFromEnv(
|
|
255
|
+
env: typeof envSchema,
|
|
256
|
+
deps: { db: Database; logger?: Logger },
|
|
257
|
+
): FxRateProvider | undefined {
|
|
258
|
+
if (env.FX_PROVIDER === "frankfurter") {
|
|
259
|
+
return createFrankfurterFxProvider({ db: deps.db, logger: deps.logger });
|
|
260
|
+
}
|
|
261
|
+
if (env.FX_RATES) {
|
|
262
|
+
if (!env.BASE_CURRENCY) {
|
|
263
|
+
// Called once at boot per container, so this warns ONCE: a sheet with
|
|
264
|
+
// no quoted base is inert (serves null for every base — even one later
|
|
265
|
+
// chosen in Studio), because we cannot know which base its rates were
|
|
266
|
+
// written for. Warned rather than thrown: the deploy still boots and
|
|
267
|
+
// the per-currency truth serves unchanged.
|
|
268
|
+
deps.logger?.warn(
|
|
269
|
+
"FX_RATES is set but BASE_CURRENCY is not — the static rate sheet has no quoted base and is INERT (no conversions will be served, even if a base currency is chosen in Studio). Set BASE_CURRENCY to the currency FX_RATES is quoted against.",
|
|
270
|
+
);
|
|
271
|
+
}
|
|
272
|
+
return createStaticFxProvider({
|
|
273
|
+
rates: parseFxRatesEnv(env.FX_RATES),
|
|
274
|
+
asOf: env.FX_RATES_AS_OF ?? null,
|
|
275
|
+
quotedBase: env.BASE_CURRENCY ?? null,
|
|
276
|
+
});
|
|
277
|
+
}
|
|
278
|
+
return undefined;
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
/**
|
|
282
|
+
* A resolved quote→base sheet, normalized for consumers: keys uppercased,
|
|
283
|
+
* non-usable rates dropped, and the identity rate (base→base = 1) injected so
|
|
284
|
+
* no reader special-cases the base currency. Carries the base it converts TO
|
|
285
|
+
* — a sheet is only meaningful relative to its base, so readers never have to
|
|
286
|
+
* pair it back up with the lens.
|
|
287
|
+
*/
|
|
288
|
+
export interface FxRatesToBase {
|
|
289
|
+
baseCurrency: string;
|
|
290
|
+
rates: Record<string, number>;
|
|
291
|
+
asOf: string | null;
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
/**
|
|
295
|
+
* The minimal FX surface the container exposes (`client.fx`). The effective
|
|
296
|
+
* base currency is resolved PER CALL (never boot-frozen): the container's
|
|
297
|
+
* resolver walks code pin → Studio operator setting → env `BASE_CURRENCY`,
|
|
298
|
+
* so a base chosen/changed/cleared in Studio takes effect on the next
|
|
299
|
+
* request without a reboot. Null base = the lens is OFF: `getRatesToBase`
|
|
300
|
+
* resolves null and every consumer renders the unconverted truth, unchanged.
|
|
301
|
+
*/
|
|
302
|
+
export interface FxLens {
|
|
303
|
+
/** The active rate source's id (`meta.id`), or null when none is wired. */
|
|
304
|
+
providerId: string | null;
|
|
305
|
+
/**
|
|
306
|
+
* Resolve the operator's EFFECTIVE reporting currency (uppercased), or
|
|
307
|
+
* null when the lens is off. Fail-soft: a throwing resolver reads as off.
|
|
308
|
+
*/
|
|
309
|
+
getBaseCurrency(): Promise<string | null>;
|
|
310
|
+
/**
|
|
311
|
+
* Resolve the quote→base sheet from the active provider. Null when the
|
|
312
|
+
* lens is off, no provider is configured, or the provider has nothing to
|
|
313
|
+
* serve. NEVER throws — the lens is the fail-soft chokepoint even for a
|
|
314
|
+
* misbehaving BYO provider, so no request path needs its own guard.
|
|
315
|
+
*/
|
|
316
|
+
getRatesToBase(): Promise<FxRatesToBase | null>;
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
/** Build the container's {@link FxLens} from the base resolver + provider. */
|
|
320
|
+
export function createFxLens(opts: {
|
|
321
|
+
/**
|
|
322
|
+
* Resolves the effective base per call (the container builds it from the
|
|
323
|
+
* code pin / operator setting / env precedence). Null = lens off.
|
|
324
|
+
*/
|
|
325
|
+
resolveBaseCurrency: () => Promise<string | null>;
|
|
326
|
+
provider?: FxRateProvider;
|
|
327
|
+
logger: Logger;
|
|
328
|
+
}): FxLens {
|
|
329
|
+
const provider = opts.provider;
|
|
330
|
+
const resolveBase = async (): Promise<string | null> => {
|
|
331
|
+
try {
|
|
332
|
+
const base = await opts.resolveBaseCurrency();
|
|
333
|
+
return base ? base.toUpperCase() : null;
|
|
334
|
+
} catch (error) {
|
|
335
|
+
// Same fail-soft posture as a misbehaving provider below: a resolver
|
|
336
|
+
// that throws (e.g. a DB blip reading the operator setting) degrades
|
|
337
|
+
// to lens-off for this request, never into a thrown request path.
|
|
338
|
+
opts.logger.warn(
|
|
339
|
+
"FX base-currency resolution threw — the base-currency lens is off for this request",
|
|
340
|
+
{ error: error instanceof Error ? error.message : String(error) },
|
|
341
|
+
);
|
|
342
|
+
return null;
|
|
343
|
+
}
|
|
344
|
+
};
|
|
345
|
+
return {
|
|
346
|
+
providerId: provider?.meta.id ?? null,
|
|
347
|
+
getBaseCurrency: resolveBase,
|
|
348
|
+
async getRatesToBase() {
|
|
349
|
+
const baseCurrency = await resolveBase();
|
|
350
|
+
if (!baseCurrency || !provider) return null;
|
|
351
|
+
try {
|
|
352
|
+
const sheet = await provider.getRates(baseCurrency);
|
|
353
|
+
if (!sheet) return null;
|
|
354
|
+
const rates: Record<string, number> = {};
|
|
355
|
+
for (const [code, rate] of Object.entries(sheet.rates)) {
|
|
356
|
+
if (typeof rate === "number" && Number.isFinite(rate) && rate > 0) {
|
|
357
|
+
rates[code.toUpperCase()] = rate;
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
rates[baseCurrency] = 1;
|
|
361
|
+
return { baseCurrency, rates, asOf: sheet.asOf ?? null };
|
|
362
|
+
} catch (error) {
|
|
363
|
+
// The provider contract says "never throw", but the lens holds the
|
|
364
|
+
// line for providers that do anyway: converted figures degrade to
|
|
365
|
+
// absent; the per-currency truth is always still served.
|
|
366
|
+
opts.logger.warn(
|
|
367
|
+
`FX provider "${provider.meta.id}" threw resolving rates — the base-currency lens is off for this request`,
|
|
368
|
+
{ error: error instanceof Error ? error.message : String(error) },
|
|
369
|
+
);
|
|
370
|
+
return null;
|
|
371
|
+
}
|
|
372
|
+
},
|
|
373
|
+
};
|
|
374
|
+
}
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
import type { Database } from "@hogsend/db";
|
|
2
|
+
import { sql } from "drizzle-orm";
|
|
3
|
+
import { globalControlPercent, isGlobalControl } from "./holdout.js";
|
|
4
|
+
import { computeLift, type LiftVerdict } from "./lift-stats.js";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* Program-level global-control readout (impact-experiments spec D4.5e).
|
|
8
|
+
* Assignment lives only in env + hash (no assignment table), so the
|
|
9
|
+
* readout recomputes membership per contact as
|
|
10
|
+
* key = externalId ?? anonymousId ?? id, which is what
|
|
11
|
+
* isGlobalControl(options.userId ?? options.to) hashes at send time
|
|
12
|
+
* (lib/tracked.ts:245-246, lib/sms-tracked.ts:225-226) for JOURNEY sends —
|
|
13
|
+
* a journey's `userId` is the ingest-resolved key
|
|
14
|
+
* (event.userId ?? event.anonymousId, lib/ingestion.ts), so an
|
|
15
|
+
* anonymous-triggered journey hashes the same anonymousId the readout
|
|
16
|
+
* falls back to.
|
|
17
|
+
*
|
|
18
|
+
* DISCLOSED APPROXIMATION: two OTHER send paths resolve a different key and
|
|
19
|
+
* can disagree with the readout for a contact whose external_id is NULL but
|
|
20
|
+
* anonymous_id is set (the readout hashes anonymous_id; these paths hash the
|
|
21
|
+
* contact's UUID instead, never anonymous_id):
|
|
22
|
+
* - bare POST /v1/emails — regardless of whether the caller supplied a
|
|
23
|
+
* userId, the route always resolves the send's userId as
|
|
24
|
+
* recipient.externalId ?? recipient.contactId (routes/emails/index.ts),
|
|
25
|
+
* so it can never fall through to anonymous_id.
|
|
26
|
+
* - list-audience campaign broadcasts — the send-campaign cursor query
|
|
27
|
+
* resolves the same externalId ?? contactId fallback
|
|
28
|
+
* (workflows/send-campaign.ts), also never anonymous_id.
|
|
29
|
+
* Journey sends stay in parity with the readout (see above); the
|
|
30
|
+
* divergence is bounded to these two paths, so the fallback chain remains
|
|
31
|
+
* a reasonable, disclosed approximation for a mixed-population program —
|
|
32
|
+
* not a blanket "no userId" case.
|
|
33
|
+
*
|
|
34
|
+
* Converter outcomes aggregate ALL definitions (global control suppresses
|
|
35
|
+
* all non-transactional sends, so any registered conversion is a fair
|
|
36
|
+
* program-level outcome; no definitionId knob in v1). ITT caveat: this is
|
|
37
|
+
* a cross-sectional randomized comparison — outcome window
|
|
38
|
+
* occurred_at >= since for BOTH buckets; random assignment keeps it
|
|
39
|
+
* causal, window symmetry keeps it fair.
|
|
40
|
+
*/
|
|
41
|
+
|
|
42
|
+
/** In-request scan ceiling — above this the readout reports `skipped`
|
|
43
|
+
* (honest ceiling; a cached cron materialization is explicitly deferred). */
|
|
44
|
+
export const GLOBAL_CONTROL_SCAN_CEILING = 500_000;
|
|
45
|
+
|
|
46
|
+
const DEFAULT_BATCH_SIZE = 5_000;
|
|
47
|
+
|
|
48
|
+
type ContactPageRow = {
|
|
49
|
+
id: string;
|
|
50
|
+
external_id: string | null;
|
|
51
|
+
anonymous_id: string | null;
|
|
52
|
+
};
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Fetches one keyset-paginated page of live contacts. Extracted to a
|
|
56
|
+
* top-level function (rather than inlined in the pagination loop) with an
|
|
57
|
+
* explicit return type — TS's control-flow narrowing of `cursor` across
|
|
58
|
+
* loop iterations otherwise creates a self-referential inference cycle
|
|
59
|
+
* (`pageQuery` → `page` → `rows` → next-iteration `cursor` → `pageQuery`)
|
|
60
|
+
* that surfaces as a spurious implicit-any (TS7022) when inlined.
|
|
61
|
+
*/
|
|
62
|
+
async function fetchContactPage(
|
|
63
|
+
db: Database,
|
|
64
|
+
cursor: string | null,
|
|
65
|
+
batchSize: number,
|
|
66
|
+
): Promise<ContactPageRow[]> {
|
|
67
|
+
const pageQuery =
|
|
68
|
+
cursor === null
|
|
69
|
+
? sql`select id, external_id, anonymous_id from contacts
|
|
70
|
+
where deleted_at is null
|
|
71
|
+
order by id asc limit ${batchSize}`
|
|
72
|
+
: sql`select id, external_id, anonymous_id from contacts
|
|
73
|
+
where deleted_at is null and id > ${cursor}::uuid
|
|
74
|
+
order by id asc limit ${batchSize}`;
|
|
75
|
+
const page = await db.execute<ContactPageRow>(pageQuery);
|
|
76
|
+
return [...page];
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export type GlobalControlReadout =
|
|
80
|
+
| { state: "off" }
|
|
81
|
+
| {
|
|
82
|
+
state: "skipped";
|
|
83
|
+
reason: "too_many_contacts";
|
|
84
|
+
percent: number;
|
|
85
|
+
contactCount: number;
|
|
86
|
+
}
|
|
87
|
+
| ({
|
|
88
|
+
state: "computed";
|
|
89
|
+
causal: true;
|
|
90
|
+
percent: number;
|
|
91
|
+
contactsScanned: number;
|
|
92
|
+
treatment: { contacts: number; converters: number; rate: number };
|
|
93
|
+
control: { contacts: number; converters: number; rate: number };
|
|
94
|
+
} & LiftVerdict);
|
|
95
|
+
|
|
96
|
+
export async function computeGlobalControlReadout(opts: {
|
|
97
|
+
db: Database;
|
|
98
|
+
since: Date;
|
|
99
|
+
/** Scan ceiling override — the route always uses the default; the
|
|
100
|
+
* parameter exists so the skipped state is testable. */
|
|
101
|
+
scanCeiling?: number;
|
|
102
|
+
batchSize?: number;
|
|
103
|
+
}): Promise<GlobalControlReadout> {
|
|
104
|
+
const percent = globalControlPercent();
|
|
105
|
+
if (percent === 0) return { state: "off" };
|
|
106
|
+
|
|
107
|
+
const ceiling = opts.scanCeiling ?? GLOBAL_CONTROL_SCAN_CEILING;
|
|
108
|
+
const batchSize = opts.batchSize ?? DEFAULT_BATCH_SIZE;
|
|
109
|
+
const sinceTs = sql`${opts.since.toISOString()}::timestamptz`;
|
|
110
|
+
|
|
111
|
+
const countRows = await opts.db.execute<{ count: number }>(
|
|
112
|
+
sql`select count(*)::int as count
|
|
113
|
+
from contacts where deleted_at is null`,
|
|
114
|
+
);
|
|
115
|
+
const contactCount = Number([...countRows][0]?.count ?? 0);
|
|
116
|
+
if (contactCount > ceiling) {
|
|
117
|
+
return {
|
|
118
|
+
state: "skipped",
|
|
119
|
+
reason: "too_many_contacts",
|
|
120
|
+
percent,
|
|
121
|
+
contactCount,
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
const converterRows = await opts.db.execute<{ contact_id: string }>(
|
|
126
|
+
sql`select distinct contact_id from conversions
|
|
127
|
+
where occurred_at >= ${sinceTs}`,
|
|
128
|
+
);
|
|
129
|
+
const converterSet = new Set([...converterRows].map((r) => r.contact_id));
|
|
130
|
+
|
|
131
|
+
let cursor: string | null = null;
|
|
132
|
+
let scanned = 0;
|
|
133
|
+
const treatment = { contacts: 0, converters: 0 };
|
|
134
|
+
const control = { contacts: 0, converters: 0 };
|
|
135
|
+
while (true) {
|
|
136
|
+
const rows = await fetchContactPage(opts.db, cursor, batchSize);
|
|
137
|
+
if (rows.length === 0) break;
|
|
138
|
+
for (const row of rows) {
|
|
139
|
+
const key = row.external_id ?? row.anonymous_id ?? row.id;
|
|
140
|
+
const bucket = isGlobalControl(key) ? control : treatment;
|
|
141
|
+
bucket.contacts += 1;
|
|
142
|
+
if (converterSet.has(row.id)) bucket.converters += 1;
|
|
143
|
+
}
|
|
144
|
+
scanned += rows.length;
|
|
145
|
+
cursor = rows[rows.length - 1]?.id ?? null;
|
|
146
|
+
if (rows.length < batchSize) break;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
const verdict = computeLift({ treatment, control });
|
|
150
|
+
return {
|
|
151
|
+
state: "computed",
|
|
152
|
+
causal: true,
|
|
153
|
+
percent,
|
|
154
|
+
contactsScanned: scanned,
|
|
155
|
+
treatment: {
|
|
156
|
+
...treatment,
|
|
157
|
+
rate:
|
|
158
|
+
treatment.contacts > 0 ? treatment.converters / treatment.contacts : 0,
|
|
159
|
+
},
|
|
160
|
+
control: {
|
|
161
|
+
...control,
|
|
162
|
+
rate: control.contacts > 0 ? control.converters / control.contacts : 0,
|
|
163
|
+
},
|
|
164
|
+
...verdict,
|
|
165
|
+
};
|
|
166
|
+
}
|