@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
|
@@ -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
|
+
});
|