@hogsend/engine 0.62.0 → 0.64.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 +13 -12
- package/src/env.ts +23 -0
- package/src/index.ts +17 -0
- package/src/journeys/journey-boundary.ts +8 -0
- package/src/lib/attachments.ts +81 -0
- package/src/lib/domain-status.return-path.test.ts +68 -0
- package/src/lib/domain-status.ts +19 -0
- package/src/lib/email-provider-boot.hogsend.test.ts +48 -0
- package/src/lib/email-provider-boot.test.ts +33 -0
- package/src/lib/email-providers-from-env.hogsend.test.ts +110 -0
- package/src/lib/email-providers-from-env.test.ts +52 -0
- package/src/lib/email-providers-from-env.ts +67 -0
- package/src/lib/email-service-types.ts +11 -0
- package/src/lib/email.ts +17 -0
- package/src/lib/mailer-bounce-idempotency.test.ts +469 -0
- package/src/lib/mailer-rejected.test.ts +229 -0
- package/src/lib/mailer-replied.test.ts +379 -0
- package/src/lib/mailer.ts +359 -24
- package/src/lib/outbound.ts +35 -0
- package/src/lib/sending-domain-guidance.test.ts +99 -0
- package/src/lib/sending-domain-guidance.ts +84 -0
- package/src/lib/tracked-attachments.test.ts +376 -0
- package/src/lib/tracked-idempotency-header.test.ts +437 -0
- package/src/lib/tracked.ts +116 -4
- package/src/lib/tracking-event-names.ts +9 -0
- package/src/lib/webhook-signing.ts +7 -0
- package/src/routes/admin/domain-conflict.test.ts +188 -0
- package/src/routes/admin/domain-return-path.test.ts +274 -0
- package/src/routes/admin/domain.ts +214 -1
|
@@ -0,0 +1,437 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
import type {
|
|
4
|
+
EmailEvent,
|
|
5
|
+
EmailProvider,
|
|
6
|
+
EmailProviderCapabilities,
|
|
7
|
+
SendEmailOptions,
|
|
8
|
+
} from "@hogsend/core";
|
|
9
|
+
import { EmailAction, type TemplateRegistry } from "@hogsend/email";
|
|
10
|
+
|
|
11
|
+
// The engine's env contract is validated at module scope (lib/hatchet.ts pulls
|
|
12
|
+
// env.ts in through lib/tracked.ts), so these must be in place BEFORE the
|
|
13
|
+
// dynamic import below. Nothing here reaches the network: the db is a fake, the
|
|
14
|
+
// provider is a fake, and Hatchet is only constructed, never called.
|
|
15
|
+
process.env.NODE_ENV ??= "test";
|
|
16
|
+
process.env.LOG_LEVEL ??= "error";
|
|
17
|
+
process.env.DATABASE_URL ??= "postgresql://test:test@localhost:5432/test";
|
|
18
|
+
process.env.BETTER_AUTH_SECRET ??=
|
|
19
|
+
"test-secret-for-node-test-minimum-32-characters-long";
|
|
20
|
+
// A structurally-valid but inert Hatchet token (the same fixture apps/api's
|
|
21
|
+
// vitest config uses). The client is constructed at import; it never dials.
|
|
22
|
+
process.env.HATCHET_CLIENT_TOKEN ??=
|
|
23
|
+
"eyJhbGciOiJFUzI1NiIsImtpZCI6InRlc3QifQ.eyJhdWQiOiJsb2NhbGhvc3QiLCJleHAiOjQ5MzMyNDA5ODMsImdycGNfYnJvYWRjYXN0X2FkZHJlc3MiOiJsb2NhbGhvc3Q6NzA3NyIsImlhdCI6MTc3OTY0MDk4MywiaXNzIjoibG9jYWxob3N0Iiwic2VydmVyX3VybCI6ImxvY2FsaG9zdCIsInN1YiI6InRlc3QtdGVuYW50LWlkIiwidG9rZW5faWQiOiJ0ZXN0LXRva2VuLWlkIn0.test";
|
|
24
|
+
|
|
25
|
+
const { sendTrackedEmail } = await import("./tracked.js");
|
|
26
|
+
const { createRecordingBoundary } = await import(
|
|
27
|
+
"../journeys/durable-law-harness.js"
|
|
28
|
+
);
|
|
29
|
+
const { deriveJourneyKey, runWithJourneyBoundary } = await import(
|
|
30
|
+
"../journeys/journey-boundary.js"
|
|
31
|
+
);
|
|
32
|
+
|
|
33
|
+
const TEMPLATE = "welcome" as never;
|
|
34
|
+
const EMAIL_SEND_ID = "es_00000000-0000-4000-8000-000000000001";
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* The registry the mailer renders through. `EmailAction` is imported rather than
|
|
38
|
+
* a hand-written component so the element is built by the SAME React copy
|
|
39
|
+
* `renderToHtml` renders with (the engine itself has no `react` dependency —
|
|
40
|
+
* it is the consumer's peer).
|
|
41
|
+
*/
|
|
42
|
+
const registry = {
|
|
43
|
+
welcome: {
|
|
44
|
+
component: () =>
|
|
45
|
+
EmailAction({
|
|
46
|
+
href: "https://example.com/welcome",
|
|
47
|
+
event: "welcome.clicked",
|
|
48
|
+
children: "Get started",
|
|
49
|
+
}),
|
|
50
|
+
defaultSubject: "Welcome",
|
|
51
|
+
},
|
|
52
|
+
} as unknown as TemplateRegistry;
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* A minimal chainable fake `db`. The tracked mailer's DB path here is: the
|
|
56
|
+
* idempotency short-circuit SELECT (no prior row), the `email_sends` INSERT, and
|
|
57
|
+
* the sent-status UPDATE. The fire-and-forget `emitOutbound` awaits its endpoint
|
|
58
|
+
* SELECT directly (no `.limit()`), so the chain is thenable as well as
|
|
59
|
+
* chainable, and resolves to zero endpoints — no outbound work, no network.
|
|
60
|
+
*/
|
|
61
|
+
function makeFakeDb() {
|
|
62
|
+
const inserted: Array<Record<string, unknown>> = [];
|
|
63
|
+
const chain = (result: unknown[]): Record<string, unknown> => {
|
|
64
|
+
const self: Record<string, unknown> = {
|
|
65
|
+
from: () => self,
|
|
66
|
+
leftJoin: () => self,
|
|
67
|
+
where: () => self,
|
|
68
|
+
orderBy: () => self,
|
|
69
|
+
limit: () => Promise.resolve(result),
|
|
70
|
+
// A drizzle query builder IS thenable: `await db.select().from(t).where(c)`
|
|
71
|
+
// with no terminal call is exactly the shape emitOutbound uses, so the
|
|
72
|
+
// fake has to be thenable to model it.
|
|
73
|
+
// biome-ignore lint/suspicious/noThenProperty: modelling a drizzle builder
|
|
74
|
+
then: (resolve: (rows: unknown[]) => void) => resolve(result),
|
|
75
|
+
};
|
|
76
|
+
return self;
|
|
77
|
+
};
|
|
78
|
+
const returning = () => Promise.resolve([{ id: EMAIL_SEND_ID }]);
|
|
79
|
+
const db = {
|
|
80
|
+
select: () => chain([]),
|
|
81
|
+
insert: () => ({
|
|
82
|
+
values: (values: Record<string, unknown>) => {
|
|
83
|
+
inserted.push(values);
|
|
84
|
+
return {
|
|
85
|
+
onConflictDoNothing: () => ({ returning }),
|
|
86
|
+
returning,
|
|
87
|
+
};
|
|
88
|
+
},
|
|
89
|
+
}),
|
|
90
|
+
update: () => ({
|
|
91
|
+
set: () => ({ where: () => Promise.resolve() }),
|
|
92
|
+
}),
|
|
93
|
+
};
|
|
94
|
+
return { db: db as never, inserted };
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* A fake provider that only records what it was handed.
|
|
99
|
+
*
|
|
100
|
+
* `capabilities` is what decides whether the wire gets the key, NEVER the id —
|
|
101
|
+
* so the fake takes the two independently and every test states both. The
|
|
102
|
+
* default is the consuming posture (`consumesIdempotencyKey: true`); pass
|
|
103
|
+
* `capabilities: {}` to model a header-forwarding transport (Resend, Postmark)
|
|
104
|
+
* that must never be handed an internal key.
|
|
105
|
+
*/
|
|
106
|
+
function makeFakeProvider(
|
|
107
|
+
over: { id?: string; capabilities?: EmailProviderCapabilities } = {},
|
|
108
|
+
) {
|
|
109
|
+
const id = over.id ?? "hogsend";
|
|
110
|
+
// `in`, not a destructuring default: an EXPLICIT `capabilities: undefined`
|
|
111
|
+
// models the pre-registry provider shape (the field is optional on the
|
|
112
|
+
// contract) and must NOT silently fall back to the consuming default.
|
|
113
|
+
const capabilities =
|
|
114
|
+
"capabilities" in over
|
|
115
|
+
? over.capabilities
|
|
116
|
+
: { consumesIdempotencyKey: true };
|
|
117
|
+
const sends: SendEmailOptions[] = [];
|
|
118
|
+
const provider = {
|
|
119
|
+
meta: { id, name: "Fake" },
|
|
120
|
+
capabilities,
|
|
121
|
+
send: async (options: SendEmailOptions) => {
|
|
122
|
+
sends.push(options);
|
|
123
|
+
return { id: "msg_fake_1" };
|
|
124
|
+
},
|
|
125
|
+
sendBatch: async () => ({ results: [] }),
|
|
126
|
+
verifyWebhook: (): EmailEvent => {
|
|
127
|
+
throw new Error("not used");
|
|
128
|
+
},
|
|
129
|
+
parseWebhook: (): EmailEvent => {
|
|
130
|
+
throw new Error("not used");
|
|
131
|
+
},
|
|
132
|
+
} as unknown as EmailProvider;
|
|
133
|
+
return { provider, sends };
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
function baseOptions(over: Record<string, unknown> = {}) {
|
|
137
|
+
return {
|
|
138
|
+
templateKey: TEMPLATE,
|
|
139
|
+
props: {} as never,
|
|
140
|
+
from: "Hogsend <noreply@example.com>",
|
|
141
|
+
to: "user@example.com",
|
|
142
|
+
// Skips suppression / control group / frequency cap / journey suppress, all
|
|
143
|
+
// of which would need far more DB shape than this fake carries and none of
|
|
144
|
+
// which this test is about.
|
|
145
|
+
skipPreferenceCheck: true,
|
|
146
|
+
...over,
|
|
147
|
+
};
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* EVERY case-insensitive match, not the first. HTTP header names are
|
|
152
|
+
* case-insensitive, so `Idempotency-Key` and `idempotency-key` on one message
|
|
153
|
+
* are the SAME header twice — and the plugin's own reader takes the last one it
|
|
154
|
+
* walks. A "first match" lookup would let a duplicate-under-different-casing bug
|
|
155
|
+
* pass this suite while shipping the wrong key on the wire.
|
|
156
|
+
*/
|
|
157
|
+
function headerValues(
|
|
158
|
+
headers: Record<string, string> | undefined,
|
|
159
|
+
name: string,
|
|
160
|
+
): string[] {
|
|
161
|
+
const lower = name.toLowerCase();
|
|
162
|
+
return Object.entries(headers ?? {})
|
|
163
|
+
.filter(([key]) => key.toLowerCase() === lower)
|
|
164
|
+
.map(([, value]) => value);
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
function headerValue(
|
|
168
|
+
headers: Record<string, string> | undefined,
|
|
169
|
+
name: string,
|
|
170
|
+
): string | undefined {
|
|
171
|
+
const values = headerValues(headers, name);
|
|
172
|
+
assert.ok(
|
|
173
|
+
values.length <= 1,
|
|
174
|
+
`expected at most one "${name}" header, got ${values.length}: ${values.join(", ")}`,
|
|
175
|
+
);
|
|
176
|
+
return values[0];
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
test("PRD 10 T4b: the derived replay-stable key reaches provider.send as Idempotency-Key", async () => {
|
|
180
|
+
// THE test this task exists for. `@hogsend/plugin-hogsend` falls back to
|
|
181
|
+
// hashing the message bytes when handed no key, and that fallback cannot
|
|
182
|
+
// protect a crash replay: `prepareTrackedHtml` mints fresh `tracked_links` ids
|
|
183
|
+
// and an open pixel carrying the send id on every attempt, so the same logical
|
|
184
|
+
// send hashes differently each time. The relay's exactly-once guard is only as
|
|
185
|
+
// good as the key it is handed — without this header a journey replayed after
|
|
186
|
+
// a worker crash sends twice.
|
|
187
|
+
const { db, inserted } = makeFakeDb();
|
|
188
|
+
const { provider, sends } = makeFakeProvider();
|
|
189
|
+
const { boundary } = createRecordingBoundary({
|
|
190
|
+
runAnchor: "run-abc",
|
|
191
|
+
currentLabel: "wait-for-activation",
|
|
192
|
+
});
|
|
193
|
+
|
|
194
|
+
await runWithJourneyBoundary(boundary, () =>
|
|
195
|
+
sendTrackedEmail({
|
|
196
|
+
db,
|
|
197
|
+
provider,
|
|
198
|
+
registry,
|
|
199
|
+
options: baseOptions({ headers: { "X-Campaign": "spring" } }),
|
|
200
|
+
}),
|
|
201
|
+
);
|
|
202
|
+
|
|
203
|
+
const expected = deriveJourneyKey({
|
|
204
|
+
kind: "send",
|
|
205
|
+
anchor: "run-abc",
|
|
206
|
+
site: "wait-for-activation",
|
|
207
|
+
discriminant: "welcome",
|
|
208
|
+
});
|
|
209
|
+
assert.equal(sends.length, 1);
|
|
210
|
+
assert.equal(headerValue(sends[0]?.headers, "Idempotency-Key"), expected);
|
|
211
|
+
// The SAME key on the wire as in the `email_sends` row. One key, both dedup
|
|
212
|
+
// layers: if these ever diverge the relay is guarding a different send than
|
|
213
|
+
// the database is, and a replay slips through whichever layer missed.
|
|
214
|
+
assert.equal(inserted[0]?.idempotencyKey, expected);
|
|
215
|
+
// The key is an ADDITION to the wire, not a replacement for it: caller headers
|
|
216
|
+
// still travel alongside it.
|
|
217
|
+
assert.equal(sends[0]?.headers?.["X-Campaign"], "spring");
|
|
218
|
+
});
|
|
219
|
+
|
|
220
|
+
for (const id of ["resend", "postmark"]) {
|
|
221
|
+
test(`a header-forwarding provider (${id}) NEVER receives the auto-threaded key`, async () => {
|
|
222
|
+
// Resend and Postmark forward `SendEmailOptions.headers` verbatim onto the
|
|
223
|
+
// DELIVERED message, so threading the engine's key to them would stamp
|
|
224
|
+
// internal identifiers — Hatchet run ids + wait labels on journey sends, the
|
|
225
|
+
// recipient's own address on campaign sends — onto every outbound email of
|
|
226
|
+
// every existing deploy. Neither declares `consumesIdempotencyKey`, and
|
|
227
|
+
// ABSENCE IS NOT CONSENT: the gate strips the key from the WIRE only, so the
|
|
228
|
+
// `email_sends` row still records it and the DB dedup layer is intact.
|
|
229
|
+
const { db, inserted } = makeFakeDb();
|
|
230
|
+
const { provider, sends } = makeFakeProvider({ id, capabilities: {} });
|
|
231
|
+
const { boundary } = createRecordingBoundary({
|
|
232
|
+
runAnchor: "run-abc",
|
|
233
|
+
currentLabel: "wait-for-activation",
|
|
234
|
+
});
|
|
235
|
+
|
|
236
|
+
await runWithJourneyBoundary(boundary, () =>
|
|
237
|
+
sendTrackedEmail({
|
|
238
|
+
db,
|
|
239
|
+
provider,
|
|
240
|
+
registry,
|
|
241
|
+
options: baseOptions({ headers: { "X-Campaign": "spring" } }),
|
|
242
|
+
}),
|
|
243
|
+
);
|
|
244
|
+
|
|
245
|
+
assert.equal(sends.length, 1);
|
|
246
|
+
assert.equal(headerValue(sends[0]?.headers, "Idempotency-Key"), undefined);
|
|
247
|
+
// Layer 2 is unconditional: the row carries the derived key even though the
|
|
248
|
+
// wire does not.
|
|
249
|
+
assert.equal(
|
|
250
|
+
inserted[0]?.idempotencyKey,
|
|
251
|
+
deriveJourneyKey({
|
|
252
|
+
kind: "send",
|
|
253
|
+
anchor: "run-abc",
|
|
254
|
+
site: "wait-for-activation",
|
|
255
|
+
discriminant: "welcome",
|
|
256
|
+
}),
|
|
257
|
+
);
|
|
258
|
+
// Caller headers still travel untouched.
|
|
259
|
+
assert.equal(sends[0]?.headers?.["X-Campaign"], "spring");
|
|
260
|
+
});
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
test("a provider NAMED `hogsend` that does not DECLARE the capability gets NO key", async () => {
|
|
264
|
+
// The point of the whole PRD. The gate used to say yes to `meta.id ===
|
|
265
|
+
// "hogsend"`, which meant one first-party package got a behaviour no third
|
|
266
|
+
// party could opt into by writing correct code — and, worse, that a
|
|
267
|
+
// regression where the package STOPS declaring the capability would be
|
|
268
|
+
// invisible. The id is now inert: only the declaration speaks.
|
|
269
|
+
const { db, inserted } = makeFakeDb();
|
|
270
|
+
const { provider, sends } = makeFakeProvider({
|
|
271
|
+
id: "hogsend",
|
|
272
|
+
capabilities: { nativeTracking: false, signedWebhooks: true },
|
|
273
|
+
});
|
|
274
|
+
const { boundary } = createRecordingBoundary({
|
|
275
|
+
runAnchor: "run-abc",
|
|
276
|
+
currentLabel: "wait-for-activation",
|
|
277
|
+
});
|
|
278
|
+
|
|
279
|
+
await runWithJourneyBoundary(boundary, () =>
|
|
280
|
+
sendTrackedEmail({ db, provider, registry, options: baseOptions() }),
|
|
281
|
+
);
|
|
282
|
+
|
|
283
|
+
assert.equal(sends.length, 1);
|
|
284
|
+
assert.equal(headerValue(sends[0]?.headers, "Idempotency-Key"), undefined);
|
|
285
|
+
// Layer 2 is untouched by the gate either way.
|
|
286
|
+
assert.equal(
|
|
287
|
+
inserted[0]?.idempotencyKey,
|
|
288
|
+
deriveJourneyKey({
|
|
289
|
+
kind: "send",
|
|
290
|
+
anchor: "run-abc",
|
|
291
|
+
site: "wait-for-activation",
|
|
292
|
+
discriminant: "welcome",
|
|
293
|
+
}),
|
|
294
|
+
);
|
|
295
|
+
});
|
|
296
|
+
|
|
297
|
+
test("a NON-`hogsend` provider that DECLARES the capability DOES get the key", async () => {
|
|
298
|
+
// The other half of the point: a third-party transport whose wire consumes
|
|
299
|
+
// the header opts in by DECLARATION alone. No engine change, no name check,
|
|
300
|
+
// no cast — it writes `consumesIdempotencyKey: true` and the key arrives.
|
|
301
|
+
const { db, inserted } = makeFakeDb();
|
|
302
|
+
const { provider, sends } = makeFakeProvider({
|
|
303
|
+
id: "acme-relay",
|
|
304
|
+
capabilities: { consumesIdempotencyKey: true },
|
|
305
|
+
});
|
|
306
|
+
const { boundary } = createRecordingBoundary({
|
|
307
|
+
runAnchor: "run-abc",
|
|
308
|
+
currentLabel: "wait-for-activation",
|
|
309
|
+
});
|
|
310
|
+
|
|
311
|
+
await runWithJourneyBoundary(boundary, () =>
|
|
312
|
+
sendTrackedEmail({ db, provider, registry, options: baseOptions() }),
|
|
313
|
+
);
|
|
314
|
+
|
|
315
|
+
const expected = deriveJourneyKey({
|
|
316
|
+
kind: "send",
|
|
317
|
+
anchor: "run-abc",
|
|
318
|
+
site: "wait-for-activation",
|
|
319
|
+
discriminant: "welcome",
|
|
320
|
+
});
|
|
321
|
+
assert.equal(sends.length, 1);
|
|
322
|
+
assert.equal(headerValue(sends[0]?.headers, "Idempotency-Key"), expected);
|
|
323
|
+
assert.equal(inserted[0]?.idempotencyKey, expected);
|
|
324
|
+
});
|
|
325
|
+
|
|
326
|
+
test("`consumesIdempotencyKey: false` is a NO, exactly like omitting it", async () => {
|
|
327
|
+
const { db } = makeFakeDb();
|
|
328
|
+
const { provider, sends } = makeFakeProvider({
|
|
329
|
+
id: "acme-relay",
|
|
330
|
+
capabilities: { consumesIdempotencyKey: false },
|
|
331
|
+
});
|
|
332
|
+
const { boundary } = createRecordingBoundary({
|
|
333
|
+
runAnchor: "run-abc",
|
|
334
|
+
currentLabel: "wait-for-activation",
|
|
335
|
+
});
|
|
336
|
+
|
|
337
|
+
await runWithJourneyBoundary(boundary, () =>
|
|
338
|
+
sendTrackedEmail({ db, provider, registry, options: baseOptions() }),
|
|
339
|
+
);
|
|
340
|
+
|
|
341
|
+
assert.equal(headerValue(sends[0]?.headers, "Idempotency-Key"), undefined);
|
|
342
|
+
});
|
|
343
|
+
|
|
344
|
+
test("a provider with NO `capabilities` at all gets no key (absence is not consent)", async () => {
|
|
345
|
+
// The pre-registry provider shape: `capabilities` is optional on the
|
|
346
|
+
// contract, so the gate has to read through an absent object without
|
|
347
|
+
// throwing and without defaulting to yes.
|
|
348
|
+
const { db } = makeFakeDb();
|
|
349
|
+
const { provider, sends } = makeFakeProvider({
|
|
350
|
+
id: "hogsend",
|
|
351
|
+
capabilities: undefined,
|
|
352
|
+
});
|
|
353
|
+
const { boundary } = createRecordingBoundary({
|
|
354
|
+
runAnchor: "run-abc",
|
|
355
|
+
currentLabel: "wait-for-activation",
|
|
356
|
+
});
|
|
357
|
+
|
|
358
|
+
await runWithJourneyBoundary(boundary, () =>
|
|
359
|
+
sendTrackedEmail({ db, provider, registry, options: baseOptions() }),
|
|
360
|
+
);
|
|
361
|
+
|
|
362
|
+
assert.equal(headerValue(sends[0]?.headers, "Idempotency-Key"), undefined);
|
|
363
|
+
});
|
|
364
|
+
|
|
365
|
+
test("an EXPLICIT caller Idempotency-Key header passes through to any provider", async () => {
|
|
366
|
+
// Pre-threading behavior, preserved: a header the caller placed in
|
|
367
|
+
// `options.headers` themselves is a deliberate choice, not the engine's —
|
|
368
|
+
// the gate never strips it, even for a header-forwarding provider that
|
|
369
|
+
// declares nothing.
|
|
370
|
+
const { db } = makeFakeDb();
|
|
371
|
+
const { provider, sends } = makeFakeProvider({
|
|
372
|
+
id: "resend",
|
|
373
|
+
capabilities: {},
|
|
374
|
+
});
|
|
375
|
+
|
|
376
|
+
await sendTrackedEmail({
|
|
377
|
+
db,
|
|
378
|
+
provider,
|
|
379
|
+
registry,
|
|
380
|
+
options: baseOptions({ headers: { "Idempotency-Key": "caller-explicit" } }),
|
|
381
|
+
});
|
|
382
|
+
|
|
383
|
+
assert.equal(
|
|
384
|
+
headerValue(sends[0]?.headers, "Idempotency-Key"),
|
|
385
|
+
"caller-explicit",
|
|
386
|
+
);
|
|
387
|
+
});
|
|
388
|
+
|
|
389
|
+
test("a caller-supplied idempotency key reaches the provider too", async () => {
|
|
390
|
+
// POST /v1/emails threads its own key. Same header, no journey required.
|
|
391
|
+
const { db } = makeFakeDb();
|
|
392
|
+
const { provider, sends } = makeFakeProvider();
|
|
393
|
+
|
|
394
|
+
await sendTrackedEmail({
|
|
395
|
+
db,
|
|
396
|
+
provider,
|
|
397
|
+
registry,
|
|
398
|
+
options: baseOptions({ idempotencyKey: "caller-key-1" }),
|
|
399
|
+
});
|
|
400
|
+
|
|
401
|
+
assert.equal(
|
|
402
|
+
headerValue(sends[0]?.headers, "Idempotency-Key"),
|
|
403
|
+
"caller-key-1",
|
|
404
|
+
);
|
|
405
|
+
});
|
|
406
|
+
|
|
407
|
+
test("no idempotency key → no Idempotency-Key header is invented", async () => {
|
|
408
|
+
// A journeyless send with no caller key has nothing replay-stable to say, and
|
|
409
|
+
// a fabricated key would be worse than none: the provider's own fallback is at
|
|
410
|
+
// least derived from the message. The header must simply be absent.
|
|
411
|
+
const { db } = makeFakeDb();
|
|
412
|
+
const { provider, sends } = makeFakeProvider();
|
|
413
|
+
|
|
414
|
+
await sendTrackedEmail({ db, provider, registry, options: baseOptions() });
|
|
415
|
+
|
|
416
|
+
assert.equal(headerValue(sends[0]?.headers, "Idempotency-Key"), undefined);
|
|
417
|
+
});
|
|
418
|
+
|
|
419
|
+
test("an explicit Idempotency-Key header from the caller is never clobbered", async () => {
|
|
420
|
+
const { db } = makeFakeDb();
|
|
421
|
+
const { provider, sends } = makeFakeProvider();
|
|
422
|
+
|
|
423
|
+
await sendTrackedEmail({
|
|
424
|
+
db,
|
|
425
|
+
provider,
|
|
426
|
+
registry,
|
|
427
|
+
options: baseOptions({
|
|
428
|
+
idempotencyKey: "derived-key",
|
|
429
|
+
headers: { "idempotency-key": "explicit-key" },
|
|
430
|
+
}),
|
|
431
|
+
});
|
|
432
|
+
|
|
433
|
+
assert.equal(
|
|
434
|
+
headerValue(sends[0]?.headers, "Idempotency-Key"),
|
|
435
|
+
"explicit-key",
|
|
436
|
+
);
|
|
437
|
+
});
|
package/src/lib/tracked.ts
CHANGED
|
@@ -21,6 +21,10 @@ import {
|
|
|
21
21
|
} from "../journeys/journey-boundary.js";
|
|
22
22
|
import { logTransition } from "../journeys/journey-log.js";
|
|
23
23
|
import { getListRegistry } from "../lists/registry-singleton.js";
|
|
24
|
+
import {
|
|
25
|
+
assertAttachmentsSendable,
|
|
26
|
+
attachmentSendMetadata,
|
|
27
|
+
} from "./attachments.js";
|
|
24
28
|
import { lookupContactIdByKey } from "./contacts.js";
|
|
25
29
|
import type { TestModeState } from "./domain-status.js";
|
|
26
30
|
import {
|
|
@@ -56,6 +60,74 @@ export type PrepareTrackedHtmlFn = (opts: {
|
|
|
56
60
|
db: Database;
|
|
57
61
|
}) => Promise<string>;
|
|
58
62
|
|
|
63
|
+
/** The neutral transport header a send's idempotency key travels on. */
|
|
64
|
+
const IDEMPOTENCY_HEADER = "Idempotency-Key";
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Does the ACTIVE provider's TRANSPORT consume the `Idempotency-Key` header —
|
|
68
|
+
* lifting it off the message before anything reaches a recipient?
|
|
69
|
+
*
|
|
70
|
+
* THE RULE: a provider gets the engine's replay-stable key if and only if it
|
|
71
|
+
* DECLARES `capabilities.consumesIdempotencyKey: true`. Nothing else qualifies
|
|
72
|
+
* it — not its id, not its package. A third party opts in the same way the
|
|
73
|
+
* first-party relay does, by writing the declaration.
|
|
74
|
+
*
|
|
75
|
+
* Absence is NOT consent, and the default is the whole safety story. Resend and
|
|
76
|
+
* Postmark forward `SendEmailOptions.headers` VERBATIM onto the delivered
|
|
77
|
+
* message (Resend `headers`, Postmark `Headers`), so volunteering the key to a
|
|
78
|
+
* provider that never asked would stamp internal keys — which embed Hatchet run
|
|
79
|
+
* ids and wait labels (`journeySend:<runId>:<site>:<template>`) and, for
|
|
80
|
+
* campaign sends, the recipient's own address (`campaign:<id>:<email>`) — onto
|
|
81
|
+
* real customer mail, silently, on nothing more than an engine upgrade. So an
|
|
82
|
+
* absent or `false` flag means the delivered headers are byte-for-byte what
|
|
83
|
+
* they were before any of this existed.
|
|
84
|
+
*
|
|
85
|
+
* An `Idempotency-Key` the CALLER placed in `options.headers` themselves is
|
|
86
|
+
* untouched by this gate: explicit headers pass through regardless of what the
|
|
87
|
+
* provider declares, exactly as they did before the key threading existed.
|
|
88
|
+
*/
|
|
89
|
+
export function providerConsumesIdempotencyKey(
|
|
90
|
+
provider: EmailProvider,
|
|
91
|
+
): boolean {
|
|
92
|
+
return provider.capabilities?.consumesIdempotencyKey === true;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Thread the send's replay-stable idempotency key onto the provider wire.
|
|
97
|
+
*
|
|
98
|
+
* `SendEmailOptions` has no `idempotencyKey` field — the contract is
|
|
99
|
+
* deliberately provider-NEUTRAL, so the key rides as a header, and ONLY to a
|
|
100
|
+
* provider that consumes it ({@link providerConsumesIdempotencyKey}): a
|
|
101
|
+
* header-forwarding provider (Resend, Postmark) would deliver it to the
|
|
102
|
+
* recipient as an SMTP header, so the caller passes `undefined` for those.
|
|
103
|
+
*
|
|
104
|
+
* This is load-bearing rather than a nicety. A transport that has to invent its
|
|
105
|
+
* own key can only hash the message bytes, and that CANNOT protect a crash
|
|
106
|
+
* replay: `prepareTrackedHtml` mints fresh `tracked_links` ids and an open pixel
|
|
107
|
+
* carrying the send id on every attempt, so a re-drive of the SAME logical send
|
|
108
|
+
* produces different HTML, a different hash, and no replay protection at all. A
|
|
109
|
+
* journey replayed after a worker crash would send twice. The engine already
|
|
110
|
+
* holds the only key that survives a replay (`journeySend:<runId>:<site>:<template>`,
|
|
111
|
+
* the same one the `email_sends` unique index dedups on), so it hands it over —
|
|
112
|
+
* one key, both dedup layers.
|
|
113
|
+
*
|
|
114
|
+
* An `Idempotency-Key` the CALLER already set is never clobbered: an explicit
|
|
115
|
+
* header is a deliberate override, and silently replacing it would make two
|
|
116
|
+
* distinct sends look like one to the transport.
|
|
117
|
+
*/
|
|
118
|
+
export function withIdempotencyHeader(
|
|
119
|
+
headers: Record<string, string> | undefined,
|
|
120
|
+
key: string | undefined,
|
|
121
|
+
): Record<string, string> | undefined {
|
|
122
|
+
if (!key) return headers;
|
|
123
|
+
const lower = IDEMPOTENCY_HEADER.toLowerCase();
|
|
124
|
+
const already = Object.keys(headers ?? {}).some(
|
|
125
|
+
(name) => name.toLowerCase() === lower,
|
|
126
|
+
);
|
|
127
|
+
if (already) return headers;
|
|
128
|
+
return { ...(headers ?? {}), [IDEMPOTENCY_HEADER]: key };
|
|
129
|
+
}
|
|
130
|
+
|
|
59
131
|
interface TrackedEmailDeps {
|
|
60
132
|
db: Database;
|
|
61
133
|
provider: EmailProvider;
|
|
@@ -129,6 +201,18 @@ async function sendTrackedEmailInner<K extends TemplateName>(
|
|
|
129
201
|
options,
|
|
130
202
|
} = opts;
|
|
131
203
|
|
|
204
|
+
// Attachment gate (PRD 17) — BEFORE any other work: no row is written, no
|
|
205
|
+
// template rendered, no provider reached for a send whose files are invalid
|
|
206
|
+
// or whose provider cannot carry them. Validation here is deliberate defence
|
|
207
|
+
// in depth with the relay (a Resend/Postmark send never passes through the
|
|
208
|
+
// relay, so this is the only pre-wire gate on those paths); the capability
|
|
209
|
+
// check fails LOUDLY rather than quietly sending the message without its
|
|
210
|
+
// files — see assertAttachmentsSendable for why absence of the flag is not
|
|
211
|
+
// consent.
|
|
212
|
+
if (options.attachments?.length) {
|
|
213
|
+
assertAttachmentsSendable(provider, options.attachments);
|
|
214
|
+
}
|
|
215
|
+
|
|
132
216
|
// Test-mode redirect (resolved by the mailer; null ⇒ live). When active, the
|
|
133
217
|
// wire `to`/`from`/`subject` + the email_sends row are redirected, but EVERY
|
|
134
218
|
// preference statement below (suppression, frequency cap, unsubscribe token)
|
|
@@ -384,7 +468,17 @@ async function sendTrackedEmailInner<K extends TemplateName>(
|
|
|
384
468
|
});
|
|
385
469
|
}
|
|
386
470
|
|
|
387
|
-
|
|
471
|
+
// The wire header travels ONLY to a transport that consumes it (the DB-layer
|
|
472
|
+
// dedup on `email_sends.idempotencyKey` below is unconditional either way) —
|
|
473
|
+
// a header-forwarding provider would deliver the key to the recipient.
|
|
474
|
+
const sendHeaders: Record<string, string> = {
|
|
475
|
+
...(withIdempotencyHeader(
|
|
476
|
+
options.headers,
|
|
477
|
+
providerConsumesIdempotencyKey(provider)
|
|
478
|
+
? options.idempotencyKey
|
|
479
|
+
: undefined,
|
|
480
|
+
) ?? {}),
|
|
481
|
+
};
|
|
388
482
|
if (unsubscribeUrl && !("List-Unsubscribe" in sendHeaders)) {
|
|
389
483
|
sendHeaders["List-Unsubscribe"] = `<${unsubscribeUrl}>`;
|
|
390
484
|
sendHeaders["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click";
|
|
@@ -473,6 +567,17 @@ async function sendTrackedEmailInner<K extends TemplateName>(
|
|
|
473
567
|
const wireSubject = redirect ? redirect.subject : subject;
|
|
474
568
|
const wireFrom = redirect ? redirect.from : options.from;
|
|
475
569
|
|
|
570
|
+
// `email_sends` records that the message HAD attachments — filenames, raw
|
|
571
|
+
// sizes, content types — NEVER the content bytes (attachmentSendMetadata).
|
|
572
|
+
// Rides the existing jsonb `metadata` column alongside the test-mode marker;
|
|
573
|
+
// no schema change.
|
|
574
|
+
const rowMetadata: Record<string, unknown> = {
|
|
575
|
+
...(redirect ? { testMode: true, originalTo: options.to } : {}),
|
|
576
|
+
...(options.attachments?.length
|
|
577
|
+
? { attachments: attachmentSendMetadata(options.attachments) }
|
|
578
|
+
: {}),
|
|
579
|
+
};
|
|
580
|
+
|
|
476
581
|
// Re-driving an orphaned "queued" row (crash before the provider returned):
|
|
477
582
|
// reuse that row instead of inserting a second one, so the provider call is
|
|
478
583
|
// re-attempted while the unique idempotency key stays honored.
|
|
@@ -493,9 +598,7 @@ async function sendTrackedEmailInner<K extends TemplateName>(
|
|
|
493
598
|
contactId: sendContactId,
|
|
494
599
|
status: "queued",
|
|
495
600
|
idempotencyKey: options.idempotencyKey,
|
|
496
|
-
...(
|
|
497
|
-
? { metadata: { testMode: true, originalTo: options.to } }
|
|
498
|
-
: {}),
|
|
601
|
+
...(Object.keys(rowMetadata).length > 0 ? { metadata: rowMetadata } : {}),
|
|
499
602
|
});
|
|
500
603
|
|
|
501
604
|
// With an idempotency key, swallow a concurrent-insert collision on the
|
|
@@ -548,6 +651,12 @@ async function sendTrackedEmailInner<K extends TemplateName>(
|
|
|
548
651
|
})
|
|
549
652
|
: rawHtml;
|
|
550
653
|
|
|
654
|
+
// Tracking FIRST, attachments alongside (PRD 17 locked order): the html
|
|
655
|
+
// above is the TRACKED html — links rewritten, open pixel injected — and
|
|
656
|
+
// the attachments ride next to it on the same wire call. An attachment
|
|
657
|
+
// never causes tracking to be skipped. Conditionally spread so a send with
|
|
658
|
+
// no attachments hands the provider options with NO `attachments` key at
|
|
659
|
+
// all — byte-identical to today's wire.
|
|
551
660
|
const result = await provider.send({
|
|
552
661
|
from: wireFrom,
|
|
553
662
|
to: wireTo,
|
|
@@ -556,6 +665,9 @@ async function sendTrackedEmailInner<K extends TemplateName>(
|
|
|
556
665
|
tags: options.tags,
|
|
557
666
|
headers: sendHeaders,
|
|
558
667
|
replyTo: options.replyTo,
|
|
668
|
+
...(options.attachments?.length
|
|
669
|
+
? { attachments: options.attachments }
|
|
670
|
+
: {}),
|
|
559
671
|
});
|
|
560
672
|
|
|
561
673
|
const sentAt = new Date();
|
|
@@ -4,6 +4,15 @@
|
|
|
4
4
|
export const EMAIL_OPENED = "email.opened" as const;
|
|
5
5
|
export const EMAIL_LINK_CLICKED = "email.link_clicked" as const;
|
|
6
6
|
|
|
7
|
+
// A human REPLIED to a message we sent (PRD 16). The BUS name deliberately
|
|
8
|
+
// EQUALS the outbound catalog name — unlike the click pair, where the bus event
|
|
9
|
+
// is `email.link_clicked` and the webhook is `email.clicked` — because the whole
|
|
10
|
+
// point of the feature is that a journey author writes exactly what the PRD
|
|
11
|
+
// promises: `ctx.waitForEvent({ event: "email.replied" })`. A second spelling
|
|
12
|
+
// would be one more thing to look up in order to stop a sequence when somebody
|
|
13
|
+
// says "please stop emailing me".
|
|
14
|
+
export const EMAIL_REPLIED = "email.replied" as const;
|
|
15
|
+
|
|
7
16
|
// First-party BUS event for a NON-email managed-link click (re-ingested through
|
|
8
17
|
// `ingestEvent` so journeys can trigger / `ctx.waitForEvent` on a click of a
|
|
9
18
|
// SPECIFIC managed link). It deliberately SHARES the name string with the
|
|
@@ -74,6 +74,13 @@ export const WEBHOOK_EVENT_TYPES = [
|
|
|
74
74
|
"email.action",
|
|
75
75
|
"email.bounced",
|
|
76
76
|
"email.complained",
|
|
77
|
+
// A human REPLIED to a message a journey sent (PRD 16). The only email event
|
|
78
|
+
// here that reports a message coming BACK rather than the fate of one going
|
|
79
|
+
// out, and the only one whose payload can be uncorrelated: a reply whose
|
|
80
|
+
// `In-Reply-To` names no send this instance made is still delivered, with
|
|
81
|
+
// `correlated: false` and null send context, because dropping a human's words
|
|
82
|
+
// to keep a payload tidy is the worse failure.
|
|
83
|
+
"email.replied",
|
|
77
84
|
"sms.sent",
|
|
78
85
|
"sms.delivered",
|
|
79
86
|
"sms.failed",
|