@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.
@@ -46,6 +46,38 @@ if (process.env.POSTMARK_SERVER_TOKEN) {
46
46
  });
47
47
  }
48
48
 
49
+ /**
50
+ * `@hogsend/plugin-hogsend` is OPT-IN for exactly the same reasons as Postmark,
51
+ * and loaded exactly the same way: an engine `optionalDependency` behind a
52
+ * top-level guarded dynamic import whose specifier is ASSEMBLED AT RUNTIME. A
53
+ * string literal here would make `tsc` resolve the module's types and fail with
54
+ * TS2307 for every consumer that doesn't have the package installed — including
55
+ * every fresh `create-hogsend` app, which is not covered by this repo's own
56
+ * type-check and so would only surface after publish.
57
+ *
58
+ * The gate is `HOGSEND_EMAIL_TOKEN`: absent, the `import()` never fires, so a
59
+ * self-hosted deploy that will never send through Hogsend Cloud never touches
60
+ * the package.
61
+ */
62
+ type CreateHogsendEmailProvider = (cfg: {
63
+ relayUrl: string;
64
+ tenantToken: string;
65
+ webhookSecret?: string;
66
+ }) => EmailProvider;
67
+
68
+ const HOGSEND_PACKAGE = ["@hogsend", "plugin-hogsend"].join("/");
69
+
70
+ let createHogsendEmailProvider: CreateHogsendEmailProvider | null = null;
71
+ if (process.env.HOGSEND_EMAIL_TOKEN) {
72
+ createHogsendEmailProvider =
73
+ await loadOptionalPlugin<CreateHogsendEmailProvider>({
74
+ specifier: HOGSEND_PACKAGE,
75
+ exportName: "createHogsendEmailProvider",
76
+ enabledBy: "HOGSEND_EMAIL_TOKEN is set",
77
+ onFailure: (message) => console.warn(message),
78
+ });
79
+ }
80
+
49
81
  /**
50
82
  * Build the env-enabled email-provider presets. Mirrors `destinationsFromEnv`:
51
83
  * a preset is constructed ONLY when its credential is present, so a
@@ -94,5 +126,40 @@ export function emailProvidersFromEnv(env: typeof envSchema): EmailProvider[] {
94
126
  );
95
127
  }
96
128
 
129
+ // Hogsend Email is OPT-IN twice over: the package only loads when
130
+ // HOGSEND_EMAIL_TOKEN is set (see the guarded import above), and registering
131
+ // it does NOT select it — EMAIL_PROVIDER=hogsend does, exactly as Postmark
132
+ // works. The Cloud provisioner injects both, so a Cloud instance gets it by
133
+ // default while every self-hosted default is untouched.
134
+ //
135
+ // The relay URL is required to BUILD it. A token with no URL is a
136
+ // misconfiguration, and a provider aimed at `undefined/api/email/send` would
137
+ // defer that config error to the first real send — so it warns here and skips.
138
+ // If `hogsend` was the selected provider the container then throws its own
139
+ // "not registered" error at boot, and the two lines together say exactly what
140
+ // is missing.
141
+ if (env.HOGSEND_EMAIL_TOKEN && createHogsendEmailProvider) {
142
+ if (!env.HOGSEND_EMAIL_RELAY_URL) {
143
+ console.warn(
144
+ "HOGSEND_EMAIL_TOKEN is set, but its env preset is skipped: " +
145
+ "HOGSEND_EMAIL_RELAY_URL is unset, so there is no Hogsend Cloud " +
146
+ "control plane to relay sends to. Set it to your control plane " +
147
+ "origin (Cloud provisioning injects it automatically).",
148
+ );
149
+ } else {
150
+ providers.push(
151
+ createHogsendEmailProvider({
152
+ relayUrl: env.HOGSEND_EMAIL_RELAY_URL,
153
+ tenantToken: env.HOGSEND_EMAIL_TOKEN,
154
+ // Absent ⇒ the provider fails closed on every inbound webhook. Sends
155
+ // still work; only status updates stop.
156
+ ...(env.HOGSEND_EMAIL_WEBHOOK_SECRET
157
+ ? { webhookSecret: env.HOGSEND_EMAIL_WEBHOOK_SECRET }
158
+ : {}),
159
+ }),
160
+ );
161
+ }
162
+ }
163
+
97
164
  return providers;
98
165
  }
@@ -1,6 +1,7 @@
1
1
  import type {
2
2
  BatchEmailItem,
3
3
  DurationObject,
4
+ EmailAttachment,
4
5
  EmailEvent,
5
6
  EmailEventType,
6
7
  SendEmailOptions,
@@ -66,6 +67,14 @@ export interface SendTrackedEmailOptions<
66
67
  * duplicate provider send.
67
68
  */
