@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
package/src/lib/mailer.ts CHANGED
@@ -13,7 +13,9 @@ import type {
13
13
  TemplateName,
14
14
  } from "@hogsend/email";
15
15
  import { getTemplate, renderToHtml, renderToPlainText } from "@hogsend/email";
16
- import { eq, inArray, sql } from "drizzle-orm";
16
+ import { and, eq, inArray, isNull, type SQL, sql } from "drizzle-orm";
17
+ import { getJourneyRegistrySingleton } from "../journeys/registry-singleton.js";
18
+ import { assertAttachmentsSendable } from "./attachments.js";
17
19
  import type { DomainStatusService } from "./domain-status.js";
18
20
  import {
19
21
  type EmailService,
@@ -37,8 +39,17 @@ import {
37
39
  TestModeNoRedirectError,
38
40
  } from "./test-mode.js";
39
41
  import type { PrepareTrackedHtmlFn } from "./tracked.js";
40
- import { sendTrackedEmail } from "./tracked.js";
41
- import { resolveEmailSendContextByMessageId } from "./tracking-events.js";
42
+ import {
43
+ providerConsumesIdempotencyKey,
44
+ sendTrackedEmail,
45
+ withIdempotencyHeader,
46
+ } from "./tracked.js";
47
+ import { EMAIL_REPLIED } from "./tracking-event-names.js";
48
+ import {
49
+ type PushTrackingEventOpts,
50
+ pushTrackingEvent,
51
+ resolveEmailSendContextByMessageId,
52
+ } from "./tracking-events.js";
42
53
 
43
54
  // Fallback logger for the provider-webhook outbound emit — `config.logger` is
44
55
  // optional, but `emitOutbound` requires one. Mirrors the engine-lib singleton
@@ -63,12 +74,62 @@ const WEBHOOK_TO_STATUS: Partial<Record<EmailEventType, string>> = {
63
74
  "email.clicked": "clicked",
64
75
  "email.bounced": "bounced",
65
76
  "email.complained": "complained",
77
+ /**
78
+ * TERMINAL (PRD 18). The provider accepted the message, returned an id, and
79
+ * then discarded it — no delivery, no bounce, no later event of any kind is
80
+ * coming, so a row left at `sent` would stay non-terminal forever.
81
+ *
82
+ * `failed` rather than `bounced`, deliberately: `bounced` carries a
83
+ * classification the engine SUPPRESSES on, and a reject is our content
84
+ * failing rather than the recipient's address. It has no timestamp column of
85
+ * its own and none is invented here — `updatedAt` is when we learned, and the
86
+ * verbatim reason reaches the consumer on the event (`EmailEvent.reject`).
87
+ */
88
+ "email.rejected": "failed",
66
89
  };
67
90
 
68
91
  /** Max recipients we will iterate on a bounce/complaint, to avoid a fan-out
69
92
  * webhook mass-suppressing addresses. Above this we log + skip suppression. */
70
93
  const MAX_SUPPRESSION_RECIPIENTS = 100;
71
94
 
95
+ /**
96
+ * See `createTrackedMailer`'s `pushReplyEvent` dep.
97
+ *
98
+ * `registry` is deliberately NOT part of this signature. The real push needs
99
+ * the journey registry, which lives in a process singleton that THROWS when it
100
+ * has not been set — so reading it at the call site would make every injected
101
+ * override depend on a global the override does not use. The default wrapper
102
+ * reads it, and only it.
103
+ */
104
+ export type PushReplyEventFn = (
105
+ opts: Omit<PushTrackingEventOpts, "registry">,
106
+ ) => Promise<unknown>;
107
+
108
+ /**
109
+ * The bus event's properties — the EARS list ("the in-reply-to id, the sender,
110
+ * and a text body") plus the context a journey needs to branch.
111
+ *
112
+ * Every value is a SCALAR or null, deliberately: `trigger.where` and
113
+ * `ctx.waitForEvent(...).properties` only carry scalars, so a nested object
114
+ * here would simply not survive to the journey that needs it.
115
+ */
116
+ function replyProperties(
117
+ event: EmailEvent,
118
+ reply: NonNullable<EmailEvent["reply"]>,
119
+ ): Record<string, unknown> {
120
+ return {
121
+ /** The RECEIVED message's own id. */
122
+ messageId: event.messageId,
123
+ inReplyTo: reply.inReplyTo ?? null,
124
+ correlated: reply.correlated,
125
+ from: reply.from,
126
+ subject: reply.subject,
127
+ text: reply.text,
128
+ textTruncated: reply.textTruncated,
129
+ recipient: reply.recipient,
130
+ };
131
+ }
132
+
72
133
  /**
73
134
  * The engine-owned high-level mailer. It owns the full send pipeline —
74
135
  * render → preference/suppression check → tracked-html rewrite → `email_sends`
@@ -87,9 +148,23 @@ export function createTrackedMailer(
87
148
  * without it (tests) keeps today's behavior; the container always passes it.
88
149
  */
89
150
  domainStatus?: DomainStatusService;
151
+ /**
152
+ * The INTERNAL bus push used by the `email.replied` path. Defaults to the
153
+ * real {@link pushTrackingEvent}, which resolves identity and pushes the
154
+ * event through `ingestEvent` so a journey can `ctx.waitForEvent` on it.
155
+ *
156
+ * Injectable for the same reason `prepareTrackedHtml` is: the default
157
+ * reaches the identity resolver and Hatchet, and a test asserting WHAT the
158
+ * mailer hands the bus should not have to stand up either.
159
+ */
160
+ pushReplyEvent?: PushReplyEventFn;
90
161
  },
