@hogsend/engine 0.53.0 → 0.55.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 (39) hide show
  1. package/package.json +12 -11
  2. package/src/buckets/check-membership.ts +45 -3
  3. package/src/connectors/define-action.ts +15 -2
  4. package/src/container.ts +85 -0
  5. package/src/env.ts +21 -0
  6. package/src/index.ts +19 -0
  7. package/src/journeys/durable-law-harness.test.ts +107 -0
  8. package/src/journeys/durable-law-harness.ts +139 -0
  9. package/src/journeys/journey-boundary.test.ts +70 -0
  10. package/src/journeys/journey-boundary.ts +10 -1
  11. package/src/journeys/with-durable-gate.test.ts +258 -0
  12. package/src/journeys/with-durable-gate.ts +141 -0
  13. package/src/lib/bucket-emit.test.ts +145 -0
  14. package/src/lib/bucket-emit.ts +29 -3
  15. package/src/lib/connector-actions.test.ts +292 -1
  16. package/src/lib/connector-actions.ts +65 -6
  17. package/src/lib/email-providers-from-env.ts +15 -16
  18. package/src/lib/enrichment-ledger.ts +207 -0
  19. package/src/lib/enrichment-provider-registry.test.ts +64 -0
  20. package/src/lib/enrichment-provider-registry.ts +35 -0
  21. package/src/lib/enrichment-providers-from-env.apollo.test.ts +30 -0
  22. package/src/lib/enrichment-providers-from-env.test.ts +28 -0
  23. package/src/lib/enrichment-providers-from-env.ts +52 -0
  24. package/src/lib/enrichment-registry-singleton.ts +45 -0
  25. package/src/lib/ingestion.ts +5 -0
  26. package/src/lib/load-optional-plugin.test.ts +133 -0
  27. package/src/lib/load-optional-plugin.ts +142 -0
  28. package/src/lib/outbound.ts +27 -0
  29. package/src/lib/refine-chain.test.ts +764 -0
  30. package/src/lib/refine-chain.ts +583 -0
  31. package/src/lib/refine-traits.test.ts +141 -0
  32. package/src/lib/refine-traits.ts +128 -0
  33. package/src/lib/refine.ts +287 -0
  34. package/src/lib/sms-providers-from-env.ts +11 -11
  35. package/src/lib/webhook-catalog-sync.test.ts +112 -0
  36. package/src/lib/webhook-signing.ts +5 -1
  37. package/src/routes/admin/contacts.ts +113 -13
  38. package/src/workflows/bucket-backfill.ts +14 -0
  39. package/src/workflows/bucket-reconcile.ts +74 -15