68
69
  idempotencyKey?: string;
70
+ /**
71
+ * Neutral attachments (PRD 17), validated + capability-gated before ANY send
72
+ * work (see `assertAttachmentsSendable`) and handed to the provider alongside
73
+ * the TRACKED html — tracking is applied first, attachments ride alongside;
74
+ * an attachment never causes tracking to be skipped. `email_sends.metadata`
75
+ * records filenames/sizes/types only, never the bytes.
76
+ */
77
+ attachments?: EmailAttachment[];
69
78
  }
70
79
 
71
80
  export interface TrackedSendResult {
@@ -184,6 +193,8 @@ export interface EmailServiceSendOptions<
184
193
  skipPreferenceCheck?: boolean;
185
194
  /** Caller-supplied idempotency key (POST /v1/emails) — dedups duplicate sends. */
186
195
  idempotencyKey?: string;
196
+ /** Neutral attachments — see `SendTrackedEmailOptions.attachments`. */
197
+ attachments?: EmailAttachment[];
187
198
  }
188
199
 
189
200
  /**
package/src/lib/email.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { EmailAttachment } from "@hogsend/core";
1
2
  import { generateUnsubscribeUrl, type TemplateName } from "@hogsend/email";
2
3
  import {
3
4
  deriveJourneyKey,
@@ -65,6 +66,18 @@ export interface SendEmailOptions {
65
66
  * engine throws an intra-run key-collision error. Additive and optional.
66
67
  */
67
68
  idempotencyLabel?: string;
69
+ /**
70
+ * Files to send with the email (invoices, receipts, tickets, exports).
71
+ * Neutral {@link EmailAttachment} shape; validated + capability-gated by the
72
+ * tracked mailer BEFORE any work — a provider that does not declare
73
+ * `capabilities.attachments` throws rather than delivering the message
74
+ * without its files. Attachments do NOT enter the replay-stable idempotency
75
+ * key (that stays `kind:anchor:site:template`), so no authoring change is
76
+ * needed for exactly-once — but if something NON-deterministic picks the
77
+ * attachment, wrap that choice in `ctx.once` like any other non-deterministic
78
+ * send input.
79
+ */
80
+ attachments?: EmailAttachment[];
68
81
  }
69
82
 
70
83
  export interface SendEmailResult {
@@ -154,6 +167,7 @@ export async function sendEmail(
154
167
  { name: "userId", value: opts.userId },
155
168
  ],
156
169
  headers,
170
+ attachments: opts.attachments,
157
171
  } as unknown as EmailServiceSendOptions;
158
172
 