91
162
  ): EmailService {
92
163
  const { provider, domainStatus } = deps;
164
+ const pushReplyEvent: PushReplyEventFn =
165
+ deps.pushReplyEvent ??
166
+ ((opts) =>
167
+ pushTrackingEvent({ ...opts, registry: getJourneyRegistrySingleton() }));
93
168
  const db = config.db as Database | undefined;
94
169
  const retryDefaults = config.retryOptions;
95
170
  const registry = config.templates;
@@ -158,10 +233,18 @@ export function createTrackedMailer(
158
233
  skipPreferenceCheck: options.skipPreferenceCheck,
159
234
  idempotencyKey: options.idempotencyKey,
160
235
  baseUrl: config.baseUrl,
236
+ attachments: options.attachments,
161
237
  },
162
238
  });
163
239
  }
164
240
 
241
+ // No-db attachment gate (the db path guards inside sendTrackedEmailInner,
242
+ // before any row is written): validate + capability-check BEFORE render or
243
+ // provider dispatch — never send the message without its files.
244
+ if (options.attachments?.length) {
245
+ assertAttachmentsSendable(provider, options.attachments);
246
+ }
247
+
165
248
  const { element, subject: defaultSubject } = getTemplate({
166
249
  key: options.template,
167
250
  props: options.props,
@@ -210,8 +293,23 @@ export function createTrackedMailer(
210
293
  subject: wireSubject,
211
294
  html,
212
295
  tags: options.tags,
213
- headers: options.headers,
296
+ // Same wire contract as the tracked path (see withIdempotencyHeader):
297
+ // the key rides as a header, and ONLY to a transport that consumes it —
298
+ // a header-forwarding provider (Resend, Postmark) would deliver it to
299
+ // the recipient. This no-db branch never auto-derives a journey key, so
300
+ // only a caller-supplied one can travel here.
301
+ headers: withIdempotencyHeader(
302
+ options.headers,
303
+ providerConsumesIdempotencyKey(provider)
304
+ ? options.idempotencyKey
305
+ : undefined,
306
+ ),
214
307
  replyTo: options.replyTo,
308
+ // Conditionally spread: a send with no attachments hands the provider
309
+ // options with NO `attachments` key — byte-identical to today's wire.
310
+ ...(options.attachments?.length
311
+ ? { attachments: options.attachments }
312
+ : {}),
215
313
  });
216
314
 
217
315
  return trackedSendResult({
@@ -222,6 +320,12 @@ export function createTrackedMailer(
222
320
  },
223
321
 
224
322
  async sendRaw(options: SendRawOptions): Promise<SendResult> {
323
+ // SendRawOptions IS the core wire contract (minus `from`), so attachments
324
+ // already ride the `...gated` spreads below — the only thing missing
325
+ // would be the gate. Validate + capability-check before anything else.
326
+ if (options.attachments?.length) {
327
+ assertAttachmentsSendable(provider, options.attachments);
328
+ }
225
329
  const gated = applyScheduledAtGate(options);
226
330
  const from = resolveFrom(options.from);
227
331
 
@@ -262,6 +366,16 @@ export function createTrackedMailer(
262
366
  async sendBatch(options: {
263
367
  emails: BatchEmailItem[];
264
368
  }): Promise<{ results: SendResult[] }> {
369
+ // BatchEmailItem inherits `attachments` from the core wire contract, so
370
+ // they already flow through the item spreads below. Gate EVERY item
371
+ // before ANY item reaches the provider — a partial batch where later
372
+ // items silently drop their files is exactly the failure the loud gate
373
+ // exists to prevent.
374
+ for (const item of options.emails) {
375
+ if (item.attachments?.length) {
376
+ assertAttachmentsSendable(provider, item.attachments);
377
+ }
378
+ }
265
379
  const testMode = resolveTestMode(domainStatus);
266
380
 
267
381
  if (testMode) {
@@ -365,26 +479,38 @@ export function createTrackedMailer(
365
479
  // provider with native tracking left ON.
366
480
  await updateEmailStatus(event.type, event.messageId);
367
481
  break;
368
- case "email.bounced":
482
+ case "email.bounced": {
369
483
  // `bounce.class` is stored in `bounceType`, the human reason in
370
484
  // `bounceReason`. Soft/transient bounces are recorded here too (status
371
485
  // `bounced`, `class:'transient'`) — the old transient →
372
486
  // `email.delivery_delayed` no-op is gone.
373
- await updateEmailStatus(event.type, event.messageId, {
374
- bounceType: event.bounce?.class,
375
- bounceReason: event.bounce?.reason,
376
- });
377
- // OUTBOUND `email.bounced` with the bounce detail (class + reason).
378
- await emitProviderEmailEvent("email.bounced", event.messageId, {
379
- bounceType: event.bounce?.class,
380
- bounceReason: event.bounce?.reason,
381
- });
382
- // Suppress (increment bounceCount toward threshold) ONLY on a permanent
383
- // bounce. Transient/unknown are recorded but never auto-suppress.
384
- if (event.bounce?.class === "permanent") {
385
- await handleBounce(event.recipients);
487
+ //
488
+ // The status write is a FIRST-TRANSITION CLAIM, not a plain SET, and
489
+ // everything with a SIDE EFFECT hangs off whether it claimed. SNS is
490
+ // at-least-once and the control plane re-drives a `pending` event row
491
+ // after 60s so a bounce is never lost, so the same bounce reaches here
492
+ // more than once — and with `bounceThreshold` at 3, three redeliveries
493
+ // of ONE bounce would permanently suppress a perfectly deliverable
494
+ // address, silently, with nothing the customer could undo. The emit is
495
+ // gated for the same reason: a redelivery must not double-fire a
496
+ // customer's destination or a journey waiting on `email.bounced`.
497
+ const claim = await claimBounce(event);
498
+ // `unrecorded` counts — see claimBounce. Only a proven duplicate stops.
499
+ if (claim !== "duplicate") {
500
+ // OUTBOUND `email.bounced` with the bounce detail (class + reason).
501
+ await emitProviderEmailEvent("email.bounced", event.messageId, {
502
+ bounceType: event.bounce?.class,
503
+ bounceReason: event.bounce?.reason,
504
+ });
505
+ // Suppress (increment bounceCount toward threshold) ONLY on a
506
+ // permanent bounce. Transient/unknown are recorded but never
507
+ // auto-suppress.
508
+ if (event.bounce?.class === "permanent") {
509
+ await handleBounce(event.recipients);
510
+ }
386
511
  }
387
512
  break;
513
+ }
388
514
  case "email.complained":
389
515
  await updateEmailStatus(event.type, event.messageId);
390
516
  // OUTBOUND `email.complained` — the provider webhook is the SINGLE
@@ -392,6 +518,36 @@ export function createTrackedMailer(
392
518
  await emitProviderEmailEvent("email.complained", event.messageId);
393
519
  await handleComplaint(event.recipients);
394
520
  break;
521
+ case "email.rejected":
522
+ // TERMINAL, and SUPPRESSING NOTHING (PRD 18). The provider accepted
523
+ // the message, returned an id, then threw it away — SES's `Reject`,
524
+ // whose only documented reason is `Bad content` (a virus we sent).
525
+ //
526
+ // Note what is deliberately ABSENT below, because each omission is the
527
+ // decision rather than an oversight:
528
+ // - NO `handleBounce`. The recipient's address is fine. Incrementing
529
+ // `bounceCount` toward the suppression threshold would let one bad
530
+ // attachment permanently block a deliverable address, silently, with
531
+ // nothing the customer could undo.
532
+ // - NO bounce facts on the row. A reject is not a bounce, and writing
533
+ // `bouncedAt` would fold it into every bounce-rate read.
534
+ // - NO outbound emit. The outbound catalog is mirrored by hand into
535
+ // `@hogsend/cli` and `@hogsend/client`, both outside this change's
536
+ // boundary; the `WebhookHandlerMap` slot the neutral type gets for
537
+ // free is the in-boundary seam for a consumer that wants to react.
538
+ await updateEmailStatus(event.type, event.messageId);
539
+ break;
540
+ case "email.replied":
541
+ // A HUMAN REPLIED (PRD 16). Note what is deliberately ABSENT, because
542
+ // each omission is the decision rather than an oversight:
543
+ // - NO `updateEmailStatus`. A reply is not a delivery outcome of our
544
+ // send. The message it answers was delivered and stays delivered;
545
+ // writing a status here would overwrite a real outcome with one no
546
+ // send ever had, and every delivery/bounce-rate read would count it.
547
+ // - NO suppression of any kind. Somebody replying is the strongest
548
+ // evidence an address works.
549
+ await handleReply(event);
550
+ break;
395
551
  case "email.delivery_delayed":
396
552
  // No-op: providers now map transient bounces to `email.bounced` with
397
553
  // `class:'transient'`, so soft bounces are recorded there instead.
@@ -423,6 +579,81 @@ export function createTrackedMailer(
423
579
  return unique;
424
580
  }
425
581
 
582
+ /**
583
+ * The outcome of trying to CLAIM a bounce for its send row.
584
+ *
585
+ * - `first` — this delivery is the one that moved the send into this bounce
586
+ * state. Count it, emit it.
587
+ * - `duplicate` — the send is already in this bounce state, so a previous
588
+ * delivery already counted and emitted. Do neither again.
589
+ * - `unrecorded` — no `email_sends` row carries this `messageId` at all, so
590
+ * there is no send-scoped state to dedupe against. See {@link claimBounce}.
591
+ */
592
+ type BounceClaim = "first" | "duplicate" | "unrecorded";
593
+
594
+ /**
595
+ * Claim a bounce for its send, exactly once per (send, bounce).
596
+ *
597
+ * The mechanism is the codebase's existing first-transition idiom — the
598
+ * `WHERE clickedAt IS NULL` of `routes/tracking/click-pipeline.ts` — applied
599
+ * to the bounce leg: the status write carries a guard, and only the delivery
600
+ * whose UPDATE actually matched a row gets to count and emit. A redelivery
601
+ * matches nothing, writes nothing, and returns `duplicate`. It is one
602
+ * statement, so two redeliveries racing each other still produce one winner.
603
+ *
604
+ * The guard admits ONE escalation, deliberately. A PERMANENT bounce is
605
+ * refused only by a send already marked permanent (`bounce_type IS DISTINCT
606
+ * FROM 'permanent'`, NULL-safe), so a soft bounce recorded first cannot
607
+ * shield the hard bounce that follows it on the same message — that would
608
+ * silently disable suppression for exactly the addresses that need it. Every
609
+ * other class claims only the first bounce of any kind (`bounced_at IS
610
+ * NULL`): they never count, and the guard is there to stop the emit
611
+ * double-firing.
612
+ *
613
+ * WHEN NO ROW MATCHES (`unrecorded`) THE BOUNCE STILL COUNTS. That is the
614
+ * deliberate choice, not an oversight: `sendRaw` writes no `email_sends` row
615
+ * at all, and a provider webhook can outrun the send row's commit, so "no
616
+ * matching row" is a REAL bounce we simply hold no state for. Dropping it
617
+ * would turn a fix for double-counting into a silent hole in suppression for
618
+ * those addresses, which is the worse failure. The residual is that a
619
+ * REDELIVERED bounce for an unrecorded send is still counted twice — there is
620
+ * nothing to key on — so it is logged rather than hidden. (The emit does not
621
+ * double-fire there: it resolves its context from the same missing row and
622
+ * no-ops.)
623
+ */
624
+ async function claimBounce(event: EmailEvent): Promise<BounceClaim> {
625
+ // No db configured: there is no send row to claim, and both `handleBounce`
626
+ // and `emitProviderEmailEvent` no-op without one anyway.
627
+ if (!db) return "unrecorded";
628
+
629
+ const guard =
630
+ event.bounce?.class === "permanent"
631
+ ? sql`${emailSends.bounceType} is distinct from ${"permanent"}`
632
+ : isNull(emailSends.bouncedAt);
633
+
634
+ const claimed = await updateEmailStatus(
635
+ "email.bounced",
636
+ event.messageId,
637
+ { bounceType: event.bounce?.class, bounceReason: event.bounce?.reason },
638
+ guard,
639
+ );
640
+ if (claimed > 0) return "first";
641
+
642
+ // Nothing matched: either the send is already in this bounce state, or we
643
+ // never recorded the send. Only the second may count, so tell them apart.
644
+ const recorded = await resolveEmailSendContextByMessageId(
645
+ db,
646
+ event.messageId,
647
+ );
648
+ if (recorded) return "duplicate";
649
+
650
+ (config.logger ?? emitLogger).warn(
651
+ "bounce for an unrecorded send: counted without send-scoped dedupe",
652
+ { messageId: event.messageId },
653
+ );
654
+ return "unrecorded";
655
+ }
656
+
426
657
  async function handleBounce(recipients: string[]): Promise<void> {
427
658
  if (!db) return;
428
659
  const emails = validRecipients(recipients);
@@ -529,27 +760,131 @@ export function createTrackedMailer(
529
760
  });
530
761
  }
531
762
 
763
+ /**
764
+ * A reply, onto the internal bus and then onto the outbound spine (PRD 16).
765
+ *
766
+ * The ORDER is the design. The bus push is awaited and its failure
767
+ * PROPAGATES, while the spine emit never throws by construction — because the
768
+ * two failures are not the same failure. A journey that never learns a human
769
+ * asked to stop keeps sending, which is the exact harm this feature exists to
770
+ * prevent; so a failed bus push must reach the caller, where the route's
771
+ * non-2xx tells the relay to re-drive (SNS's retry is the durable one, and
772
+ * the idempotency key below is what makes a re-drive safe). A subscriber
773
+ * missing one webhook is an ordinary outbound failure the delivery table
774
+ * already retries.
775
+ *
776
+ * `inReplyTo` is the ONLY thing correlation is allowed to key on, and it is
777
+ * present only when the relay proved the id belongs to a send this instance
778
+ * made. Everything else on `reply` came out of a stranger's message.
779
+ */
780
+ async function handleReply(event: EmailEvent): Promise<void> {
781
+ if (!db) return;
782
+ const reply = event.reply;
783
+ // A provider that named the type and carried no detail. Nothing to
784
+ // correlate and nothing to say — better silent than inventing a payload of
785
+ // nulls that reads like a real reply on every subscriber's dashboard.
786
+ if (!reply) {
787
+ (config.logger ?? emitLogger).warn(
788
+ "email.replied arrived with no reply detail",
789
+ { messageId: event.messageId },
790
+ );
791
+ return;
792
+ }
793
+
794
+ const ctx = reply.inReplyTo
795
+ ? await resolveEmailSendContextByMessageId(db, reply.inReplyTo)
796
+ : null;
797
+
798
+ // The received message's id is stable across every SNS redelivery and
799
+ // every relay re-drive, so it is the dedupe on BOTH legs. A duplicate
800
+ // `email.replied` can exit a journey a second time, and an exit is not a
801
+ // thing that can be taken back.
802
+ const dedupeKey = `reply:${event.messageId}`;
803
+
804
+ // UNCORRELATED replies skip this leg and only this leg: there is no contact
805
+ // key to ingest against, and resolving one from the sender's own `From:`
806
+ // would mint a contact out of a stranger's message (#621). The spine emit
807
+ // below still fires, so the reply is delivered and marked uncorrelated
808
+ // rather than dropped.
809
+ if (ctx) {
810
+ await pushReplyEvent({
811
+ db,
812
+ hatchet,
813
+ logger: config.logger ?? emitLogger,
814
+ event: EMAIL_REPLIED,
815
+ emailSendId: ctx.emailSendId,
816
+ idempotencyKey: dedupeKey,
817
+ properties: replyProperties(event, reply),
818
+ });
819
+ }
820
+
821
+ await emitOutbound({
822
+ db,
823
+ hatchet,
824
+ logger: config.logger ?? emitLogger,
825
+ event: "email.replied",
826
+ dedupeKey,
827
+ payload: {
828
+ messageId: event.messageId,
829
+ inReplyTo: reply.inReplyTo ?? null,
830
+ correlated: reply.correlated,
831
+ emailSendId: ctx?.emailSendId ?? null,
832
+ templateKey: ctx?.templateKey ?? null,
833
+ userId: ctx?.userId ?? null,
834
+ to: ctx?.to ?? null,
835
+ from: reply.from,
836
+ subject: reply.subject,
837
+ text: reply.text,
838
+ textTruncated: reply.textTruncated,
839
+ recipient: reply.recipient,
840
+ at: event.occurredAt,
841
+ },
842
+ });
843
+ }
844
+
845
+ /**
846
+ * Write the send's status for a provider webhook. Returns how many rows the
847
+ * statement wrote, which only the guarded caller reads.
848
+ *
849
+ * `guard` is an EXTRA predicate ANDed onto the message-id match, which turns
850
+ * the plain SET into a first-transition claim (see {@link claimBounce}).
851
+ * Ungarded — every caller but the bounce leg — the write stays a plain SET
852
+ * and so stays replay-safe by writing the same values again. Open/click in
853
+ * particular pass no guard on purpose: their per-hit write is deliberate.
854
+ */
532
855
  async function updateEmailStatus(
533
856
  eventType: EmailEventType,
534
857
  messageId: string,
535
858
  extra?: { bounceType?: string; bounceReason?: string },
536
- ): Promise<void> {
537
- if (!db) return;
859
+ guard?: SQL,
860
+ ): Promise<number> {
861
+ if (!db) return 0;
538
862
 
539
863
  const timestampField = WEBHOOK_TO_STATUS_FIELD[eventType];
540
864
  const status = WEBHOOK_TO_STATUS[eventType];
541
- if (!timestampField || !status) return;
865
+ // The STATUS is what makes a row terminal; the timestamp column is
866
+ // optional. `email.rejected` has a status and no column of its own, and
867
+ // borrowing `bouncedAt` for it would quietly fold every reject into the
868
+ // bounce-rate reads. Every other type still writes both.
869
+ if (!status) return 0;
542
870
 
543
- await db
871
+ const written = await db
544
872
  .update(emailSends)
545
873
  .set({
546
874
  status: status as typeof emailSends.$inferSelect.status,
547
- [timestampField]: new Date(),
875
+ ...(timestampField ? { [timestampField]: new Date() } : {}),
548
876
  ...(extra?.bounceType ? { bounceType: extra.bounceType } : {}),
549
877
  ...(extra?.bounceReason ? { bounceReason: extra.bounceReason } : {}),
550
878
  updatedAt: new Date(),
551
879
  })
552
- .where(eq(emailSends.messageId, messageId));
880
+ .where(
881
+ guard
882
+ ? and(eq(emailSends.messageId, messageId), guard)
883
+ : eq(emailSends.messageId, messageId),
884
+ )
885
+ .returning({ id: emailSends.id });
886
+
887
+ return written.length;
553
888
  }
554
889
 
555
890
  return service;
@@ -0,0 +1,137 @@
1
+ import assert from "node:assert/strict";
2
+ import test from "node:test";
3
+ import type { OutboundPayloads } from "./outbound.js";
4
+
5
+ /**
6
+ * The `account.*` outbound payload shapes (PRD 08 T2).
7
+ *
8
+ * The load-bearing assertion here is not the field list — it is that `version`
9
+ * crosses the wire as a decimal STRING. `linked_accounts.version` is a Postgres
10
+ * `bigint` (DECISIONS §5.1) and the whole consistency contract is a consumer's
11
+ * `incoming.version > stored.version` guard, so a version that has been through
12
+ * a JS `number` at ANY point in the producer is silently wrong above
13
+ * `Number.MAX_SAFE_INTEGER` and breaks the guard in exactly the case it exists
14
+ * for. A type-only test cannot see a `Number(row.version)` in a serializer, so
15
+ * the last two cases are runtime assertions on a BUILT payload.
16
+ */
17
+
18
+ /** The store's row shape, narrowed to what a payload build reads. */
19
+ interface FakeLinkRow {
20
+ provider: string;
21
+ providerUserId: string;
22
+ contactId: string;
23
+ version: bigint;
24
+ }
25
+
26
+ /** Stand-in for the T3 builder: the serialization under test is `String()`. */
27
+ function buildLinkedPayload(
28
+ row: FakeLinkRow,
29
+ ): OutboundPayloads["account.linked"] {
30
+ return {
31
+ state: "linked",
32
+ provider: row.provider,
33
+ providerUserId: row.providerUserId,
34
+ contactId: row.contactId,
35
+ userId: "usr_1",
36
+ email: "player@example.com",
37
+ username: "player",
38
+ method: "oauth",
39
+ relink: false,
40
+ version: String(row.version),
41
+ at: "2026-08-14T00:00:00.000Z",
42
+ };
43
+ }
44
+
45
+ test("an account.linked payload type-checks with every documented field", () => {
46
+ const linked: OutboundPayloads["account.linked"] = {
47
+ state: "linked",
48
+ provider: "steam",
49
+ providerUserId: "76561198000000000",
50
+ contactId: "ct_1",
51
+ userId: "usr_1",
52
+ email: "player@example.com",
53
+ username: "player",
54
+ method: "oauth",
55
+ relink: true,
56
+ version: "3",
57
+ at: "2026-08-14T00:00:00.000Z",
58
+ };
59
+ const unlinked: OutboundPayloads["account.unlinked"] = {
60
+ state: "unlinked",
61
+ provider: "steam",
62
+ providerUserId: "76561198000000000",
63
+ contactId: "ct_1",
64
+ userId: null,
65
+ email: null,
66
+ reason: "relinked",
67
+ version: "2",
68
+ at: "2026-08-14T00:00:00.000Z",
69
+ };
70
+ const failed: OutboundPayloads["account.link_failed"] = {
71
+ provider: "steam",
72
+ reason: "state_invalid",
73
+ contactId: null,
74
+ at: "2026-08-14T00:00:00.000Z",
75
+ };
76
+
77
+ assert.deepEqual(Object.keys(linked).sort(), [
78
+ "at",
79
+ "contactId",
80
+ "email",
81
+ "method",
82
+ "provider",
83
+ "providerUserId",
84
+ "relink",
85
+ "state",
86
+ "userId",
87
+ "username",
88
+ "version",
89
+ ]);
90
+ assert.deepEqual(Object.keys(unlinked).sort(), [
91
+ "at",
92
+ "contactId",
93
+ "email",
94
+ "provider",
95
+ "providerUserId",
96
+ "reason",
97
+ "state",
98
+ "userId",
99
+ "version",
100
+ ]);
101
+ // `account.link_failed` carries NO version and NO state: nothing mutated.
102
+ assert.deepEqual(Object.keys(failed).sort(), [
103
+ "at",
104
+ "contactId",
105
+ "provider",
106
+ "reason",
107
+ ]);
108
+ });
109
+
110
+ test("version serializes as a string, not a number", () => {
111
+ const payload = buildLinkedPayload({
112
+ provider: "steam",
113
+ providerUserId: "76561198000000000",
114
+ contactId: "ct_1",
115
+ version: 7n,
116
+ });
117
+ assert.equal(typeof payload.version, "string");
118
+ assert.equal(payload.version, "7");
119
+ });
120
+
121
+ test("a version above Number.MAX_SAFE_INTEGER round-trips through the payload without loss", () => {
122
+ // ODD and above 2^53: every EVEN integer below 2^54 is exactly representable
123
+ // in float64, so an assertion on an even value passes whether or not the code
124
+ // rounds (DECISIONS §5.1). 9007199254740993 rounds to ...992 through a JS
125
+ // number, so this assertion is non-vacuous.
126
+ const payload = buildLinkedPayload({
127
+ provider: "steam",
128
+ providerUserId: "76561198000000000",
129
+ contactId: "ct_1",
130
+ version: 9007199254740993n,
131
+ });
132
+ const roundTripped = JSON.parse(
133
+ JSON.stringify(payload),
134
+ ) as OutboundPayloads["account.linked"];
135
+ assert.equal(roundTripped.version, "9007199254740993");
136
+ assert.notEqual(String(Number(payload.version)), payload.version);
137
+ });