@hogsend/engine 0.53.0 → 0.54.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.
@@ -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
+ }
@@ -0,0 +1,112 @@
1
+ import assert from "node:assert/strict";
2
+ import { readFileSync } from "node:fs";
3
+ import test from "node:test";
4
+ import { fileURLToPath } from "node:url";
5
+ import { WEBHOOK_EVENT_TYPES } from "./webhook-signing.js";
6
+
7
+ /**
8
+ * THE DRIFT CHECK the outbound catalog never had.
9
+ *
10
+ * `WEBHOOK_EVENT_TYPES` is vendored into two copies that cannot import the
11
+ * engine — the CLI's own tuple and the client's `OutboundEventType` union — and
12
+ * until this file the only thing keeping them in sync was a comment asking
13
+ * nicely. Every event added since has been a coin flip.
14
+ *
15
+ * So: read the two vendored files off disk and compare the FULL sets, not just
16
+ * the newest member. Whoever adds event 32 and forgets a copy gets a failing
17
+ * test naming the file they missed, rather than a subscriber who can never
18
+ * register for it.
19
+ *
20
+ * This is a monorepo-source check by construction — it reads sibling packages'
21
+ * `src/`, which is exactly the coupling it is asserting.
22
+ */
23
+
24
+ const CLI_CATALOG = fileURLToPath(
25
+ new URL("../../../cli/src/commands/webhooks.ts", import.meta.url),
26
+ );
27
+ const CLIENT_CATALOG = fileURLToPath(
28
+ new URL("../../../client/src/types.ts", import.meta.url),
29
+ );
30
+
31
+ /** The source between `start` and the next `end`, exclusive. */
32
+ function between(file: string, start: string, end: string): string {
33
+ const source = readFileSync(file, "utf8");
34
+ const from = source.indexOf(start);
35
+ assert.notEqual(from, -1, `${file}: could not find \`${start}\``);
36
+ const to = source.indexOf(end, from + start.length);
37
+ assert.notEqual(
38
+ to,
39
+ -1,
40
+ `${file}: could not find \`${end}\` after \`${start}\``,
41
+ );
42
+ return source.slice(from + start.length, to);
43
+ }
44
+
45
+ /** Every `"<namespace>.<name>"` literal in a block of source. */
46
+ function eventLiterals(block: string): string[] {
47
+ return [...block.matchAll(/"([a-z]+\.[a-z_]+)"/g)].map(
48
+ (match) => match[1] as string,
49
+ );
50
+ }
51
+
52
+ function readCliCatalog(): string[] {
53
+ return eventLiterals(
54
+ between(CLI_CATALOG, "const WEBHOOK_EVENT_TYPES = [", "] as const;"),
55
+ );
56
+ }
57
+
58
+ function readClientCatalog(): string[] {
59
+ return eventLiterals(
60
+ between(CLIENT_CATALOG, "export type OutboundEventType =", ";"),
61
+ );
62
+ }
63
+
64
+ /** Set-wise, because the three copies are not in the same ORDER (they never
65
+ * have been) — only membership is load-bearing. */
66
+ function assertSameSet(actual: string[], expected: string[], what: string) {
67
+ const missing = expected.filter((event) => !actual.includes(event));
68
+ const extra = actual.filter(
69
+ (event) => !(expected as string[]).includes(event),
70
+ );
71
+ assert.deepEqual(
72
+ { missing, extra },
73
+ { missing: [], extra: [] },
74
+ `${what} has drifted from the engine's WEBHOOK_EVENT_TYPES`,
75
+ );
76
+ assert.equal(
77
+ new Set(actual).size,
78
+ actual.length,
79
+ `${what} contains a duplicate entry`,
80
+ );
81
+ }
82
+
83
+ test("AC 4: contact.refined is present in ALL THREE hand-synced catalogs", () => {
84
+ assert.ok(
85
+ (WEBHOOK_EVENT_TYPES as readonly string[]).includes("contact.refined"),
86
+ "engine WEBHOOK_EVENT_TYPES is missing contact.refined",
87
+ );
88
+ assert.ok(
89
+ readCliCatalog().includes("contact.refined"),
90
+ "packages/cli/src/commands/webhooks.ts is missing contact.refined",
91
+ );
92
+ assert.ok(
93
+ readClientCatalog().includes("contact.refined"),
94
+ "packages/client/src/types.ts is missing contact.refined",
95
+ );
96
+ });
97
+
98
+ test("AC 4: the CLI's vendored catalog is the engine catalog, entry for entry", () => {
99
+ assertSameSet(
100
+ readCliCatalog(),
101
+ [...WEBHOOK_EVENT_TYPES],
102
+ "packages/cli/src/commands/webhooks.ts",
103
+ );
104
+ });
105
+
106
+ test("AC 4: the client's OutboundEventType union is the engine catalog, entry for entry", () => {
107
+ assertSameSet(
108
+ readClientCatalog(),
109
+ [...WEBHOOK_EVENT_TYPES],
110
+ "packages/client/src/types.ts",
111
+ );
112
+ });
@@ -25,7 +25,7 @@ import { Webhook } from "svix";
25
25
  */
26
26
 
27
27
  /**
28
- * The 30-event catalog — the SINGLE source of truth (schema, routes, client,
28
+ * The 31-event catalog — the SINGLE source of truth (schema, routes, client,
29
29
  * CLI all derive from this). The `webhook.test` sentinel is intentionally NOT a
30
30
  * member (it is delivered out-of-band regardless of an endpoint's `eventTypes`).
31
31
  *
@@ -63,6 +63,10 @@ export const WEBHOOK_EVENT_TYPES = [
63
63
  // Global control group membership (impact plan §4.3) — emitted once per
64
64
  // contact key on the first withheld send.
65
65
  "contact.control_group",
66
+ // A refinement landed vendor traits on a contact (`refineContact`). Emitted
67
+ // ONLY on a genuine `status: "refined"` — never on `cached`, `not_found` or
68
+ // `skipped`. A cache hit spends nothing and is not an event.
69
+ "contact.refined",
66
70
  "email.sent",
67
71
  "email.delivered",
68
72
  "email.opened",