159
173
  const effect = {
@@ -172,6 +186,9 @@ export async function sendEmail(
172
186
  ...(resolvedIdempotencyKey
173
187
  ? { idempotencyKey: resolvedIdempotencyKey }
174
188
  : {}),
189
+ // Carried on the effect so a scoped services.email override (deterministic
190
+ // journey harnesses) sees the files too, instead of silently dropping them.
191
+ ...(opts.attachments?.length ? { attachments: opts.attachments } : {}),
175
192
  };
176
193
 
177
194
  // Layer 1 (fast path): when inside a journey on an eviction-capable engine,
@@ -0,0 +1,469 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import type { EmailEvent, EmailProvider } from "@hogsend/core";
4
+ import type { Database } from "@hogsend/db";
5
+ import { emailPreferences, emailSends, webhookDeliveries } from "@hogsend/db";
6
+ import type { TemplateRegistry } from "@hogsend/email";
7
+ import type { SQL } from "drizzle-orm";
8
+ import { PgDialect } from "drizzle-orm/pg-core";
9
+
10
+ // mailer's import chain reaches env.ts (validates required env vars at import
11
+ // time) and lib/hatchet.ts (parses HATCHET_CLIENT_TOKEN as a JWT at import
12
+ // time) — stub both BEFORE the dynamic import. Nothing is ever contacted: the
13
+ // db is a fake and the provider is never called on this path.
14
+ process.env.DATABASE_URL ??= "postgresql://test:test@localhost:5432/test";
15
+ process.env.BETTER_AUTH_SECRET ??= "test-secret";
16
+ process.env.HATCHET_CLIENT_TOKEN ??=
17
+ "eyJhbGciOiJFUzI1NiIsImtpZCI6InRlc3QifQ.eyJhdWQiOiJsb2NhbGhvc3QiLCJleHAiOjQ5MzMyNDA5ODMsImdycGNfYnJvYWRjYXN0X2FkZHJlc3MiOiJsb2NhbGhvc3Q6NzA3NyIsImlhdCI6MTc3OTY0MDk4MywiaXNzIjoibG9jYWxob3N0Iiwic2VydmVyX3VybCI6ImxvY2FsaG9zdCIsInN1YiI6InRlc3QtdGVuYW50LWlkIiwidG9rZW5faWQiOiJ0ZXN0LXRva2VuLWlkIn0.test";
18
+ const { createTrackedMailer } = await import("./mailer.js");
19
+
20
+ /**
21
+ * BOUNCE IDEMPOTENCY.
22
+ *
23
+ * SNS is at-least-once, and the control plane deliberately re-drives a
24
+ * `pending` event row after 60s so a bounce is never LOST — which means the
25
+ * SAME bounce can reach this instance more than once. Two things must survive
26
+ * that, and neither is cosmetic:
27
+ *
28
+ * 1. **the suppression counter.** `bounceThreshold` defaults to 3, so THREE
29
+ * redeliveries of ONE bounce would permanently suppress a perfectly
30
+ * deliverable address — silently, with nothing the customer can undo;
31
+ * 2. **the outbound `email.bounced` emit.** A redelivery double-fires the
32
+ * customer's webhook destination and fires a journey waiting on
33
+ * `email.bounced` twice.
34
+ *
35
+ * Asserted against a db fake that EVALUATES the statement's WHERE clause
36
+ * against modelled row state (rendered through drizzle's own pg dialect)
37
+ * rather than assuming a guard exists. That is the point: a fake that simply
38
+ * refused the second write would pass whether or not the engine actually
39
+ * guards, which is the vacuous-green trap this repo has been bitten by. Delete
40
+ * the guard and these tests go red.
41
+ */
42
+
43
+ const dialect = new PgDialect();
44
+
45
+ /** `bounced_at` → `bouncedAt`. */
46
+ function camel(column: string): string {
47
+ return column.replace(/_([a-z])/g, (_, c: string) => c.toUpperCase());
48
+ }
49
+
50
+ /**
51
+ * Evaluate a rendered WHERE against a modelled row. Supports EXACTLY the three
52
+ * predicate shapes this path emits and THROWS on anything else — an unknown
53
+ * shape must fail loudly rather than silently evaluate to "matched".
54
+ */
55
+ function matches(row: Record<string, unknown>, condition: unknown): boolean {
56
+ const { sql: text, params } = dialect.sqlToQuery(condition as SQL);
57
+ const terms = text.replace(/^\(/, "").replace(/\)$/, "").split(" and ");
58
+ return terms.every((raw) => {
59
+ const term = raw.trim();
60
+ let m = /^"[a-z_]+"\."([a-z_]+)" = \$(\d+)$/.exec(term);
61
+ if (m) return row[camel(m[1] as string)] === params[Number(m[2]) - 1];
62
+ m = /^"[a-z_]+"\."([a-z_]+)" is null$/.exec(term);
63
+ if (m) return row[camel(m[1] as string)] == null;
64
+ m = /^"[a-z_]+"\."([a-z_]+)" is distinct from \$(\d+)$/.exec(term);
65
+ if (m) return row[camel(m[1] as string)] !== params[Number(m[2]) - 1];
66
+ throw new Error(`fake db: unsupported predicate \`${term}\``);
67
+ });
68
+ }
69
+
70
+ interface FakeSend {
71
+ id: string;
72
+ messageId: string;
73
+ toEmail: string;
74
+ status: string;
75
+ sentAt: Date | null;
76
+ deliveredAt: Date | null;
77
+ openedAt: Date | null;
78
+ clickedAt: Date | null;
79
+ bouncedAt: Date | null;
80
+ bounceType: string | null;
81
+ bounceReason: string | null;
82
+ }
83
+
84
+ function send(messageId: string, overrides: Partial<FakeSend> = {}): FakeSend {
85
+ return {
86
+ id: `send-${messageId}`,
87
+ messageId,
88
+ toEmail: "recipient@example.com",
89
+ status: "sent",
90
+ sentAt: new Date(),
91
+ deliveredAt: null,
92
+ openedAt: null,
93
+ clickedAt: null,
94
+ bouncedAt: null,
95
+ bounceType: null,
96
+ bounceReason: null,
97
+ ...overrides,
98
+ };
99
+ }
100
+
101
+ interface RecordedUpdate {
102
+ values: Record<string, unknown>;
103
+ /** How many modelled rows the statement's WHERE actually matched. */
104
+ matched: number;
105
+ }
106
+
107
+ interface FakeDb {
108
+ db: Database;
109
+ sends: FakeSend[];
110
+ sendUpdates: RecordedUpdate[];
111
+ preferenceUpdates: RecordedUpdate[];
112
+ /** Advanced by 1 per issued `bounce_count + 1` statement. */
113
+ bounceCount: () => number;
114
+ outbound: () => { eventType: string }[];
115
+ warnings: { message: string; meta?: unknown }[];
116
+ }
117
+
118
+ /** A resolved promise that also answers `.returning()`, like drizzle's builder. */
119
+ function settled<T>(
120
+ rows: T[],
121
+ ): Promise<T[]> & { returning: () => Promise<T[]> } {
122
+ const promise = Promise.resolve(rows) as Promise<T[]> & {
123
+ returning: () => Promise<T[]>;
124
+ };
125
+ promise.returning = () => Promise.resolve(rows);
126
+ return promise;
127
+ }
128
+
129
+ function fakeDb(rows: FakeSend[]): FakeDb {
130
+ const sendUpdates: RecordedUpdate[] = [];
131
+ const preferenceUpdates: RecordedUpdate[] = [];
132
+ const deliveries: { eventType: string }[] = [];
133
+ const warnings: { message: string; meta?: unknown }[] = [];
134
+ let bounceCount = 0;
135
+
136
+ const db = {
137
+ update(table: unknown) {
138
+ return {
139
+ set(values: Record<string, unknown>) {
140
+ return {
141
+ where(condition: unknown) {
142
+ if (table === emailSends) {
143
+ const hit = rows.filter((row) =>
144
+ matches(row as unknown as Record<string, unknown>, condition),
145
+ );
146
+ for (const row of hit) {
147
+ for (const [key, value] of Object.entries(values)) {
148
+ // Drizzle `sql` expressions (the counter increments) are
149
+ // modelled separately; plain values write through.
150
+ if (
151
+ value &&
152
+ typeof value === "object" &&
153
+ "queryChunks" in value
154
+ ) {
155
+ continue;
156
+ }
157
+ (row as unknown as Record<string, unknown>)[key] = value;
158
+ }
159
+ }
160
+ sendUpdates.push({ values, matched: hit.length });
161
+ return settled(hit.map((row) => ({ id: row.id })));
162
+ }
163
+ if (table === emailPreferences) {
164
+ preferenceUpdates.push({ values, matched: 1 });
165
+ if ("bounceCount" in values) bounceCount += 1;
166
+ return settled([{ id: "pref-1" }]);
167
+ }
168
+ return settled<{ id: string }>([]);
169
+ },
170
+ };
171
+ },
172
+ };
173
+ },
174
+ select() {
175
+ return {
176
+ from() {
177
+ return {
178
+ // `resolveEmailSendContextByMessageId` joins to `journey_states`;
179
+ // `emitOutbound`'s endpoint select does not. The join tells the two
180
+ // reads apart, so one fake serves both.
181
+ leftJoin: () => ({
182
+ where: (condition: unknown) => ({
183
+ limit: () =>
184
+ Promise.resolve(
185
+ rows
186
+ .filter((row) =>
187
+ matches(
188
+ row as unknown as Record<string, unknown>,
189
+ condition,
190
+ ),
191
+ )
192
+ .map((row) => ({
193
+ emailSendId: row.id,
194
+ toEmail: row.toEmail,
195
+ templateKey: "onboarding-day-1",
196
+ sendContactId: null,
197
+ userId: null,
198
+ userEmail: null,
199
+ enrollmentContactId: null,
200
+ sendUserId: null,
201
+ sendUserEmail: null,
202
+ })),
203
+ ),
204
+ }),
205
+ }),
206
+ // One subscribed endpoint, so the spine has somewhere to deliver.
207
+ where: () => Promise.resolve([{ id: "endpoint-1" }]),
208
+ };
209
+ },
210
+ };
211
+ },
212
+ insert(table: unknown) {
213
+ return {
214
+ values(values: unknown) {
215
+ if (table === webhookDeliveries) {
216
+ deliveries.push(...(values as { eventType: string }[]));
217
+ }
218
+ return {
219
+ onConflictDoNothing: () => ({
220
+ returning: () => Promise.resolve([]),
221
+ }),
222
+ returning: () => Promise.resolve([]),
223
+ };
224
+ },
225
+ };
226
+ },
227
+ };
228
+
229
+ return {
230
+ db: db as unknown as Database,
231
+ sends: rows,
232
+ sendUpdates,
233
+ preferenceUpdates,
234
+ bounceCount: () => bounceCount,
235
+ outbound: () => deliveries,
236
+ warnings,
237
+ };
238
+ }
239
+
240
+ /** Never called on the webhook path — present only to satisfy the contract. */
241
+ const provider = {
242
+ meta: { id: "test", name: "Test" },
243
+ capabilities: { nativeTracking: false },
244
+ send: async () => ({ id: "unused" }),
245
+ } as unknown as EmailProvider;
246
+
247
+ function mailer(fake: FakeDb) {
248
+ return createTrackedMailer(
249
+ {
250
+ defaultFrom: "test@example.com",
251
+ templates: {} as TemplateRegistry,
252
+ db: fake.db,
253
+ logger: {
254
+ debug: () => {},
255
+ info: () => {},
256
+ warn: (message: string, meta?: unknown) => {
257
+ fake.warnings.push({ message, meta });
258
+ },
259
+ error: () => {},
260
+ } as never,
261
+ },
262
+ { provider },
263
+ );
264
+ }
265
+
266
+ function bounced(
267
+ messageId: string,
268
+ bounce: { class?: string; reason?: string } = { class: "permanent" },
269
+ ): EmailEvent {
270
+ return {
271
+ type: "email.bounced",
272
+ messageId,
273
+ recipients: ["recipient@example.com"],
274
+ occurredAt: "2026-08-12T10:00:00.000Z",
275
+ bounce: bounce as EmailEvent["bounce"],
276
+ raw: {},
277
+ };
278
+ }
279
+
280
+ /** The outbound emit is fire-and-forget — let its continuation land. */
281
+ async function drain(): Promise<void> {
282
+ for (let i = 0; i < 20; i += 1) {
283
+ await new Promise((resolve) => setImmediate(resolve));
284
+ }
285
+ }
286
+
287
+ function bouncedEmits(fake: FakeDb): number {
288
+ return fake.outbound().filter((row) => row.eventType === "email.bounced")
289
+ .length;
290
+ }
291
+
292
+ test("THE test: the same bounce delivered three times counts ONCE", async () => {
293
+ // The headline claim. With `bounceThreshold` at 3, an ungated counter turns
294
+ // three redeliveries of ONE bounce into a permanent suppression of an address
295
+ // that never did anything wrong.
296
+ const fake = fakeDb([send("msg-1")]);
297
+ const service = mailer(fake);
298
+
299
+ await service.handleWebhook(bounced("msg-1"));
300
+ await drain();
301
+ assert.equal(fake.bounceCount(), 1, "the first delivery must count");
302
+ assert.equal(bouncedEmits(fake), 1, "the first delivery must emit");
303
+
304
+ await service.handleWebhook(bounced("msg-1"));
305
+ await drain();
306
+ assert.equal(fake.bounceCount(), 1, "a redelivery must NOT count again");
307
+ assert.equal(bouncedEmits(fake), 1, "a redelivery must NOT emit again");
308
+
309
+ await service.handleWebhook(bounced("msg-1"));
310
+ await drain();
311
+ assert.equal(fake.bounceCount(), 1, "still exactly one after a third");
312
+ assert.equal(bouncedEmits(fake), 1, "still exactly one emit after a third");
313
+
314
+ // Nothing was suppressed: one count is two short of the threshold.
315
+ assert.equal(fake.preferenceUpdates.length, 1);
316
+ });
317
+
318
+ test("the first delivery still records the bounce facts on the send", async () => {
319
+ // The guard must not cost the row its state. This is the control for the test
320
+ // above: if the claim wrote nothing at all, "counted once" would be vacuous.
321
+ const fake = fakeDb([send("msg-1")]);
322
+ await mailer(fake).handleWebhook(
323
+ bounced("msg-1", { class: "permanent", reason: "550 5.1.1 unknown" }),
324
+ );
325
+
326
+ const row = fake.sends[0] as FakeSend;
327
+ assert.equal(row.status, "bounced");
328
+ assert.ok(row.bouncedAt instanceof Date);
329
+ assert.equal(row.bounceType, "permanent");
330
+ assert.equal(row.bounceReason, "550 5.1.1 unknown");
331
+ });
332
+
333
+ test("a SECOND, DISTINCT bounce for the same address still counts", async () => {
334
+ // Do not over-dedupe. Two sends to the same address that both bounce are two
335
+ // bounces, and suppression exists precisely so the second one moves the
336
+ // counter. Dedupe is scoped to (send, bounce), never to the address.
337
+ const fake = fakeDb([send("msg-1"), send("msg-2")]);
338
+ const service = mailer(fake);
339
+
340
+ await service.handleWebhook(bounced("msg-1"));
341
+ await service.handleWebhook(bounced("msg-2"));
342
+ await drain();
343
+
344
+ assert.equal(fake.bounceCount(), 2);
345
+ assert.equal(bouncedEmits(fake), 2);
346
+ });
347
+
348
+ test("a permanent bounce AFTER a transient one on the same send counts", async () => {
349
+ // The escalation the guard deliberately admits. A soft bounce recorded first
350
+ // must not shield the hard bounce that follows it — that would silently
351
+ // disable suppression for exactly the addresses that need it.
352
+ const fake = fakeDb([send("msg-1")]);
353
+ const service = mailer(fake);
354
+
355
+ await service.handleWebhook(bounced("msg-1", { class: "transient" }));
356
+ await drain();
357
+ assert.equal(fake.bounceCount(), 0, "a transient bounce never counts");
358
+
359
+ await service.handleWebhook(bounced("msg-1", { class: "permanent" }));
360
+ await drain();
361
+ assert.equal(fake.bounceCount(), 1, "the permanent escalation DOES count");
362
+
363
+ // ...and the permanent one is itself idempotent from there on.
364
+ await service.handleWebhook(bounced("msg-1", { class: "permanent" }));
365
+ await drain();
366
+ assert.equal(fake.bounceCount(), 1);
367
+ });
368
+
369
+ test("a transient bounce still auto-suppresses NOTHING, however often it arrives", async () => {
370
+ const fake = fakeDb([send("msg-1")]);
371
+ const service = mailer(fake);
372
+
373
+ await service.handleWebhook(bounced("msg-1", { class: "transient" }));
374
+ await service.handleWebhook(bounced("msg-1", { class: "transient" }));
375
+ await drain();
376
+
377
+ assert.deepEqual(fake.preferenceUpdates, []);
378
+ assert.equal(fake.bounceCount(), 0);
379
+ // The redelivered transient does not re-emit either.
380
+ assert.equal(bouncedEmits(fake), 1);
381
+ assert.equal((fake.sends[0] as FakeSend).bounceType, "transient");
382
+ });
383
+
384
+ test("a bounce for a send we never recorded STILL counts", async () => {
385
+ // The deliberate edge (requirement 4). `sendRaw` writes no `email_sends` row
386
+ // at all, and a webhook can outrun the send row's commit — so "no matching
387
+ // row" is a REAL bounce we have no send-scoped state to dedupe against.
388
+ // Silently dropping it would disable suppression for those addresses
389
+ // entirely, which is the worse failure, so the count is preserved (today's
390
+ // behaviour) and the un-dedupable path is logged instead of hidden.
391
+ const fake = fakeDb([]);
392
+ const service = mailer(fake);
393
+
394
+ await service.handleWebhook(bounced("msg-unknown"));
395
+ await drain();
396
+
397
+ assert.equal(fake.bounceCount(), 1);
398
+ assert.ok(
399
+ fake.warnings.some((entry) => /unrecorded send/.test(entry.message)),
400
+ "the un-dedupable path must be logged, not silent",
401
+ );
402
+
403
+ // The residual, pinned deliberately rather than left to be discovered: with
404
+ // no send row there is nothing to claim, so a redelivery counts again. The
405
+ // emit does NOT double-fire — it resolves its context from the same missing
406
+ // row and no-ops.
407
+ await service.handleWebhook(bounced("msg-unknown"));
408
+ await drain();
409
+ assert.equal(fake.bounceCount(), 2);
410
+ assert.equal(bouncedEmits(fake), 0);
411
+ });
412
+
413
+ test("opened and clicked are NOT gated — every hit still writes", async () => {
414
+ // The per-hit behaviour of open/click is deliberate and documented in the
415
+ // dispatch branch. The bounce guard must not leak onto it.
416
+ const fake = fakeDb([send("msg-1")]);
417
+ const service = mailer(fake);
418
+
419
+ await service.handleWebhook({
420
+ type: "email.opened",
421
+ messageId: "msg-1",
422
+ recipients: ["recipient@example.com"],
423
+ occurredAt: "2026-08-12T10:00:00.000Z",
424
+ raw: {},
425
+ });
426
+ await service.handleWebhook({
427
+ type: "email.opened",
428
+ messageId: "msg-1",
429
+ recipients: ["recipient@example.com"],
430
+ occurredAt: "2026-08-12T10:00:01.000Z",
431
+ raw: {},
432
+ });
433
+ await service.handleWebhook({
434
+ type: "email.clicked",
435
+ messageId: "msg-1",
436
+ recipients: ["recipient@example.com"],
437
+ occurredAt: "2026-08-12T10:00:02.000Z",
438
+ raw: {},
439
+ });
440
+ await drain();
441
+
442
+ // Three statements, and every one of them MATCHED a row: an accidental
443
+ // `WHERE openedAt IS NULL` here would leave the second open matching nothing.
444
+ assert.equal(fake.sendUpdates.length, 3);
445
+ for (const update of fake.sendUpdates) {
446
+ assert.equal(update.matched, 1);
447
+ }
448
+ });
449
+
450
+ test("a delivered webhook is untouched by the bounce guard", async () => {
451
+ const fake = fakeDb([send("msg-1")]);
452
+ const service = mailer(fake);
453
+
454
+ await service.handleWebhook({
455
+ type: "email.delivered",
456
+ messageId: "msg-1",
457
+ recipients: ["recipient@example.com"],
458
+ occurredAt: "2026-08-12T10:00:00.000Z",
459
+ raw: {},
460
+ });
461
+ await drain();
462
+
463
+ assert.equal((fake.sends[0] as FakeSend).status, "delivered");
464
+ assert.deepEqual(fake.preferenceUpdates, []);
465
+ assert.equal(
466
+ fake.outbound().filter((row) => row.eventType === "email.delivered").length,
467
+ 1,
468
+ );
469
+ });