@shipstatic/ship 2.2.0-beta.5 → 2.2.0-beta.7

package/dist/index.d.cts

@@ -725,6 +725,23 @@ 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 @@ 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 +806,9 @@ 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 +855,14 @@ 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;
@@ -1964,17 +1990,45 @@ interface ShipClientOptions {
     deployEndpoint?: string | undefined;
 }
 /**
- * Event map for Ship SDK events
- * Core events for observability: request, response, error
+ * Event map for Ship SDK events.
+ *
+ * **Every failure is visible, and the event NAME says whether it ended the
+ * call.** One call emits `retry* (error | response)` — so the stream is
+ * unambiguous at every prefix, and a consumer never has to wait to find out
+ * what it is watching.
+ *
+ * `request` counts what went out; `retry` counts what failed and will be
+ * tried again; `error` and `response` are the two terminal answers, exactly
+ * one of which arrives.
  */
 interface ShipEvents {
-    /** Emitted before each API request */
+    /** Emitted before each API request — once per ATTEMPT, so it counts what actually went out. */
     request: [url: string, init: RequestInit];
-    /** Emitted after successful API response */
+    /** Emitted after successful API response — once, on the attempt that worked. */
     response: [response: Response, url: string];
     /**
-     * Emitted when something fails. TWO populations arrive here, which is why
-     * the type is `Error` and not `ShipError`:
+     * Emitted when an attempt failed and the client is going to try again.
+     * Carries the same normalized `ShipError` the terminal `error` would, plus
+     * `attempt` — the number of the attempt that just failed, counting from 1,
+     * which matches the arithmetic the docs use ("two retries by default, so
+     * three attempts"). Under that numbering the value reads both ways at once:
+     * attempt N failing IS retry N, so `retry 1 of ${maxRetries}` needs no
+     * adjustment.
+     *
+     * This event exists so `error` can keep meaning what it always meant. When
+     * retries landed, `error` fired per attempt — honest about what happened,
+     * but it silently redefined the event: a consumer seeing `error, error,
+     * response` could not tell "failed, retrying" from "failed, terminally" at
+     * any prefix, and counting `error`s no longer counted failed calls. Two
+     * names, two meanings, and nothing lost: every failure is still announced.
+     *
+     * A failure the loop will NOT retry is terminal and emits `error` directly,
+     * never this. So is an abort that lands mid-backoff.
+     */
+    retry: [error: Error, url: string, attempt: number];
+    /**
+     * Emitted when the CALL failed — terminally, exactly once. TWO populations
+     * arrive here, which is why the type is `Error` and not `ShipError`:
      *
      *  - a failed request — always a `ShipError` (`executeRequest` normalizes
      *    every failure through `ShipError.fromFetchError` before emitting), so
@@ -2052,9 +2106,16 @@ declare class ApiHttp extends SimpleEvents {
      * for headers, the timeout signal, the events and error normalization — so
      * an attempt is a whole request and nothing has to be undone between two.
      *
-     * **Events stay honest across attempts**: `request` and `error` fire per
-     * attempt, so a consumer counting requests sees what actually went out;
-     * `response` fires once, on the one that worked.
+     * **Every failure is visible, and the event NAME says whether it ended the
+     * call.** One call emits `retry* (error | response)`: `request` fires per
+     * attempt, so a consumer counting requests sees what actually went out; a
+     * failure that will be tried again is a `retry`; `error` and `response` are
+     * the two terminal answers, exactly one of which arrives.
+     *
+     * The failure events are emitted HERE rather than in `attemptOnce`, and
+     * that placement is the whole mechanism: terminality is a property of the
+     * loop — of `isRetryable` and the attempt budget — so it is knowable only
+     * at the one point that owns both. An attempt cannot name its own failure.
      *
      * **The caller's `timeout` governs an ATTEMPT, not the wall clock.** Each
      * attempt is an honest request and deserves the ceiling the caller named;
@@ -2073,7 +2134,12 @@ declare class ApiHttp extends SimpleEvents {
     /** Did this request carry the header that makes a repeat safe? */
     private hasIdempotencyKey;
     /**
-     * One attempt: headers, timeout signal, events, and error normalization.
+     * One attempt: headers, timeout signal, the `request`/`response` events, and
+     * error normalization.
+     *
+     * It does NOT emit a failure event. An attempt cannot know whether its own
+     * failure ended the call — that is `executeRequest`'s question — so it
+     * normalizes and throws, and the loop names what happened.
      */
     private attemptOnce;
     /**
@@ -2436,6 +2502,56 @@ interface MD5Result {
 }
 declare function calculateMD5(input: Blob | Buffer | string): Promise<MD5Result>;
 
+/**
+ * @file One ordered table of deploy-file rules, and the single evaluation two
+ * renderers share.
+ *
+ * **The defect this closes:** one rule was rendering as three sentences. A
+ * file over the size cap said `File x is too large. Maximum allowed size is
+ * 20MB.` from the deploy pipelines, `File size (21 MB) exceeds limit of 20 MB`
+ * from `validateFiles`, and `File too large. Maximum 20971520 bytes allowed`
+ * from the API — against the dual-validation doctrine that an error reads the
+ * same wherever it was caught (root `CLAUDE.md`). Both pipelines also restated
+ * the whole ordered check, so node/browser parity was a comment.
+ *
+ * **A rule states a predicate and a sentence; a renderer chooses only how to
+ * DELIVER it.** That is the `SHAPES`-table move (`cli/formatters.ts`) applied
+ * to validation: the throwing renderer raises the first broken rule, the
+ * collecting renderer records it, and neither authors prose. Adding a rule is
+ * a row, and both surfaces get it in the same position by construction.
+ *
+ * **Wording follows the API where a choice existed**, so the deferred Phase B
+ * — promoting this table to `@shipstatic/types` with the API consuming it —
+ * has less to move. Two deliberate deviations, recorded rather than silent:
+ *
+ * - **Sizes are formatted, not raw bytes.** The API says `20971520 bytes`;
+ *   a browser upload UI showing that is worse for the person reading it, and
+ *   the unit is the smaller half of the sentence to reconcile later.
+ * - **The path is named.** The API has no path to name; the throwing renderer
+ *   has nothing BUT the message, so dropping it would leave a CLI user asking
+ *   which file.
+ *
+ * Out of scope, and left where they are: `validateDeployPath` (a rule about
+ * the deploy PATH rather than the file, and pipelines-only), and
+ * `validateFiles`' UI-tier pre-checks — empty, negative, count, unbuilt
+ * marker, processing error — which have one holder each and no drift.
+ */
+
+/** What a rule is asked about: one file, and the deploy so far. */
+interface FileRuleInput {
+    /** The path this file will be served at. */
+    readonly path: string;
+    /** This file's size in bytes. */
+    readonly size: number;
+    /** Bytes accumulated INCLUDING this file — the total rule's subject. */
+    readonly totalSize: number;
+}
+
+/**
+ * @file Shared security validation for the deploy pipeline.
+ * Used by both Node.js and browser file processing pipelines.
+ */
+
 /**
  * Validate a deploy path for security concerns.
  * Rejects paths containing path traversal patterns or null bytes.
@@ -2454,24 +2570,22 @@ declare function calculateMD5(input: Blob | Buffer | string): Promise<MD5Result>
  */
 declare function validateDeployPath(deployPath: string, sourceIdentifier: string): void;
 /**
- * Validate a deploy file's name and extension.
- * Rejects unsafe filenames (shell/URL-dangerous chars, reserved names)
- * and file extensions the platform refuses to host.
+ * The THROWING renderer of `FILE_RULES` — the deploy pipelines' shape.
  *
- * **The blocklist is the platform's, delivered — not this package's.** It
- * arrives as `PlatformLimits.blockedExtensions` from `GET /limits`, which the
- * client has already fetched by the time any file is processed. That is what
- * keeps a pinned CLI from enforcing a policy the platform has moved on from,
- * in either direction. Callers pass `[]` when the API sent no list (one that
- * predates the field): the check then does nothing and the API refuses the
- * file at the boundary, which is the correct place for it to be refused.
+ * It raises the first rule the file breaks and nothing else: the rules, their
+ * order and their sentences all live in `file-rules.ts`, so this function
+ * cannot re-order, skip or reword one. That is what makes node/browser parity
+ * structural — both pipelines call this, and this calls the one table.
  *
- * @param deployPath - The deployment path to validate
- * @param sourceIdentifier - Human-readable identifier for error messages
- * @param blockedExtensions - The platform's blocklist, from `/limits`
- * @throws {ShipError} If the filename is unsafe or the extension is blocked
+ * Its counterpart is the collecting renderer in `file-validation.ts`
+ * (`validateFiles`), which reaches the same verdict and reports it as a list
+ * instead of a throw.
+ *
+ * @param input - The file and the deploy so far (`totalSize` INCLUDES it)
+ * @param limits - The platform's limits, from `/limits`
+ * @throws {ShipError} The first broken rule's sentence
  */
-declare function validateDeployFile(deployPath: string, sourceIdentifier: string, blockedExtensions: readonly string[]): void;
+declare function validateDeployFile(input: FileRuleInput, limits: PlatformLimits): void;
 
 /**
  * Utility functions for string manipulation.

package/dist/index.d.ts

@@ -725,6 +725,23 @@ 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 @@ 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 +806,9 @@ 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 +855,14 @@ 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;
@@ -1964,17 +1990,45 @@ interface ShipClientOptions {
     deployEndpoint?: string | undefined;
 }
 /**
- * Event map for Ship SDK events
- * Core events for observability: request, response, error
+ * Event map for Ship SDK events.
+ *
+ * **Every failure is visible, and the event NAME says whether it ended the
+ * call.** One call emits `retry* (error | response)` — so the stream is
+ * unambiguous at every prefix, and a consumer never has to wait to find out
+ * what it is watching.
+ *
+ * `request` counts what went out; `retry` counts what failed and will be
+ * tried again; `error` and `response` are the two terminal answers, exactly
+ * one of which arrives.
  */
 interface ShipEvents {
-    /** Emitted before each API request */
+    /** Emitted before each API request — once per ATTEMPT, so it counts what actually went out. */
     request: [url: string, init: RequestInit];
-    /** Emitted after successful API response */
+    /** Emitted after successful API response — once, on the attempt that worked. */
     response: [response: Response, url: string];
     /**
-     * Emitted when something fails. TWO populations arrive here, which is why
-     * the type is `Error` and not `ShipError`:
+     * Emitted when an attempt failed and the client is going to try again.
+     * Carries the same normalized `ShipError` the terminal `error` would, plus
+     * `attempt` — the number of the attempt that just failed, counting from 1,
+     * which matches the arithmetic the docs use ("two retries by default, so
+     * three attempts"). Under that numbering the value reads both ways at once:
+     * attempt N failing IS retry N, so `retry 1 of ${maxRetries}` needs no
+     * adjustment.
+     *
+     * This event exists so `error` can keep meaning what it always meant. When
+     * retries landed, `error` fired per attempt — honest about what happened,
+     * but it silently redefined the event: a consumer seeing `error, error,
+     * response` could not tell "failed, retrying" from "failed, terminally" at
+     * any prefix, and counting `error`s no longer counted failed calls. Two
+     * names, two meanings, and nothing lost: every failure is still announced.
+     *
+     * A failure the loop will NOT retry is terminal and emits `error` directly,
+     * never this. So is an abort that lands mid-backoff.
+     */
+    retry: [error: Error, url: string, attempt: number];
+    /**
+     * Emitted when the CALL failed — terminally, exactly once. TWO populations
+     * arrive here, which is why the type is `Error` and not `ShipError`:
      *
      *  - a failed request — always a `ShipError` (`executeRequest` normalizes
      *    every failure through `ShipError.fromFetchError` before emitting), so
@@ -2052,9 +2106,16 @@ declare class ApiHttp extends SimpleEvents {
      * for headers, the timeout signal, the events and error normalization — so
      * an attempt is a whole request and nothing has to be undone between two.
      *
-     * **Events stay honest across attempts**: `request` and `error` fire per
-     * attempt, so a consumer counting requests sees what actually went out;
-     * `response` fires once, on the one that worked.
+     * **Every failure is visible, and the event NAME says whether it ended the
+     * call.** One call emits `retry* (error | response)`: `request` fires per
+     * attempt, so a consumer counting requests sees what actually went out; a
+     * failure that will be tried again is a `retry`; `error` and `response` are
+     * the two terminal answers, exactly one of which arrives.
+     *
+     * The failure events are emitted HERE rather than in `attemptOnce`, and
+     * that placement is the whole mechanism: terminality is a property of the
+     * loop — of `isRetryable` and the attempt budget — so it is knowable only
+     * at the one point that owns both. An attempt cannot name its own failure.
      *
      * **The caller's `timeout` governs an ATTEMPT, not the wall clock.** Each
      * attempt is an honest request and deserves the ceiling the caller named;
@@ -2073,7 +2134,12 @@ declare class ApiHttp extends SimpleEvents {
     /** Did this request carry the header that makes a repeat safe? */
     private hasIdempotencyKey;
     /**
-     * One attempt: headers, timeout signal, events, and error normalization.
+     * One attempt: headers, timeout signal, the `request`/`response` events, and
+     * error normalization.
+     *
+     * It does NOT emit a failure event. An attempt cannot know whether its own
+     * failure ended the call — that is `executeRequest`'s question — so it
+     * normalizes and throws, and the loop names what happened.
      */
     private attemptOnce;
     /**
@@ -2436,6 +2502,56 @@ interface MD5Result {
 }
 declare function calculateMD5(input: Blob | Buffer | string): Promise<MD5Result>;
 
+/**
+ * @file One ordered table of deploy-file rules, and the single evaluation two
+ * renderers share.
+ *
+ * **The defect this closes:** one rule was rendering as three sentences. A
+ * file over the size cap said `File x is too large. Maximum allowed size is
+ * 20MB.` from the deploy pipelines, `File size (21 MB) exceeds limit of 20 MB`
+ * from `validateFiles`, and `File too large. Maximum 20971520 bytes allowed`
+ * from the API — against the dual-validation doctrine that an error reads the
+ * same wherever it was caught (root `CLAUDE.md`). Both pipelines also restated
+ * the whole ordered check, so node/browser parity was a comment.
+ *
+ * **A rule states a predicate and a sentence; a renderer chooses only how to
+ * DELIVER it.** That is the `SHAPES`-table move (`cli/formatters.ts`) applied
+ * to validation: the throwing renderer raises the first broken rule, the
+ * collecting renderer records it, and neither authors prose. Adding a rule is
+ * a row, and both surfaces get it in the same position by construction.
+ *
+ * **Wording follows the API where a choice existed**, so the deferred Phase B
+ * — promoting this table to `@shipstatic/types` with the API consuming it —
+ * has less to move. Two deliberate deviations, recorded rather than silent:
+ *
+ * - **Sizes are formatted, not raw bytes.** The API says `20971520 bytes`;
+ *   a browser upload UI showing that is worse for the person reading it, and
+ *   the unit is the smaller half of the sentence to reconcile later.
+ * - **The path is named.** The API has no path to name; the throwing renderer
+ *   has nothing BUT the message, so dropping it would leave a CLI user asking
+ *   which file.
+ *
+ * Out of scope, and left where they are: `validateDeployPath` (a rule about
+ * the deploy PATH rather than the file, and pipelines-only), and
+ * `validateFiles`' UI-tier pre-checks — empty, negative, count, unbuilt
+ * marker, processing error — which have one holder each and no drift.
+ */
+
+/** What a rule is asked about: one file, and the deploy so far. */
+interface FileRuleInput {
+    /** The path this file will be served at. */
+    readonly path: string;
+    /** This file's size in bytes. */
+    readonly size: number;
+    /** Bytes accumulated INCLUDING this file — the total rule's subject. */
+    readonly totalSize: number;
+}
+
+/**
+ * @file Shared security validation for the deploy pipeline.
+ * Used by both Node.js and browser file processing pipelines.
+ */
+
 /**
  * Validate a deploy path for security concerns.
  * Rejects paths containing path traversal patterns or null bytes.
@@ -2454,24 +2570,22 @@ declare function calculateMD5(input: Blob | Buffer | string): Promise<MD5Result>
  */
 declare function validateDeployPath(deployPath: string, sourceIdentifier: string): void;
 /**
- * Validate a deploy file's name and extension.
- * Rejects unsafe filenames (shell/URL-dangerous chars, reserved names)
- * and file extensions the platform refuses to host.
+ * The THROWING renderer of `FILE_RULES` — the deploy pipelines' shape.
  *
- * **The blocklist is the platform's, delivered — not this package's.** It
- * arrives as `PlatformLimits.blockedExtensions` from `GET /limits`, which the
- * client has already fetched by the time any file is processed. That is what
- * keeps a pinned CLI from enforcing a policy the platform has moved on from,
- * in either direction. Callers pass `[]` when the API sent no list (one that
- * predates the field): the check then does nothing and the API refuses the
- * file at the boundary, which is the correct place for it to be refused.
+ * It raises the first rule the file breaks and nothing else: the rules, their
+ * order and their sentences all live in `file-rules.ts`, so this function
+ * cannot re-order, skip or reword one. That is what makes node/browser parity
+ * structural — both pipelines call this, and this calls the one table.
  *
- * @param deployPath - The deployment path to validate
- * @param sourceIdentifier - Human-readable identifier for error messages
- * @param blockedExtensions - The platform's blocklist, from `/limits`
- * @throws {ShipError} If the filename is unsafe or the extension is blocked
+ * Its counterpart is the collecting renderer in `file-validation.ts`
+ * (`validateFiles`), which reaches the same verdict and reports it as a list
+ * instead of a throw.
+ *
+ * @param input - The file and the deploy so far (`totalSize` INCLUDES it)
+ * @param limits - The platform's limits, from `/limits`
+ * @throws {ShipError} The first broken rule's sentence
  */
-declare function validateDeployFile(deployPath: string, sourceIdentifier: string, blockedExtensions: readonly string[]): void;
+declare function validateDeployFile(input: FileRuleInput, limits: PlatformLimits): void;
 
 /**
  * Utility functions for string manipulation.