@hogsend/engine 0.54.0 → 0.56.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/package.json +11 -11
- package/src/buckets/check-membership.ts +58 -3
- package/src/lib/bucket-emit.test.ts +145 -0
- package/src/lib/bucket-emit.ts +29 -3
- package/src/lib/email-providers-from-env.ts +15 -16
- package/src/lib/enrichment-ledger.ts +1 -1
- package/src/lib/enrichment-providers-from-env.test.ts +5 -44
- package/src/lib/enrichment-providers-from-env.ts +8 -41
- package/src/lib/ingestion.ts +16 -0
- package/src/lib/load-optional-plugin.test.ts +133 -0
- package/src/lib/load-optional-plugin.ts +142 -0
- package/src/lib/outbound.ts +3 -3
- package/src/lib/refine-chain.test.ts +83 -25
- package/src/lib/refine-chain.ts +124 -23
- package/src/lib/refine-traits.test.ts +74 -41
- package/src/lib/refine-traits.ts +107 -52
- package/src/lib/refine.ts +28 -27
- package/src/lib/sms-providers-from-env.ts +11 -11
- package/src/workflows/bucket-backfill.ts +14 -0
- package/src/workflows/bucket-reconcile.ts +74 -15
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hogsend/engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.56.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -53,18 +53,18 @@
|
|
|
53
53
|
"svix": "^1.95.1",
|
|
54
54
|
"winston": "^3.19.0",
|
|
55
55
|
"zod": "^4.4.3",
|
|
56
|
-
"@hogsend/attribution": "^0.
|
|
57
|
-
"@hogsend/core": "^0.
|
|
58
|
-
"@hogsend/db": "^0.
|
|
59
|
-
"@hogsend/email": "^0.
|
|
60
|
-
"@hogsend/plugin-posthog": "^0.
|
|
61
|
-
"@hogsend/plugin-resend": "^0.
|
|
62
|
-
"@hogsend/sms": "^0.
|
|
56
|
+
"@hogsend/attribution": "^0.56.0",
|
|
57
|
+
"@hogsend/core": "^0.56.0",
|
|
58
|
+
"@hogsend/db": "^0.56.0",
|
|
59
|
+
"@hogsend/email": "^0.56.0",
|
|
60
|
+
"@hogsend/plugin-posthog": "^0.56.0",
|
|
61
|
+
"@hogsend/plugin-resend": "^0.56.0",
|
|
62
|
+
"@hogsend/sms": "^0.56.0"
|
|
63
63
|
},
|
|
64
64
|
"optionalDependencies": {
|
|
65
|
-
"@hogsend/plugin-apollo": "^0.
|
|
66
|
-
"@hogsend/plugin-postmark": "^0.
|
|
67
|
-
"@hogsend/plugin-twilio": "^0.
|
|
65
|
+
"@hogsend/plugin-apollo": "^0.56.0",
|
|
66
|
+
"@hogsend/plugin-postmark": "^0.56.0",
|
|
67
|
+
"@hogsend/plugin-twilio": "^0.56.0"
|
|
68
68
|
},
|
|
69
69
|
"devDependencies": {
|
|
70
70
|
"@types/node": "^22.15.3",
|
|
@@ -51,6 +51,16 @@ export async function checkBucketMembership(opts: {
|
|
|
51
51
|
logger: Logger;
|
|
52
52
|
userId: string;
|
|
53
53
|
userEmail: string | null;
|
|
54
|
+
/**
|
|
55
|
+
* The subject contact's resolved row id (`contacts.id`) — `ingestEvent` has
|
|
56
|
+
* already resolved the contact before calling us, so it threads the id here
|
|
57
|
+
* and we carry it into every `emitBucketTransition` as the ENGINE-INTERNAL
|
|
58
|
+
* provenance pin. Without it, a transition for a contact whose canonical key
|
|
59
|
+
* is its `anonymous_id` re-ingests a bare `userId` and mints a phantom
|
|
60
|
+
* `external_id` twin (issue #608). Optional: a caller without a resolved
|
|
61
|
+
* contact degrades to the pin-less emit.
|
|
62
|
+
*/
|
|
63
|
+
contactId?: string;
|
|
54
64
|
event: string;
|
|
55
65
|
/**
|
|
56
66
|
* D2: the event payload — candidate-narrowing ONLY. It NO LONGER participates
|
|
@@ -62,6 +72,14 @@ export async function checkBucketMembership(opts: {
|
|
|
62
72
|
* the very first event after a property change evaluates correctly (risk 7).
|
|
63
73
|
*/
|
|
64
74
|
contactProperties?: Record<string, unknown>;
|
|
75
|
+
/**
|
|
76
|
+
* Extra property NAMES for candidate-narrowing ONLY — never overlaid on the
|
|
77
|
+
* contact row for value eval. A producer whose write patch omits a key it
|
|
78
|
+
* nonetheless changed (refinement's fill-if-absent drops already-held facts to
|
|
79
|
+
* avoid clobbering first-party data) lists those names here so their fit
|
|
80
|
+
* buckets are still re-checked against live contact state.
|
|
81
|
+
*/
|
|
82
|
+
touchProperties?: string[];
|
|
65
83
|
/** Optional override; defaults to the process bucket-registry singleton. */
|
|
66
84
|
bucketRegistry?: ReturnType<typeof getBucketRegistrySingleton>;
|
|
67
85
|
}): Promise<BucketTransition[]> {
|
|
@@ -71,9 +89,11 @@ export async function checkBucketMembership(opts: {
|
|
|
71
89
|
hatchet,
|
|
72
90
|
logger,
|
|
73
91
|
userId,
|
|
92
|
+
contactId,
|
|
74
93
|
event,
|
|
75
94
|
eventProperties,
|
|
76
95
|
contactProperties: contactPropertiesPatch,
|
|
96
|
+
touchProperties,
|
|
77
97
|
} = opts;
|
|
78
98
|
// The caller's email comes verbatim from the raw event payload — normalize
|
|
79
99
|
// ONCE here so the membership row, the emitted bucket:* transition events,
|
|
@@ -107,6 +127,10 @@ export async function checkBucketMembership(opts: {
|
|
|
107
127
|
for (const key of [
|
|
108
128
|
...Object.keys(eventProperties ?? {}),
|
|
109
129
|
...Object.keys(contactPropertiesPatch ?? {}),
|
|
130
|
+
// Names-only touches (e.g. refinement's fill-if-absent dropped facts) surface
|
|
131
|
+
// a fit bucket here so it is re-checked against live contact state below,
|
|
132
|
+
// even though the value is not in this ingest's write patch.
|
|
133
|
+
...(touchProperties ?? []),
|
|
110
134
|
]) {
|
|
111
135
|
for (const bucket of bucketRegistry.getByReferencedProperty(key)) {
|
|
112
136
|
candidateMap.set(bucket.id, bucket);
|
|
@@ -209,6 +233,7 @@ export async function checkBucketMembership(opts: {
|
|
|
209
233
|
bucket,
|
|
210
234
|
userId,
|
|
211
235
|
userEmail,
|
|
236
|
+
contactId,
|
|
212
237
|
});
|
|
213
238
|
if (transition) transitions.push(transition);
|
|
214
239
|
} else if (wasMember && isMember) {
|
|
@@ -227,6 +252,7 @@ export async function checkBucketMembership(opts: {
|
|
|
227
252
|
active,
|
|
228
253
|
userId,
|
|
229
254
|
userEmail,
|
|
255
|
+
contactId,
|
|
230
256
|
});
|
|
231
257
|
if (transition) transitions.push(transition);
|
|
232
258
|
}
|
|
@@ -244,8 +270,19 @@ async function handleJoin(opts: {
|
|
|
244
270
|
bucket: BucketMeta;
|
|
245
271
|
userId: string;
|
|
246
272
|
userEmail: string | null;
|
|
273
|
+
/** Provenance pin for the emit — see `checkBucketMembership` (issue #608). */
|
|
274
|
+
contactId?: string;
|
|
247
275
|
}): Promise<BucketTransition | null> {
|
|
248
|
-
const {
|
|
276
|
+
const {
|
|
277
|
+
db,
|
|
278
|
+
registry,
|
|
279
|
+
hatchet,
|
|
280
|
+
logger,
|
|
281
|
+
bucket,
|
|
282
|
+
userId,
|
|
283
|
+
userEmail,
|
|
284
|
+
contactId,
|
|
285
|
+
} = opts;
|
|
249
286
|
|
|
250
287
|
// entryCount ordinal = 1 + count of ALL prior memberships (active + left) for
|
|
251
288
|
// this (user, bucket) (Section 6.3 / 8.2). priorCount also drives the entryLimit
|
|
@@ -312,6 +349,10 @@ async function handleJoin(opts: {
|
|
|
312
349
|
bucket,
|
|
313
350
|
userId,
|
|
314
351
|
userEmail,
|
|
352
|
+
// Pin the re-ingest to the already-resolved contact row so an
|
|
353
|
+
// anonymous-only contact's transition folds in instead of minting a
|
|
354
|
+
// phantom twin (issue #608).
|
|
355
|
+
contactId,
|
|
315
356
|
epoch,
|
|
316
357
|
source: "event",
|
|
317
358
|
});
|
|
@@ -335,9 +376,20 @@ async function handleLeave(opts: {
|
|
|
335
376
|
active: typeof bucketMemberships.$inferSelect;
|
|
336
377
|
userId: string;
|
|
337
378
|
userEmail: string | null;
|
|
379
|
+
/** Provenance pin for the emit — see `checkBucketMembership` (issue #608). */
|
|
380
|
+
contactId?: string;
|
|
338
381
|
}): Promise<BucketTransition | null> {
|
|
339
|
-
const {
|
|
340
|
-
|
|
382
|
+
const {
|
|
383
|
+
db,
|
|
384
|
+
registry,
|
|
385
|
+
hatchet,
|
|
386
|
+
logger,
|
|
387
|
+
bucket,
|
|
388
|
+
active,
|
|
389
|
+
userId,
|
|
390
|
+
userEmail,
|
|
391
|
+
contactId,
|
|
392
|
+
} = opts;
|
|
341
393
|
|
|
342
394
|
// minDwell DEFERS (never silently drops) the leave (Section 6.3). We set a
|
|
343
395
|
// pending-leave deadline on expiresAt = enteredAt + minDwell so the reconcile
|
|
@@ -401,6 +453,9 @@ async function handleLeave(opts: {
|
|
|
401
453
|
bucket,
|
|
402
454
|
userId,
|
|
403
455
|
userEmail,
|
|
456
|
+
// Same provenance pin as the join emit — a leave re-ingests through the
|
|
457
|
+
// identical path and would mint the same phantom twin (issue #608).
|
|
458
|
+
contactId,
|
|
404
459
|
epoch: flipped.entryCount,
|
|
405
460
|
source: "event",
|
|
406
461
|
reason: "criteria",
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
4
|
+
import type { BucketMeta } from "@hogsend/core";
|
|
5
|
+
import type { JourneyRegistry } from "@hogsend/core/registry";
|
|
6
|
+
import type { Database } from "@hogsend/db";
|
|
7
|
+
import type { IngestEvent, ingestEvent } from "./ingestion.js";
|
|
8
|
+
import type { Logger } from "./logger.js";
|
|
9
|
+
|
|
10
|
+
// bucket-emit's import chain reaches env.ts (validates required env vars at
|
|
11
|
+
// import time) and lib/hatchet.ts (parses HATCHET_CLIENT_TOKEN as a JWT at
|
|
12
|
+
// import time) — stub both BEFORE the dynamic import. Nothing is ever
|
|
13
|
+
// contacted: the ingest seam intercepts everything. The token is the same
|
|
14
|
+
// well-formed dummy JWT apps/api's vitest config injects.
|
|
15
|
+
process.env.DATABASE_URL ??= "postgresql://test:test@localhost:5432/test";
|
|
16
|
+
process.env.BETTER_AUTH_SECRET ??= "test-secret";
|
|
17
|
+
process.env.HATCHET_CLIENT_TOKEN ??=
|
|
18
|
+
"eyJhbGciOiJFUzI1NiIsImtpZCI6InRlc3QifQ.eyJhdWQiOiJsb2NhbGhvc3QiLCJleHAiOjQ5MzMyNDA5ODMsImdycGNfYnJvYWRjYXN0X2FkZHJlc3MiOiJsb2NhbGhvc3Q6NzA3NyIsImlhdCI6MTc3OTY0MDk4MywiaXNzIjoibG9jYWxob3N0Iiwic2VydmVyX3VybCI6ImxvY2FsaG9zdCIsInN1YiI6InRlc3QtdGVuYW50LWlkIiwidG9rZW5faWQiOiJ0ZXN0LXRva2VuLWlkIn0.test";
|
|
19
|
+
const { emitBucketTransition } = await import("./bucket-emit.js");
|
|
20
|
+
|
|
21
|
+
// ---------------------------------------------------------------------------
|
|
22
|
+
// Issue #608 — the `contactId` provenance pin. `emitBucketTransition`
|
|
23
|
+
// re-ingests every transition; `userId` is the contact's CANONICAL key
|
|
24
|
+
// (`external_id ?? anonymous_id ?? id`), but the resolver treats a bare
|
|
25
|
+
// `userId` as an EXTERNAL key, so an anonymous-only contact gets a phantom
|
|
26
|
+
// `external_id` twin minted per transition unless the pin rides the re-ingest.
|
|
27
|
+
// These tests assert at the `ingest` seam (no live DB — the Section 14
|
|
28
|
+
// pattern): the pin must ride BOTH re-ingests (per-bucket alias AND generic),
|
|
29
|
+
// and its absence must degrade to exactly the pin-less call shape.
|
|
30
|
+
// ---------------------------------------------------------------------------
|
|
31
|
+
|
|
32
|
+
const noop = () => {};
|
|
33
|
+
const logger: Logger = {
|
|
34
|
+
debug: noop,
|
|
35
|
+
info: noop,
|
|
36
|
+
warn: noop,
|
|
37
|
+
error: noop,
|
|
38
|
+
} as unknown as Logger;
|
|
39
|
+
|
|
40
|
+
const bucket: BucketMeta = {
|
|
41
|
+
id: "power-users",
|
|
42
|
+
name: "Power users",
|
|
43
|
+
} as BucketMeta;
|
|
44
|
+
|
|
45
|
+
/** A registry stub with a journey bound to the generic `bucket:<kind>` form, so
|
|
46
|
+
* the SECOND (generic) re-ingest actually fires and can be asserted on. */
|
|
47
|
+
function genericBoundRegistry(): JourneyRegistry {
|
|
48
|
+
return {
|
|
49
|
+
getByTriggerEvent: (event: string) =>
|
|
50
|
+
event === "bucket:entered" || event === "bucket:left" ? [{}] : [],
|
|
51
|
+
} as unknown as JourneyRegistry;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** Recording ingest stub — captures each re-ingested event. */
|
|
55
|
+
function recordingIngest() {
|
|
56
|
+
const events: IngestEvent[] = [];
|
|
57
|
+
const ingest: typeof ingestEvent = async (opts) => {
|
|
58
|
+
events.push(opts.event);
|
|
59
|
+
return { stored: true, exits: [], contactKey: opts.event.userId ?? "" };
|
|
60
|
+
};
|
|
61
|
+
return { events, ingest };
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
// db/hatchet are never touched by the stubbed ingest; emitOutbound is
|
|
65
|
+
// fire-and-forget (`void ...catch(logger.warn)`) so its rejection on the empty
|
|
66
|
+
// db stub is swallowed by design.
|
|
67
|
+
const db = {} as Database;
|
|
68
|
+
const hatchet = {} as HatchetClient;
|
|
69
|
+
|
|
70
|
+
const CONTACT_ID = "9f3a1c2e-0000-4000-8000-000000000608";
|
|
71
|
+
|
|
72
|
+
test("entered: the contactId pin rides BOTH re-ingests (alias + generic)", async () => {
|
|
73
|
+
const { events, ingest } = recordingIngest();
|
|
74
|
+
|
|
75
|
+
await emitBucketTransition({
|
|
76
|
+
db,
|
|
77
|
+
registry: genericBoundRegistry(),
|
|
78
|
+
hatchet,
|
|
79
|
+
logger,
|
|
80
|
+
kind: "entered",
|
|
81
|
+
bucket,
|
|
82
|
+
userId: "anon-608",
|
|
83
|
+
userEmail: null,
|
|
84
|
+
contactId: CONTACT_ID,
|
|
85
|
+
epoch: 1,
|
|
86
|
+
ingest,
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
assert.equal(events.length, 2);
|
|
90
|
+
const [alias, generic] = events;
|
|
91
|
+
assert.equal(alias?.event, "bucket:entered:power-users");
|
|
92
|
+
assert.equal(generic?.event, "bucket:entered");
|
|
93
|
+
// The pin on EACH leg — dropping it on either one leaves the phantom-twin
|
|
94
|
+
// mint half-alive (issue #608).
|
|
95
|
+
assert.equal(alias?.contactId, CONTACT_ID);
|
|
96
|
+
assert.equal(generic?.contactId, CONTACT_ID);
|
|
97
|
+
});
|
|
98
|
+
|
|
99
|
+
test("left: the contactId pin rides the leave re-ingest too", async () => {
|
|
100
|
+
const { events, ingest } = recordingIngest();
|
|
101
|
+
|
|
102
|
+
await emitBucketTransition({
|
|
103
|
+
db,
|
|
104
|
+
registry: genericBoundRegistry(),
|
|
105
|
+
hatchet,
|
|
106
|
+
logger,
|
|
107
|
+
kind: "left",
|
|
108
|
+
bucket,
|
|
109
|
+
userId: "anon-608",
|
|
110
|
+
userEmail: null,
|
|
111
|
+
contactId: CONTACT_ID,
|
|
112
|
+
epoch: 2,
|
|
113
|
+
reason: "criteria",
|
|
114
|
+
ingest,
|
|
115
|
+
});
|
|
116
|
+
|
|
117
|
+
assert.equal(events.length, 2);
|
|
118
|
+
for (const event of events) {
|
|
119
|
+
assert.equal(event.contactId, CONTACT_ID);
|
|
120
|
+
}
|
|
121
|
+
});
|
|
122
|
+
|
|
123
|
+
test("no contactId: degrades to exactly the pin-less re-ingest", async () => {
|
|
124
|
+
const { events, ingest } = recordingIngest();
|
|
125
|
+
|
|
126
|
+
await emitBucketTransition({
|
|
127
|
+
db,
|
|
128
|
+
registry: genericBoundRegistry(),
|
|
129
|
+
hatchet,
|
|
130
|
+
logger,
|
|
131
|
+
kind: "entered",
|
|
132
|
+
bucket,
|
|
133
|
+
userId: "anon-608",
|
|
134
|
+
userEmail: null,
|
|
135
|
+
epoch: 1,
|
|
136
|
+
ingest,
|
|
137
|
+
});
|
|
138
|
+
|
|
139
|
+
// A producer with no resolved contact row in scope (e.g. the fast-expiry
|
|
140
|
+
// timer) must NOT invent a pin — the resolver falls back to value keys.
|
|
141
|
+
assert.equal(events.length, 2);
|
|
142
|
+
for (const event of events) {
|
|
143
|
+
assert.equal(event.contactId, undefined);
|
|
144
|
+
}
|
|
145
|
+
});
|
package/src/lib/bucket-emit.ts
CHANGED
|
@@ -40,6 +40,17 @@ export async function emitBucketTransition(opts: {
|
|
|
40
40
|
bucket: BucketMeta;
|
|
41
41
|
userId: string;
|
|
42
42
|
userEmail: string | null;
|
|
43
|
+
/**
|
|
44
|
+
* The subject contact's resolved row id (`contacts.id`) — the ENGINE-INTERNAL
|
|
45
|
+
* provenance pin, threaded into BOTH re-ingests below. `userId` here is the
|
|
46
|
+
* contact's CANONICAL key (`external_id ?? anonymous_id ?? id`), but the
|
|
47
|
+
* resolver treats a bare `userId` as an EXTERNAL key and never probes
|
|
48
|
+
* `anonymous_id` — so without the pin an anonymous-only contact gets a
|
|
49
|
+
* phantom `external_id` twin minted on every transition (issue #608).
|
|
50
|
+
* OPTIONAL: a producer that has no resolved contact row in scope degrades to
|
|
51
|
+
* the pin-less resolve (exactly the pre-pin behaviour).
|
|
52
|
+
*/
|
|
53
|
+
contactId?: string;
|
|
43
54
|
epoch: number;
|
|
44
55
|
source?: BucketTransitionSource;
|
|
45
56
|
/** Carried on a `left` transition's properties → `ctx.reason`. */
|
|
@@ -52,6 +63,12 @@ export async function emitBucketTransition(opts: {
|
|
|
52
63
|
* absorbed by the `userEvents` dedup. Surfaced as `dwellCount`.
|
|
53
64
|
*/
|
|
54
65
|
dwellOrdinal?: number;
|
|
66
|
+
/**
|
|
67
|
+
* Testing seam — the re-ingest fn (defaults to the real `ingestEvent`), so a
|
|
68
|
+
* unit test can assert the provenance pin rides BOTH re-ingests without a
|
|
69
|
+
* live database (the Section 14 pattern `checkBucketMembership` uses).
|
|
70
|
+
*/
|
|
71
|
+
ingest?: typeof ingestEvent;
|
|
55
72
|
}): Promise<void> {
|
|
56
73
|
const {
|
|
57
74
|
db,
|
|
@@ -62,11 +79,13 @@ export async function emitBucketTransition(opts: {
|
|
|
62
79
|
bucket,
|
|
63
80
|
userId,
|
|
64
81
|
userEmail,
|
|
82
|
+
contactId,
|
|
65
83
|
epoch,
|
|
66
84
|
source = "event",
|
|
67
85
|
reason,
|
|
68
86
|
dwellLabel,
|
|
69
87
|
dwellOrdinal,
|
|
88
|
+
ingest = ingestEvent,
|
|
70
89
|
} = opts;
|
|
71
90
|
|
|
72
91
|
// The dwell transition emits a labelled event so two dwell reactions on one
|
|
@@ -114,8 +133,10 @@ export async function emitBucketTransition(opts: {
|
|
|
114
133
|
|
|
115
134
|
// Per-bucket alias — the recommended, narrowly-routed binding. The
|
|
116
135
|
// deterministic idempotencyKey rides the userEvents dedup short-circuit as
|
|
117
|
-
// defense-in-depth (Section 6.3).
|
|
118
|
-
|
|
136
|
+
// defense-in-depth (Section 6.3). `contactId` pins the resolver to the known
|
|
137
|
+
// row so an anonymous canonical key folds back in instead of minting a
|
|
138
|
+
// phantom `external_id` twin (issue #608).
|
|
139
|
+
await ingest({
|
|
119
140
|
db,
|
|
120
141
|
registry,
|
|
121
142
|
hatchet,
|
|
@@ -124,6 +145,7 @@ export async function emitBucketTransition(opts: {
|
|
|
124
145
|
event: eventName,
|
|
125
146
|
userId,
|
|
126
147
|
userEmail: userEmail ?? "",
|
|
148
|
+
contactId,
|
|
127
149
|
eventProperties: properties,
|
|
128
150
|
source: "bucket",
|
|
129
151
|
idempotencyKey,
|
|
@@ -134,7 +156,7 @@ export async function emitBucketTransition(opts: {
|
|
|
134
156
|
// recursion-guarded generic event is not written for nothing (Section 8.5).
|
|
135
157
|
const genericEvent = `bucket:${kind}`;
|
|
136
158
|
if (registry.getByTriggerEvent(genericEvent).length > 0) {
|
|
137
|
-
await
|
|
159
|
+
await ingest({
|
|
138
160
|
db,
|
|
139
161
|
registry,
|
|
140
162
|
hatchet,
|
|
@@ -143,6 +165,10 @@ export async function emitBucketTransition(opts: {
|
|
|
143
165
|
event: genericEvent,
|
|
144
166
|
userId,
|
|
145
167
|
userEmail: userEmail ?? "",
|
|
168
|
+
// Same provenance pin as the alias emit above — dropping it on ONLY
|
|
169
|
+
// this leg would leave the twin-minting half-alive for generic-bound
|
|
170
|
+
// journeys (issue #608).
|
|
171
|
+
contactId,
|
|
146
172
|
eventProperties: properties,
|
|
147
173
|
source: "bucket",
|
|
148
174
|
idempotencyKey: `bucket:${bucket.id}:${userId}:${kind}:${epoch}:generic`,
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
import type { EmailProvider } from "@hogsend/core";
|
|
2
2
|
import { createResendProvider } from "@hogsend/plugin-resend";
|
|
3
3
|
import type { env as envSchema } from "../env.js";
|
|
4
|
+
import { loadOptionalPlugin } from "./load-optional-plugin.js";
|
|
4
5
|
|
|
5
6
|
/**
|
|
6
|
-
* `@hogsend/plugin-postmark` is an OPT-IN
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
* with E404 on plugin-postmark for every consumer that doesn't have it.
|
|
7
|
+
* `@hogsend/plugin-postmark` is an OPT-IN package: an engine
|
|
8
|
+
* `optionalDependency`, NOT a hard one. So we MUST NOT statically import it — a
|
|
9
|
+
* static `import` would make the package mandatory at engine load for every
|
|
10
|
+
* consumer, including the ones that never send through Postmark.
|
|
11
11
|
*
|
|
12
12
|
* Instead we load it lazily, ONCE, behind a top-level guarded dynamic import:
|
|
13
13
|
* the `import()` only fires when `POSTMARK_SERVER_TOKEN` is present (the same
|
|
@@ -34,17 +34,16 @@ const POSTMARK_PACKAGE = ["@hogsend", "plugin-postmark"].join("/");
|
|
|
34
34
|
|
|
35
35
|
let createPostmarkProvider: CreatePostmarkProvider | null = null;
|
|
36
36
|
if (process.env.POSTMARK_SERVER_TOKEN) {
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
}
|
|
37
|
+
// Previously a bare `catch {}` that swallowed the failure silently. If
|
|
38
|
+
// Postmark was the resolved active provider the container still threw its
|
|
39
|
+
// "not registered" boot error, but a deploy that merely set the token fell
|
|
40
|
+
// back to Resend with nothing in the logs to say why.
|
|
41
|
+
createPostmarkProvider = await loadOptionalPlugin<CreatePostmarkProvider>({
|
|
42
|
+
specifier: POSTMARK_PACKAGE,
|
|
43
|
+
exportName: "createPostmarkProvider",
|
|
44
|
+
enabledBy: "POSTMARK_SERVER_TOKEN is set",
|
|
45
|
+
onFailure: (message) => console.warn(message),
|
|
46
|
+
});
|
|
48
47
|
}
|
|
49
48
|
|
|
50
49
|
/**
|
|
@@ -22,7 +22,7 @@ export interface EnrichmentLookupRow {
|
|
|
22
22
|
refinedAt: Date;
|
|
23
23
|
expiresAt: Date;
|
|
24
24
|
raw: Record<string, unknown> | null;
|
|
25
|
-
/** The normalized
|
|
25
|
+
/** The normalized canonical trait patch the paid answer produced. */
|
|
26
26
|
traits: Record<string, unknown> | null;
|
|
27
27
|
spendWindow: Date | null;
|
|
28
28
|
spendCount: number;
|
|
@@ -1,10 +1,7 @@
|
|
|
1
1
|
import assert from "node:assert/strict";
|
|
2
2
|
import test from "node:test";
|
|
3
3
|
import type { env as envSchema } from "../env.js";
|
|
4
|
-
import {
|
|
5
|
-
enrichmentProvidersFromEnv,
|
|
6
|
-
loadEnrichmentPluginFactory,
|
|
7
|
-
} from "./enrichment-providers-from-env.js";
|
|
4
|
+
import { enrichmentProvidersFromEnv } from "./enrichment-providers-from-env.js";
|
|
8
5
|
|
|
9
6
|
// This test process never sets APOLLO_API_KEY, so the module-scope guarded
|
|
10
7
|
// dynamic import in enrichment-providers-from-env.ts must not have fired —
|
|
@@ -25,43 +22,7 @@ test("AC 7 (preset half): key set but factory unresolved → empty list, no thro
|
|
|
25
22
|
assert.deepEqual(enrichmentProvidersFromEnv(envWithKey), []);
|
|
26
23
|
});
|
|
27
24
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
const messages: string[] = [];
|
|
33
|
-
const factory = await loadEnrichmentPluginFactory({
|
|
34
|
-
specifier: "@hogsend/plugin-test-does-not-exist",
|
|
35
|
-
exportName: "createTestProvider",
|
|
36
|
-
onMissing: (message) => messages.push(message),
|
|
37
|
-
});
|
|
38
|
-
assert.equal(factory, null);
|
|
39
|
-
assert.equal(messages.length, 1);
|
|
40
|
-
assert.match(messages[0] ?? "", /@hogsend\/plugin-test-does-not-exist/);
|
|
41
|
-
});
|
|
42
|
-
|
|
43
|
-
test("AC 7 control: resolvable specifier → returns the named export", async () => {
|
|
44
|
-
// Proves the null above comes from the unresolvable specifier, not a broken
|
|
45
|
-
// loader — keeping the guard-half assertion honest.
|
|
46
|
-
const messages: string[] = [];
|
|
47
|
-
const factory = await loadEnrichmentPluginFactory<
|
|
48
|
-
typeof import("node:path")["join"]
|
|
49
|
-
>({
|
|
50
|
-
specifier: "node:path",
|
|
51
|
-
exportName: "join",
|
|
52
|
-
onMissing: (message) => messages.push(message),
|
|
53
|
-
});
|
|
54
|
-
assert.equal(typeof factory, "function");
|
|
55
|
-
assert.equal(messages.length, 0);
|
|
56
|
-
});
|
|
57
|
-
|
|
58
|
-
test("a resolvable specifier MISSING the named export → null + logged, no throw", async () => {
|
|
59
|
-
const messages: string[] = [];
|
|
60
|
-
const factory = await loadEnrichmentPluginFactory({
|
|
61
|
-
specifier: "node:path",
|
|
62
|
-
exportName: "createApolloProvider",
|
|
63
|
-
onMissing: (message) => messages.push(message),
|
|
64
|
-
});
|
|
65
|
-
assert.equal(factory, null);
|
|
66
|
-
assert.equal(messages.length, 1);
|
|
67
|
-
});
|
|
25
|
+
// The guard itself now lives in `load-optional-plugin.ts` and is covered by
|
|
26
|
+
// `load-optional-plugin.test.ts` — including the classification this preset
|
|
27
|
+
// depends on (absent package vs installed-but-broken). Only the preset's own
|
|
28
|
+
// behaviour is asserted here.
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { EnrichmentProvider } 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-apollo` is an OPT-IN, deferred-publish package — an engine
|
|
@@ -18,49 +19,15 @@ type CreateApolloProvider = (cfg: { apiKey: string }) => EnrichmentProvider;
|
|
|
18
19
|
|
|
19
20
|
const APOLLO_PACKAGE = ["@hogsend", "plugin-apollo"].join("/");
|
|
20
21
|
|
|
21
|
-
/**
|
|
22
|
-
* The guard around the dynamic import, extracted so it is testable against an
|
|
23
|
-
* INJECTED unresolvable specifier (never against `@hogsend/plugin-apollo`
|
|
24
|
-
* genuinely being absent — once that package lands in `optionalDependencies`,
|
|
25
|
-
* an absence-based test would silently assert the opposite of what it means).
|
|
26
|
-
*
|
|
27
|
-
* Resolves to the named factory export, or null when the package cannot be
|
|
28
|
-
* resolved / the export is missing — in which case `onMissing` fires (once,
|
|
29
|
-
* since the module-scope call site runs once per process) and nothing throws:
|
|
30
|
-
* a key set without the plugin installed degrades gracefully, and if the
|
|
31
|
-
* provider was EXPLICITLY requested the container still throws its clear
|
|
32
|
-
* "not registered" boot error.
|
|
33
|
-
*/
|
|
34
|
-
export async function loadEnrichmentPluginFactory<T>(opts: {
|
|
35
|
-
specifier: string;
|
|
36
|
-
exportName: string;
|
|
37
|
-
onMissing?: (message: string) => void;
|
|
38
|
-
}): Promise<T | null> {
|
|
39
|
-
try {
|
|
40
|
-
const mod = (await import(opts.specifier)) as Record<string, unknown>;
|
|
41
|
-
const factory = mod[opts.exportName];
|
|
42
|
-
if (typeof factory !== "function") {
|
|
43
|
-
throw new Error(`missing export "${opts.exportName}"`);
|
|
44
|
-
}
|
|
45
|
-
return factory as T;
|
|
46
|
-
} catch {
|
|
47
|
-
opts.onMissing?.(
|
|
48
|
-
`enrichment plugin "${opts.specifier}" is not installed — its env preset is skipped. ` +
|
|
49
|
-
`Install the package (pnpm add ${opts.specifier}) to enable it.`,
|
|
50
|
-
);
|
|
51
|
-
return null;
|
|
52
|
-
}
|
|
53
|
-
}
|
|
54
|
-
|
|
55
22
|
let createApolloProvider: CreateApolloProvider | null = null;
|
|
56
23
|
if (process.env.APOLLO_API_KEY) {
|
|
57
|
-
createApolloProvider =
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
24
|
+
createApolloProvider = await loadOptionalPlugin<CreateApolloProvider>({
|
|
25
|
+
specifier: APOLLO_PACKAGE,
|
|
26
|
+
exportName: "createApolloProvider",
|
|
27
|
+
enabledBy: "APOLLO_API_KEY is set",
|
|
28
|
+
// Module scope ⇒ logs ONCE per process, and only when the key is set.
|
|
29
|
+
onFailure: (message) => console.warn(message),
|
|
30
|
+
});
|
|
64
31
|
}
|
|
65
32
|
|
|
66
33
|
/**
|
package/src/lib/ingestion.ts
CHANGED
|
@@ -71,6 +71,14 @@ export interface IngestEvent {
|
|
|
71
71
|
eventProperties: Record<string, unknown>;
|
|
72
72
|
/** D2: → `contacts.properties` merge ONLY. */
|
|
73
73
|
contactProperties?: Record<string, unknown>;
|
|
74
|
+
/**
|
|
75
|
+
* Extra property NAMES to re-evaluate buckets for — candidate-narrowing ONLY,
|
|
76
|
+
* NOT written and NOT in value eval. Lets a producer whose write patch omits a
|
|
77
|
+
* key (e.g. refinement's fill-if-absent, which drops already-held facts so it
|
|
78
|
+
* never clobbers first-party data) still trigger a fit bucket that references
|
|
79
|
+
* that key. Off by default; only engine-internal callers set it.
|
|
80
|
+
*/
|
|
81
|
+
touchProperties?: string[];
|
|
74
82
|
/**
|
|
75
83
|
* The groupType→groupKey association map for this event — persisted on
|
|
76
84
|
* `user_events.groups`, drives group membership (each group row is ensured +
|
|
@@ -778,10 +786,18 @@ export async function ingestEvent(opts: {
|
|
|
778
786
|
hatchet,
|
|
779
787
|
logger,
|
|
780
788
|
userId: resolvedKey,
|
|
789
|
+
// The resolved row id rides along as the ENGINE-INTERNAL provenance pin
|
|
790
|
+
// for the bucket transition re-ingests: `resolvedKey` may be the
|
|
791
|
+
// contact's `anonymous_id`, which a bare re-ingest would treat as an
|
|
792
|
+
// external key and mint a phantom twin for (issue #608).
|
|
793
|
+
contactId,
|
|
781
794
|
userEmail: event.userEmail || null,
|
|
782
795
|
event: event.event,
|
|
783
796
|
eventProperties: event.eventProperties,
|
|
784
797
|
contactProperties: event.contactProperties ?? {},
|
|
798
|
+
...(event.touchProperties
|
|
799
|
+
? { touchProperties: event.touchProperties }
|
|
800
|
+
: {}),
|
|
785
801
|
});
|
|
786
802
|
} catch (err) {
|
|
787
803
|
logger.warn("Bucket membership check failed", {
|