@shipstatic/types 2.5.0-beta.17 → 2.5.0-beta.19

package/dist/index.d.ts

@@ -668,7 +668,8 @@ export declare class ShipError extends Error {
      * Routing:
      * - Already a `ShipError` → returned as-is (caller's intent preserved)
      * - `AbortError` → `ShipError.cancelled(...)`
-     * - `TypeError` whose message mentions "fetch" → `ShipError.network(...)`
+     * - 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, ...)`
      *
@@ -1093,6 +1094,21 @@ export interface StaticFile {
 }
 /** Default API URL if not otherwise configured. */
 export declare const DEFAULT_API = "https://api.shipstatic.com";
+/**
+ * How long an anonymous deployment lives before it expires.
+ *
+ * The lifetime of the public tier, and one fact with several readers. The API
+ * stamps a deployment's `expires` from it and gives a claim code exactly the
+ * same window — a live site with a dead claim link is a coherence bug, so the
+ * two are one constant rather than two that agree. Both MCP transports quote
+ * the duration in prose an agent reads, and derive it from here rather than
+ * writing it out, which they did in eight places until this export existed.
+ *
+ * Seconds, spelled in the name: this platform has both second- and
+ * millisecond-valued durations, and the pair is only safe when each says which
+ * it is.
+ */
+export declare const PUBLIC_DEPLOYMENT_TTL_SECONDS: number;
 /**
  * Universal deploy input — the union of every shape the SDK accepts.
  *
@@ -1144,8 +1160,8 @@ export interface DeploymentUploadOptions {
      *
      * **Agents are the audience.** A human notices a duplicate; an automated
      * retry does not. Pick a key that identifies the ATTEMPT — a run id, a
-     * commit sha, a uuid minted before the first try — never one that varies
-     * per attempt, which would defeat the point.
+     * commit sha, a uuid minted before the first try — never one minted fresh
+     * on each retry, which would defeat the point.
      *
      * The replay is per-caller, and it stores successes only: a failed deploy
      * retries fresh under the same key.

package/dist/index.js

@@ -237,6 +237,42 @@ const SERVER_PRODUCIBLE_ERROR_TYPES = new Set(Object.values(ErrorType).filter((t
  * contract, and truncating a long validation message would be the bug.
  */
 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.
+ */
+function isTransportFailure(cause) {
+    if (typeof cause.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');
+}
 /**
  * Simple unified error class for both API and SDK
  */
@@ -362,7 +398,8 @@ export class ShipError extends Error {
      * Routing:
      * - Already a `ShipError` → returned as-is (caller's intent preserved)
      * - `AbortError` → `ShipError.cancelled(...)`
-     * - `TypeError` whose message mentions "fetch" → `ShipError.network(...)`
+     * - 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, ...)`
      *
@@ -378,7 +415,7 @@ export class ShipError extends Error {
             if (cause.name === 'AbortError') {
                 return ShipError.cancelled(`${op} was cancelled`);
             }
-            if (cause instanceof TypeError && cause.message.includes('fetch')) {
+            if (isTransportFailure(cause)) {
                 return ShipError.network(`${op} failed: ${cause.message}`, { cause });
             }
             return new ShipError(ErrorType.Api, `${op} failed: ${cause.message}`);
@@ -1002,6 +1039,21 @@ export function isDeployment(input) {
 // =============================================================================
 /** Default API URL if not otherwise configured. */
 export const DEFAULT_API = 'https://api.shipstatic.com';
+/**
+ * How long an anonymous deployment lives before it expires.
+ *
+ * The lifetime of the public tier, and one fact with several readers. The API
+ * stamps a deployment's `expires` from it and gives a claim code exactly the
+ * same window — a live site with a dead claim link is a coherence bug, so the
+ * two are one constant rather than two that agree. Both MCP transports quote
+ * the duration in prose an agent reads, and derive it from here rather than
+ * writing it out, which they did in eight places until this export existed.
+ *
+ * Seconds, spelled in the name: this platform has both second- and
+ * millisecond-valued durations, and the pair is only safe when each says which
+ * it is.
+ */
+export const PUBLIC_DEPLOYMENT_TTL_SECONDS = 3 * 24 * 60 * 60;
 // =============================================================================
 // FILE UPLOAD TYPES
 // =============================================================================

package/package.json

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

package/src/index.ts

@@ -754,6 +754,42 @@ const SERVER_PRODUCIBLE_ERROR_TYPES = new Set<string>(
  */
 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.
+ */
+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');
+}
+
 /**
  * Standard error response format used everywhere
  */
@@ -900,7 +936,8 @@ export class ShipError extends Error {
    * Routing:
    * - Already a `ShipError` → returned as-is (caller's intent preserved)
    * - `AbortError` → `ShipError.cancelled(...)`
-   * - `TypeError` whose message mentions "fetch" → `ShipError.network(...)`
+   * - 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, ...)`
    *
@@ -917,7 +954,7 @@ export class ShipError extends Error {
       if (cause.name === 'AbortError') {
         return ShipError.cancelled(`${op} was cancelled`);
       }
-      if (cause instanceof TypeError && cause.message.includes('fetch')) {
+      if (isTransportFailure(cause)) {
         return ShipError.network(`${op} failed: ${cause.message}`, { cause });
       }
       return new ShipError(ErrorType.Api, `${op} failed: ${cause.message}`);
@@ -1735,6 +1772,22 @@ export interface StaticFile {
 /** Default API URL if not otherwise configured. */
 export const DEFAULT_API = 'https://api.shipstatic.com';
 
+/**
+ * How long an anonymous deployment lives before it expires.
+ *
+ * The lifetime of the public tier, and one fact with several readers. The API
+ * stamps a deployment's `expires` from it and gives a claim code exactly the
+ * same window — a live site with a dead claim link is a coherence bug, so the
+ * two are one constant rather than two that agree. Both MCP transports quote
+ * the duration in prose an agent reads, and derive it from here rather than
+ * writing it out, which they did in eight places until this export existed.
+ *
+ * Seconds, spelled in the name: this platform has both second- and
+ * millisecond-valued durations, and the pair is only safe when each says which
+ * it is.
+ */
+export const PUBLIC_DEPLOYMENT_TTL_SECONDS = 3 * 24 * 60 * 60;
+
 // =============================================================================
 // RESOURCE INTERFACE CONTRACTS
 // =============================================================================
@@ -1791,8 +1844,8 @@ export interface DeploymentUploadOptions {
    *
    * **Agents are the audience.** A human notices a duplicate; an automated
    * retry does not. Pick a key that identifies the ATTEMPT — a run id, a
-   * commit sha, a uuid minted before the first try — never one that varies
-   * per attempt, which would defeat the point.
+   * commit sha, a uuid minted before the first try — never one minted fresh
+   * on each retry, which would defeat the point.
    *
    * The replay is per-caller, and it stores successes only: a failed deploy
    * retries fresh under the same key.