@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.
Files changed (62) hide show
  1. package/README.md +2 -0
  2. package/dist/bounce/handler.d.ts +22 -2
  3. package/dist/bounce/handler.d.ts.map +1 -1
  4. package/dist/bounce/handler.js +60 -17
  5. package/dist/capability.d.ts +12 -0
  6. package/dist/capability.d.ts.map +1 -1
  7. package/dist/capability.js +25 -15
  8. package/dist/crypto/signingKey.d.ts.map +1 -1
  9. package/dist/crypto/token.d.ts +43 -11
  10. package/dist/crypto/token.d.ts.map +1 -1
  11. package/dist/crypto/token.js +158 -55
  12. package/dist/http/callbacks.d.ts +8 -3
  13. package/dist/http/callbacks.d.ts.map +1 -1
  14. package/dist/http/callbacks.js +67 -12
  15. package/dist/http/guards.d.ts.map +1 -1
  16. package/dist/http/guards.js +9 -0
  17. package/dist/http/routes.d.ts +8 -4
  18. package/dist/http/routes.d.ts.map +1 -1
  19. package/dist/http/routes.js +67 -21
  20. package/dist/http/schemas.d.ts +41 -13
  21. package/dist/http/schemas.d.ts.map +1 -1
  22. package/dist/http/schemas.js +38 -15
  23. package/dist/jobs/read.d.ts +12 -9
  24. package/dist/jobs/read.d.ts.map +1 -1
  25. package/dist/jobs/read.js +6 -5
  26. package/dist/migrations/0002_job_filters.d.ts +15 -0
  27. package/dist/migrations/0002_job_filters.d.ts.map +1 -0
  28. package/dist/migrations/0002_job_filters.js +25 -0
  29. package/dist/send/enqueue.d.ts +26 -3
  30. package/dist/send/enqueue.d.ts.map +1 -1
  31. package/dist/send/enqueue.js +25 -2
  32. package/dist/send/errorMapping.d.ts +15 -20
  33. package/dist/send/errorMapping.d.ts.map +1 -1
  34. package/dist/send/errorMapping.js +33 -27
  35. package/dist/send/runSend.d.ts +2 -2
  36. package/dist/send/runSend.d.ts.map +1 -1
  37. package/dist/send/runSend.js +1 -1
  38. package/dist/send/suppression.d.ts +4 -0
  39. package/dist/send/suppression.d.ts.map +1 -1
  40. package/dist/send/suppression.js +4 -0
  41. package/dist/templates/engine.d.ts +1 -1
  42. package/dist/templates/engine.js +1 -1
  43. package/dist/version.generated.d.ts +1 -1
  44. package/dist/version.generated.d.ts.map +1 -1
  45. package/dist/version.generated.js +1 -1
  46. package/package.json +3 -3
  47. package/src/bounce/handler.ts +84 -32
  48. package/src/capability.ts +47 -27
  49. package/src/crypto/signingKey.ts +4 -2
  50. package/src/crypto/token.ts +225 -92
  51. package/src/http/callbacks.ts +100 -32
  52. package/src/http/guards.ts +9 -0
  53. package/src/http/routes.ts +96 -28
  54. package/src/http/schemas.ts +75 -24
  55. package/src/jobs/read.ts +14 -9
  56. package/src/migrations/0002_job_filters.ts +35 -0
  57. package/src/send/enqueue.ts +52 -5
  58. package/src/send/errorMapping.ts +45 -38
  59. package/src/send/runSend.ts +6 -7
  60. package/src/send/suppression.ts +13 -0
  61. package/src/templates/engine.ts +1 -1
  62. package/src/version.generated.ts +1 -1
@@ -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 and whatever the provider said with it.
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
- * **Exposed because the job row needs it and only the error object had it (pithy-sh/pithy#555).**
23
- * `runSend` persisted the bare `code` into `pithy_email_jobs.error`, so a magic link that failed five
24
- * times against a token for the wrong account recorded `E_UNKNOWN` five times and nothing about why —
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" }` (#534 captured the body; `liveSend.integration.test.ts` documents the same rejection for a
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
- * **Named rather than inferred from the code being numeric.** Treating every numeric code as terminal was
62
- * the first shape of this fix and it bought the auth case by making a *momentary* numeric failure
63
- * permanent too — one attempt, `status: "failed"`, where the retry budget used to apply. A code nobody
64
- * here recognizes is still unknown, whichever alphabet it is written in, and unknown has earned its
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, and that is not a detail.** The Email Service binding surfaces `E_*` strings,
87
- * but the REST path and the account layer behind it answer with Cloudflare's own numeric codes — an
88
- * unauthorized send is `{ code: 10000, message: "Authentication error" }` (#534 captured the body). Read
89
- * as "no code" that became `E_UNKNOWN`, which is both silent *and* retryable, so a credential fault
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
- * **And a value with neither field still leaves a trace.** `String(err)` rather than `""`: an opaque
93
- * throw is the case where the operator has least to go on, so an empty string is the one answer that
94
- * cannot help. `E_UNKNOWN` remains the code — it means *nothing named itself*, which is the fact that
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, and that is deliberately unchanged.** A failure this module has
116
- * no code at all keeps its bounded retry, and so does a *numeric* provider code nobody here has listed —
117
- * see {@link isProviderNumericCode} for why those two are alike and an unlisted `E_*` is not.
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
- * What changed for #555 is that the **authentication** class is now named and terminal: `10000
120
- * Authentication error` is a token that cannot send as this domain, and spending five attempts on it in
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 detail = `email send failed: ${code}${message ? ` — ${message}` : ""}`;
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 {
@@ -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** (pithy-sh/pithy#327).
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 — and a batch that backed off overnight dated its remaining jobs, and the
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 described as "the last error code/message", and it held only
317
- // the code — so a magic link that failed five times recorded `E_UNKNOWN` five times, and the one
318
- // sentence naming the cause was discarded with the error object (pithy-sh/pithy#555, and #534's
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" };
@@ -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)])]),
@@ -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 (signing
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.
@@ -13,4 +13,4 @@
13
13
  export const PACKAGE_NAME = "@pithy-sh/email";
14
14
 
15
15
  /** This package's version, stamped from its own package.json at generation time. */
16
- export const PACKAGE_VERSION = "0.8.2";
16
+ export const PACKAGE_VERSION = "0.10.0";