@pithy-sh/email 0.8.2 → 0.10.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/README.md +2 -0
- package/dist/bounce/handler.d.ts +22 -2
- package/dist/bounce/handler.d.ts.map +1 -1
- package/dist/bounce/handler.js +60 -17
- package/dist/capability.d.ts +12 -0
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +25 -15
- package/dist/crypto/signingKey.d.ts.map +1 -1
- package/dist/crypto/token.d.ts +43 -11
- package/dist/crypto/token.d.ts.map +1 -1
- package/dist/crypto/token.js +158 -55
- package/dist/http/callbacks.d.ts +8 -3
- package/dist/http/callbacks.d.ts.map +1 -1
- package/dist/http/callbacks.js +67 -12
- package/dist/http/guards.d.ts.map +1 -1
- package/dist/http/guards.js +9 -0
- package/dist/http/routes.d.ts +8 -4
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +67 -21
- package/dist/http/schemas.d.ts +41 -13
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +38 -15
- package/dist/jobs/read.d.ts +12 -9
- package/dist/jobs/read.d.ts.map +1 -1
- package/dist/jobs/read.js +6 -5
- package/dist/migrations/0002_job_filters.d.ts +15 -0
- package/dist/migrations/0002_job_filters.d.ts.map +1 -0
- package/dist/migrations/0002_job_filters.js +25 -0
- package/dist/send/enqueue.d.ts +26 -3
- package/dist/send/enqueue.d.ts.map +1 -1
- package/dist/send/enqueue.js +25 -2
- package/dist/send/errorMapping.d.ts +15 -20
- package/dist/send/errorMapping.d.ts.map +1 -1
- package/dist/send/errorMapping.js +33 -27
- package/dist/send/runSend.d.ts +2 -2
- package/dist/send/runSend.d.ts.map +1 -1
- package/dist/send/runSend.js +1 -1
- package/dist/send/suppression.d.ts +4 -0
- package/dist/send/suppression.d.ts.map +1 -1
- package/dist/send/suppression.js +4 -0
- package/dist/templates/engine.d.ts +1 -1
- package/dist/templates/engine.js +1 -1
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.d.ts.map +1 -1
- package/dist/version.generated.js +1 -1
- package/package.json +3 -3
- package/src/bounce/handler.ts +84 -32
- package/src/capability.ts +47 -27
- package/src/crypto/signingKey.ts +4 -2
- package/src/crypto/token.ts +225 -92
- package/src/http/callbacks.ts +100 -32
- package/src/http/guards.ts +9 -0
- package/src/http/routes.ts +96 -28
- package/src/http/schemas.ts +75 -24
- package/src/jobs/read.ts +14 -9
- package/src/migrations/0002_job_filters.ts +35 -0
- package/src/send/enqueue.ts +52 -5
- package/src/send/errorMapping.ts +45 -38
- package/src/send/runSend.ts +6 -7
- package/src/send/suppression.ts +13 -0
- package/src/templates/engine.ts +1 -1
- package/src/version.generated.ts +1 -1
package/src/send/errorMapping.ts
CHANGED
|
@@ -17,18 +17,12 @@ export interface ClassifiedSendError {
|
|
|
17
17
|
/** The `E_*` code reported by the binding, a numeric provider code as a string, or `E_UNKNOWN` for none. */
|
|
18
18
|
code: string;
|
|
19
19
|
/**
|
|
20
|
-
* The cause, as one operator-facing line: the code
|
|
20
|
+
* The cause, as one operator-facing line: the code, whatever the provider said with it, and the sending domain
|
|
21
|
+
* when the code says that domain cannot send.
|
|
21
22
|
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
* while this exact string, naming `10000 Authentication error`, was being built two lines down and
|
|
26
|
-
* thrown away with the error it decorated. Same family as #534: a failure that discards the cause it
|
|
27
|
-
* was handed.
|
|
28
|
-
*
|
|
29
|
-
* Identical to `error.payload.detail`, deliberately — one composition, two readers, so the row and the
|
|
30
|
-
* log cannot drift. `detail` is stripped at the client boundary, which is where a provider's own words
|
|
31
|
-
* belong.
|
|
23
|
+
* `runSend` writes it to `pithy_email_jobs.error`, so the row names the cause rather than the bare code.
|
|
24
|
+
* Identical to `error.payload.detail`: one composition, two readers, so the row and the log cannot drift.
|
|
25
|
+
* `detail` is stripped at the client boundary, which is where a provider's own words belong.
|
|
32
26
|
*/
|
|
33
27
|
detail: string;
|
|
34
28
|
/** Whether the send should be retried with backoff. */
|
|
@@ -55,18 +49,31 @@ const RATE_LIMITED = new Set(["E_RATE_LIMIT_EXCEEDED", "E_DAILY_LIMIT_EXCEEDED"]
|
|
|
55
49
|
*
|
|
56
50
|
* `10000` is Cloudflare's own: a token that is alive but not scoped for Email Sending, or scoped for an
|
|
57
51
|
* account that does not own the sending domain, is answered `{ code: 10000, message: "Authentication
|
|
58
|
-
* error" }` (
|
|
59
|
-
* general account token). That is the exact failure #555 spent five attempts on in silence.
|
|
52
|
+
* error" }` (`liveSend.integration.test.ts` documents the same rejection for a general account token).
|
|
60
53
|
*
|
|
61
|
-
* **
|
|
62
|
-
*
|
|
63
|
-
*
|
|
64
|
-
*
|
|
65
|
-
* bounded retry since the module was written. So the auth class is listed, and the rule below is
|
|
66
|
-
* unchanged for everything else.
|
|
54
|
+
* **Listed rather than inferred from the code being numeric.** Treating every numeric code as terminal would
|
|
55
|
+
* make a momentary numeric failure permanent too — one attempt, `status: "failed"`, where the retry budget
|
|
56
|
+
* applies. A code nobody here recognizes is still unknown, whichever alphabet it is written in, and unknown
|
|
57
|
+
* keeps its bounded retry.
|
|
67
58
|
*/
|
|
68
59
|
const UNAUTHORIZED = new Set(["10000", "E_UNAUTHORIZED", "E_FORBIDDEN"]);
|
|
69
60
|
|
|
61
|
+
/**
|
|
62
|
+
* Codes that mean **the sender's domain cannot send**: not onboarded onto Email Service, or not verified.
|
|
63
|
+
* Terminal like every unlisted `E_*`, and named so the job's error says which domain to onboard.
|
|
64
|
+
*/
|
|
65
|
+
const SENDER_DOMAIN = new Set(["E_SENDER_DOMAIN_NOT_AVAILABLE", "E_SENDER_NOT_VERIFIED"]);
|
|
66
|
+
|
|
67
|
+
/** The domain half of an address, lowercased, or `null` when it carries none. */
|
|
68
|
+
function domainOf(address: string): string | null {
|
|
69
|
+
const at = address.lastIndexOf("@");
|
|
70
|
+
if (at < 0 || at === address.length - 1) return null;
|
|
71
|
+
return address
|
|
72
|
+
.slice(at + 1)
|
|
73
|
+
.trim()
|
|
74
|
+
.toLowerCase();
|
|
75
|
+
}
|
|
76
|
+
|
|
70
77
|
/**
|
|
71
78
|
* Whether a code is one of Cloudflare's numeric ones rather than the binding's `E_*` spelling.
|
|
72
79
|
*
|
|
@@ -83,16 +90,14 @@ function isProviderNumericCode(code: string): boolean {
|
|
|
83
90
|
/**
|
|
84
91
|
* Read a thrown value's `.code`/`.message` without assuming its shape.
|
|
85
92
|
*
|
|
86
|
-
* **A numeric code counts
|
|
87
|
-
*
|
|
88
|
-
*
|
|
89
|
-
*
|
|
90
|
-
* consumed every attempt without ever naming itself (#555).
|
|
93
|
+
* **A numeric code counts.** The Email Service binding surfaces `E_*` strings, but the REST path and the
|
|
94
|
+
* account layer behind it answer with Cloudflare's own numeric codes — an unauthorized send is
|
|
95
|
+
* `{ code: 10000, message: "Authentication error" }`. Read as "no code" that would be `E_UNKNOWN`, which is
|
|
96
|
+
* both silent *and* retryable, so a credential fault would consume every attempt without naming itself.
|
|
91
97
|
*
|
|
92
|
-
* **
|
|
93
|
-
*
|
|
94
|
-
*
|
|
95
|
-
* earns the bounded retry.
|
|
98
|
+
* **A value with neither field still leaves a trace.** `String(err)` rather than `""`: an opaque throw is
|
|
99
|
+
* the case where the operator has least to go on. `E_UNKNOWN` remains the code — it means *nothing named
|
|
100
|
+
* itself*, which is the fact that earns the bounded retry.
|
|
96
101
|
*/
|
|
97
102
|
function readError(err: unknown): { code: string; message: string } {
|
|
98
103
|
if (err && typeof err === "object") {
|
|
@@ -112,19 +117,21 @@ function readError(err: unknown): { code: string; message: string } {
|
|
|
112
117
|
* suppressed locally too; rate/quota and transient delivery codes are retryable; everything else
|
|
113
118
|
* (validation, sender, content, headers) is terminal.
|
|
114
119
|
*
|
|
115
|
-
* **An unrecognized code is retryable
|
|
116
|
-
*
|
|
117
|
-
*
|
|
120
|
+
* **An unrecognized code is retryable**: a failure with no code at all keeps its bounded retry, and so does
|
|
121
|
+
* a *numeric* provider code nobody here has listed — see {@link isProviderNumericCode} for why those two are
|
|
122
|
+
* alike and an unlisted `E_*` is not. The **authentication** class is named and terminal: `10000
|
|
123
|
+
* Authentication error` is a token that cannot send as this domain, and no retry changes that — see
|
|
124
|
+
* {@link UNAUTHORIZED} for why that is a list rather than "numeric means permanent".
|
|
118
125
|
*
|
|
119
|
-
*
|
|
120
|
-
*
|
|
121
|
-
* silence is what hid the whole incident. See {@link UNAUTHORIZED} for why that is a list rather than
|
|
122
|
-
* "numeric means permanent" — the latter was this fix's first shape, and it made a momentary numeric
|
|
123
|
-
* failure permanent as a side effect.
|
|
126
|
+
* `context.fromAddress` is the job's sender. When the code says its domain cannot send, the detail names the
|
|
127
|
+
* domain, so the operator knows which one to onboard.
|
|
124
128
|
*/
|
|
125
|
-
export function classifySendError(err: unknown): ClassifiedSendError {
|
|
129
|
+
export function classifySendError(err: unknown, context: { fromAddress?: string } = {}): ClassifiedSendError {
|
|
126
130
|
const { code, message } = readError(err);
|
|
127
|
-
const
|
|
131
|
+
const domain = SENDER_DOMAIN.has(code) && context.fromAddress ? domainOf(context.fromAddress) : null;
|
|
132
|
+
const detail = `email send failed: ${code}${message ? ` — ${message}` : ""}${
|
|
133
|
+
domain ? ` (${domain} is not set up for sending on Email Service)` : ""
|
|
134
|
+
}`;
|
|
128
135
|
|
|
129
136
|
if (code === "E_RECIPIENT_SUPPRESSED") {
|
|
130
137
|
return {
|
package/src/send/runSend.ts
CHANGED
|
@@ -73,11 +73,11 @@ export interface SendDeps {
|
|
|
73
73
|
/** This worker's environment name, stamped on each send (X-Pithy-Env) so the single inbound worker can route. */
|
|
74
74
|
environment?: string;
|
|
75
75
|
/**
|
|
76
|
-
* When this pass began — **stable across a Workflow resume
|
|
76
|
+
* When this pass began — **stable across a Workflow resume**.
|
|
77
77
|
*
|
|
78
78
|
* Everything that dates the work reads this: `sentAt`, the redaction stamp, the events, and how long a
|
|
79
79
|
* tracked link stays valid. A driver body re-executes from the top on a resume, so a clock read there
|
|
80
|
-
* answers with the resume —
|
|
80
|
+
* answers with the resume — a batch that backed off overnight would date its remaining jobs, and the
|
|
81
81
|
* expiry of every link in them, a day late. `runSendBatch` journals this in a step so a resume reads
|
|
82
82
|
* back the instant the batch began.
|
|
83
83
|
*
|
|
@@ -294,7 +294,7 @@ export async function runSend(deps: SendDeps, jobId: string): Promise<SendOutcom
|
|
|
294
294
|
|
|
295
295
|
return { jobId, status: "sent", messageId: result.messageId };
|
|
296
296
|
} catch (err) {
|
|
297
|
-
const classified = classifySendError(err);
|
|
297
|
+
const classified = classifySendError(err, { fromAddress: job.fromAddress });
|
|
298
298
|
|
|
299
299
|
if (classified.suppressed) {
|
|
300
300
|
await patchJob(deps, jobId, { status: "suppressed", error: classified.code, bounceCode: classified.code });
|
|
@@ -313,10 +313,9 @@ export async function runSend(deps: SendDeps, jobId: string): Promise<SendOutcom
|
|
|
313
313
|
throw classified.error;
|
|
314
314
|
}
|
|
315
315
|
|
|
316
|
-
// **`detail`, not `code`.** The column is
|
|
317
|
-
//
|
|
318
|
-
//
|
|
319
|
-
// family). `detail` leads with the code, so nothing a reader had before is lost.
|
|
316
|
+
// **`detail`, not `code`.** The column is "the last error code/message", and the bare code says nothing
|
|
317
|
+
// about why — `detail` leads with the code and adds the provider's words and, for a domain that cannot
|
|
318
|
+
// send, the domain. The job keeps its own sender: nothing is retried as another one.
|
|
320
319
|
await patchJob(deps, jobId, { status: "failed", error: classified.detail });
|
|
321
320
|
await recordEvent(deps.db, { jobId, recipient, type: "failed", detail: classified.detail }, deps.passStartedAt);
|
|
322
321
|
return { jobId, status: "failed" };
|
package/src/send/suppression.ts
CHANGED
|
@@ -129,6 +129,10 @@ export interface SuppressionListFilter {
|
|
|
129
129
|
reason?: SuppressionReason;
|
|
130
130
|
/** Look one address up exactly, rather than paging the list. */
|
|
131
131
|
email?: string;
|
|
132
|
+
/** The blocks in force at `now` (`true`), or the ones whose expiry has passed (`false`). Every row when absent. */
|
|
133
|
+
active?: boolean;
|
|
134
|
+
/** The instant `active` is judged at. Defaults to the moment of the read. */
|
|
135
|
+
now?: Date;
|
|
132
136
|
/** The previous page's `nextCursor`. A malformed one is a first page. */
|
|
133
137
|
cursor?: string;
|
|
134
138
|
/** How many rows to return, clamped into range. */
|
|
@@ -182,6 +186,15 @@ export async function listSuppressions(
|
|
|
182
186
|
// neighbors would be a way to enumerate the list one query at a time while looking like a question
|
|
183
187
|
// about a single address.
|
|
184
188
|
if (filter.email) query = query.where("email", "=", normalizeAddress(filter.email));
|
|
189
|
+
if (filter.active !== undefined) {
|
|
190
|
+
// The expiry is exclusive, as `suppressionView` reads it: at the instant it names, the block is over.
|
|
191
|
+
const at = SQLiteDate.encode(filter.now ?? new Date());
|
|
192
|
+
query = query.where((eb) =>
|
|
193
|
+
filter.active
|
|
194
|
+
? eb.or([eb("expiresAt", "is", null), eb("expiresAt", ">", at)])
|
|
195
|
+
: eb.and([eb("expiresAt", "is not", null), eb("expiresAt", "<=", at)]),
|
|
196
|
+
);
|
|
197
|
+
}
|
|
185
198
|
if (after) {
|
|
186
199
|
query = query.where((eb) =>
|
|
187
200
|
eb.or([eb("createdAt", "<", after.sort), eb.and([eb("createdAt", "=", after.sort), eb("id", "<", after.id)])]),
|
package/src/templates/engine.ts
CHANGED
|
@@ -19,7 +19,7 @@ import { type EmailTheme, widthPx } from "./theme";
|
|
|
19
19
|
* evals at request time (CLAUDE.md §Email: "precompiled, no runtime compile/eval"). Rendering is then
|
|
20
20
|
* pure string substitution.
|
|
21
21
|
*
|
|
22
|
-
* Tracking is applied here, not in the template: callback tokens are minted ahead of render (
|
|
22
|
+
* Tracking is applied here, not in the template: callback tokens are minted ahead of render (sealing
|
|
23
23
|
* is async; Handlebars helpers are not) and the resulting URLs are placed into the render context.
|
|
24
24
|
* Click tracking rewrites the declared link locations; open tracking injects a pixel; and an **elective**
|
|
25
25
|
* template gets an unsubscribe link, which a marketing template additionally cannot render without.
|
package/src/version.generated.ts
CHANGED