@shipstatic/types 2.7.0-beta.1 → 2.7.0-beta.3

package/README.md

@@ -78,9 +78,9 @@ try { response = await fetch(url); }
 catch (cause) { throw ShipError.fromFetchError(cause, 'Get account'); }
 ```
 
-`fromHttpResponse` trusts the body's `error` field when it's a known server-producible `ErrorType` — so a server's `ShipError.validation(...)` round-trips back to `ErrorType.Validation` on the client. For non-API responses (CDN errors, intermediaries) or malformed bodies it falls back to status-derived (401 → `Authentication`, 403 → `Forbidden`, 429 → `RateLimit`, else → `Api`). Client-only types (`Network`, `Cancelled`, `File`, `Config`) are filtered out of the trusted set. Body's `message` and `details` are preserved best-effort.
+`fromHttpResponse` trusts the body's `error` field when it's a known server-producible `ErrorType` — so a server's `ShipError.validation(...)` round-trips back to `ErrorType.Validation` on the client. For non-API responses (CDN errors, intermediaries) or malformed bodies it falls back to status-derived (401 → `Authentication`, 403 → `Forbidden`, 429 → `RateLimit`, else → `Api`). Client-only types (`Network`, `Timeout`, `Cancelled`, `File`, `Config`) are filtered out of the trusted set. Body's `message` and `details` are preserved best-effort.
 
-`fromFetchError` routes by the thrown cause: an existing `ShipError` is returned unchanged, `AbortError` becomes `Cancelled`, a fetch `TypeError` becomes `Network`, anything else becomes `Api` (with no HTTP status — the request never reached the server).
+`fromFetchError` routes by the thrown cause: an existing `ShipError` is returned unchanged, `AbortError` becomes `Cancelled`, `TimeoutError` becomes `Timeout`, a fetch `TypeError` becomes `Network`, anything else becomes `Api` (with no HTTP status — the request never reached the server). `Timeout` is a distinct type inside the network category — `isNetworkError()` is true for it — so a surface can retry it like any transport failure while still saying "timed out" rather than "check your connection".
 
 Both helpers accept an optional operation-name string for contextual messages (`"Get account was cancelled"`, `"Get account failed: ..."`).
 

package/dist/index.d.ts

@@ -725,6 +725,23 @@ export declare const ErrorType: {
     readonly Maintenance: "maintenance";
     /** Network/connection error. Client-side only — set by HTTP clients on fetch failure; never produced server-side. */
     readonly Network: "network_error";
+    /**
+     * A deadline expired before the exchange completed. Client-side only — set
+     * by HTTP clients when a timeout signal fires; never produced server-side.
+     *
+     * A member of the NETWORK category rather than a sibling of it:
+     * `isNetworkError()` answers "nothing was exchanged", which is true of a
+     * deadline exactly as it is of a refused connection, so every consumer that
+     * retries, declines to report, or declines to relay a wire message on that
+     * category is already right about a timeout. The distinct TYPE exists for
+     * the one decision the category cannot make — what to SAY. "Check your
+     * internet connection" is the wrong sentence for a five-minute deploy
+     * ceiling, and a surface can only tell the two apart by type.
+     *
+     * The same relationship every comparable SDK ships:
+     * `APIConnectionTimeoutError extends APIConnectionError`.
+     */
+    readonly Timeout: "timeout_error";
     /** Operation was cancelled. Client-side only — set on `AbortSignal` abort; never produced server-side. */
     readonly Cancelled: "operation_cancelled";
     /** File operation error. Client-side only — set by SDK during local file processing; never produced server-side. */
@@ -769,7 +786,7 @@ export declare class ShipError extends Error {
      * on the client). Falls back to status-derived (401 → Authentication,
      * 403 → Forbidden, 429 → RateLimit, else → Api) for non-API responses
      * (CDN errors, intermediaries) or malformed bodies. Client-only types
-     * (`Network`, `Cancelled`, `File`, `Config`) are filtered out of the
+     * (`Network`, `Timeout`, `Cancelled`, `File`, `Config`) are filtered out of the
      * trusted set — a misbehaving server claiming one of those is ignored.
      *
      * `operationName` (e.g. `"Get account"`) is used to compose the fallback
@@ -788,12 +805,31 @@ export declare class ShipError extends Error {
      *
      * Routing:
      * - Already a `ShipError` → returned as-is (caller's intent preserved)
-     * - `AbortError` → `ShipError.cancelled(...)`
+     * - `AbortError` → `ShipError.cancelled(...)` — someone stopped it on purpose
+     * - `TimeoutError` → `ShipError.timeout(...)` — a deadline expired; the
+     *   message names the timeout, and the type is in the network CATEGORY
+     *   because nothing was exchanged
      * - A transport failure → `ShipError.network(...)` — see `isTransportFailure`
      *   for what each runtime offers as evidence
      * - Any other `Error` → `ShipError(Api, ...)` (no HTTP status — fetch never reached the server)
      * - Anything else (string, undefined, etc.) → `ShipError(Api, ...)`
      *
+     * **Abort and timeout are read from `name` BEFORE any `instanceof Error`
+     * gate.** A `DOMException` satisfies that gate in every runtime measured
+     * (Node, Bun, Chromium, Firefox, WebKit, workerd — all six), but the
+     * inheritance is a comparatively recent spec change and this classification
+     * has no reason to depend on it: `name` is where the meaning lives, and
+     * reading it first costs nothing. The suite plants a non-`Error`
+     * `DOMException` shape to hold the arm, since no runtime on the table
+     * produces one.
+     *
+     * A caller's own `AbortSignal.timeout()` is the reachable source of
+     * `TimeoutError` — and the two are NOT interchangeable per runtime: WebKit
+     * reports a fired `AbortSignal.timeout()` as `AbortError`, so on Safari a
+     * deadline is indistinguishable from a cancellation and lands on
+     * `Cancelled`. Recorded rather than worked around; `Cancelled` is honest
+     * there, since the caller's signal is what stopped it.
+     *
      * The optional `operationName` is composed into the message for context:
      * `"Get account was cancelled"`, `"Get account failed: ..."`. Defaults to
      * `"Request"` when omitted.
@@ -819,6 +855,14 @@ export declare class ShipError extends Error {
     static authentication(message?: string, details?: unknown): ShipError;
     static business(message: string, status?: number, details?: unknown): ShipError;
     static network(message: string, details?: unknown): ShipError;
+    /**
+     * A deadline expired before the exchange completed.
+     *
+     * Statusless like its four client-only siblings: no exchange completed, so
+     * there is no HTTP status to report. `isNetworkError()` is true — see
+     * `ErrorType.Timeout` for why the category is shared and the type is not.
+     */
+    static timeout(message: string, details?: unknown): ShipError;
     static cancelled(message: string, details?: unknown): ShipError;
     static file(message: string, details?: unknown): ShipError;
     static config(message: string, details?: unknown): ShipError;

package/dist/index.js

@@ -271,6 +271,23 @@ export const ErrorType = {
     Maintenance: 'maintenance',
     /** Network/connection error. Client-side only — set by HTTP clients on fetch failure; never produced server-side. */
     Network: 'network_error',
+    /**
+     * A deadline expired before the exchange completed. Client-side only — set
+     * by HTTP clients when a timeout signal fires; never produced server-side.
+     *
+     * A member of the NETWORK category rather than a sibling of it:
+     * `isNetworkError()` answers "nothing was exchanged", which is true of a
+     * deadline exactly as it is of a refused connection, so every consumer that
+     * retries, declines to report, or declines to relay a wire message on that
+     * category is already right about a timeout. The distinct TYPE exists for
+     * the one decision the category cannot make — what to SAY. "Check your
+     * internet connection" is the wrong sentence for a five-minute deploy
+     * ceiling, and a surface can only tell the two apart by type.
+     *
+     * The same relationship every comparable SDK ships:
+     * `APIConnectionTimeoutError extends APIConnectionError`.
+     */
+    Timeout: 'timeout_error',
     /** Operation was cancelled. Client-side only — set on `AbortSignal` abort; never produced server-side. */
     Cancelled: 'operation_cancelled',
     /** File operation error. Client-side only — set by SDK during local file processing; never produced server-side. */
@@ -286,6 +303,7 @@ export const ErrorType = {
  */
 const CLIENT_ONLY_ERROR_TYPES = new Set([
     ErrorType.Network,
+    ErrorType.Timeout,
     ErrorType.Cancelled,
     ErrorType.File,
     ErrorType.Config,
@@ -301,12 +319,20 @@ const ERROR_CATEGORIES = {
      * over the statusless ones too — those are raised locally and have no
      * status for `isClientError`'s second arm to read, so omitting one makes it
      * read as a server fault. The rule is the membership test: every type in
-     * `CLIENT_ONLY_ERROR_TYPES` except `Network` (which `isNetworkError` owns)
-     * belongs here.
+     * `CLIENT_ONLY_ERROR_TYPES` except the two `isNetworkError` owns belongs
+     * here.
      *
      * `Cancelled` was missing until 2026-07-29, which is exactly that failure:
      * a caller who aborted their own deploy was told "server error: please try
      * again" — the CLI's fallback for everything this set does not claim.
+     *
+     * `Timeout` is deliberately NOT here, and it is the sharper case, because
+     * it is the one client-only type that is not the client's fault: the
+     * caller set a ceiling, but what exhausted it was the network or the
+     * server. Reading it as client-attributable would say the caller erred,
+     * and it would silently disarm every consumer whose retry predicate
+     * declines `isClientError()` — a deadline is precisely the failure worth
+     * a second attempt.
      */
     client: new Set([
         ErrorType.Business,
@@ -318,7 +344,14 @@ const ERROR_CATEGORIES = {
         ErrorType.RateLimit,
         ErrorType.Validation,
     ]),
-    network: new Set([ErrorType.Network]),
+    /**
+     * The exchange never happened. Two types, one category: a refused
+     * connection and an expired deadline differ in what a surface should SAY
+     * and in nothing else a consumer decides on — both are retryable, neither
+     * carries a wire message to relay, neither is worth reporting as an
+     * incident. See `ErrorType.Timeout` for why the type is distinct anyway.
+     */
+    network: new Set([ErrorType.Network, ErrorType.Timeout]),
     auth: new Set([ErrorType.Authentication]),
 };
 /**
@@ -340,38 +373,71 @@ const MAX_FOREIGN_MESSAGE_LENGTH = 200;
 /**
  * Did the runtime say the exchange never completed?
  *
- * WHATWG has `fetch` reject with a **TypeError** on network error, and undici,
- * Chromium and Firefox comply. Bun does not: it rejects with a plain `Error`
- * carrying a system `code` string. Captured 2026-08-05 (the capture script is
- * in `tests/errors.test.ts`, "runtime failure shapes"):
- *
- * | failure       | Node 22 / undici          | Bun 1.3.14                                   |
- * |---------------|---------------------------|----------------------------------------------|
- * | refused       | `TypeError: fetch failed` | `Error` `code: 'ConnectionRefused'`          |
- * | DNS failure   | `TypeError: fetch failed` | `Error` `code: 'ConnectionRefused'`          |
- * | reset         | `TypeError: fetch failed` | `Error` `code: 'ECONNRESET'`                 |
- * | TLS rejected  | `TypeError: fetch failed` | `Error` `code: 'UNKNOWN_CERTIFICATE_…ERROR'` |
- *
- * So the test is the **evidence, not a list of dialect strings**: a string
- * `code` is a runtime naming a transport-level failure. An allowlist of codes
- * was written first and rejected — the TLS row alone would mean enumerating
- * BoringSSL's certificate table, and a code nobody guessed is precisely the bug
- * this closes. Two kinds of error are deliberately NOT caught: ordinary JS
- * faults carry no `code` at all, and a `DOMException`'s is a **number**, so
- * aborts and timeouts fall through to their own arms.
- *
- * The accepted trade: a caller's `TokenProvider` that throws a coded error
- * (`ENOENT` from a keychain read) is typed `Network` rather than `Api`. Both
- * are wrong for it, `Network` is the cheaper wrong — it says "nothing was
- * exchanged", which is true, where `Api` claims a server answered.
+ * Clients branch on the TYPE, never on message strings, so a misclassified
+ * transport failure is a lie every consumer inherits — and the one that costs
+ * most: `Api` claims a server answered when nothing was exchanged, and a
+ * retrying caller will not retry it.
+ *
+ * **Every row below is a transcript, not a belief.** Captured 2026-08-12
+ * against real runtimes — Node and Bun by direct run, the three engines by a
+ * one-off playwright probe, workerd through miniflare. The capture scripts are
+ * in `tests/errors.test.ts`, "runtime failure shapes".
+ *
+ * | runtime          | connection refused / DNS failure                     | malformed URL                                    |
+ * |------------------|------------------------------------------------------|--------------------------------------------------|
+ * | Node 22 / undici | `TypeError: fetch failed`                             | `TypeError: Failed to parse URL from …`          |
+ * | Bun 1.3.14       | `Error` `code:'ConnectionRefused'`                    | `TypeError` `code:'ERR_INVALID_URL'`             |
+ * | Chromium 151     | `TypeError: Failed to fetch`                          | `TypeError: …Failed to parse URL from …`         |
+ * | Firefox 153      | `TypeError: NetworkError when attempting to fetch …`  | `TypeError: … is not a valid URL.`               |
+ * | WebKit 26.5      | `TypeError: Load failed`                              | `TypeError: URL is not valid or contains user …` |
+ * | workerd          | `Error: Network connection lost.` (DNS: `internal error; reference = …`) | `TypeError: Invalid URL: …`   |
+ *
+ * Reading that table gives the rule, and it is the INVERSE of the obvious one.
+ * The transport class is unbounded — every OS, TLS and DNS failure any engine
+ * will ever name — while the class fetch raises for its own ARGUMENTS is
+ * small, and every runtime names the URL when it complains about one. So the
+ * bounded side is the one worth testing, and the residual risk points the safe
+ * way: an unrecognised sentence lands on `Network`, which says only that
+ * nothing was exchanged.
+ *
+ * That inversion is what fixes **WebKit**, whose `Load failed` carries no code
+ * and no "fetch", and which every browser-SDK and `@shipstatic/drop` user on
+ * Safari was hitting as `Api`. It also makes the six runtimes AGREE about a
+ * malformed URL, which they did not before: the previous rule tested the
+ * message for "fetch", and Chromium's and Firefox's URL complaints both
+ * contain it, so the same mistake was `Network` on three engines and `Api` on
+ * three.
+ *
+ * **workerd is the recorded gap.** It rejects with a plain `Error`, no code
+ * and no shared sentence — and its two failure modes produce two unrelated
+ * ones — so nothing here can classify it and it lands on `Api`. Left alone
+ * rather than patched with a dialect string: the one consumer running ship in
+ * that runtime (`cloudflare/mcp`) reaches the API through a service BINDING,
+ * which is in-process and does not produce transport rejections at all.
+ *
+ * The accepted trade is unchanged: a caller's `TokenProvider` that throws a
+ * coded error (`ENOENT` from a keychain read) is typed `Network` rather than
+ * `Api`. Both are wrong for it; `Network` is the cheaper wrong.
  */
 function isTransportFailure(cause) {
-    if (typeof cause.code === 'string')
+    const code = cause.code;
+    // Bun is the one runtime that puts a CODE on an argument error, so it is
+    // excluded before the code arm can claim it.
+    if (code === 'ERR_INVALID_URL')
+        return false;
+    // A string `code` is a runtime naming a transport-level failure. An
+    // allowlist of codes was written first and rejected — the TLS row alone
+    // would mean enumerating BoringSSL's certificate table, and a code nobody
+    // guessed is precisely the bug this closes. A `DOMException`'s code is a
+    // NUMBER, so aborts and timeouts never reach here.
+    if (typeof code === 'string')
         return true;
-    // Spec runtimes put no code on the rejection itself. The message test is what
-    // keeps fetch's ARGUMENT errors out — `Failed to parse URL from …` is a
-    // caller's config mistake, not a transport failure.
-    return cause instanceof TypeError && cause.message.includes('fetch');
+    // WHATWG has fetch reject with a TypeError for BOTH halves — network error
+    // and argument error — so among TypeErrors the URL is the discriminator.
+    if (cause instanceof TypeError)
+        return !/\burl\b/i.test(cause.message);
+    // Anything else — an ordinary JS fault, or workerd — is not evidence.
+    return false;
 }
 /**
  * Simple unified error class for both API and SDK
@@ -414,7 +480,7 @@ export class ShipError extends Error {
      * on the client). Falls back to status-derived (401 → Authentication,
      * 403 → Forbidden, 429 → RateLimit, else → Api) for non-API responses
      * (CDN errors, intermediaries) or malformed bodies. Client-only types
-     * (`Network`, `Cancelled`, `File`, `Config`) are filtered out of the
+     * (`Network`, `Timeout`, `Cancelled`, `File`, `Config`) are filtered out of the
      * trusted set — a misbehaving server claiming one of those is ignored.
      *
      * `operationName` (e.g. `"Get account"`) is used to compose the fallback
@@ -497,12 +563,31 @@ export class ShipError extends Error {
      *
      * Routing:
      * - Already a `ShipError` → returned as-is (caller's intent preserved)
-     * - `AbortError` → `ShipError.cancelled(...)`
+     * - `AbortError` → `ShipError.cancelled(...)` — someone stopped it on purpose
+     * - `TimeoutError` → `ShipError.timeout(...)` — a deadline expired; the
+     *   message names the timeout, and the type is in the network CATEGORY
+     *   because nothing was exchanged
      * - A transport failure → `ShipError.network(...)` — see `isTransportFailure`
      *   for what each runtime offers as evidence
      * - Any other `Error` → `ShipError(Api, ...)` (no HTTP status — fetch never reached the server)
      * - Anything else (string, undefined, etc.) → `ShipError(Api, ...)`
      *
+     * **Abort and timeout are read from `name` BEFORE any `instanceof Error`
+     * gate.** A `DOMException` satisfies that gate in every runtime measured
+     * (Node, Bun, Chromium, Firefox, WebKit, workerd — all six), but the
+     * inheritance is a comparatively recent spec change and this classification
+     * has no reason to depend on it: `name` is where the meaning lives, and
+     * reading it first costs nothing. The suite plants a non-`Error`
+     * `DOMException` shape to hold the arm, since no runtime on the table
+     * produces one.
+     *
+     * A caller's own `AbortSignal.timeout()` is the reachable source of
+     * `TimeoutError` — and the two are NOT interchangeable per runtime: WebKit
+     * reports a fired `AbortSignal.timeout()` as `AbortError`, so on Safari a
+     * deadline is indistinguishable from a cancellation and lands on
+     * `Cancelled`. Recorded rather than worked around; `Cancelled` is honest
+     * there, since the caller's signal is what stopped it.
+     *
      * The optional `operationName` is composed into the message for context:
      * `"Get account was cancelled"`, `"Get account failed: ..."`. Defaults to
      * `"Request"` when omitted.
@@ -511,10 +596,22 @@ export class ShipError extends Error {
         if (isShipError(cause))
             return cause;
         const op = operationName || 'Request';
+        // Read by NAME, ahead of the Error gate — see the note above.
+        const name = cause?.name;
+        if (name === 'AbortError') {
+            return ShipError.cancelled(`${op} was cancelled`);
+        }
+        if (name === 'TimeoutError') {
+            // A deadline: not a fault, not a cancellation, and — since it has its
+            // own type — no longer merely "network". Nothing was exchanged, which
+            // is what keeps it in the network CATEGORY and therefore retryable; the
+            // type is what lets a surface say "timed out" instead of sending
+            // someone to check their Wi-Fi. The runtime's own sentence is dropped
+            // rather than relayed: "The operation was aborted due to timeout" is
+            // the mechanism, not the news.
+            return ShipError.timeout(`${op} timed out`, { cause });
+        }
         if (cause instanceof Error) {
-            if (cause.name === 'AbortError') {
-                return ShipError.cancelled(`${op} was cancelled`);
-            }
             if (isTransportFailure(cause)) {
                 return ShipError.network(`${op} failed: ${cause.message}`, { cause });
             }
@@ -561,6 +658,16 @@ export class ShipError extends Error {
     static network(message, details) {
         return new ShipError(ErrorType.Network, message, undefined, details);
     }
+    /**
+     * A deadline expired before the exchange completed.
+     *
+     * Statusless like its four client-only siblings: no exchange completed, so
+     * there is no HTTP status to report. `isNetworkError()` is true — see
+     * `ErrorType.Timeout` for why the category is shared and the type is not.
+     */
+    static timeout(message, details) {
+        return new ShipError(ErrorType.Timeout, message, undefined, details);
+    }
     static cancelled(message, details) {
         return new ShipError(ErrorType.Cancelled, message, undefined, details);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "2.7.0-beta.1",
+  "version": "2.7.0-beta.3",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -815,6 +815,23 @@ export const ErrorType = {
   Maintenance: 'maintenance',
   /** Network/connection error. Client-side only — set by HTTP clients on fetch failure; never produced server-side. */
   Network: 'network_error',
+  /**
+   * A deadline expired before the exchange completed. Client-side only — set
+   * by HTTP clients when a timeout signal fires; never produced server-side.
+   *
+   * A member of the NETWORK category rather than a sibling of it:
+   * `isNetworkError()` answers "nothing was exchanged", which is true of a
+   * deadline exactly as it is of a refused connection, so every consumer that
+   * retries, declines to report, or declines to relay a wire message on that
+   * category is already right about a timeout. The distinct TYPE exists for
+   * the one decision the category cannot make — what to SAY. "Check your
+   * internet connection" is the wrong sentence for a five-minute deploy
+   * ceiling, and a surface can only tell the two apart by type.
+   *
+   * The same relationship every comparable SDK ships:
+   * `APIConnectionTimeoutError extends APIConnectionError`.
+   */
+  Timeout: 'timeout_error',
   /** Operation was cancelled. Client-side only — set on `AbortSignal` abort; never produced server-side. */
   Cancelled: 'operation_cancelled',
   /** File operation error. Client-side only — set by SDK during local file processing; never produced server-side. */
@@ -833,6 +850,7 @@ export type ErrorType = (typeof ErrorType)[keyof typeof ErrorType];
  */
 const CLIENT_ONLY_ERROR_TYPES = new Set<string>([
   ErrorType.Network,
+  ErrorType.Timeout,
   ErrorType.Cancelled,
   ErrorType.File,
   ErrorType.Config,
@@ -849,12 +867,20 @@ const ERROR_CATEGORIES = {
    * over the statusless ones too — those are raised locally and have no
    * status for `isClientError`'s second arm to read, so omitting one makes it
    * read as a server fault. The rule is the membership test: every type in
-   * `CLIENT_ONLY_ERROR_TYPES` except `Network` (which `isNetworkError` owns)
-   * belongs here.
+   * `CLIENT_ONLY_ERROR_TYPES` except the two `isNetworkError` owns belongs
+   * here.
    *
    * `Cancelled` was missing until 2026-07-29, which is exactly that failure:
    * a caller who aborted their own deploy was told "server error: please try
    * again" — the CLI's fallback for everything this set does not claim.
+   *
+   * `Timeout` is deliberately NOT here, and it is the sharper case, because
+   * it is the one client-only type that is not the client's fault: the
+   * caller set a ceiling, but what exhausted it was the network or the
+   * server. Reading it as client-attributable would say the caller erred,
+   * and it would silently disarm every consumer whose retry predicate
+   * declines `isClientError()` — a deadline is precisely the failure worth
+   * a second attempt.
    */
   client: new Set<ErrorType>([
     ErrorType.Business,
@@ -866,7 +892,14 @@ const ERROR_CATEGORIES = {
     ErrorType.RateLimit,
     ErrorType.Validation,
   ]),
-  network: new Set<ErrorType>([ErrorType.Network]),
+  /**
+   * The exchange never happened. Two types, one category: a refused
+   * connection and an expired deadline differ in what a surface should SAY
+   * and in nothing else a consumer decides on — both are retryable, neither
+   * carries a wire message to relay, neither is worth reporting as an
+   * incident. See `ErrorType.Timeout` for why the type is distinct anyway.
+   */
+  network: new Set<ErrorType>([ErrorType.Network, ErrorType.Timeout]),
   auth: new Set<ErrorType>([ErrorType.Authentication]),
 } as const;
 
@@ -893,37 +926,72 @@ const MAX_FOREIGN_MESSAGE_LENGTH = 200;
 /**
  * Did the runtime say the exchange never completed?
  *
- * WHATWG has `fetch` reject with a **TypeError** on network error, and undici,
- * Chromium and Firefox comply. Bun does not: it rejects with a plain `Error`
- * carrying a system `code` string. Captured 2026-08-05 (the capture script is
- * in `tests/errors.test.ts`, "runtime failure shapes"):
- *
- * | failure       | Node 22 / undici          | Bun 1.3.14                                   |
- * |---------------|---------------------------|----------------------------------------------|
- * | refused       | `TypeError: fetch failed` | `Error` `code: 'ConnectionRefused'`          |
- * | DNS failure   | `TypeError: fetch failed` | `Error` `code: 'ConnectionRefused'`          |
- * | reset         | `TypeError: fetch failed` | `Error` `code: 'ECONNRESET'`                 |
- * | TLS rejected  | `TypeError: fetch failed` | `Error` `code: 'UNKNOWN_CERTIFICATE_…ERROR'` |
- *
- * So the test is the **evidence, not a list of dialect strings**: a string
- * `code` is a runtime naming a transport-level failure. An allowlist of codes
- * was written first and rejected — the TLS row alone would mean enumerating
- * BoringSSL's certificate table, and a code nobody guessed is precisely the bug
- * this closes. Two kinds of error are deliberately NOT caught: ordinary JS
- * faults carry no `code` at all, and a `DOMException`'s is a **number**, so
- * aborts and timeouts fall through to their own arms.
- *
- * The accepted trade: a caller's `TokenProvider` that throws a coded error
- * (`ENOENT` from a keychain read) is typed `Network` rather than `Api`. Both
- * are wrong for it, `Network` is the cheaper wrong — it says "nothing was
- * exchanged", which is true, where `Api` claims a server answered.
+ * Clients branch on the TYPE, never on message strings, so a misclassified
+ * transport failure is a lie every consumer inherits — and the one that costs
+ * most: `Api` claims a server answered when nothing was exchanged, and a
+ * retrying caller will not retry it.
+ *
+ * **Every row below is a transcript, not a belief.** Captured 2026-08-12
+ * against real runtimes — Node and Bun by direct run, the three engines by a
+ * one-off playwright probe, workerd through miniflare. The capture scripts are
+ * in `tests/errors.test.ts`, "runtime failure shapes".
+ *
+ * | runtime          | connection refused / DNS failure                     | malformed URL                                    |
+ * |------------------|------------------------------------------------------|--------------------------------------------------|
+ * | Node 22 / undici | `TypeError: fetch failed`                             | `TypeError: Failed to parse URL from …`          |
+ * | Bun 1.3.14       | `Error` `code:'ConnectionRefused'`                    | `TypeError` `code:'ERR_INVALID_URL'`             |
+ * | Chromium 151     | `TypeError: Failed to fetch`                          | `TypeError: …Failed to parse URL from …`         |
+ * | Firefox 153      | `TypeError: NetworkError when attempting to fetch …`  | `TypeError: … is not a valid URL.`               |
+ * | WebKit 26.5      | `TypeError: Load failed`                              | `TypeError: URL is not valid or contains user …` |
+ * | workerd          | `Error: Network connection lost.` (DNS: `internal error; reference = …`) | `TypeError: Invalid URL: …`   |
+ *
+ * Reading that table gives the rule, and it is the INVERSE of the obvious one.
+ * The transport class is unbounded — every OS, TLS and DNS failure any engine
+ * will ever name — while the class fetch raises for its own ARGUMENTS is
+ * small, and every runtime names the URL when it complains about one. So the
+ * bounded side is the one worth testing, and the residual risk points the safe
+ * way: an unrecognised sentence lands on `Network`, which says only that
+ * nothing was exchanged.
+ *
+ * That inversion is what fixes **WebKit**, whose `Load failed` carries no code
+ * and no "fetch", and which every browser-SDK and `@shipstatic/drop` user on
+ * Safari was hitting as `Api`. It also makes the six runtimes AGREE about a
+ * malformed URL, which they did not before: the previous rule tested the
+ * message for "fetch", and Chromium's and Firefox's URL complaints both
+ * contain it, so the same mistake was `Network` on three engines and `Api` on
+ * three.
+ *
+ * **workerd is the recorded gap.** It rejects with a plain `Error`, no code
+ * and no shared sentence — and its two failure modes produce two unrelated
+ * ones — so nothing here can classify it and it lands on `Api`. Left alone
+ * rather than patched with a dialect string: the one consumer running ship in
+ * that runtime (`cloudflare/mcp`) reaches the API through a service BINDING,
+ * which is in-process and does not produce transport rejections at all.
+ *
+ * The accepted trade is unchanged: a caller's `TokenProvider` that throws a
+ * coded error (`ENOENT` from a keychain read) is typed `Network` rather than
+ * `Api`. Both are wrong for it; `Network` is the cheaper wrong.
  */
 function isTransportFailure(cause: Error): boolean {
-  if (typeof (cause as { code?: unknown }).code === 'string') return true;
-  // Spec runtimes put no code on the rejection itself. The message test is what
-  // keeps fetch's ARGUMENT errors out — `Failed to parse URL from …` is a
-  // caller's config mistake, not a transport failure.
-  return cause instanceof TypeError && cause.message.includes('fetch');
+  const code = (cause as { code?: unknown }).code;
+
+  // Bun is the one runtime that puts a CODE on an argument error, so it is
+  // excluded before the code arm can claim it.
+  if (code === 'ERR_INVALID_URL') return false;
+
+  // A string `code` is a runtime naming a transport-level failure. An
+  // allowlist of codes was written first and rejected — the TLS row alone
+  // would mean enumerating BoringSSL's certificate table, and a code nobody
+  // guessed is precisely the bug this closes. A `DOMException`'s code is a
+  // NUMBER, so aborts and timeouts never reach here.
+  if (typeof code === 'string') return true;
+
+  // WHATWG has fetch reject with a TypeError for BOTH halves — network error
+  // and argument error — so among TypeErrors the URL is the discriminator.
+  if (cause instanceof TypeError) return !/\burl\b/i.test(cause.message);
+
+  // Anything else — an ordinary JS fault, or workerd — is not evidence.
+  return false;
 }
 
 /**
@@ -984,7 +1052,7 @@ export class ShipError extends Error {
    * on the client). Falls back to status-derived (401 → Authentication,
    * 403 → Forbidden, 429 → RateLimit, else → Api) for non-API responses
    * (CDN errors, intermediaries) or malformed bodies. Client-only types
-   * (`Network`, `Cancelled`, `File`, `Config`) are filtered out of the
+   * (`Network`, `Timeout`, `Cancelled`, `File`, `Config`) are filtered out of the
    * trusted set — a misbehaving server claiming one of those is ignored.
    *
    * `operationName` (e.g. `"Get account"`) is used to compose the fallback
@@ -1071,12 +1139,31 @@ export class ShipError extends Error {
    *
    * Routing:
    * - Already a `ShipError` → returned as-is (caller's intent preserved)
-   * - `AbortError` → `ShipError.cancelled(...)`
+   * - `AbortError` → `ShipError.cancelled(...)` — someone stopped it on purpose
+   * - `TimeoutError` → `ShipError.timeout(...)` — a deadline expired; the
+   *   message names the timeout, and the type is in the network CATEGORY
+   *   because nothing was exchanged
    * - A transport failure → `ShipError.network(...)` — see `isTransportFailure`
    *   for what each runtime offers as evidence
    * - Any other `Error` → `ShipError(Api, ...)` (no HTTP status — fetch never reached the server)
    * - Anything else (string, undefined, etc.) → `ShipError(Api, ...)`
    *
+   * **Abort and timeout are read from `name` BEFORE any `instanceof Error`
+   * gate.** A `DOMException` satisfies that gate in every runtime measured
+   * (Node, Bun, Chromium, Firefox, WebKit, workerd — all six), but the
+   * inheritance is a comparatively recent spec change and this classification
+   * has no reason to depend on it: `name` is where the meaning lives, and
+   * reading it first costs nothing. The suite plants a non-`Error`
+   * `DOMException` shape to hold the arm, since no runtime on the table
+   * produces one.
+   *
+   * A caller's own `AbortSignal.timeout()` is the reachable source of
+   * `TimeoutError` — and the two are NOT interchangeable per runtime: WebKit
+   * reports a fired `AbortSignal.timeout()` as `AbortError`, so on Safari a
+   * deadline is indistinguishable from a cancellation and lands on
+   * `Cancelled`. Recorded rather than worked around; `Cancelled` is honest
+   * there, since the caller's signal is what stopped it.
+   *
    * The optional `operationName` is composed into the message for context:
    * `"Get account was cancelled"`, `"Get account failed: ..."`. Defaults to
    * `"Request"` when omitted.
@@ -1086,10 +1173,23 @@ export class ShipError extends Error {
 
     const op = operationName || 'Request';
 
+    // Read by NAME, ahead of the Error gate — see the note above.
+    const name = (cause as { name?: unknown } | null | undefined)?.name;
+    if (name === 'AbortError') {
+      return ShipError.cancelled(`${op} was cancelled`);
+    }
+    if (name === 'TimeoutError') {
+      // A deadline: not a fault, not a cancellation, and — since it has its
+      // own type — no longer merely "network". Nothing was exchanged, which
+      // is what keeps it in the network CATEGORY and therefore retryable; the
+      // type is what lets a surface say "timed out" instead of sending
+      // someone to check their Wi-Fi. The runtime's own sentence is dropped
+      // rather than relayed: "The operation was aborted due to timeout" is
+      // the mechanism, not the news.
+      return ShipError.timeout(`${op} timed out`, { cause });
+    }
+
     if (cause instanceof Error) {
-      if (cause.name === 'AbortError') {
-        return ShipError.cancelled(`${op} was cancelled`);
-      }
       if (isTransportFailure(cause)) {
         return ShipError.network(`${op} failed: ${cause.message}`, { cause });
       }
@@ -1146,6 +1246,17 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.Network, message, undefined, details);
   }
 
+  /**
+   * A deadline expired before the exchange completed.
+   *
+   * Statusless like its four client-only siblings: no exchange completed, so
+   * there is no HTTP status to report. `isNetworkError()` is true — see
+   * `ErrorType.Timeout` for why the category is shared and the type is not.
+   */
+  static timeout(message: string, details?: unknown): ShipError {
+    return new ShipError(ErrorType.Timeout, message, undefined, details);
+  }
+
   static cancelled(message: string, details?: unknown): ShipError {
     return new ShipError(ErrorType.Cancelled, message, undefined, details);
   }