@hogsend/engine 0.63.0 → 0.65.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.
Files changed (92) hide show
  1. package/package.json +13 -12
  2. package/src/account-links/__fixtures__/fake-fetch.test.ts +57 -0
  3. package/src/account-links/__fixtures__/fake-fetch.ts +114 -0
  4. package/src/account-links/__fixtures__/steam.json +21 -0
  5. package/src/account-links/__fixtures__/twitch.json +22 -0
  6. package/src/account-links/index.ts +8 -0
  7. package/src/account-links/steam.test.ts +243 -0
  8. package/src/account-links/steam.ts +48 -0
  9. package/src/account-links/twitch.test.ts +157 -0
  10. package/src/account-links/twitch.ts +99 -0
  11. package/src/container.account-links.env.test.ts +65 -0
  12. package/src/container.account-links.halfenv.test.ts +48 -0
  13. package/src/container.account-links.test.ts +185 -0
  14. package/src/container.ts +120 -0
  15. package/src/env.ts +60 -0
  16. package/src/index.ts +104 -1
  17. package/src/journeys/journey-boundary.ts +8 -0
  18. package/src/lib/account-link-emit.ts +126 -0
  19. package/src/lib/account-link-events.ts +180 -0
  20. package/src/lib/account-link-hooks.test.ts +158 -0
  21. package/src/lib/account-link-hooks.ts +73 -0
  22. package/src/lib/account-link-ingest.ts +364 -0
  23. package/src/lib/account-link-nonce.test.ts +52 -0
  24. package/src/lib/account-link-nonce.ts +57 -0
  25. package/src/lib/account-link-origins.test.ts +72 -0
  26. package/src/lib/account-link-origins.ts +87 -0
  27. package/src/lib/account-link-pkce.test.ts +91 -0
  28. package/src/lib/account-link-pkce.ts +106 -0
  29. package/src/lib/account-link-provider-registry.test.ts +52 -0
  30. package/src/lib/account-link-provider-registry.ts +61 -0
  31. package/src/lib/account-link-throttle.test.ts +178 -0
  32. package/src/lib/account-link-throttle.ts +130 -0
  33. package/src/lib/account-link-url.ts +85 -0
  34. package/src/lib/account-links-emit.test.ts +525 -0
  35. package/src/lib/account-links-env.test.ts +40 -0
  36. package/src/lib/account-links-from-env.test.ts +187 -0
  37. package/src/lib/account-links-from-env.ts +126 -0
  38. package/src/lib/account-links.ts +1300 -0
  39. package/src/lib/app-secret.ts +34 -0
  40. package/src/lib/attachments.ts +81 -0
  41. package/src/lib/connector-actions.test.ts +13 -4
  42. package/src/lib/connector-state.account-link.test.ts +114 -0
  43. package/src/lib/connector-state.ts +48 -3
  44. package/src/lib/contacts.ts +320 -6
  45. package/src/lib/domain-status.return-path.test.ts +68 -0
  46. package/src/lib/domain-status.ts +19 -0
  47. package/src/lib/email-provider-boot.hogsend.test.ts +48 -0
  48. package/src/lib/email-provider-boot.test.ts +33 -0
  49. package/src/lib/email-providers-from-env.hogsend.test.ts +110 -0
  50. package/src/lib/email-providers-from-env.test.ts +52 -0
  51. package/src/lib/email-providers-from-env.ts +67 -0
  52. package/src/lib/email-service-types.ts +11 -0
  53. package/src/lib/email.ts +17 -0
  54. package/src/lib/mailer-bounce-idempotency.test.ts +469 -0
  55. package/src/lib/mailer-rejected.test.ts +229 -0
  56. package/src/lib/mailer-replied.test.ts +379 -0
  57. package/src/lib/mailer.ts +359 -24
  58. package/src/lib/outbound-account-payloads.test.ts +137 -0
  59. package/src/lib/outbound.ts +126 -0
  60. package/src/lib/provider-credentials.ts +19 -5
  61. package/src/lib/sending-domain-guidance.test.ts +99 -0
  62. package/src/lib/sending-domain-guidance.ts +84 -0
  63. package/src/lib/tracked-attachments.test.ts +376 -0
  64. package/src/lib/tracked-idempotency-header.test.ts +437 -0
  65. package/src/lib/tracked.ts +116 -4
  66. package/src/lib/tracking-event-names.ts +9 -0
  67. package/src/lib/webhook-catalog-sync.test.ts +24 -0
  68. package/src/lib/webhook-signing.ts +25 -1
  69. package/src/routes/accounts/callback.ts +597 -0
  70. package/src/routes/accounts/emit.ts +231 -0
  71. package/src/routes/accounts/import-links.ts +210 -0
  72. package/src/routes/accounts/index.ts +75 -0
  73. package/src/routes/accounts/lookup.ts +177 -0
  74. package/src/routes/accounts/me.ts +215 -0
  75. package/src/routes/accounts/mint.ts +279 -0
  76. package/src/routes/accounts/pages.ts +62 -0
  77. package/src/routes/accounts/resolve.ts +61 -0
  78. package/src/routes/accounts/serialize.ts +96 -0
  79. package/src/routes/accounts/shared.ts +107 -0
  80. package/src/routes/accounts/start.ts +229 -0
  81. package/src/routes/accounts/unlink.ts +98 -0
  82. package/src/routes/admin/agent.ts +2 -0
  83. package/src/routes/admin/api-keys.ts +7 -0
  84. package/src/routes/admin/contacts.ts +38 -2
  85. package/src/routes/admin/domain-conflict.test.ts +188 -0
  86. package/src/routes/admin/domain-return-path.test.ts +274 -0
  87. package/src/routes/admin/domain.ts +214 -1
  88. package/src/routes/connectors/index.ts +17 -0
  89. package/src/routes/contacts/index.ts +8 -0
  90. package/src/routes/index.ts +75 -0
  91. package/src/testing-barrel.test.ts +74 -0
  92. package/src/testing.ts +17 -0
@@ -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
+ });