@@ -0,0 +1,141 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import type { EnrichmentResult } from "@hogsend/core";
4
+ import { flattenTraits, pickRefinedTraits } from "./refine-traits.js";
5
+
6
+ const REFINED_AT = new Date("2026-07-25T10:00:00.000Z");
7
+ const META = { provider: "fake", refinedAt: REFINED_AT };
8
+
9
+ test("flattenTraits maps every documented field to a flat refined_* key", () => {
10
+ const result: EnrichmentResult = {
11
+ found: true,
12
+ person: {
13
+ title: "VP of Engineering",
14
+ seniority: "vp",
15
+ department: "engineering",
16
+ linkedinUrl: "https://linkedin.com/in/x",
17
+ country: "US",
18
+ },
19
+ company: {
20
+ name: "Acme",
21
+ domain: "acme.com",
22
+ industry: "software",
23
+ employeeCount: 250,
24
+ estimatedRevenue: 12_000_000,
25
+ country: "US",
26
+ },
27
+ raw: {},
28
+ };
29
+
30
+ assert.deepEqual(flattenTraits(result, META), {
31
+ refined_title: "VP of Engineering",
32
+ refined_seniority: "vp",
33
+ refined_department: "engineering",
34
+ refined_linkedin_url: "https://linkedin.com/in/x",
35
+ refined_country: "US",
36
+ refined_company_name: "Acme",
37
+ refined_company_domain: "acme.com",
38
+ refined_company_industry: "software",
39
+ refined_company_employees: 250,
40
+ refined_company_revenue: 12_000_000,
41
+ refined_company_country: "US",
42
+ refined_at: "2026-07-25T10:00:00.000Z",
43
+ refined_provider: "fake",
44
+ });
45
+ });
46
+
47
+ // AC 8 — the numeric traits must be REAL JSON numbers. `conditions/property.ts`
48
+ // does no coercion, so a `"250"` would silently never match a `gte(100)`.
49
+ test("AC 8: employee count is a real JSON number, and survives JSON round-trip", () => {
50
+ const patch = flattenTraits(
51
+ { found: true, company: { employeeCount: 250 }, raw: {} },
52
+ META,
53
+ );
54
+
55
+ assert.equal(typeof patch.refined_company_employees, "number");
56
+ assert.equal(patch.refined_company_employees, 250);
57
+ // jsonb storage is a JSON round-trip — the type must survive it.
58
+ const roundTripped = JSON.parse(JSON.stringify(patch));
59
+ assert.equal(typeof roundTripped.refined_company_employees, "number");
60
+ assert.ok((roundTripped.refined_company_employees as number) >= 100);
61
+ });
62
+
63
+ test("AC 8: a numeric STRING from an untyped provider is coerced to a number", () => {
64
+ const patch = flattenTraits(
65
+ {
66
+ found: true,
67
+ // A JS (untyped) provider can hand back a numeric string; writing it
68
+ // verbatim would break every `gte` bucket silently.
69
+ company: { employeeCount: "250" as unknown as number },
70
+ raw: {},
71
+ },
72
+ META,
73
+ );
74
+
75
+ assert.equal(patch.refined_company_employees, 250);
76
+ assert.equal(typeof patch.refined_company_employees, "number");
77
+ });
78
+
79
+ // AC 9 — an absent field must be OMITTED, never written as null: the patch is
80
+ // wrapped in `jsonb_strip_nulls`, so a null DELETES a previously-good key.
81
+ test("AC 9: absent fields are omitted from the patch entirely (never null)", () => {
82
+ const patch = flattenTraits(
83
+ { found: true, person: { title: "CTO" }, raw: {} },
84
+ META,
85
+ );
86
+
87
+ assert.deepEqual(Object.keys(patch).sort(), [
88
+ "refined_at",
89
+ "refined_provider",
90
+ "refined_title",
91
+ ]);
92
+ assert.equal("refined_seniority" in patch, false);
93
+ assert.equal("refined_company_name" in patch, false);
94
+ for (const value of Object.values(patch)) {
95
+ assert.notEqual(value, null);
96
+ }
97
+ });
98
+
99
+ test("AC 9: null / empty-string / non-finite fields are omitted, not written", () => {
100
+ const patch = flattenTraits(
101
+ {
102
+ found: true,
103
+ person: {
104
+ title: null as unknown as string,
105
+ seniority: " ",
106
+ department: "sales",
107
+ },
108
+ company: {
109
+ employeeCount: Number.NaN,
110
+ estimatedRevenue: "not-a-number" as unknown as number,
111
+ },
112
+ raw: {},
113
+ },
114
+ META,
115
+ );
116
+
117
+ assert.deepEqual(Object.keys(patch).sort(), [
118
+ "refined_at",
119
+ "refined_department",
120
+ "refined_provider",
121
+ ]);
122
+ });
123
+
124
+ test("a not-found result still stamps only the two synthetic traits", () => {
125
+ assert.deepEqual(flattenTraits({ found: false, raw: null }, META), {
126
+ refined_at: "2026-07-25T10:00:00.000Z",
127
+ refined_provider: "fake",
128
+ });
129
+ });
130
+
131
+ test("pickRefinedTraits returns only the refined_* subset", () => {
132
+ assert.deepEqual(
133
+ pickRefinedTraits({
134
+ plan: "pro",
135
+ refined_title: "CTO",
136
+ refined_company_employees: 250,
137
+ }),
138
+ { refined_title: "CTO", refined_company_employees: 250 },
139
+ );
140
+ assert.deepEqual(pickRefinedTraits(undefined), {});
141
+ });
@@ -0,0 +1,128 @@
1
+ import type { EnrichmentResult } from "@hogsend/core";
2
+
3
+ /**
4
+ * Identity of the lookup that produced a patch — the two synthetic traits every
5
+ * successful refinement stamps alongside the vendor's own fields.
6
+ */
7
+ export interface RefinedTraitsMeta {
8
+ /** The enrichment provider id that answered (`refined_provider`). */
9
+ provider: string;
10
+ /** The lookup instant, written as an ISO string (`refined_at`). */
11
+ refinedAt: Date;
12
+ }
13
+
14
+ /**
15
+ * Map a normalized {@link EnrichmentResult} onto the FLAT, top-level,
16
+ * `refined_`-prefixed contact-property patch that `ingestEvent` merges into
17
+ * `contacts.properties`.
18
+ *
19
+ * Two rules make this function load-bearing rather than cosmetic:
20
+ *
21
+ * - **Flat keys only.** `evaluatePropertyConditions` reads
22
+ * `journeyContext[condition.property]`, so a bucket authors
23
+ * `b.prop("refined_seniority")`. A dotted path would never resolve, which is
24
+ * why nothing here nests.
25
+ * - **Absent means ABSENT.** An undefined vendor field is omitted from the
26
+ * patch entirely — never written as `null`. `mergePropertiesSql` wraps the
27
+ * patch in `jsonb_strip_nulls`, so a null would DELETE a previously-good key
28
+ * rather than leave it alone.
29
+ *
30
+ * Numeric traits are written as real JSON numbers: `conditions/property.ts` does
31
+ * no coercion, so a `"42"` would silently never match a `gte`.
32
+ */
33
+ export function flattenTraits(
34
+ result: EnrichmentResult,
35
+ meta: RefinedTraitsMeta,
36
+ ): Record<string, unknown> {
37
+ const patch: Record<string, unknown> = {};
38
+ const person = result.person;
39
+ const company = result.company;
40
+
41
+ putString(patch, "refined_title", person?.title);
42
+ putString(patch, "refined_seniority", person?.seniority);
43
+ putString(patch, "refined_department", person?.department);
44
+ putString(patch, "refined_linkedin_url", person?.linkedinUrl);
45
+ putString(patch, "refined_country", person?.country);
46
+
47
+ putString(patch, "refined_company_name", company?.name);
48
+ putString(patch, "refined_company_domain", company?.domain);
49
+ putString(patch, "refined_company_industry", company?.industry);
50
+ putNumber(patch, "refined_company_employees", company?.employeeCount);
51
+ putNumber(patch, "refined_company_revenue", company?.estimatedRevenue);
52
+ putString(patch, "refined_company_country", company?.country);
53
+
54
+ patch.refined_at = meta.refinedAt.toISOString();
55
+ patch.refined_provider = meta.provider;
56
+
57
+ return patch;
58
+ }
59
+
60
+ /** The prefix every trait this module writes carries. */
61
+ export const REFINED_TRAIT_PREFIX = "refined_";
62
+
63
+ /**
64
+ * The two keys {@link flattenTraits} stamps that are PROVENANCE, not vendor
65
+ * facts. Named once here so a consumer of the patch (the `contact.refined`
66
+ * outbound payload) can tell "what the vendor told us" apart from "when, and
67
+ * who told us" without re-listing them and drifting.
68
+ */
69
+ export const REFINED_META_KEYS: readonly string[] = [
70
+ "refined_at",
71
+ "refined_provider",
72
+ ];
73
+
74
+ /**
75
+ * The `refined_*` subset of an already-stored `contacts.properties` bag — what
76
+ * a cache hit compares the ledger row's stored patch against, to tell "this
77
+ * contact already has the paid answer" apart from "another contact at the same
78
+ * domain paid for it and this one has never seen it".
79
+ */
80
+ export function pickRefinedTraits(
81
+ properties: Record<string, unknown> | null | undefined,
82
+ ): Record<string, unknown> {
83
+ const picked: Record<string, unknown> = {};
84
+ if (!properties) return picked;
85
+ for (const [key, value] of Object.entries(properties)) {
86
+ if (key.startsWith(REFINED_TRAIT_PREFIX)) picked[key] = value;
87
+ }
88
+ return picked;
89
+ }
90
+
91
+ /**
92
+ * Write a string trait, omitting anything that carries no information. An empty
93
+ * (or whitespace-only) string is dropped for the same reason a null is: it is
94
+ * not a fact, and writing it would overwrite a previously-good value.
95
+ */
96
+ function putString(
97
+ patch: Record<string, unknown>,
98
+ key: string,
99
+ value: unknown,
100
+ ): void {
101
+ if (typeof value !== "string") return;
102
+ const trimmed = value.trim();
103
+ if (trimmed === "") return;
104
+ patch[key] = trimmed;
105
+ }
106
+
107
+ /**
108
+ * Write a numeric trait as a real JSON number. A provider is contractually
109
+ * obliged to normalize to `number`, but a JS (untyped) provider can still hand
110
+ * back a numeric string — coercing here is the difference between a working
111
+ * `b.prop("refined_company_employees").gte(100)` and one that silently never
112
+ * matches. Non-finite / non-numeric values are omitted entirely.
113
+ */
114
+ function putNumber(
115
+ patch: Record<string, unknown>,
116
+ key: string,
117
+ value: unknown,
118
+ ): void {
119
+ if (typeof value === "number") {
120
+ if (Number.isFinite(value)) patch[key] = value;
121
+ return;
122
+ }
123
+ if (typeof value !== "string") return;
124
+ const trimmed = value.trim();
125
+ if (trimmed === "") return;
126
+ const parsed = Number(trimmed);
127
+ if (Number.isFinite(parsed)) patch[key] = parsed;
128
+ }
@@ -0,0 +1,287 @@
1
+ import { contacts, type Database } from "@hogsend/db";
2
+ import { and, eq, isNull, type SQL } from "drizzle-orm";
3
+ import { getJourneyRegistrySingleton } from "../journeys/registry-singleton.js";
4
+ import { contactKey, normalizeEmail } from "./contacts.js";
5
+ import { getDb } from "./db.js";
6
+ import {
7
+ countEnrichmentLookups,
8
+ findEnrichmentLookup,
9
+ startOfUtcMonth,
10
+ upsertEnrichmentLookup,
11
+ } from "./enrichment-ledger.js";
12
+ import {
13
+ getEnrichmentProvider,
14
+ getEnrichmentProviderRegistry,
15
+ } from "./enrichment-registry-singleton.js";
16
+ import { hatchet } from "./hatchet.js";
17
+ import { ingestEvent } from "./ingestion.js";
18
+ import { createLogger } from "./logger.js";
19
+ import { emitOutbound } from "./outbound.js";
20
+ import {
21
+ REFINE_EVENT,
22
+ type RefineChainDeps,
23
+ type RefineContactOptions,
24
+ type RefineContactResult,
25
+ type RefineTarget,
26
+ runRefineChain,
27
+ } from "./refine-chain.js";
28
+ import { pickRefinedTraits } from "./refine-traits.js";
29
+
30
+ export type {
31
+ RefineContactOptions,
32
+ RefineContactResult,
33
+ } from "./refine-chain.js";
34
+ export { REFINE_EVENT } from "./refine-chain.js";
35
+
36
+ const logger = createLogger(process.env.LOG_LEVEL);
37
+
38
+ /** `contacts.id` is a uuid; only compare against it for a uuid-shaped ref. */
39
+ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
40
+
41
+ /**
42
+ * Refinement — the one new public function of this release. Resolves a contact,
43
+ * spends AT MOST one provider lookup, and lands the vendor's answer as flat
44
+ * `refined_*` contact properties THROUGH `ingestEvent`, so bucket membership
45
+ * re-evaluates synchronously and the GTM loop closes:
46
+ *
47
+ * ```
48
+ * behaviour → bucket("gtm-high-intent").on("enter")
49
+ * → refineContact()
50
+ * → contacts.properties.refined_* (via ingestEvent)
51
+ * → checkBucketMembership re-runs
52
+ * → bucket("gtm-qualified", b => b.prop("refined_company_employees").gte(100))
53
+ * ```
54
+ *
55
+ * A STANDALONE import, never a `ctx` method — the journey context stays
56
+ * orchestration primitives only, exactly like `sendEmail()` and `sendSms()`.
57
+ *
58
+ * Replay-safety is two-layer. Layer 1 is Hatchet's durable `memo`, keyed by
59
+ * `deriveJourneyKey({ kind: "refine", … })` over the CALLER'S ARGUMENTS ONLY and
60
+ * issued UNCONDITIONALLY whenever a journey boundary exists — see the law
61
+ * spelled out on `runRefineChain`. Layer 2 is the `enrichment_lookups` unique
62
+ * index, which carries exactly-once on its own outside a journey.
63
+ *
64
+ * It NEVER throws. A vendor 5xx writes an `error` ledger row (which records the
65
+ * spend but does not suppress a later retry) and returns
66
+ * `{ status: "skipped", reason: "provider_error" }`; a failed ingest returns
67
+ * `{ status: "skipped", reason: "ingest_failed" }` rather than escaping into the
68
+ * journey run that called it.
69
+ */
70
+ export async function refineContact(
71
+ opts: RefineContactOptions = {},
72
+ ): Promise<RefineContactResult> {
73
+ const db = getDb();
74
+
75
+ // An explicit `provider` id overrides the container's active provider; an id
76
+ // that resolves to nothing is a `no_provider` skip, not a throw.
77
+ const active = getEnrichmentProvider();
78
+ const provider = opts.provider
79
+ ? getEnrichmentProviderRegistry()?.get(opts.provider)
80
+ : active;
81
+
82
+ const deps: RefineChainDeps = {
83
+ ...(provider ? { provider, providerId: provider.meta.id } : {}),
84
+ ttlDays: readPositiveInt(process.env.ENRICHMENT_TTL_DAYS, 90),
85
+ monthlyCap: readPositiveInt(process.env.ENRICHMENT_MONTHLY_LOOKUPS, 0),
86
+ now: () => new Date(),
87
+ logger,
88
+ budgetWindowStart: startOfUtcMonth,
89
+ resolveTarget: (target) => resolveRefineTarget(db, target),
90
+ findLedgerRow: async (input) => {
91
+ const row = await findEnrichmentLookup({ db, ...input });
92
+ return row
93
+ ? { status: row.status, expiresAt: row.expiresAt, traits: row.traits }
94
+ : null;
95
+ },
96
+ countLookupsSince: (input) =>
97
+ countEnrichmentLookups({ db, since: input.since }),
98
+ writeLedgerRow: (input) => upsertEnrichmentLookup({ db, ...input }),
99
+ // OUTBOUND `contact.refined` — fire-and-forget, exactly the `bucket.entered`
100
+ // shape (bucket-emit.ts). `emitOutbound` never throws; the `.catch` is
101
+ // defence-in-depth so a webhook problem can never fail a refinement.
102
+ emitRefined: (input) => {
103
+ void emitOutbound({
104
+ db,
105
+ hatchet,
106
+ logger,
107
+ event: "contact.refined",
108
+ dedupeKey: input.dedupeKey,
109
+ payload: {
110
+ userId: input.userId ?? null,
111
+ email: input.email ?? null,
112
+ contactId: input.contactId ?? null,
113
+ provider: input.provider,
114
+ traits: input.traitKeys,
115
+ at: input.refinedAt.toISOString(),
116
+ },
117
+ }).catch(logger.warn);
118
+ },
119
+ ingest: async (input) => {
120
+ await ingestEvent({
121
+ db,
122
+ registry: getJourneyRegistrySingleton(),
123
+ hatchet,
124
+ logger,
125
+ event: {
126
+ event: REFINE_EVENT,
127
+ ...(input.userId ? { userId: input.userId } : {}),
128
+ ...(input.email ? { userEmail: input.email } : {}),
129
+ ...(input.contactId ? { contactId: input.contactId } : {}),
130
+ eventProperties: input.eventProperties,
131
+ contactProperties: input.contactProperties,
132
+ source: "enrichment",
133
+ ...(input.idempotencyKey
134
+ ? { idempotencyKey: input.idempotencyKey }
135
+ : {}),
136
+ },
137
+ });
138
+ },
139
+ };
140
+
141
+ return runRefineChain(deps, opts);
142
+ }
143
+
144
+ /**
145
+ * Resolve the refinement subject and everything the lookup needs from it: the
146
+ * canonical key the ingest writes back under, the lookup key (email first, then
147
+ * the contact's company domain), the vendor query's name/company hints, and the
148
+ * `refined_*` traits already on the row (what a cache hit compares against to
149
+ * decide whether this contact still needs the stored answer landed).
150
+ *
151
+ * An email with no contact row is still refinable — the ingest at the end of the
152
+ * chain creates the contact — so a brand-new address is not a `no_lookup_key`.
153
+ */
154
+ async function resolveRefineTarget(
155
+ db: Database,
156
+ opts: RefineContactOptions,
157
+ ): Promise<RefineTarget | null> {
158
+ const email = opts.email ? normalizeEmail(opts.email) : undefined;
159
+ const userId = opts.userId?.trim() || undefined;
160
+ const row = await findContactRow(db, {
161
+ contactId: opts.contactId,
162
+ email,
163
+ userId,
164
+ });
165
+
166
+ if (!row) {
167
+ // No row yet: an email is still a perfectly good lookup key.
168
+ if (!email) return null;
169
+ return { email, ...(userId ? { userId } : {}) };
170
+ }
171
+
172
+ const properties = row.properties ?? {};
173
+ const resolvedEmail = row.email ?? email;
174
+ // REPLAY SAFETY: every key here must be one this function does NOT write.
175
+ // The domain becomes the `lookupKey`, which is the `enrichment_lookups`
176
+ // arbiter — Layer 2, the version-independent exactly-once backstop. (Layer 1,
177
+ // the memo key, is derived from the caller's arguments alone and is immune.)
178
+ // A self-referential source would make a replay derive a DIFFERENT ledger key,
179
+ // miss the row it just wrote, and charge the vendor a second time.
180
+ //
181
+ // `refined_company_domain` is deliberately EXCLUDED: `flattenTraits` writes it
182
+ // (refine-traits.ts) from the vendor's canonical domain, which need not equal
183
+ // the one we looked up by. A contact carrying only `domain` would resolve via
184
+ // `domain` on the original run, then — once `refined_company_domain` exists and
185
+ // outranks it — resolve differently on replay, deriving a different memo key.
186
+ // The three keys below are externally supplied and therefore replay-stable.
187
+ const domain = readString(
188
+ properties,
189
+ "company_domain",
190
+ "companyDomain",
191
+ "domain",
192
+ );
193
+
194
+ return {
195
+ contactId: row.id,
196
+ userId: contactKey(row),
197
+ ...(resolvedEmail ? { email: resolvedEmail } : {}),
198
+ // Email is the higher-signal key, so a domain is only the lookup subject
199
+ // when there is no email at all.
200
+ ...(!resolvedEmail && domain ? { domain } : {}),
201
+ ...spread("firstName", readString(properties, "firstName", "first_name")),
202
+ ...spread("lastName", readString(properties, "lastName", "last_name")),
203
+ ...spread(
204
+ "company",
205
+ readString(
206
+ properties,
207
+ "company",
208
+ "company_name",
209
+ "companyName",
210
+ "refined_company_name",
211
+ ),
212
+ ),
213
+ refinedProperties: pickRefinedTraits(properties),
214
+ };
215
+ }
216
+
217
+ type ContactRow = typeof contacts.$inferSelect;
218
+
219
+ /** Live-row lookup by the most specific key the caller supplied. */
220
+ async function findContactRow(
221
+ db: Database,
222
+ keys: { contactId?: string; email?: string; userId?: string },
223
+ ): Promise<ContactRow | null> {
224
+ const live = async (where: SQL | undefined): Promise<ContactRow | null> => {
225
+ const rows = await db
226
+ .select()
227
+ .from(contacts)
228
+ .where(and(where, isNull(contacts.deletedAt)))
229
+ .limit(1);
230
+ return rows[0] ?? null;
231
+ };
232
+
233
+ if (keys.contactId && UUID.test(keys.contactId)) {
234
+ const row = await live(eq(contacts.id, keys.contactId));
235
+ if (row) return row;
236
+ }
237
+ if (keys.email) {
238
+ const row = await live(eq(contacts.email, keys.email));
239
+ if (row) return row;
240
+ }
241
+ if (keys.userId) {
242
+ // `userId` is the canonical key — external_id ?? anonymous_id ?? id — so
243
+ // try each leg in that same precedence.
244
+ const byExternal = await live(eq(contacts.externalId, keys.userId));
245
+ if (byExternal) return byExternal;
246
+ const byAnonymous = await live(eq(contacts.anonymousId, keys.userId));
247
+ if (byAnonymous) return byAnonymous;
248
+ if (UUID.test(keys.userId)) {
249
+ const byId = await live(eq(contacts.id, keys.userId));
250
+ if (byId) return byId;
251
+ }
252
+ }
253
+ return null;
254
+ }
255
+
256
+ /** `{ [field]: value }` when `value` is set, else `{}` — a typed spread hatch. */
257
+ function spread<K extends "firstName" | "lastName" | "company">(
258
+ field: K,
259
+ value: string | undefined,
260
+ ): Partial<RefineTarget> {
261
+ return value ? ({ [field]: value } as Partial<RefineTarget>) : {};
262
+ }
263
+
264
+ /** First non-empty string among `keys`, or undefined. */
265
+ function readString(
266
+ properties: Record<string, unknown>,
267
+ ...keys: string[]
268
+ ): string | undefined {
269
+ for (const key of keys) {
270
+ const value = properties[key];
271
+ if (typeof value === "string" && value.trim() !== "") return value.trim();
272
+ }
273
+ return undefined;
274
+ }
275
+
276
+ /**
277
+ * Read a non-negative integer knob from the live `process.env` at CALL time,
278
+ * with the same coercion + default `env.ts` declares (which stays the schema
279
+ * authority). Mirrors `holdout.ts`'s `GLOBAL_CONTROL_PERCENT` read: a live read
280
+ * lets an operator retune the enrichment budget without a redeploy.
281
+ */
282
+ function readPositiveInt(raw: string | undefined, fallback: number): number {
283
+ if (raw === undefined || raw.trim() === "") return fallback;
284
+ const parsed = Number(raw);
285
+ if (!Number.isFinite(parsed) || parsed < 0) return fallback;
286
+ return Math.floor(parsed);
287
+ }
@@ -1,5 +1,6 @@
1
1
  import type { SmsProvider } from "@hogsend/core";
