@hogsend/engine 0.63.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.
@@ -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
+ });
@@ -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
- const sendHeaders: Record<string, string> = { ...(options.headers ?? {}) };
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
- ...(redirect
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",