@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.
- 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,229 @@
|
|
|
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 } from "@hogsend/db";
|
|
6
|
+
import type { TemplateRegistry } from "@hogsend/email";
|
|
7
|
+
|
|
8
|
+
// mailer's import chain reaches env.ts (validates required env vars at import
|
|
9
|
+
// time) and lib/hatchet.ts (parses HATCHET_CLIENT_TOKEN as a JWT at import
|
|
10
|
+
// time) — stub both BEFORE the dynamic import. Nothing is ever contacted: the
|
|
11
|
+
// db is a recorder and the provider is never called on this path.
|
|
12
|
+
process.env.DATABASE_URL ??= "postgresql://test:test@localhost:5432/test";
|
|
13
|
+
process.env.BETTER_AUTH_SECRET ??= "test-secret";
|
|
14
|
+
process.env.HATCHET_CLIENT_TOKEN ??=
|
|
15
|
+
"eyJhbGciOiJFUzI1NiIsImtpZCI6InRlc3QifQ.eyJhdWQiOiJsb2NhbGhvc3QiLCJleHAiOjQ5MzMyNDA5ODMsImdycGNfYnJvYWRjYXN0X2FkZHJlc3MiOiJsb2NhbGhvc3Q6NzA3NyIsImlhdCI6MTc3OTY0MDk4MywiaXNzIjoibG9jYWxob3N0Iiwic2VydmVyX3VybCI6ImxvY2FsaG9zdCIsInN1YiI6InRlc3QtdGVuYW50LWlkIiwidG9rZW5faWQiOiJ0ZXN0LXRva2VuLWlkIn0.test";
|
|
16
|
+
const { createTrackedMailer } = await import("./mailer.js");
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* `email.rejected` handling (PRD 18).
|
|
20
|
+
*
|
|
21
|
+
* SES accepted the message, returned a message id, and then threw it away
|
|
22
|
+
* because it detected a virus. Two things have to be true of that, and the
|
|
23
|
+
* second one is the reason this file exists:
|
|
24
|
+
*
|
|
25
|
+
* 1. the send reaches a TERMINAL status — no further event is coming, so a row
|
|
26
|
+
* left at `sent` stays non-terminal permanently;
|
|
27
|
+
* 2. **NOTHING is suppressed.** The recipient's address is fine; our content
|
|
28
|
+
* was the problem. Folding a reject onto the bounce path would let one bad
|
|
29
|
+
* attachment permanently block a deliverable address, silently, with the
|
|
30
|
+
* customer discovering it months later.
|
|
31
|
+
*
|
|
32
|
+
* Asserted at the DB seam with a recording fake, so the assertion is about the
|
|
33
|
+
* statements the mailer actually issues rather than about a mock's call count.
|
|
34
|
+
* The reject deliberately NAMES a recipient (the normalizer sends
|
|
35
|
+
* `mail.destination`, because a reject is message-scoped): a no-suppression
|
|
36
|
+
* test over an empty recipient list would pass whatever the code did.
|
|
37
|
+
*/
|
|
38
|
+
|
|
39
|
+
interface RecordedUpdate {
|
|
40
|
+
table: unknown;
|
|
41
|
+
values: Record<string, unknown>;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* A resolved statement that also answers `.returning()`, like drizzle's
|
|
46
|
+
* builder. The bounce leg claims its send with a guarded `UPDATE ... RETURNING`
|
|
47
|
+
* (see `claimBounce`), so the recorder has to model the row it matched: one
|
|
48
|
+
* row = "a real send that had not bounced yet", which is what every bounce
|
|
49
|
+
* control below assumes.
|
|
50
|
+
*/
|
|
51
|
+
function settled(): Promise<{ id: string }[]> & {
|
|
52
|
+
returning: () => Promise<{ id: string }[]>;
|
|
53
|
+
} {
|
|
54
|
+
const rows = [{ id: "send-row-uuid" }];
|
|
55
|
+
const promise = Promise.resolve(rows) as Promise<{ id: string }[]> & {
|
|
56
|
+
returning: () => Promise<{ id: string }[]>;
|
|
57
|
+
};
|
|
58
|
+
promise.returning = () => Promise.resolve(rows);
|
|
59
|
+
return promise;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
function recordingDb(): { db: Database; updates: RecordedUpdate[] } {
|
|
63
|
+
const updates: RecordedUpdate[] = [];
|
|
64
|
+
const db = {
|
|
65
|
+
update(table: unknown) {
|
|
66
|
+
return {
|
|
67
|
+
set(values: Record<string, unknown>) {
|
|
68
|
+
updates.push({ table, values });
|
|
69
|
+
return { where: () => settled() };
|
|
70
|
+
},
|
|
71
|
+
};
|
|
72
|
+
},
|
|
73
|
+
};
|
|
74
|
+
return { db: db as unknown as Database, updates };
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** Never called on the webhook path — present only to satisfy the contract. */
|
|
78
|
+
const provider = {
|
|
79
|
+
meta: { id: "test", name: "Test" },
|
|
80
|
+
capabilities: { nativeTracking: false },
|
|
81
|
+
send: async () => ({ id: "unused" }),
|
|
82
|
+
} as unknown as EmailProvider;
|
|
83
|
+
|
|
84
|
+
function mailer(db: Database) {
|
|
85
|
+
return createTrackedMailer(
|
|
86
|
+
{
|
|
87
|
+
defaultFrom: "test@example.com",
|
|
88
|
+
templates: {} as TemplateRegistry,
|
|
89
|
+
db,
|
|
90
|
+
},
|
|
91
|
+
{ provider },
|
|
92
|
+
);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
function rejected(overrides: Partial<EmailEvent> = {}): EmailEvent {
|
|
96
|
+
return {
|
|
97
|
+
type: "email.rejected",
|
|
98
|
+
messageId: "0100018f-ses-rejected-id",
|
|
99
|
+
recipients: ["good-address@example.com"],
|
|
100
|
+
occurredAt: new Date().toISOString(),
|
|
101
|
+
reject: { reason: "Bad content" },
|
|
102
|
+
raw: {},
|
|
103
|
+
...overrides,
|
|
104
|
+
};
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
test("email.rejected marks the send TERMINAL", async () => {
|
|
108
|
+
const { db, updates } = recordingDb();
|
|
109
|
+
const result = await mailer(db).handleWebhook(rejected());
|
|
110
|
+
|
|
111
|
+
assert.equal(result.type, "email.rejected");
|
|
112
|
+
|
|
113
|
+
const sendUpdates = updates.filter((row) => row.table === emailSends);
|
|
114
|
+
assert.equal(sendUpdates.length, 1);
|
|
115
|
+
// `failed` is the terminal status this schema already has for "did not reach
|
|
116
|
+
// the recipient and nothing further is coming". It is NOT `bounced`: that
|
|
117
|
+
// status carries a bounce classification the engine suppresses on.
|
|
118
|
+
assert.equal(sendUpdates[0]?.values.status, "failed");
|
|
119
|
+
});
|
|
120
|
+
|
|
121
|
+
test("email.rejected records no bounce facts on the send row", async () => {
|
|
122
|
+
const { db, updates } = recordingDb();
|
|
123
|
+
await mailer(db).handleWebhook(rejected());
|
|
124
|
+
|
|
125
|
+
const values = updates.find((row) => row.table === emailSends)?.values ?? {};
|
|
126
|
+
assert.equal("bouncedAt" in values, false);
|
|
127
|
+
assert.equal("bounceType" in values, false);
|
|
128
|
+
assert.equal("bounceReason" in values, false);
|
|
129
|
+
// A reject never arrived, so it must not read as a delivery either.
|
|
130
|
+
assert.equal("deliveredAt" in values, false);
|
|
131
|
+
});
|
|
132
|
+
|
|
133
|
+
test("email.rejected SUPPRESSES NOTHING, even naming a recipient", async () => {
|
|
134
|
+
// THE assertion of this PRD. `email_preferences` is the only table
|
|
135
|
+
// suppression and the bounce counter live in, so ZERO writes to it is the
|
|
136
|
+
// whole claim: no `bounceCount` increment, no `suppressed` flag, nothing to
|
|
137
|
+
// undo later.
|
|
138
|
+
const { db, updates } = recordingDb();
|
|
139
|
+
await mailer(db).handleWebhook(rejected());
|
|
140
|
+
|
|
141
|
+
const preferenceUpdates = updates.filter(
|
|
142
|
+
(row) => row.table === emailPreferences,
|
|
143
|
+
);
|
|
144
|
+
assert.deepEqual(preferenceUpdates, []);
|
|
145
|
+
});
|
|
146
|
+
|
|
147
|
+
test("a reject carrying a bounce block STILL suppresses nothing", async () => {
|
|
148
|
+
// Defence in depth. The plugin already strips `bounce` off a reject, so this
|
|
149
|
+
// is what happens if a future provider (or a hand-built event) does not: the
|
|
150
|
+
// engine branches on the TYPE, never on the presence of the block.
|
|
151
|
+
const { db, updates } = recordingDb();
|
|
152
|
+
await mailer(db).handleWebhook(
|
|
153
|
+
rejected({ bounce: { class: "permanent", code: "Permanent/General" } }),
|
|
154
|
+
);
|
|
155
|
+
|
|
156
|
+
assert.deepEqual(
|
|
157
|
+
updates.filter((row) => row.table === emailPreferences),
|
|
158
|
+
[],
|
|
159
|
+
);
|
|
160
|
+
});
|
|
161
|
+
|
|
162
|
+
test("a permanent bounce DOES suppress — the mutation check's control", async () => {
|
|
163
|
+
// The counterweight. Without this, "no preference writes" could pass because
|
|
164
|
+
// the recording db never sees preference writes at all, and the
|
|
165
|
+
// no-suppression test above would be vacuous.
|
|
166
|
+
const { db, updates } = recordingDb();
|
|
167
|
+
await mailer(db).handleWebhook({
|
|
168
|
+
type: "email.bounced",
|
|
169
|
+
messageId: "0100018f-ses-bounced-id",
|
|
170
|
+
recipients: ["good-address@example.com"],
|
|
171
|
+
occurredAt: new Date().toISOString(),
|
|
172
|
+
bounce: { class: "permanent", code: "Permanent/General" },
|
|
173
|
+
raw: {},
|
|
174
|
+
});
|
|
175
|
+
|
|
176
|
+
const preferenceUpdates = updates.filter(
|
|
177
|
+
(row) => row.table === emailPreferences,
|
|
178
|
+
);
|
|
179
|
+
assert.equal(preferenceUpdates.length, 1);
|
|
180
|
+
assert.ok("bounceCount" in (preferenceUpdates[0]?.values ?? {}));
|
|
181
|
+
});
|
|
182
|
+
|
|
183
|
+
test("a consumer handler for email.rejected is invoked with the reason", async () => {
|
|
184
|
+
// How a journey learns the send is never arriving: the neutral type gets a
|
|
185
|
+
// `WebhookHandlerMap` slot for free, and the reason rides verbatim.
|
|
186
|
+
const { db } = recordingDb();
|
|
187
|
+
const seen: EmailEvent[] = [];
|
|
188
|
+
const service = createTrackedMailer(
|
|
189
|
+
{
|
|
190
|
+
defaultFrom: "test@example.com",
|
|
191
|
+
templates: {} as TemplateRegistry,
|
|
192
|
+
db,
|
|
193
|
+
webhookHandlers: {
|
|
194
|
+
"email.rejected": (event) => {
|
|
195
|
+
seen.push(event);
|
|
196
|
+
},
|
|
197
|
+
},
|
|
198
|
+
},
|
|
199
|
+
{ provider },
|
|
200
|
+
);
|
|
201
|
+
|
|
202
|
+
const result = await service.handleWebhook(rejected());
|
|
203
|
+
|
|
204
|
+
assert.equal(result.handled, true);
|
|
205
|
+
assert.equal(seen.length, 1);
|
|
206
|
+
assert.deepEqual(seen[0]?.reject, { reason: "Bad content" });
|
|
207
|
+
});
|
|
208
|
+
|
|
209
|
+
test("a provider that never emits email.rejected behaves exactly as today", async () => {
|
|
210
|
+
// The back-compat line: adding a union member must not change any existing
|
|
211
|
+
// branch. A delivery still writes `delivered` + `deliveredAt` and touches no
|
|
212
|
+
// preference row.
|
|
213
|
+
const { db, updates } = recordingDb();
|
|
214
|
+
await mailer(db).handleWebhook({
|
|
215
|
+
type: "email.delivered",
|
|
216
|
+
messageId: "0100018f-ses-delivered-id",
|
|
217
|
+
recipients: ["good-address@example.com"],
|
|
218
|
+
occurredAt: new Date().toISOString(),
|
|
219
|
+
raw: {},
|
|
220
|
+
});
|
|
221
|
+
|
|
222
|
+
const values = updates.find((row) => row.table === emailSends)?.values ?? {};
|
|
223
|
+
assert.equal(values.status, "delivered");
|
|
224
|
+
assert.ok(values.deliveredAt instanceof Date);
|
|
225
|
+
assert.deepEqual(
|
|
226
|
+
updates.filter((row) => row.table === emailPreferences),
|
|
227
|
+
[],
|
|
228
|
+
);
|
|
229
|
+
});
|
|
@@ -0,0 +1,379 @@
|
|
|
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
|
+
|
|
8
|
+
// mailer's import chain reaches env.ts (validates required env vars at import
|
|
9
|
+
// time) and lib/hatchet.ts (parses HATCHET_CLIENT_TOKEN as a JWT at import
|
|
10
|
+
// time) — stub both BEFORE the dynamic import. Nothing is ever contacted: the
|
|
11
|
+
// db is a recorder, the provider is never called on this path, and the bus push
|
|
12
|
+
// is injected.
|
|
13
|
+
process.env.DATABASE_URL ??= "postgresql://test:test@localhost:5432/test";
|
|
14
|
+
process.env.BETTER_AUTH_SECRET ??= "test-secret";
|
|
15
|
+
process.env.HATCHET_CLIENT_TOKEN ??=
|
|
16
|
+
"eyJhbGciOiJFUzI1NiIsImtpZCI6InRlc3QifQ.eyJhdWQiOiJsb2NhbGhvc3QiLCJleHAiOjQ5MzMyNDA5ODMsImdycGNfYnJvYWRjYXN0X2FkZHJlc3MiOiJsb2NhbGhvc3Q6NzA3NyIsImlhdCI6MTc3OTY0MDk4MywiaXNzIjoibG9jYWxob3N0Iiwic2VydmVyX3VybCI6ImxvY2FsaG9zdCIsInN1YiI6InRlc3QtdGVuYW50LWlkIiwidG9rZW5faWQiOiJ0ZXN0LXRva2VuLWlkIn0.test";
|
|
17
|
+
const { createTrackedMailer } = await import("./mailer.js");
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* `email.replied` handling (PRD 16 task 5).
|
|
21
|
+
*
|
|
22
|
+
* The feature exists for ONE reason, stated in the PRD: "so a JOURNEY can know
|
|
23
|
+
* a human replied, and stop." Without it a contact answers "please stop
|
|
24
|
+
* emailing me" and the sequence sends three more. So the two claims asserted
|
|
25
|
+
* here are the two halves of that:
|
|
26
|
+
*
|
|
27
|
+
* 1. the reply reaches the INTERNAL bus under the name a journey waits on,
|
|
28
|
+
* carrying the in-reply-to id, the sender and the text — the EARS list;
|
|
29
|
+
* 2. the reply reaches the OUTBOUND spine, correlated or not.
|
|
30
|
+
*
|
|
31
|
+
* And the two things it must NOT do, both of which are silent when broken:
|
|
32
|
+
*
|
|
33
|
+
* - **no status write.** A reply is not a delivery outcome. A message that was
|
|
34
|
+
* delivered and then answered is still delivered, and writing a status here
|
|
35
|
+
* would overwrite that with something no send ever had;
|
|
36
|
+
* - **no suppression.** Somebody replying is the strongest possible evidence
|
|
37
|
+
* the address works. `email_preferences` is where suppression lives, so zero
|
|
38
|
+
* writes to it is the claim.
|
|
39
|
+
*
|
|
40
|
+
* Asserted at the DB seam with a recording fake, so the assertions are about
|
|
41
|
+
* statements the mailer actually issues rather than about a mock's call count.
|
|
42
|
+
*/
|
|
43
|
+
|
|
44
|
+
interface RecordedUpdate {
|
|
45
|
+
table: unknown;
|
|
46
|
+
values: Record<string, unknown>;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
interface RecordedInsert {
|
|
50
|
+
table: unknown;
|
|
51
|
+
values: unknown;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
interface SendRow {
|
|
55
|
+
emailSendId: string;
|
|
56
|
+
toEmail: string;
|
|
57
|
+
templateKey: string | null;
|
|
58
|
+
sendContactId: string | null;
|
|
59
|
+
userId: string | null;
|
|
60
|
+
userEmail: string | null;
|
|
61
|
+
enrollmentContactId: string | null;
|
|
62
|
+
sendUserId: string | null;
|
|
63
|
+
sendUserEmail: string | null;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* A db that answers the ONE read this path makes (`email_sends` by provider
|
|
68
|
+
* message id) and records every write.
|
|
69
|
+
*
|
|
70
|
+
* `selectRows` is what the message-id lookup returns: `[]` models a reply that
|
|
71
|
+
* correlates to nothing, which is the uncorrelated case the EARS names.
|
|
72
|
+
*/
|
|
73
|
+
/**
|
|
74
|
+
* A resolved statement that also answers `.returning()`, like drizzle's
|
|
75
|
+
* builder. The bounce leg claims its send with a guarded `UPDATE ... RETURNING`
|
|
76
|
+
* (see `claimBounce`), so the recorder has to model the row it matched: one
|
|
77
|
+
* row = "a real send that had not bounced yet", which is what the bounce
|
|
78
|
+
* control below assumes.
|
|
79
|
+
*/
|
|
80
|
+
function settled(): Promise<{ id: string }[]> & {
|
|
81
|
+
returning: () => Promise<{ id: string }[]>;
|
|
82
|
+
} {
|
|
83
|
+
const rows = [{ id: "send-row-uuid" }];
|
|
84
|
+
const promise = Promise.resolve(rows) as Promise<{ id: string }[]> & {
|
|
85
|
+
returning: () => Promise<{ id: string }[]>;
|
|
86
|
+
};
|
|
87
|
+
promise.returning = () => Promise.resolve(rows);
|
|
88
|
+
return promise;
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
function recordingDb(selectRows: SendRow[] = []): {
|
|
92
|
+
db: Database;
|
|
93
|
+
updates: RecordedUpdate[];
|
|
94
|
+
inserts: RecordedInsert[];
|
|
95
|
+
} {
|
|
96
|
+
const updates: RecordedUpdate[] = [];
|
|
97
|
+
const inserts: RecordedInsert[] = [];
|
|
98
|
+
const db = {
|
|
99
|
+
update(table: unknown) {
|
|
100
|
+
return {
|
|
101
|
+
set(values: Record<string, unknown>) {
|
|
102
|
+
updates.push({ table, values });
|
|
103
|
+
return { where: () => settled() };
|
|
104
|
+
},
|
|
105
|
+
};
|
|
106
|
+
},
|
|
107
|
+
insert(table: unknown) {
|
|
108
|
+
return {
|
|
109
|
+
values(values: unknown) {
|
|
110
|
+
inserts.push({ table, values });
|
|
111
|
+
return {
|
|
112
|
+
onConflictDoNothing: () => ({
|
|
113
|
+
returning: () => Promise.resolve([]),
|
|
114
|
+
}),
|
|
115
|
+
returning: () => Promise.resolve([]),
|
|
116
|
+
};
|
|
117
|
+
},
|
|
118
|
+
};
|
|
119
|
+
},
|
|
120
|
+
select() {
|
|
121
|
+
return {
|
|
122
|
+
from() {
|
|
123
|
+
return {
|
|
124
|
+
// `resolveEmailSendContextByMessageId` JOINS to `journey_states`;
|
|
125
|
+
// `emitOutbound`'s subscribed-endpoint select does not. The two
|
|
126
|
+
// shapes are told apart by that join, so one recorder can serve
|
|
127
|
+
// both reads without either answering the other's question.
|
|
128
|
+
leftJoin: () => ({
|
|
129
|
+
where: () => ({ limit: () => Promise.resolve(selectRows) }),
|
|
130
|
+
}),
|
|
131
|
+
// One subscribed endpoint, so the spine has somewhere to deliver.
|
|
132
|
+
where: () => Promise.resolve([{ id: "endpoint-1" }]),
|
|
133
|
+
};
|
|
134
|
+
},
|
|
135
|
+
};
|
|
136
|
+
},
|
|
137
|
+
};
|
|
138
|
+
return { db: db as unknown as Database, updates, inserts };
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** Never called on the webhook path — present only to satisfy the contract. */
|
|
142
|
+
const provider = {
|
|
143
|
+
meta: { id: "test", name: "Test" },
|
|
144
|
+
capabilities: { nativeTracking: false },
|
|
145
|
+
send: async () => ({ id: "unused" }),
|
|
146
|
+
} as unknown as EmailProvider;
|
|
147
|
+
|
|
148
|
+
interface PushedEvent {
|
|
149
|
+
event: string;
|
|
150
|
+
emailSendId: string;
|
|
151
|
+
properties?: Record<string, unknown>;
|
|
152
|
+
idempotencyKey?: string;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
function mailer(db: Database, pushed: PushedEvent[] = []) {
|
|
156
|
+
return createTrackedMailer(
|
|
157
|
+
{ defaultFrom: "test@example.com", templates: {} as TemplateRegistry, db },
|
|
158
|
+
{
|
|
159
|
+
provider,
|
|
160
|
+
// The bus push is the one seam injected here: the real one reaches
|
|
161
|
+
// `ingestEvent`, which resolves identity and pushes to Hatchet. What this
|
|
162
|
+
// file is asserting is WHAT the mailer hands the bus, not what the bus
|
|
163
|
+
// then does with it.
|
|
164
|
+
pushReplyEvent: async (opts) => {
|
|
165
|
+
pushed.push({
|
|
166
|
+
event: opts.event,
|
|
167
|
+
emailSendId: opts.emailSendId,
|
|
168
|
+
...(opts.properties ? { properties: opts.properties } : {}),
|
|
169
|
+
...(opts.idempotencyKey
|
|
170
|
+
? { idempotencyKey: opts.idempotencyKey }
|
|
171
|
+
: {}),
|
|
172
|
+
});
|
|
173
|
+
return undefined;
|
|
174
|
+
},
|
|
175
|
+
},
|
|
176
|
+
);
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
const SEND: SendRow = {
|
|
180
|
+
emailSendId: "send-row-uuid",
|
|
181
|
+
toEmail: "contact@example.com",
|
|
182
|
+
templateKey: "onboarding-day-1",
|
|
183
|
+
sendContactId: null,
|
|
184
|
+
userId: "user_42",
|
|
185
|
+
userEmail: "contact@example.com",
|
|
186
|
+
enrollmentContactId: null,
|
|
187
|
+
sendUserId: null,
|
|
188
|
+
sendUserEmail: null,
|
|
189
|
+
};
|
|
190
|
+
|
|
191
|
+
function replied(overrides: Partial<EmailEvent> = {}): EmailEvent {
|
|
192
|
+
return {
|
|
193
|
+
type: "email.replied",
|
|
194
|
+
messageId: "0100019-the-received-reply",
|
|
195
|
+
recipients: ["hello@reply.acme.test"],
|
|
196
|
+
occurredAt: new Date().toISOString(),
|
|
197
|
+
reply: {
|
|
198
|
+
recipient: "hello@reply.acme.test",
|
|
199
|
+
from: "human@sender.test",
|
|
200
|
+
subject: "Re: your onboarding email",
|
|
201
|
+
text: "Please stop emailing me.",
|
|
202
|
+
textTruncated: false,
|
|
203
|
+
correlated: true,
|
|
204
|
+
inReplyTo: "0100018f-the-original-send",
|
|
205
|
+
},
|
|
206
|
+
raw: {},
|
|
207
|
+
...overrides,
|
|
208
|
+
};
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
test("a correlated reply reaches the bus under the name a journey waits on", async () => {
|
|
212
|
+
const { db } = recordingDb([SEND]);
|
|
213
|
+
const pushed: PushedEvent[] = [];
|
|
214
|
+
const result = await mailer(db, pushed).handleWebhook(replied());
|
|
215
|
+
|
|
216
|
+
assert.equal(result.type, "email.replied");
|
|
217
|
+
assert.equal(pushed.length, 1);
|
|
218
|
+
// The EXACT string the PRD promises a journey can wait on. A second spelling
|
|
219
|
+
// here would make `ctx.waitForEvent({ event: "email.replied" })` silently
|
|
220
|
+
// never fire.
|
|
221
|
+
assert.equal(pushed[0]?.event, "email.replied");
|
|
222
|
+
assert.equal(pushed[0]?.emailSendId, "send-row-uuid");
|
|
223
|
+
});
|
|
224
|
+
|
|
225
|
+
test("the bus event carries the in-reply-to id, the sender and the text", async () => {
|
|
226
|
+
// The EARS list, verbatim: "SHALL emit `email.replied` with the in-reply-to
|
|
227
|
+
// id, the sender, and a text body". Each of the three is what a journey
|
|
228
|
+
// branches on, so each is asserted by name rather than by shape.
|
|
229
|
+
const { db } = recordingDb([SEND]);
|
|
230
|
+
const pushed: PushedEvent[] = [];
|
|
231
|
+
await mailer(db, pushed).handleWebhook(replied());
|
|
232
|
+
|
|
233
|
+
const properties = pushed[0]?.properties ?? {};
|
|
234
|
+
assert.equal(properties.inReplyTo, "0100018f-the-original-send");
|
|
235
|
+
assert.equal(properties.from, "human@sender.test");
|
|
236
|
+
assert.equal(properties.text, "Please stop emailing me.");
|
|
237
|
+
assert.equal(properties.correlated, true);
|
|
238
|
+
assert.equal(properties.messageId, "0100019-the-received-reply");
|
|
239
|
+
});
|
|
240
|
+
|
|
241
|
+
test("a redelivered reply carries the SAME idempotency key", async () => {
|
|
242
|
+
// SNS is at-least-once and the relay re-drives a failed instance hop, so the
|
|
243
|
+
// same reply can arrive twice. A duplicate `email.replied` on the bus can
|
|
244
|
+
// exit a journey a second time, and an exit is not a thing that can be taken
|
|
245
|
+
// back — the key is what collapses the pair, and it is derived from the
|
|
246
|
+
// RECEIVED message's id, which is stable across every redelivery.
|
|
247
|
+
const { db } = recordingDb([SEND]);
|
|
248
|
+
const pushed: PushedEvent[] = [];
|
|
249
|
+
const service = mailer(db, pushed);
|
|
250
|
+
await service.handleWebhook(replied());
|
|
251
|
+
await service.handleWebhook(replied());
|
|
252
|
+
|
|
253
|
+
assert.equal(pushed.length, 2);
|
|
254
|
+
assert.equal(pushed[0]?.idempotencyKey, pushed[1]?.idempotencyKey);
|
|
255
|
+
assert.match(String(pushed[0]?.idempotencyKey), /0100019-the-received-reply/);
|
|
256
|
+
});
|
|
257
|
+
|
|
258
|
+
test("an UNCORRELATED reply is still delivered, and marked uncorrelated", async () => {
|
|
259
|
+
// The EARS: "WHEN a reply cannot be correlated to an `email_sends` row, the
|
|
260
|
+
// system SHALL still store and deliver it, and SHALL mark it uncorrelated."
|
|
261
|
+
// There is no contact key to ingest against, so the bus is skipped — but the
|
|
262
|
+
// spine is NOT, because a human still replied and dropping their words to
|
|
263
|
+
// keep a payload tidy is the worse failure.
|
|
264
|
+
const { db, inserts } = recordingDb([]);
|
|
265
|
+
const pushed: PushedEvent[] = [];
|
|
266
|
+
await mailer(db, pushed).handleWebhook(
|
|
267
|
+
replied({
|
|
268
|
+
reply: {
|
|
269
|
+
recipient: "hello@reply.acme.test",
|
|
270
|
+
from: "stranger@elsewhere.test",
|
|
271
|
+
subject: "hello",
|
|
272
|
+
text: "who is this",
|
|
273
|
+
textTruncated: false,
|
|
274
|
+
correlated: false,
|
|
275
|
+
},
|
|
276
|
+
}),
|
|
277
|
+
);
|
|
278
|
+
|
|
279
|
+
assert.deepEqual(pushed, []);
|
|
280
|
+
|
|
281
|
+
const delivery = inserts.find((row) => row.table === webhookDeliveries);
|
|
282
|
+
assert.ok(delivery, "an uncorrelated reply must still reach the spine");
|
|
283
|
+
const payload = (
|
|
284
|
+
delivery.values as { payload: { data: Record<string, unknown> } }[]
|
|
285
|
+
)[0]?.payload;
|
|
286
|
+
assert.equal(payload?.data.correlated, false);
|
|
287
|
+
assert.equal(payload?.data.inReplyTo, null);
|
|
288
|
+
assert.equal(payload?.data.emailSendId, null);
|
|
289
|
+
assert.equal(payload?.data.from, "stranger@elsewhere.test");
|
|
290
|
+
});
|
|
291
|
+
|
|
292
|
+
test("a correlated reply reaches the spine with its send context", async () => {
|
|
293
|
+
const { db, inserts } = recordingDb([SEND]);
|
|
294
|
+
await mailer(db).handleWebhook(replied());
|
|
295
|
+
|
|
296
|
+
const delivery = inserts.find((row) => row.table === webhookDeliveries);
|
|
297
|
+
assert.ok(delivery, "a correlated reply must reach the spine");
|
|
298
|
+
const rows = delivery.values as {
|
|
299
|
+
eventType: string;
|
|
300
|
+
dedupeKey: string | null;
|
|
301
|
+
payload: { data: Record<string, unknown> };
|
|
302
|
+
}[];
|
|
303
|
+
assert.equal(rows[0]?.eventType, "email.replied");
|
|
304
|
+
// The spine's own dedupe, for the same at-least-once reason as the bus key.
|
|
305
|
+
assert.match(String(rows[0]?.dedupeKey), /0100019-the-received-reply/);
|
|
306
|
+
assert.equal(rows[0]?.payload.data.emailSendId, "send-row-uuid");
|
|
307
|
+
assert.equal(rows[0]?.payload.data.userId, "user_42");
|
|
308
|
+
assert.equal(rows[0]?.payload.data.templateKey, "onboarding-day-1");
|
|
309
|
+
});
|
|
310
|
+
|
|
311
|
+
test("a reply writes NO status onto the send it answers", async () => {
|
|
312
|
+
// A reply is not a delivery outcome. The send it answers was delivered and
|
|
313
|
+
// stays delivered; writing a status here would overwrite a real outcome with
|
|
314
|
+
// one no send ever had, and every bounce-rate and delivery read would then
|
|
315
|
+
// count it.
|
|
316
|
+
const { db, updates } = recordingDb([SEND]);
|
|
317
|
+
await mailer(db).handleWebhook(replied());
|
|
318
|
+
|
|
319
|
+
assert.deepEqual(
|
|
320
|
+
updates.filter((row) => row.table === emailSends),
|
|
321
|
+
[],
|
|
322
|
+
);
|
|
323
|
+
});
|
|
324
|
+
|
|
325
|
+
test("a reply SUPPRESSES NOTHING", async () => {
|
|
326
|
+
// Somebody replying is the strongest evidence an address works.
|
|
327
|
+
// `email_preferences` is the only table suppression and the bounce counter
|
|
328
|
+
// live in, so zero writes to it is the whole claim.
|
|
329
|
+
const { db, updates } = recordingDb([SEND]);
|
|
330
|
+
await mailer(db).handleWebhook(replied());
|
|
331
|
+
|
|
332
|
+
assert.deepEqual(
|
|
333
|
+
updates.filter((row) => row.table === emailPreferences),
|
|
334
|
+
[],
|
|
335
|
+
);
|
|
336
|
+
});
|
|
337
|
+
|
|
338
|
+
test("a permanent bounce still writes both — the mutation check's control", async () => {
|
|
339
|
+
// The counterweight. Without it, the two "writes nothing" tests above could
|
|
340
|
+
// pass because the recording db never sees any write at all.
|
|
341
|
+
const { db, updates } = recordingDb([SEND]);
|
|
342
|
+
await mailer(db).handleWebhook({
|
|
343
|
+
type: "email.bounced",
|
|
344
|
+
messageId: "0100018f-ses-bounced-id",
|
|
345
|
+
recipients: ["good-address@example.com"],
|
|
346
|
+
occurredAt: new Date().toISOString(),
|
|
347
|
+
bounce: { class: "permanent", code: "Permanent/General" },
|
|
348
|
+
raw: {},
|
|
349
|
+
});
|
|
350
|
+
|
|
351
|
+
assert.equal(updates.filter((row) => row.table === emailSends).length, 1);
|
|
352
|
+
assert.equal(
|
|
353
|
+
updates.filter((row) => row.table === emailPreferences).length,
|
|
354
|
+
1,
|
|
355
|
+
);
|
|
356
|
+
});
|
|
357
|
+
|
|
358
|
+
test("a consumer handler for email.replied receives the reply detail", async () => {
|
|
359
|
+
const { db } = recordingDb([SEND]);
|
|
360
|
+
const seen: EmailEvent[] = [];
|
|
361
|
+
const service = createTrackedMailer(
|
|
362
|
+
{
|
|
363
|
+
defaultFrom: "test@example.com",
|
|
364
|
+
templates: {} as TemplateRegistry,
|
|
365
|
+
db,
|
|
366
|
+
webhookHandlers: {
|
|
367
|
+
"email.replied": (event) => {
|
|
368
|
+
seen.push(event);
|
|
369
|
+
},
|
|
370
|
+
},
|
|
371
|
+
},
|
|
372
|
+
{ provider, pushReplyEvent: async () => undefined },
|
|
373
|
+
);
|
|
374
|
+
|
|
375
|
+
const result = await service.handleWebhook(replied());
|
|
376
|
+
|
|
377
|
+
assert.equal(result.handled, true);
|
|
378
|
+
assert.equal(seen[0]?.reply?.from, "human@sender.test");
|
|
379
|
+
});
|