@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
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 {
|
|
41
|
-
|
|
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
|
-
|
|
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
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
//
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
//
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
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
|
-
|
|
537
|
-
|
|
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
|
-
|
|
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(
|
|
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;
|
package/src/lib/outbound.ts
CHANGED
|
@@ -211,6 +211,41 @@ export interface OutboundPayloads {
|
|
|
211
211
|
complaintType?: string;
|
|
212
212
|
reason?: string;
|
|
213
213
|
};
|
|
214
|
+
/**
|
|
215
|
+
* A HUMAN REPLIED (PRD 16). The one email event that reports a message
|
|
216
|
+
* coming BACK, so its shape is deliberately NOT `EmailEventPayload`: every
|
|
217
|
+
* send-context field is NULLABLE because a reply that could not be
|
|
218
|
+
* correlated to an `email_sends` row is still delivered here rather than
|
|
219
|
+
* dropped, exactly as the uncorrelated-reply EARS requires.
|
|
220
|
+
*
|
|
221
|
+
* `messageId` is the RECEIVED message's id; `inReplyTo` is the id of OUR
|
|
222
|
+
* send it answers, and it is present only when the relay PROVED that send
|
|
223
|
+
* belongs to this instance. A subscriber may key on `inReplyTo`; it must
|
|
224
|
+
* never key on anything else here, because every other field came out of a
|
|
225
|
+
* message a stranger composed.
|
|
226
|
+
*/
|
|
227
|
+
"email.replied": {
|
|
228
|
+
/** The inbound message's own id — never the id of the send it answers. */
|
|
229
|
+
messageId: string;
|
|
230
|
+
/** OUR send's message id, proven. Null on an uncorrelated reply. */
|
|
231
|
+
inReplyTo: string | null;
|
|
232
|
+
correlated: boolean;
|
|
233
|
+
/** Send context, all null when uncorrelated. */
|
|
234
|
+
emailSendId: string | null;
|
|
235
|
+
templateKey: string | null;
|
|
236
|
+
userId: string | null;
|
|
237
|
+
/** The address WE sent to — not the reply's sender. Null uncorrelated. */
|
|
238
|
+
to: string | null;
|
|
239
|
+
/** The reply's sender, as parsed. Attacker-supplied; display only. */
|
|
240
|
+
from: string | null;
|
|
241
|
+
subject: string | null;
|
|
242
|
+
/** Bounded plain text. Never HTML. */
|
|
243
|
+
text: string | null;
|
|
244
|
+
textTruncated: boolean;
|
|
245
|
+
/** The address the reply arrived at (`hello@reply.acme.com`). */
|
|
246
|
+
recipient: string;
|
|
247
|
+
at: string;
|
|
248
|
+
};
|
|
214
249
|
"sms.sent": {
|
|
215
250
|
smsSendId: string;
|
|
216
251
|
messageId: string;
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
|
|
4
|
+
import {
|
|
5
|
+
exampleSendingSubdomain,
|
|
6
|
+
looksLikeRootDomain,
|
|
7
|
+
SENDING_DOMAIN_GUIDANCE,
|
|
8
|
+
} from "./sending-domain-guidance.js";
|
|
9
|
+
|
|
10
|
+
// Same single-label rule apps/cloud/src/lib/sending-domains.ts enforces for
|
|
11
|
+
// return-path labels — a label we RECOMMEND must be one we can publish.
|
|
12
|
+
const DNS_LABEL_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
|
|
13
|
+
|
|
14
|
+
test("looksLikeRootDomain: true for bare two-label domains", () => {
|
|
15
|
+
assert.equal(looksLikeRootDomain("acme.com"), true);
|
|
16
|
+
});
|
|
17
|
+
|
|
18
|
+
test("looksLikeRootDomain: normalizes case", () => {
|
|
19
|
+
assert.equal(looksLikeRootDomain("ACME.COM"), true);
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
test("looksLikeRootDomain: strips a trailing dot", () => {
|
|
23
|
+
assert.equal(looksLikeRootDomain("acme.com."), true);
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
test("looksLikeRootDomain: true for known multi-part public suffixes", () => {
|
|
27
|
+
assert.equal(looksLikeRootDomain("acme.co.uk"), true);
|
|
28
|
+
assert.equal(looksLikeRootDomain("acme.com.au"), true);
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
test("looksLikeRootDomain: false for subdomains", () => {
|
|
32
|
+
assert.equal(looksLikeRootDomain("notifications.acme.com"), false);
|
|
33
|
+
assert.equal(looksLikeRootDomain("mail.acme.co.uk"), false);
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
test("looksLikeRootDomain: false for empty / whitespace / single label", () => {
|
|
37
|
+
assert.equal(looksLikeRootDomain(""), false);
|
|
38
|
+
assert.equal(looksLikeRootDomain(" "), false);
|
|
39
|
+
assert.equal(looksLikeRootDomain("localhost"), false);
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
test("exampleSendingSubdomain prefixes the first recommended label", () => {
|
|
43
|
+
assert.equal(exampleSendingSubdomain("acme.com"), "notifications.acme.com");
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
test("guidance constant is frozen", () => {
|
|
47
|
+
assert.equal(Object.isFrozen(SENDING_DOMAIN_GUIDANCE), true);
|
|
48
|
+
assert.equal(
|
|
49
|
+
Object.isFrozen(SENDING_DOMAIN_GUIDANCE.recommendedLabels),
|
|
50
|
+
true,
|
|
51
|
+
);
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
test("recommended labels are valid single DNS labels", () => {
|
|
55
|
+
assert.ok(SENDING_DOMAIN_GUIDANCE.recommendedLabels.length > 0);
|
|
56
|
+
for (const label of SENDING_DOMAIN_GUIDANCE.recommendedLabels) {
|
|
57
|
+
assert.match(label, DNS_LABEL_RE);
|
|
58
|
+
}
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
// --- Wire proof: the field reaches the EngineDomainStatus snapshot ----------
|
|
62
|
+
// No engine-package test file covers getStatus (the existing coverage lives in
|
|
63
|
+
// apps/api vitest), so the assertion is made here by constructing the service
|
|
64
|
+
// with a domains-less provider — getStatus resolves instantly without any
|
|
65
|
+
// provider call.
|
|
66
|
+
|
|
67
|
+
const { createDomainStatusService } = await import("./domain-status.js");
|
|
68
|
+
|
|
69
|
+
type EngineEnv = Parameters<typeof createDomainStatusService>[0]["env"];
|
|
70
|
+
type EngineLogger = Parameters<typeof createDomainStatusService>[0]["logger"];
|
|
71
|
+
type EngineProvider = Parameters<
|
|
72
|
+
typeof createDomainStatusService
|
|
73
|
+
>[0]["provider"];
|
|
74
|
+
|
|
75
|
+
const noopLogger = {
|
|
76
|
+
error: () => {},
|
|
77
|
+
warn: () => {},
|
|
78
|
+
info: () => {},
|
|
79
|
+
http: () => {},
|
|
80
|
+
debug: () => {},
|
|
81
|
+
} as unknown as EngineLogger;
|
|
82
|
+
|
|
83
|
+
test("getStatus snapshot carries the guidance block", async () => {
|
|
84
|
+
const service = createDomainStatusService({
|
|
85
|
+
provider: { meta: { id: "resend", name: "Resend" } } as EngineProvider,
|
|
86
|
+
env: {
|
|
87
|
+
EMAIL_DOMAIN: "acme.com",
|
|
88
|
+
EMAIL_FROM: undefined,
|
|
89
|
+
RESEND_FROM_EMAIL: undefined,
|
|
90
|
+
HOGSEND_TEST_MODE: "auto",
|
|
91
|
+
HOGSEND_TEST_EMAIL: undefined,
|
|
92
|
+
STUDIO_ADMIN_EMAIL: undefined,
|
|
93
|
+
} as unknown as EngineEnv,
|
|
94
|
+
logger: noopLogger,
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
const snapshot = await service.getStatus();
|
|
98
|
+
assert.equal(snapshot.guidance.title, "Send from a subdomain");
|
|
99
|
+
});
|