@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.
- package/package.json +12 -11
- package/src/buckets/check-membership.ts +45 -3
- package/src/connectors/define-action.ts +15 -2
- package/src/container.ts +85 -0
- package/src/env.ts +21 -0
- package/src/index.ts +19 -0
- package/src/journeys/durable-law-harness.test.ts +107 -0
- package/src/journeys/durable-law-harness.ts +139 -0
- package/src/journeys/journey-boundary.test.ts +70 -0
- package/src/journeys/journey-boundary.ts +10 -1
- package/src/journeys/with-durable-gate.test.ts +258 -0
- package/src/journeys/with-durable-gate.ts +141 -0
- package/src/lib/bucket-emit.test.ts +145 -0
- package/src/lib/bucket-emit.ts +29 -3
- package/src/lib/connector-actions.test.ts +292 -1
- package/src/lib/connector-actions.ts +65 -6
- package/src/lib/email-providers-from-env.ts +15 -16
- package/src/lib/enrichment-ledger.ts +207 -0
- package/src/lib/enrichment-provider-registry.test.ts +64 -0
- package/src/lib/enrichment-provider-registry.ts +35 -0
- package/src/lib/enrichment-providers-from-env.apollo.test.ts +30 -0
- package/src/lib/enrichment-providers-from-env.test.ts +28 -0
- package/src/lib/enrichment-providers-from-env.ts +52 -0
- package/src/lib/enrichment-registry-singleton.ts +45 -0
- package/src/lib/ingestion.ts +5 -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 +27 -0
- package/src/lib/refine-chain.test.ts +764 -0
- package/src/lib/refine-chain.ts +583 -0
- package/src/lib/refine-traits.test.ts +141 -0
- package/src/lib/refine-traits.ts +128 -0
- package/src/lib/refine.ts +287 -0
- package/src/lib/sms-providers-from-env.ts +11 -11
- package/src/lib/webhook-catalog-sync.test.ts +112 -0
- package/src/lib/webhook-signing.ts +5 -1
- package/src/routes/admin/contacts.ts +113 -13
- package/src/workflows/bucket-backfill.ts +14 -0
- package/src/workflows/bucket-reconcile.ts +74 -15
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,10 +1,32 @@
|
|
|
1
1
|
import assert from "node:assert/strict";
|
|
2
2
|
import test from "node:test";
|
|
3
|
+
import type { Database } from "@hogsend/db";
|
|
4
|
+
import {
|
|
5
|
+
ConnectorActionRegistry,
|
|
6
|
+
resetConnectorActionRegistry,
|
|
7
|
+
setConnectorActionRegistry,
|
|
8
|
+
} from "../connectors/action-registry-singleton.js";
|
|
9
|
+
import type {
|
|
10
|
+
DefinedConnectorAction,
|
|
11
|
+
ResolvedActionContact,
|
|
12
|
+
} from "../connectors/define-action.js";
|
|
3
13
|
import {
|
|
4
14
|
type JourneyBoundary,
|
|
5
15
|
runWithJourneyBoundary,
|
|
6
16
|
} from "../journeys/journey-boundary.js";
|
|
7
|
-
import {
|
|
17
|
+
import {
|
|
18
|
+
type ColdPosture,
|
|
19
|
+
defineContactSource,
|
|
20
|
+
} from "../sources/define-contact-source.js";
|
|
21
|
+
import {
|
|
22
|
+
buildContactSourceRegistry,
|
|
23
|
+
ContactSourceRegistry,
|
|
24
|
+
setContactSourceRegistry,
|
|
25
|
+
} from "../sources/registry.js";
|
|
26
|
+
import {
|
|
27
|
+
checkActionAudience,
|
|
28
|
+
sendConnectorAction,
|
|
29
|
+
} from "./connector-actions.js";
|
|
8
30
|
|
|
9
31
|
test("a scoped connector override requires registration validation before capture", async () => {
|
|
10
32
|
let captures = 0;
|
|
@@ -34,3 +56,272 @@ test("a scoped connector override requires registration validation before captur
|
|
|
34
56
|
);
|
|
35
57
|
assert.equal(captures, 0);
|
|
36
58
|
});
|
|
59
|
+
|
|
60
|
+
// ---------------------------------------------------------------------------
|
|
61
|
+
// Cold-channel gate (PRD 05). The engine suite is pure/unit (no DB), so these
|
|
62
|
+
// drive `checkActionAudience` directly with a fake preference DB + a fake
|
|
63
|
+
// contact resolver; `sendConnectorAction` end-to-end coverage is limited to the
|
|
64
|
+
// paths that touch no DB (the no-audience ops action). The gate's placement
|
|
65
|
+
// inside the durable memo closure is structural (it runs from `gate()` inside
|
|
66
|
+
// `boundary.memoize`) and is not re-derived here.
|
|
67
|
+
// ---------------------------------------------------------------------------
|
|
68
|
+
|
|
69
|
+
/** Fake `Database` serving `readRecipientPreferences` an empty result set. */
|
|
70
|
+
function fakePrefDb(rows: unknown[] = []): Database {
|
|
71
|
+
return {
|
|
72
|
+
select: () => ({
|
|
73
|
+
from: () => ({
|
|
74
|
+
where: () => Promise.resolve(rows),
|
|
75
|
+
}),
|
|
76
|
+
}),
|
|
77
|
+
} as unknown as Database;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
function prospect(source: string | null): ResolvedActionContact {
|
|
81
|
+
return {
|
|
82
|
+
id: "11111111-1111-1111-1111-111111111111",
|
|
83
|
+
email: "prospect@example.com",
|
|
84
|
+
discordId: null,
|
|
85
|
+
externalId: null,
|
|
86
|
+
source,
|
|
87
|
+
properties: {},
|
|
88
|
+
};
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** A member-directed DM action whose `run` counts invocations. */
|
|
92
|
+
function memberAction(counter: { runs: number }): DefinedConnectorAction {
|
|
93
|
+
return {
|
|
94
|
+
connectorId: "discord",
|
|
95
|
+
name: "dmMember",
|
|
96
|
+
audience: {
|
|
97
|
+
kind: "member",
|
|
98
|
+
ref: (args) => (args as { ref: string }).ref,
|
|
99
|
+
},
|
|
100
|
+
run: async () => {
|
|
101
|
+
counter.runs += 1;
|
|
102
|
+
return { delivered: true };
|
|
103
|
+
},
|
|
104
|
+
};
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function claySource(coldPosture?: ColdPosture) {
|
|
108
|
+
return defineContactSource({
|
|
109
|
+
meta: { id: "clay", name: "Clay" },
|
|
110
|
+
auth: { type: "match", header: "x-clay-secret", envKey: "CLAY_SECRET" },
|
|
111
|
+
transform: async () => null,
|
|
112
|
+
...(coldPosture ? { coldPosture } : {}),
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** Install a registry for the test, restoring an empty one afterwards. */
|
|
117
|
+
function withSources<T>(
|
|
118
|
+
sources: ReturnType<typeof claySource>[],
|
|
119
|
+
fn: () => Promise<T>,
|
|
120
|
+
): Promise<T> {
|
|
121
|
+
buildContactSourceRegistry(sources);
|
|
122
|
+
return fn().finally(() => {
|
|
123
|
+
setContactSourceRegistry(new ContactSourceRegistry());
|
|
124
|
+
});
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** Capture stdout (winston Console transport) around `fn`. */
|
|
128
|
+
async function captureStdout<T>(
|
|
129
|
+
fn: () => Promise<T>,
|
|
130
|
+
): Promise<{ result: T; output: string }> {
|
|
131
|
+
const chunks: string[] = [];
|
|
132
|
+
const original = process.stdout.write.bind(process.stdout);
|
|
133
|
+
// biome-ignore lint/suspicious/noExplicitAny: stdout.write overload capture
|
|
134
|
+
(process.stdout as any).write = (chunk: any, ...rest: any[]) => {
|
|
135
|
+
chunks.push(String(chunk));
|
|
136
|
+
return original(chunk, ...rest);
|
|
137
|
+
};
|
|
138
|
+
try {
|
|
139
|
+
const result = await fn();
|
|
140
|
+
// Let winston's stream pipeline flush before restoring.
|
|
141
|
+
await new Promise((resolve) => setImmediate(resolve));
|
|
142
|
+
return { result, output: chunks.join("") };
|
|
143
|
+
} finally {
|
|
144
|
+
// biome-ignore lint/suspicious/noExplicitAny: restore the original writer
|
|
145
|
+
(process.stdout as any).write = original;
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
test("AC1: a prospect from a registered source is blocked on a channel the posture blocks", async () => {
|
|
150
|
+
await withSources([claySource()], async () => {
|
|
151
|
+
const counter = { runs: 0 };
|
|
152
|
+
const action = memberAction(counter);
|
|
153
|
+
const verdict = await checkActionAudience(
|
|
154
|
+
fakePrefDb(),
|
|
155
|
+
async () => prospect("clay"),
|
|
156
|
+
action,
|
|
157
|
+
"discord",
|
|
158
|
+
"dmMember",
|
|
159
|
+
{ ref: "prospect@example.com" },
|
|
160
|
+
);
|
|
161
|
+
assert.deepEqual(verdict, {
|
|
162
|
+
skipped: true,
|
|
163
|
+
reason: "cold_channel_blocked",
|
|
164
|
+
connectorId: "discord",
|
|
165
|
+
action: "dmMember",
|
|
166
|
+
});
|
|
167
|
+
// The connector's run was never invoked by the gate.
|
|
168
|
+
assert.equal(counter.runs, 0);
|
|
169
|
+
});
|
|
170
|
+
});
|
|
171
|
+
|
|
172
|
+
test("AC2: the same prospect is allowed on a channel the posture explicitly allows", async () => {
|
|
173
|
+
await withSources([claySource({ discord: "allow" })], async () => {
|
|
174
|
+
const verdict = await checkActionAudience(
|
|
175
|
+
fakePrefDb(),
|
|
176
|
+
async () => prospect("clay"),
|
|
177
|
+
memberAction({ runs: 0 }),
|
|
178
|
+
"discord",
|
|
179
|
+
"dmMember",
|
|
180
|
+
{ ref: "prospect@example.com" },
|
|
181
|
+
);
|
|
182
|
+
assert.equal(verdict, null);
|
|
183
|
+
});
|
|
184
|
+
});
|
|
185
|
+
|
|
186
|
+
test("AC3: a contact with a null source is not a prospect and proceeds", async () => {
|
|
187
|
+
await withSources([claySource()], async () => {
|
|
188
|
+
const verdict = await checkActionAudience(
|
|
189
|
+
fakePrefDb(),
|
|
190
|
+
async () => prospect(null),
|
|
191
|
+
memberAction({ runs: 0 }),
|
|
192
|
+
"discord",
|
|
193
|
+
"dmMember",
|
|
194
|
+
{ ref: "prospect@example.com" },
|
|
195
|
+
);
|
|
196
|
+
assert.equal(verdict, null);
|
|
197
|
+
});
|
|
198
|
+
});
|
|
199
|
+
|
|
200
|
+
test("AC4: a source not in the registry is not a prospect and proceeds", async () => {
|
|
201
|
+
await withSources([claySource()], async () => {
|
|
202
|
+
const verdict = await checkActionAudience(
|
|
203
|
+
fakePrefDb(),
|
|
204
|
+
async () => prospect("api"),
|
|
205
|
+
memberAction({ runs: 0 }),
|
|
206
|
+
"discord",
|
|
207
|
+
"dmMember",
|
|
208
|
+
{ ref: "prospect@example.com" },
|
|
209
|
+
);
|
|
210
|
+
assert.equal(verdict, null);
|
|
211
|
+
});
|
|
212
|
+
});
|
|
213
|
+
|
|
214
|
+
test("AC5: an unresolvable contact fails open (allowed, unchanged)", async () => {
|
|
215
|
+
await withSources([claySource()], async () => {
|
|
216
|
+
const verdict = await checkActionAudience(
|
|
217
|
+
fakePrefDb(),
|
|
218
|
+
async () => null,
|
|
219
|
+
memberAction({ runs: 0 }),
|
|
220
|
+
"discord",
|
|
221
|
+
"dmMember",
|
|
222
|
+
{ ref: "nobody@example.com" },
|
|
223
|
+
);
|
|
224
|
+
assert.equal(verdict, null);
|
|
225
|
+
});
|
|
226
|
+
});
|
|
227
|
+
|
|
228
|
+
test("AC6: an ops action (no audience) is never gated — even with prospect sources registered", async () => {
|
|
229
|
+
await withSources([claySource()], async () => {
|
|
230
|
+
// Direct: the gate returns null WITHOUT consulting the resolver.
|
|
231
|
+
let resolves = 0;
|
|
232
|
+
const opsAction: DefinedConnectorAction = {
|
|
233
|
+
connectorId: "discord",
|
|
234
|
+
name: "sendChannelMessage",
|
|
235
|
+
run: async () => ({ messageId: "m1" }),
|
|
236
|
+
};
|
|
237
|
+
const verdict = await checkActionAudience(
|
|
238
|
+
fakePrefDb(),
|
|
239
|
+
async () => {
|
|
240
|
+
resolves += 1;
|
|
241
|
+
return prospect("clay");
|
|
242
|
+
},
|
|
243
|
+
opsAction,
|
|
244
|
+
"discord",
|
|
245
|
+
"sendChannelMessage",
|
|
246
|
+
{ channelId: "c1" },
|
|
247
|
+
);
|
|
248
|
+
assert.equal(verdict, null);
|
|
249
|
+
assert.equal(resolves, 0);
|
|
250
|
+
|
|
251
|
+
// End-to-end: sendConnectorAction runs the ops action to completion. This
|
|
252
|
+
// path touches no DB (the lazy postgres client never issues a query).
|
|
253
|
+
process.env.DATABASE_URL ??=
|
|
254
|
+
"postgresql://never:connects@localhost:9/never";
|
|
255
|
+
let runs = 0;
|
|
256
|
+
setConnectorActionRegistry(
|
|
257
|
+
new ConnectorActionRegistry([
|
|
258
|
+
{
|
|
259
|
+
connectorId: "discord",
|
|
260
|
+
name: "opsAlert",
|
|
261
|
+
run: async () => {
|
|
262
|
+
runs += 1;
|
|
263
|
+
return { delivered: true };
|
|
264
|
+
},
|
|
265
|
+
},
|
|
266
|
+
]),
|
|
267
|
+
);
|
|
268
|
+
try {
|
|
269
|
+
const result = await sendConnectorAction({
|
|
270
|
+
connectorId: "discord",
|
|
271
|
+
action: "opsAlert",
|
|
272
|
+
args: { channelId: "c1" },
|
|
273
|
+
});
|
|
274
|
+
assert.deepEqual(result, { delivered: true });
|
|
275
|
+
assert.equal(runs, 1);
|
|
276
|
+
} finally {
|
|
277
|
+
resetConnectorActionRegistry();
|
|
278
|
+
}
|
|
279
|
+
});
|
|
280
|
+
});
|
|
281
|
+
|
|
282
|
+
test("AC7: a cold skip logs once at info with the source id and blocked channel", async () => {
|
|
283
|
+
await withSources([claySource()], async () => {
|
|
284
|
+
const { result, output } = await captureStdout(() =>
|
|
285
|
+
checkActionAudience(
|
|
286
|
+
fakePrefDb(),
|
|
287
|
+
async () => prospect("clay"),
|
|
288
|
+
memberAction({ runs: 0 }),
|
|
289
|
+
"discord",
|
|
290
|
+
"dmMember",
|
|
291
|
+
{ ref: "prospect@example.com" },
|
|
292
|
+
),
|
|
293
|
+
);
|
|
294
|
+
assert.equal(
|
|
295
|
+
(result as { reason?: string } | null)?.reason,
|
|
296
|
+
"cold_channel_blocked",
|
|
297
|
+
);
|
|
298
|
+
const lines = output
|
|
299
|
+
.split("\n")
|
|
300
|
+
.filter((line) => line.includes("cold channel blocked"));
|
|
301
|
+
assert.equal(lines.length, 1, `expected exactly one log line:\n${output}`);
|
|
302
|
+
assert.match(lines[0] as string, /"clay"/);
|
|
303
|
+
assert.match(lines[0] as string, /"discord"/);
|
|
304
|
+
});
|
|
305
|
+
});
|
|
306
|
+
|
|
307
|
+
test("a throwing cold-posture lookup fails open (allowed)", async () => {
|
|
308
|
+
const throwing = new (class extends ContactSourceRegistry {
|
|
309
|
+
override isProspectSource(): boolean {
|
|
310
|
+
throw new Error("registry exploded");
|
|
311
|
+
}
|
|
312
|
+
})();
|
|
313
|
+
setContactSourceRegistry(throwing);
|
|
314
|
+
try {
|
|
315
|
+
const verdict = await checkActionAudience(
|
|
316
|
+
fakePrefDb(),
|
|
317
|
+
async () => prospect("clay"),
|
|
318
|
+
memberAction({ runs: 0 }),
|
|
319
|
+
"discord",
|
|
320
|
+
"dmMember",
|
|
321
|
+
{ ref: "prospect@example.com" },
|
|
322
|
+
);
|
|
323
|
+
assert.equal(verdict, null);
|
|
324
|
+
} finally {
|
|
325
|
+
setContactSourceRegistry(new ContactSourceRegistry());
|
|
326
|
+
}
|
|
327
|
+
});
|
|
@@ -12,6 +12,11 @@ import {
|
|
|
12
12
|
registerKey,
|
|
13
13
|
} from "../journeys/journey-boundary.js";
|
|
14
14
|
import { getListRegistry } from "../lists/registry-singleton.js";
|
|
15
|
+
import {
|
|
16
|
+
defaultColdPosture,
|
|
17
|
+
isColdChannelAllowed,
|
|
18
|
+
} from "../sources/define-contact-source.js";
|
|
19
|
+
import { getContactSourceRegistry } from "../sources/registry.js";
|
|
15
20
|
import { getDb } from "./db.js";
|
|
16
21
|
import { createLogger } from "./logger.js";
|
|
17
22
|
import { readRecipientPreferences } from "./recipient-preferences.js";
|
|
@@ -83,6 +88,7 @@ async function resolveContact(
|
|
|
83
88
|
email: contacts.email,
|
|
84
89
|
discordId: contacts.discordId,
|
|
85
90
|
externalId: contacts.externalId,
|
|
91
|
+
source: contacts.source,
|
|
86
92
|
properties: contacts.properties,
|
|
87
93
|
})
|
|
88
94
|
.from(contacts)
|
|
@@ -107,6 +113,7 @@ async function resolveContact(
|
|
|
107
113
|
email: row.email ?? null,
|
|
108
114
|
discordId: row.discordId ?? null,
|
|
109
115
|
externalId: row.externalId ?? null,
|
|
116
|
+
source: row.source ?? null,
|
|
110
117
|
properties: (row.properties ?? {}) as Record<string, unknown>,
|
|
111
118
|
};
|
|
112
119
|
}
|
|
@@ -127,6 +134,12 @@ async function resolveContact(
|
|
|
127
134
|
* wins. A candidate that resolves NO contact (a raw snowflake, a group-chat
|
|
128
135
|
* id, an unlinked ref) means there is NO preference surface to consult — the
|
|
129
136
|
* send is ALLOWED (null). Only once a contact is resolved do preferences gate.
|
|
137
|
+
* - On a resolved contact the COLD-CHANNEL GATE runs first: when the
|
|
138
|
+
* contact's `source` names a registered Contact Source (⇒ a cold prospect),
|
|
139
|
+
* the source's resolved {@link ColdPosture} must allow this connector's
|
|
140
|
+
* channel or the action skips with `cold_channel_blocked` (logged once at
|
|
141
|
+
* info with the source id + blocked channel). Null/unregistered `source` ⇒
|
|
142
|
+
* not a prospect ⇒ unaffected; a throwing posture lookup fails OPEN.
|
|
130
143
|
* - On a resolved contact we read the aggregated {@link readRecipientPreferences}
|
|
131
144
|
* keyed by its email + `externalId ?? id` (the SAME key form preference writes
|
|
132
145
|
* use), then: `unsubscribedAll` → skip `unsubscribed_all`; else channel
|
|
@@ -135,8 +148,13 @@ async function resolveContact(
|
|
|
135
148
|
*
|
|
136
149
|
* Deliberately does NOT consume `prefs.suppressed` — that is an email-transport
|
|
137
150
|
* hard-bounce/complaint signal, irrelevant to a chat channel.
|
|
151
|
+
*
|
|
152
|
+
* Exported ONLY for unit tests (the engine suite is pure/unit and cannot drive
|
|
153
|
+
* the DB-backed `sendConnectorAction` path) — production callers go through
|
|
154
|
+
* {@link sendConnectorAction}, which runs this gate INSIDE the durable memo
|
|
155
|
+
* closure so the verdict replays verbatim.
|
|
138
156
|
*/
|
|
139
|
-
async function checkActionAudience(
|
|
157
|
+
export async function checkActionAudience(
|
|
140
158
|
db: Database,
|
|
141
159
|
resolveCachedContact: (ref: string) => Promise<ResolvedActionContact | null>,
|
|
142
160
|
action: DefinedConnectorAction,
|
|
@@ -170,6 +188,42 @@ async function checkActionAudience(
|
|
|
170
188
|
// fully-unresolved recipient (raw id / group chat) falls through to allow.
|
|
171
189
|
if (!contact) continue;
|
|
172
190
|
|
|
191
|
+
// COLD-CHANNEL GATE (PRD 05): a contact whose `source` names a registered
|
|
192
|
+
// Contact Source is a cold prospect; its source's resolved posture decides
|
|
193
|
+
// which channels may reach it before consent (default: email only). The
|
|
194
|
+
// connector's id IS the channel id. Checked BEFORE the preference read so a
|
|
195
|
+
// blocked prospect costs no extra round-trip. A null/unregistered `source`
|
|
196
|
+
// is not a prospect and is unaffected; a THROWING posture lookup fails
|
|
197
|
+
// OPEN (warn + fall through), matching this gate's failure posture.
|
|
198
|
+
try {
|
|
199
|
+
const sources = getContactSourceRegistry();
|
|
200
|
+
if (sources.isProspectSource(contact.source)) {
|
|
201
|
+
const posture =
|
|
202
|
+
sources.get(contact.source as string)?.coldPosture ??
|
|
203
|
+
defaultColdPosture();
|
|
204
|
+
if (!isColdChannelAllowed(posture, connectorId)) {
|
|
205
|
+
logger.info("connector action skipped: cold channel blocked", {
|
|
206
|
+
connectorId,
|
|
207
|
+
action: actionName,
|
|
208
|
+
source: contact.source,
|
|
209
|
+
channel: connectorId,
|
|
210
|
+
});
|
|
211
|
+
return {
|
|
212
|
+
skipped: true,
|
|
213
|
+
reason: "cold_channel_blocked",
|
|
214
|
+
connectorId,
|
|
215
|
+
action: actionName,
|
|
216
|
+
};
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
} catch (error) {
|
|
220
|
+
logger.warn("cold-channel gate threw; sending anyway", {
|
|
221
|
+
connectorId,
|
|
222
|
+
action: actionName,
|
|
223
|
+
error: error instanceof Error ? error.message : String(error),
|
|
224
|
+
});
|
|
225
|
+
}
|
|
226
|
+
|
|
173
227
|
const prefs = await readRecipientPreferences(db, {
|
|
174
228
|
email: contact.email,
|
|
175
229
|
userId: contact.externalId ?? contact.id,
|
|
@@ -327,11 +381,16 @@ export async function sendConnectorAction(
|
|
|
327
381
|
input.args,
|
|
328
382
|
);
|
|
329
383
|
if (skip) {
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
384
|
+
// A cold-channel skip already logged once (with the source id + blocked
|
|
385
|
+
// channel) inside checkActionAudience — don't log it a second time under
|
|
386
|
+
// the misleading "recipient preferences" banner.
|
|
387
|
+
if (skip.reason !== "cold_channel_blocked") {
|
|
388
|
+
logger.info("connector action skipped: recipient preferences", {
|
|
389
|
+
connectorId: input.connectorId,
|
|
390
|
+
action: input.action,
|
|
391
|
+
reason: skip.reason,
|
|
392
|
+
});
|
|
393
|
+
}
|
|
335
394
|
return skip;
|
|
336
395
|
}
|
|
337
396
|
return run();
|
|
@@ -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
|
/**
|