@pithy-sh/email 0.2.0 → 0.3.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.
@@ -10,8 +10,23 @@ import type { PithyError } from "@pithy-sh/core/src/error/pithyError";
10
10
  */
11
11
  /** How a given send error is handled: which Pithy error to raise, and whether the send Workflow retries. */
12
12
  export interface ClassifiedSendError {
13
- /** The `E_*` code reported by the binding, or `E_UNKNOWN` when none was present. */
13
+ /** The `E_*` code reported by the binding, a numeric provider code as a string, or `E_UNKNOWN` for none. */
14
14
  code: string;
15
+ /**
16
+ * The cause, as one operator-facing line: the code and whatever the provider said with it.
17
+ *
18
+ * **Exposed because the job row needs it and only the error object had it (pithy-sh/pithy#555).**
19
+ * `runSend` persisted the bare `code` into `pithy_email_jobs.error`, so a magic link that failed five
20
+ * times against a token for the wrong account recorded `E_UNKNOWN` five times and nothing about why —
21
+ * while this exact string, naming `10000 Authentication error`, was being built two lines down and
22
+ * thrown away with the error it decorated. Same family as #534: a failure that discards the cause it
23
+ * was handed.
24
+ *
25
+ * Identical to `error.payload.detail`, deliberately — one composition, two readers, so the row and the
26
+ * log cannot drift. `detail` is stripped at the client boundary, which is where a provider's own words
27
+ * belong.
28
+ */
29
+ detail: string;
15
30
  /** Whether the send should be retried with backoff. */
16
31
  retryable: boolean;
17
32
  /** Whether the failure means the recipient is suppressed (so the address should be locally suppressed). */
@@ -22,8 +37,17 @@ export interface ClassifiedSendError {
22
37
  /**
23
38
  * Classify a send failure. `E_RECIPIENT_SUPPRESSED` is terminal and means the address must be
24
39
  * suppressed locally too; rate/quota and transient delivery codes are retryable; everything else
25
- * (validation, sender, content, headers) is terminal. An unknown code is treated as a transient
26
- * failure so a momentary fault gets one bounded retry rather than failing the job outright.
40
+ * (validation, sender, content, headers) is terminal.
41
+ *
42
+ * **An unrecognized code is retryable, and that is deliberately unchanged.** A failure this module has
43
+ * no code at all keeps its bounded retry, and so does a *numeric* provider code nobody here has listed —
44
+ * see {@link isProviderNumericCode} for why those two are alike and an unlisted `E_*` is not.
45
+ *
46
+ * What changed for #555 is that the **authentication** class is now named and terminal: `10000
47
+ * Authentication error` is a token that cannot send as this domain, and spending five attempts on it in
48
+ * silence is what hid the whole incident. See {@link UNAUTHORIZED} for why that is a list rather than
49
+ * "numeric means permanent" — the latter was this fix's first shape, and it made a momentary numeric
50
+ * failure permanent as a side effect.
27
51
  */
28
52
  export declare function classifySendError(err: unknown): ClassifiedSendError;
29
53
  //# sourceMappingURL=errorMapping.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"errorMapping.d.ts","sourceRoot":"","sources":["../../src/send/errorMapping.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAGtE;;;;;;GAMG;AAEH,4GAA4G;AAC5G,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,SAAS,EAAE,OAAO,CAAC;IACnB,2GAA2G;IAC3G,UAAU,EAAE,OAAO,CAAC;IACpB,qFAAqF;IACrF,KAAK,EAAE,UAAU,CAAC;CACnB;AAuBD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,mBAAmB,CAmBnE"}
1
+ {"version":3,"file":"errorMapping.d.ts","sourceRoot":"","sources":["../../src/send/errorMapping.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAGtE;;;;;;GAMG;AAEH,4GAA4G;AAC5G,MAAM,WAAW,mBAAmB;IAClC,4GAA4G;IAC5G,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;;OAaG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,SAAS,EAAE,OAAO,CAAC;IACnB,2GAA2G;IAC3G,UAAU,EAAE,OAAO,CAAC;IACpB,qFAAqF;IACrF,KAAK,EAAE,UAAU,CAAC;CACnB;AAsED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,mBAAmB,CA6BnE"}
@@ -11,41 +11,103 @@ const RETRYABLE = /* @__PURE__ */ new Set([
11
11
  ]);
12
12
  /** Rate/quota codes map to the dedicated 429 error so the cause reads clearly in logs. */
13
13
  const RATE_LIMITED = /* @__PURE__ */ new Set(["E_RATE_LIMIT_EXCEEDED", "E_DAILY_LIMIT_EXCEEDED"]);
14
- /** Read a thrown value's `.code`/`.message` without assuming its shape. */
14
+ /**
15
+ * Codes that mean **this Worker could not authenticate** — terminal, because no retry clears a credential.
16
+ *
17
+ * `10000` is Cloudflare's own: a token that is alive but not scoped for Email Sending, or scoped for an
18
+ * account that does not own the sending domain, is answered `{ code: 10000, message: "Authentication
19
+ * error" }` (#534 captured the body; `liveSend.integration.test.ts` documents the same rejection for a
20
+ * general account token). That is the exact failure #555 spent five attempts on in silence.
21
+ *
22
+ * **Named rather than inferred from the code being numeric.** Treating every numeric code as terminal was
23
+ * the first shape of this fix and it bought the auth case by making a *momentary* numeric failure
24
+ * permanent too — one attempt, `status: "failed"`, where the retry budget used to apply. A code nobody
25
+ * here recognizes is still unknown, whichever alphabet it is written in, and unknown has earned its
26
+ * bounded retry since the module was written. So the auth class is listed, and the rule below is
27
+ * unchanged for everything else.
28
+ */
29
+ const UNAUTHORIZED = /* @__PURE__ */ new Set([
30
+ "10000",
31
+ "E_UNAUTHORIZED",
32
+ "E_FORBIDDEN"
33
+ ]);
34
+ /**
35
+ * Whether a code is one of Cloudflare's numeric ones rather than the binding's `E_*` spelling.
36
+ *
37
+ * The distinction decides the retry, so it is a predicate rather than a guess at the call site. An `E_*`
38
+ * code this module does not list stays **terminal**, exactly as it always has — the binding's documented
39
+ * unknowns are validation, sender, content and header faults, and retrying one cannot help. A *numeric*
40
+ * code this module does not list is retryable, because it arrives from the account/REST layer where a
41
+ * momentary fault is ordinary and nothing here has an opinion yet.
42
+ */
43
+ function isProviderNumericCode(code) {
44
+ return /^[0-9]+$/.test(code);
45
+ }
46
+ /**
47
+ * Read a thrown value's `.code`/`.message` without assuming its shape.
48
+ *
49
+ * **A numeric code counts, and that is not a detail.** The Email Service binding surfaces `E_*` strings,
50
+ * but the REST path and the account layer behind it answer with Cloudflare's own numeric codes — an
51
+ * unauthorized send is `{ code: 10000, message: "Authentication error" }` (#534 captured the body). Read
52
+ * as "no code" that became `E_UNKNOWN`, which is both silent *and* retryable, so a credential fault
53
+ * consumed every attempt without ever naming itself (#555).
54
+ *
55
+ * **And a value with neither field still leaves a trace.** `String(err)` rather than `""`: an opaque
56
+ * throw is the case where the operator has least to go on, so an empty string is the one answer that
57
+ * cannot help. `E_UNKNOWN` remains the code — it means *nothing named itself*, which is the fact that
58
+ * earns the bounded retry.
59
+ */
15
60
  function readError(err) {
16
- if (err && typeof err === "object") return {
17
- code: "code" in err && typeof err.code === "string" ? err.code : "E_UNKNOWN",
18
- message: "message" in err && typeof err.message === "string" ? err.message : ""
19
- };
61
+ if (err && typeof err === "object") {
62
+ const raw = "code" in err ? err.code : void 0;
63
+ const code = typeof raw === "string" && raw !== "" ? raw : typeof raw === "number" ? String(raw) : "E_UNKNOWN";
64
+ const named = "message" in err && typeof err.message === "string" ? err.message : "";
65
+ return {
66
+ code,
67
+ message: named !== "" ? named : code === "E_UNKNOWN" ? String(err) : ""
68
+ };
69
+ }
20
70
  return {
21
71
  code: "E_UNKNOWN",
22
- message: typeof err === "string" ? err : ""
72
+ message: typeof err === "string" ? err : String(err)
23
73
  };
24
74
  }
25
75
  /**
26
76
  * Classify a send failure. `E_RECIPIENT_SUPPRESSED` is terminal and means the address must be
27
77
  * suppressed locally too; rate/quota and transient delivery codes are retryable; everything else
28
- * (validation, sender, content, headers) is terminal. An unknown code is treated as a transient
29
- * failure so a momentary fault gets one bounded retry rather than failing the job outright.
78
+ * (validation, sender, content, headers) is terminal.
79
+ *
80
+ * **An unrecognized code is retryable, and that is deliberately unchanged.** A failure this module has
81
+ * no code at all keeps its bounded retry, and so does a *numeric* provider code nobody here has listed —
82
+ * see {@link isProviderNumericCode} for why those two are alike and an unlisted `E_*` is not.
83
+ *
84
+ * What changed for #555 is that the **authentication** class is now named and terminal: `10000
85
+ * Authentication error` is a token that cannot send as this domain, and spending five attempts on it in
86
+ * silence is what hid the whole incident. See {@link UNAUTHORIZED} for why that is a list rather than
87
+ * "numeric means permanent" — the latter was this fix's first shape, and it made a momentary numeric
88
+ * failure permanent as a side effect.
30
89
  */
31
90
  function classifySendError(err) {
32
91
  const { code, message } = readError(err);
33
92
  const detail = `email send failed: ${code}${message ? ` — ${message}` : ""}`;
34
93
  if (code === "E_RECIPIENT_SUPPRESSED") return {
35
94
  code,
95
+ detail,
36
96
  retryable: false,
37
97
  suppressed: true,
38
98
  error: new EmailSuppressedError({ detail }, { cause: err })
39
99
  };
40
100
  if (RATE_LIMITED.has(code)) return {
41
101
  code,
102
+ detail,
42
103
  retryable: true,
43
104
  suppressed: false,
44
105
  error: new EmailRateLimitedError({ detail }, { cause: err })
45
106
  };
46
107
  return {
47
108
  code,
48
- retryable: RETRYABLE.has(code) || code === "E_UNKNOWN",
109
+ detail,
110
+ retryable: RETRYABLE.has(code) || code === "E_UNKNOWN" || isProviderNumericCode(code) && !UNAUTHORIZED.has(code),
49
111
  suppressed: false,
50
112
  error: new EmailSendFailedError({ detail }, { cause: err })
51
113
  };
@@ -1 +1 @@
1
- {"version":3,"file":"runSend.d.ts","sourceRoot":"","sources":["../../src/send/runSend.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,wBAAwB,EAAe,MAAM,gBAAgB,CAAC;AAE3F,OAAO,EAAE,KAAK,kBAAkB,EAAmC,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,kGAAkG;AAClG,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,yDAAyD;AACzD,MAAM,WAAW,QAAQ;IACvB,gDAAgD;IAChD,EAAE,EAAE,aAAa,CAAC;IAClB,sGAAsG;IACtG,aAAa,EAAE,wBAAwB,CAAC;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,UAAU,CAAC;IAClB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,6GAA6G;IAC7G,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,iHAAiH;IACjH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,IAAI,CAAC;IACpB;;;;;;;;;;;;;OAaG;IACH,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAED,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAuBD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAgLjF"}
1
+ {"version":3,"file":"runSend.d.ts","sourceRoot":"","sources":["../../src/send/runSend.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,wBAAwB,EAAe,MAAM,gBAAgB,CAAC;AAE3F,OAAO,EAAE,KAAK,kBAAkB,EAAmC,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5C;;;;;;;;;;;;;;;;;;GAkBG;AAEH,kGAAkG;AAClG,MAAM,WAAW,WAAW;IAC1B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,yDAAyD;AACzD,MAAM,WAAW,QAAQ;IACvB,gDAAgD;IAChD,EAAE,EAAE,aAAa,CAAC;IAClB,sGAAsG;IACtG,aAAa,EAAE,wBAAwB,CAAC;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB,KAAK,EAAE,UAAU,CAAC;IAClB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,6GAA6G;IAC7G,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,iHAAiH;IACjH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,IAAI,CAAC;IACpB;;;;;;;;;;;;;OAaG;IACH,WAAW,EAAE,MAAM,IAAI,CAAC;CACzB;AAED,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CACvC;AAuBD,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAoLjF"}
@@ -197,18 +197,18 @@ async function runSend(deps, jobId) {
197
197
  };
198
198
  }
199
199
  if (classified.retryable && attempts < deps.maxAttempts) {
200
- await patchJob(deps, jobId, { error: classified.code });
200
+ await patchJob(deps, jobId, { error: classified.detail });
201
201
  throw classified.error;
202
202
  }
203
203
  await patchJob(deps, jobId, {
204
204
  status: "failed",
205
- error: classified.code
205
+ error: classified.detail
206
206
  });
207
207
  await recordEvent(deps.db, {
208
208
  jobId,
209
209
  recipient,
210
210
  type: "failed",
211
- detail: classified.code
211
+ detail: classified.detail
212
212
  }, deps.passStartedAt);
213
213
  return {
214
214
  jobId,
@@ -3,5 +3,5 @@
3
3
  /** This package's npm name — the join key against a release feed. */
4
4
  export declare const PACKAGE_NAME = "@pithy-sh/email";
5
5
  /** This package's version, stamped from its own package.json at generation time. */
6
- export declare const PACKAGE_VERSION = "0.2.0";
6
+ export declare const PACKAGE_VERSION = "0.3.0";
7
7
  //# sourceMappingURL=version.generated.d.ts.map
@@ -4,6 +4,6 @@
4
4
  /** This package's npm name — the join key against a release feed. */
5
5
  const PACKAGE_NAME = "@pithy-sh/email";
6
6
  /** This package's version, stamped from its own package.json at generation time. */
7
- const PACKAGE_VERSION = "0.2.0";
7
+ const PACKAGE_VERSION = "0.3.0";
8
8
  //#endregion
9
9
  export { PACKAGE_NAME, PACKAGE_VERSION };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pithy-sh/email",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -14,8 +14,23 @@ import { EmailRateLimitedError, EmailSendFailedError, EmailSuppressedError } fro
14
14
 
15
15
  /** How a given send error is handled: which Pithy error to raise, and whether the send Workflow retries. */
16
16
  export interface ClassifiedSendError {
17
- /** The `E_*` code reported by the binding, or `E_UNKNOWN` when none was present. */
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
+ /**
20
+ * The cause, as one operator-facing line: the code and whatever the provider said with it.
21
+ *
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.
32
+ */
33
+ detail: string;
19
34
  /** Whether the send should be retried with backoff. */
20
35
  retryable: boolean;
21
36
  /** Whether the failure means the recipient is suppressed (so the address should be locally suppressed). */
@@ -35,21 +50,77 @@ const RETRYABLE = new Set([
35
50
  /** Rate/quota codes map to the dedicated 429 error so the cause reads clearly in logs. */
36
51
  const RATE_LIMITED = new Set(["E_RATE_LIMIT_EXCEEDED", "E_DAILY_LIMIT_EXCEEDED"]);
37
52
 
38
- /** Read a thrown value's `.code`/`.message` without assuming its shape. */
53
+ /**
54
+ * Codes that mean **this Worker could not authenticate** — terminal, because no retry clears a credential.
55
+ *
56
+ * `10000` is Cloudflare's own: a token that is alive but not scoped for Email Sending, or scoped for an
57
+ * 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.
60
+ *
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.
67
+ */
68
+ const UNAUTHORIZED = new Set(["10000", "E_UNAUTHORIZED", "E_FORBIDDEN"]);
69
+
70
+ /**
71
+ * Whether a code is one of Cloudflare's numeric ones rather than the binding's `E_*` spelling.
72
+ *
73
+ * The distinction decides the retry, so it is a predicate rather than a guess at the call site. An `E_*`
74
+ * code this module does not list stays **terminal**, exactly as it always has — the binding's documented
75
+ * unknowns are validation, sender, content and header faults, and retrying one cannot help. A *numeric*
76
+ * code this module does not list is retryable, because it arrives from the account/REST layer where a
77
+ * momentary fault is ordinary and nothing here has an opinion yet.
78
+ */
79
+ function isProviderNumericCode(code: string): boolean {
80
+ return /^[0-9]+$/.test(code);
81
+ }
82
+
83
+ /**
84
+ * Read a thrown value's `.code`/`.message` without assuming its shape.
85
+ *
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).
91
+ *
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.
96
+ */
39
97
  function readError(err: unknown): { code: string; message: string } {
40
98
  if (err && typeof err === "object") {
41
- const code = "code" in err && typeof err.code === "string" ? err.code : "E_UNKNOWN";
42
- const message = "message" in err && typeof err.message === "string" ? err.message : "";
43
- return { code, message };
99
+ const raw = "code" in err ? err.code : undefined;
100
+ const code = typeof raw === "string" && raw !== "" ? raw : typeof raw === "number" ? String(raw) : "E_UNKNOWN";
101
+ // `String(err)` only where nothing named itself. A coded throw carrying no message would otherwise
102
+ // record `E_INVALID_SENDER — [object Object]`, which is the code the operator already had plus noise —
103
+ // and that string is what the job row and the admin detail route now read.
104
+ const named = "message" in err && typeof err.message === "string" ? err.message : "";
105
+ return { code, message: named !== "" ? named : code === "E_UNKNOWN" ? String(err) : "" };
44
106
  }
45
- return { code: "E_UNKNOWN", message: typeof err === "string" ? err : "" };
107
+ return { code: "E_UNKNOWN", message: typeof err === "string" ? err : String(err) };
46
108
  }
47
109
 
48
110
  /**
49
111
  * Classify a send failure. `E_RECIPIENT_SUPPRESSED` is terminal and means the address must be
50
112
  * suppressed locally too; rate/quota and transient delivery codes are retryable; everything else
51
- * (validation, sender, content, headers) is terminal. An unknown code is treated as a transient
52
- * failure so a momentary fault gets one bounded retry rather than failing the job outright.
113
+ * (validation, sender, content, headers) is terminal.
114
+ *
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.
118
+ *
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.
53
124
  */
54
125
  export function classifySendError(err: unknown): ClassifiedSendError {
55
126
  const { code, message } = readError(err);
@@ -58,6 +129,7 @@ export function classifySendError(err: unknown): ClassifiedSendError {
58
129
  if (code === "E_RECIPIENT_SUPPRESSED") {
59
130
  return {
60
131
  code,
132
+ detail,
61
133
  retryable: false,
62
134
  suppressed: true,
63
135
  error: new EmailSuppressedError({ detail }, { cause: err }),
@@ -65,9 +137,18 @@ export function classifySendError(err: unknown): ClassifiedSendError {
65
137
  }
66
138
 
67
139
  if (RATE_LIMITED.has(code)) {
68
- return { code, retryable: true, suppressed: false, error: new EmailRateLimitedError({ detail }, { cause: err }) };
140
+ return {
141
+ code,
142
+ detail,
143
+ retryable: true,
144
+ suppressed: false,
145
+ error: new EmailRateLimitedError({ detail }, { cause: err }),
146
+ };
69
147
  }
70
148
 
71
- const retryable = RETRYABLE.has(code) || code === "E_UNKNOWN";
72
- return { code, retryable, suppressed: false, error: new EmailSendFailedError({ detail }, { cause: err }) };
149
+ // Three ways to earn a retry, and nothing else: a code documented as transient, no code at all, or a
150
+ // numeric provider code that is not the authentication class. An unlisted `E_*` stays terminal.
151
+ const retryable =
152
+ RETRYABLE.has(code) || code === "E_UNKNOWN" || (isProviderNumericCode(code) && !UNAUTHORIZED.has(code));
153
+ return { code, detail, retryable, suppressed: false, error: new EmailSendFailedError({ detail }, { cause: err }) };
73
154
  }
@@ -309,12 +309,16 @@ export async function runSend(deps: SendDeps, jobId: string): Promise<SendOutcom
309
309
 
310
310
  if (classified.retryable && attempts < deps.maxAttempts) {
311
311
  // Persist the last error, then throw so the Workflow step retries with backoff (row stays `sending`).
312
- await patchJob(deps, jobId, { error: classified.code });
312
+ await patchJob(deps, jobId, { error: classified.detail });
313
313
  throw classified.error;
314
314
  }
315
315
 
316
- await patchJob(deps, jobId, { status: "failed", error: classified.code });
317
- await recordEvent(deps.db, { jobId, recipient, type: "failed", detail: classified.code }, deps.passStartedAt);
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.
320
+ await patchJob(deps, jobId, { status: "failed", error: classified.detail });
321
+ await recordEvent(deps.db, { jobId, recipient, type: "failed", detail: classified.detail }, deps.passStartedAt);
318
322
  return { jobId, status: "failed" };
319
323
  }
320
324
  }
@@ -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.2.0";
16
+ export const PACKAGE_VERSION = "0.3.0";