2
2
  import type { env as envSchema } from "../env.js";
3
+ import { loadOptionalPlugin } from "./load-optional-plugin.js";
3
4
 
4
5
  /**
5
6
  * `@hogsend/plugin-twilio` is an OPT-IN, deferred-publish package — an engine
@@ -25,17 +26,16 @@ const TWILIO_PACKAGE = ["@hogsend", "plugin-twilio"].join("/");
25
26
 
26
27
  let createTwilioProvider: CreateTwilioProvider | null = null;
27
28
  if (process.env.TWILIO_ACCOUNT_SID && process.env.TWILIO_AUTH_TOKEN) {
28
- try {
29
- ({ createTwilioProvider } = (await import(TWILIO_PACKAGE)) as {
30
- createTwilioProvider: CreateTwilioProvider;
31
- });
32
- } catch {
33
- // Credentials set but the opt-in package isn't installed. Leave the factory
34
- // null — `smsProvidersFromEnv` skips the preset, and if Twilio was the
35
- // resolved active provider the container throws a clear "not registered"
36
- // error directing the operator to install `@hogsend/plugin-twilio`.
37
- createTwilioProvider = null;
38
- }
29
+ // Previously a bare `catch {}` that swallowed the failure with no log at all:
30
+ // a Twilio-configured deploy registered no provider, the container installed
31
+ // the inert throwing stub, and the first symptom was `sendSms` throwing at
32
+ // send time with nothing at boot to explain why. Report it where it happens.
33
+ createTwilioProvider = await loadOptionalPlugin<CreateTwilioProvider>({
34
+ specifier: TWILIO_PACKAGE,
35
+ exportName: "createTwilioProvider",
36
+ enabledBy: "TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN are set",
37
+ onFailure: (message) => console.warn(message),
38
+ });
39
39
  }
40
40
 
41
41
  /**