@shipstatic/types 2.7.0-beta.2 → 2.7.0-beta.4

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

@@ -671,6 +671,12 @@ export declare const DEPLOY_FIELDS: {
     readonly VIA: "via";
     /** Plaintext password — the API hashes it server-side. */
     readonly PASSWORD: "password";
+    /**
+     * Requested lifetime in SECONDS — a duration, never an instant. The API
+     * computes and stores the expiry, so the wire carries no client clock.
+     * See {@link validateTtl}.
+     */
+    readonly TTL: "ttl";
     /** @internal Server-processing flag — first-party `/upload` only. */
     readonly BUILD: "build";
     /** @internal Server-processing flag — first-party `/upload` only. */
@@ -725,6 +731,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 +792,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
@@ -789,8 +812,9 @@ export declare class ShipError extends Error {
      * Routing:
      * - Already a `ShipError` → returned as-is (caller's intent preserved)
      * - `AbortError` → `ShipError.cancelled(...)` — someone stopped it on purpose
-     * - `TimeoutError` → `ShipError.network(...)` — a deadline expired, so
-     *   nothing was exchanged; the message names the timeout
+     * - `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)
@@ -837,6 +861,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;
@@ -1233,6 +1265,47 @@ export declare function validateApiUrl(apiUrl: string): void;
  * Example: "happy-cat-abc1234.shipstatic.com"
  */
 export declare function isDeployment(input: string): boolean;
+/**
+ * The envelope a requested lifetime must fit — one word, one grammar, wherever
+ * the platform lets a caller choose how long something lives.
+ *
+ * Two resources wear it: `TokenCreateOptions.ttl` and
+ * `DeploymentUploadOptions.ttl`. It lives here rather than on the server by
+ * the format-vs-policy rule — a client can decide offline whether a duration
+ * is well-formed, and the API rejects the same value the same way. What is
+ * NOT here is any per-plan ceiling: no such policy exists, and one delivered
+ * speculatively through `/limits` would be an owner for a decision nobody has
+ * made.
+ */
+export declare const TTL_CONSTRAINTS: {
+    /**
+     * Shortest requestable lifetime, in seconds. One rather than zero: a
+     * deployment that expires the instant it is created is not a shorter lease,
+     * it is a deploy that was never live, and `0` is how an unset variable
+     * arrives.
+     */
+    readonly MIN_SECONDS: 1;
+    /** Longest requestable lifetime, in seconds — one year. */
+    readonly MAX_SECONDS: number;
+};
+/**
+ * Validate a requested lifetime in SECONDS and return it, or `undefined` when
+ * none was asked for.
+ *
+ * **A duration, never an instant.** The caller says how long; the server owns
+ * what time it is and stamps the expiry — so a client's clock, however wrong,
+ * cannot shorten or extend a lease. That is the tokens precedent, and it is
+ * why this rule measures a count of seconds rather than checking a timestamp
+ * against `now`.
+ *
+ * Fractions are refused rather than rounded: a caller who wrote `1.5` meant
+ * something the wire cannot carry, and silently choosing `1` or `2` for them
+ * is a decision the platform has no standing to make.
+ *
+ * Single source of truth shared by the API (the tokens route and the deploy
+ * schema), the SDK's request boundary, and the CLI's parser.
+ */
+export declare function validateTtl(value: unknown): number | undefined;
 /**
  * Request payload for SPA check endpoint
  */
@@ -1365,6 +1438,27 @@ export interface DeploymentUploadOptions {
      * into missing analytics rather than an error. See {@link DeploymentVia}.
      */
     via?: DeploymentViaType;
+    /**
+     * Seconds until this deployment expires; omit for one that never does.
+     *
+     * The platform reclaims it when the time is up — an ephemeral deployment,
+     * chosen by the deployer rather than by the identity. The same word and the
+     * same grammar as {@link TokenCreateOptions.ttl}, bounded by
+     * {@link TTL_CONSTRAINTS}.
+     *
+     * **Requires a credential.** An anonymous deploy has no deployer, and the
+     * platform owns anonymous lifetime as policy
+     * ({@link PUBLIC_DEPLOYMENT_TTL_SECONDS}) — so a ttl on one is refused
+     * rather than honoured or ignored.
+     *
+     * **A deployment carrying one cannot be linked to a domain.** A domain is a
+     * commitment and a deadline is its opposite; the API refuses the link, which
+     * is what keeps the reaper from tearing a live domain's target away.
+     *
+     * Immutable, like every other field of a deployment: to keep something
+     * longer, redeploy.
+     */
+    ttl?: number;
     /**
      * Optional password that protects this deployment.
      *

package/dist/index.js

@@ -214,6 +214,12 @@ export const DEPLOY_FIELDS = {
     VIA: 'via',
     /** Plaintext password — the API hashes it server-side. */
     PASSWORD: 'password',
+    /**
+     * Requested lifetime in SECONDS — a duration, never an instant. The API
+     * computes and stores the expiry, so the wire carries no client clock.
+     * See {@link validateTtl}.
+     */
+    TTL: 'ttl',
     /** @internal Server-processing flag — first-party `/upload` only. */
     BUILD: 'build',
     /** @internal Server-processing flag — first-party `/upload` only. */
@@ -271,6 +277,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 +309,7 @@ export const ErrorType = {
  */
 const CLIENT_ONLY_ERROR_TYPES = new Set([
     ErrorType.Network,
+    ErrorType.Timeout,
     ErrorType.Cancelled,
     ErrorType.File,
     ErrorType.Config,
@@ -301,12 +325,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 +350,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]),
 };
 /**
@@ -382,9 +421,24 @@ const MAX_FOREIGN_MESSAGE_LENGTH = 200;
  * 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.
+ * **The `TokenProvider` case stopped being a trade when clients gained
+ * retries.** A caller's provider that throws a coded error is typed `Network`
+ * here, which was recorded as "both are wrong for it; `Network` is the cheaper
+ * wrong" — written when the classification decided only what a surface would
+ * SAY. It now also decides whether the call is retried, and that turns the
+ * cheaper wrong into the right answer: a `TokenProvider` is where minting and
+ * refresh live, so the common one is an OAuth refresh over the network, and a
+ * transient failure there is precisely what another attempt repairs.
+ *
+ * The residual cost is a deterministic provider fault — a genuinely missing
+ * keychain entry — invoking the provider three times over a few hundred
+ * milliseconds before failing with the same error. No request leaves the
+ * process on any of them. That is the cheap direction of a bet whose other
+ * side is a refused deploy, and suppressing it would need a way to mark
+ * credential faults non-retryable: machinery with one holder, refused by the
+ * estate's stopping rule. Provider failures that carry no code are `Api` and
+ * are not retried at all, and a provider yielding nothing is `Authentication`
+ * by the fail-closed invariant, which is likewise terminal.
  */
 function isTransportFailure(cause) {
     const code = cause.code;
@@ -447,7 +501,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
@@ -531,8 +585,9 @@ export class ShipError extends Error {
      * Routing:
      * - Already a `ShipError` → returned as-is (caller's intent preserved)
      * - `AbortError` → `ShipError.cancelled(...)` — someone stopped it on purpose
-     * - `TimeoutError` → `ShipError.network(...)` — a deadline expired, so
-     *   nothing was exchanged; the message names the timeout
+     * - `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)
@@ -568,11 +623,14 @@ export class ShipError extends Error {
             return ShipError.cancelled(`${op} was cancelled`);
         }
         if (name === 'TimeoutError') {
-            // A deadline, not a fault and not a cancellation: nothing was exchanged,
-            // which is exactly what `Network` claims. The runtime's own sentence is
-            // dropped here rather than relayed — "The operation was aborted due to
-            // timeout" is the mechanism, not the news.
-            return ShipError.network(`${op} timed out`, { cause });
+            // 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 (isTransportFailure(cause)) {
@@ -621,6 +679,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);
     }
@@ -1264,6 +1332,60 @@ export function validateApiUrl(apiUrl) {
 export function isDeployment(input) {
     return /^[a-z]+-[a-z]+-[a-z0-9]{7}(\.[a-z0-9.-]+)?$/i.test(input);
 }
+/**
+ * The envelope a requested lifetime must fit — one word, one grammar, wherever
+ * the platform lets a caller choose how long something lives.
+ *
+ * Two resources wear it: `TokenCreateOptions.ttl` and
+ * `DeploymentUploadOptions.ttl`. It lives here rather than on the server by
+ * the format-vs-policy rule — a client can decide offline whether a duration
+ * is well-formed, and the API rejects the same value the same way. What is
+ * NOT here is any per-plan ceiling: no such policy exists, and one delivered
+ * speculatively through `/limits` would be an owner for a decision nobody has
+ * made.
+ */
+export const TTL_CONSTRAINTS = {
+    /**
+     * Shortest requestable lifetime, in seconds. One rather than zero: a
+     * deployment that expires the instant it is created is not a shorter lease,
+     * it is a deploy that was never live, and `0` is how an unset variable
+     * arrives.
+     */
+    MIN_SECONDS: 1,
+    /** Longest requestable lifetime, in seconds — one year. */
+    MAX_SECONDS: 365 * 24 * 60 * 60,
+};
+/**
+ * Validate a requested lifetime in SECONDS and return it, or `undefined` when
+ * none was asked for.
+ *
+ * **A duration, never an instant.** The caller says how long; the server owns
+ * what time it is and stamps the expiry — so a client's clock, however wrong,
+ * cannot shorten or extend a lease. That is the tokens precedent, and it is
+ * why this rule measures a count of seconds rather than checking a timestamp
+ * against `now`.
+ *
+ * Fractions are refused rather than rounded: a caller who wrote `1.5` meant
+ * something the wire cannot carry, and silently choosing `1` or `2` for them
+ * is a decision the platform has no standing to make.
+ *
+ * Single source of truth shared by the API (the tokens route and the deploy
+ * schema), the SDK's request boundary, and the CLI's parser.
+ */
+export function validateTtl(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw ShipError.validation('TTL must be a number of seconds');
+    }
+    if (!Number.isInteger(value)) {
+        throw ShipError.validation('TTL must be a whole number of seconds');
+    }
+    if (value < TTL_CONSTRAINTS.MIN_SECONDS || value > TTL_CONSTRAINTS.MAX_SECONDS) {
+        throw ShipError.validation(`TTL must be between ${TTL_CONSTRAINTS.MIN_SECONDS} and ${TTL_CONSTRAINTS.MAX_SECONDS} seconds`);
+    }
+    return value;
+}
 // =============================================================================
 // PLATFORM CONSTANTS
 // =============================================================================

package/package.json

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

package/src/index.ts

@@ -756,6 +756,12 @@ export const DEPLOY_FIELDS = {
   VIA: 'via',
   /** Plaintext password — the API hashes it server-side. */
   PASSWORD: 'password',
+  /**
+   * Requested lifetime in SECONDS — a duration, never an instant. The API
+   * computes and stores the expiry, so the wire carries no client clock.
+   * See {@link validateTtl}.
+   */
+  TTL: 'ttl',
   /** @internal Server-processing flag — first-party `/upload` only. */
   BUILD: 'build',
   /** @internal Server-processing flag — first-party `/upload` only. */
@@ -815,6 +821,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 +856,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 +873,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 +898,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;
 
@@ -935,9 +974,24 @@ const MAX_FOREIGN_MESSAGE_LENGTH = 200;
  * 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.
+ * **The `TokenProvider` case stopped being a trade when clients gained
+ * retries.** A caller's provider that throws a coded error is typed `Network`
+ * here, which was recorded as "both are wrong for it; `Network` is the cheaper
+ * wrong" — written when the classification decided only what a surface would
+ * SAY. It now also decides whether the call is retried, and that turns the
+ * cheaper wrong into the right answer: a `TokenProvider` is where minting and
+ * refresh live, so the common one is an OAuth refresh over the network, and a
+ * transient failure there is precisely what another attempt repairs.
+ *
+ * The residual cost is a deterministic provider fault — a genuinely missing
+ * keychain entry — invoking the provider three times over a few hundred
+ * milliseconds before failing with the same error. No request leaves the
+ * process on any of them. That is the cheap direction of a bet whose other
+ * side is a refused deploy, and suppressing it would need a way to mark
+ * credential faults non-retryable: machinery with one holder, refused by the
+ * estate's stopping rule. Provider failures that carry no code are `Api` and
+ * are not retried at all, and a provider yielding nothing is `Authentication`
+ * by the fail-closed invariant, which is likewise terminal.
  */
 function isTransportFailure(cause: Error): boolean {
   const code = (cause as { code?: unknown }).code;
@@ -1019,7 +1073,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
@@ -1107,8 +1161,9 @@ export class ShipError extends Error {
    * Routing:
    * - Already a `ShipError` → returned as-is (caller's intent preserved)
    * - `AbortError` → `ShipError.cancelled(...)` — someone stopped it on purpose
-   * - `TimeoutError` → `ShipError.network(...)` — a deadline expired, so
-   *   nothing was exchanged; the message names the timeout
+   * - `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)
@@ -1145,11 +1200,14 @@ export class ShipError extends Error {
       return ShipError.cancelled(`${op} was cancelled`);
     }
     if (name === 'TimeoutError') {
-      // A deadline, not a fault and not a cancellation: nothing was exchanged,
-      // which is exactly what `Network` claims. The runtime's own sentence is
-      // dropped here rather than relayed — "The operation was aborted due to
-      // timeout" is the mechanism, not the news.
-      return ShipError.network(`${op} timed out`, { cause });
+      // 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) {
@@ -1209,6 +1267,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);
   }
@@ -1985,6 +2054,63 @@ export function isDeployment(input: string): boolean {
   return /^[a-z]+-[a-z]+-[a-z0-9]{7}(\.[a-z0-9.-]+)?$/i.test(input);
 }
 
+/**
+ * The envelope a requested lifetime must fit — one word, one grammar, wherever
+ * the platform lets a caller choose how long something lives.
+ *
+ * Two resources wear it: `TokenCreateOptions.ttl` and
+ * `DeploymentUploadOptions.ttl`. It lives here rather than on the server by
+ * the format-vs-policy rule — a client can decide offline whether a duration
+ * is well-formed, and the API rejects the same value the same way. What is
+ * NOT here is any per-plan ceiling: no such policy exists, and one delivered
+ * speculatively through `/limits` would be an owner for a decision nobody has
+ * made.
+ */
+export const TTL_CONSTRAINTS = {
+  /**
+   * Shortest requestable lifetime, in seconds. One rather than zero: a
+   * deployment that expires the instant it is created is not a shorter lease,
+   * it is a deploy that was never live, and `0` is how an unset variable
+   * arrives.
+   */
+  MIN_SECONDS: 1,
+  /** Longest requestable lifetime, in seconds — one year. */
+  MAX_SECONDS: 365 * 24 * 60 * 60,
+} as const;
+
+/**
+ * Validate a requested lifetime in SECONDS and return it, or `undefined` when
+ * none was asked for.
+ *
+ * **A duration, never an instant.** The caller says how long; the server owns
+ * what time it is and stamps the expiry — so a client's clock, however wrong,
+ * cannot shorten or extend a lease. That is the tokens precedent, and it is
+ * why this rule measures a count of seconds rather than checking a timestamp
+ * against `now`.
+ *
+ * Fractions are refused rather than rounded: a caller who wrote `1.5` meant
+ * something the wire cannot carry, and silently choosing `1` or `2` for them
+ * is a decision the platform has no standing to make.
+ *
+ * Single source of truth shared by the API (the tokens route and the deploy
+ * schema), the SDK's request boundary, and the CLI's parser.
+ */
+export function validateTtl(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw ShipError.validation('TTL must be a number of seconds');
+  }
+  if (!Number.isInteger(value)) {
+    throw ShipError.validation('TTL must be a whole number of seconds');
+  }
+  if (value < TTL_CONSTRAINTS.MIN_SECONDS || value > TTL_CONSTRAINTS.MAX_SECONDS) {
+    throw ShipError.validation(
+      `TTL must be between ${TTL_CONSTRAINTS.MIN_SECONDS} and ${TTL_CONSTRAINTS.MAX_SECONDS} seconds`,
+    );
+  }
+  return value;
+}
+
 // =============================================================================
 // SPA CHECK TYPES
 // =============================================================================
@@ -2142,6 +2268,27 @@ export interface DeploymentUploadOptions {
    * into missing analytics rather than an error. See {@link DeploymentVia}.
    */
   via?: DeploymentViaType;
+  /**
+   * Seconds until this deployment expires; omit for one that never does.
+   *
+   * The platform reclaims it when the time is up — an ephemeral deployment,
+   * chosen by the deployer rather than by the identity. The same word and the
+   * same grammar as {@link TokenCreateOptions.ttl}, bounded by
+   * {@link TTL_CONSTRAINTS}.
+   *
+   * **Requires a credential.** An anonymous deploy has no deployer, and the
+   * platform owns anonymous lifetime as policy
+   * ({@link PUBLIC_DEPLOYMENT_TTL_SECONDS}) — so a ttl on one is refused
+   * rather than honoured or ignored.
+   *
+   * **A deployment carrying one cannot be linked to a domain.** A domain is a
+   * commitment and a deadline is its opposite; the API refuses the link, which
+   * is what keeps the reaper from tearing a live domain's target away.
+   *
+   * Immutable, like every other field of a deployment: to keep something
+   * longer, redeploy.
+   */
+  ttl?: number;
   /**
    * Optional password that protects this deployment.
    *