@shipstatic/ship 2.0.0-beta.9 → 2.1.0

package/README.md

@@ -129,7 +129,7 @@ ship ping
 
 ```typescript
 ship.account.get()            // → whoami
-ship.ping()                   // → boolean
+ship.ping()                   // → { timestamp } (server clock; reachability is the absence of a throw)
 ship.getLimits()              // → platform plan limits (cached)
 ```
 
@@ -139,6 +139,8 @@ ship.getLimits()              // → platform plan limits (cached)
 
 The `-q` flag outputs only the resource identifier — perfect for piping and scripting:
 
+`ship tokens create -q` is the one exception: it prints the token **secret**, which is shown once and never again.
+
 ```bash
 # Deploy and link domain in one pipe
 ship ./dist -q | ship domains set www.example.com
@@ -318,7 +320,15 @@ The **CLI** (`ship`) resolves its token in this order:
 
 1. CLI flag: `--token`
 2. Environment variable: `SHIP_TOKEN`
-3. Config files: `.shiprc` or `package.json` `"ship"` key (run `ship config` to create one)
+3. Config file: `~/.shiprc` (run `ship config` to create one)
+
+`--config <file>` reads any path you name instead of `~/.shiprc`, which is how per-environment
+configs work (`ship --config dev.shiprc ...`). The file is strict JSON; an empty one means "no
+config".
+
+**No repository file is ever read.** A `.shiprc` or `package.json` `"ship"` key in your working
+directory is ignored — cloning a repo can never change which account you deploy to, or which
+host your token is sent to.
 
 The **SDK** (`new Ship(...)`) resolves its token in this order:
 

package/SKILL.md

@@ -223,6 +223,8 @@ Every command supports three modes:
 | `--json` | JSON on stdout | Parsing programmatically |
 | `-q` | Identifier only | Piping between commands |
 
+`-q` prints the resource identifier — except `tokens create -q`, which prints the token **secret** (shown once, never again).
+
 Errors go to stderr in all modes. Exit 0 = success, 1 = error.
 
 List commands return `{"<resource>s": [...], "cursor": null}`. A non-null `cursor` means more pages remain — pass it back with `--cursor` to continue, and size pages with `--limit`. There is no total; a count is an aggregate over a collection, not a property of one page. `domains list` text mode omits status — use `--json` to see `pending` vs `success`.

package/dist/browser.d.ts

@@ -12,6 +12,28 @@ declare const DeploymentStatus: {
     readonly DELETING: "deleting";
 };
 type DeploymentStatusType = (typeof DeploymentStatus)[keyof typeof DeploymentStatus];
+/**
+ * Which client made a deployment — the origin-tracking vocabulary.
+ *
+ * A closed set with many authors: the CLI, the SDK, the dashboard, both MCP
+ * transports, the GitHub Action, the n8n node and the VS Code extension each
+ * name themselves here. It lived in the API's config until 2026-08-06, where
+ * being server-side made it unenforceable in the one direction that matters —
+ * every client wrote a bare string, and a value outside the set was **silently
+ * dropped** by the server, so a typo did not fail anywhere. It stopped
+ * recording where deploys came from and said nothing.
+ */
+declare const DeploymentVia: {
+    readonly WEB: "web";
+    readonly SDK: "sdk";
+    readonly CLI: "cli";
+    readonly MCP: "mcp";
+    readonly GIT: "git";
+    readonly N8N: "n8n";
+    readonly GPT: "gpt";
+    readonly VSC: "vsc";
+};
+type DeploymentViaType = (typeof DeploymentVia)[keyof typeof DeploymentVia];
 /**
  * Core deployment object - used in both API responses and SDK
  */
@@ -32,7 +54,15 @@ interface Deployment {
     readonly password: boolean;
     /** Labels for categorization and filtering (lowercase, alphanumeric with separators). Always present, empty array when none. */
     labels: string[];
-    /** The client/tool used to create this deployment (e.g., 'web', 'sdk', 'cli'), null if unknown */
+    /**
+     * The client/tool that created this deployment, null if unknown.
+     *
+     * Deliberately wider than {@link DeploymentViaType}: this is stored data,
+     * and rows predate the vocabulary being closed. Narrowing the ENTITY would
+     * be a claim about every row already in the database; narrowing the
+     * REQUEST option ({@link DeploymentUploadOptions.via}) is a claim about
+     * what a client may send, which is ours to make.
+     */
     readonly via: string | null;
     /** Unix timestamp (seconds) when deployment was created */
     readonly created: number;
@@ -49,62 +79,6 @@ interface DeploymentCreateResponse extends Deployment {
     /** Claim URL for public deployments. Present when deployed without credentials. */
     readonly claim?: string;
 }
-/**
- * Every path the public API answers on, declared once.
- *
- * The URL surface was written out in four places — the API's mounts, the
- * SDK's client, the dashboard's client, and the post-deploy smoke — so a
- * rename meant finding all four. The first three now read this table.
- *
- * The smoke (`cloudflare/api/smoke.mjs`) deliberately still spells its own:
- * five of its nine paths are `/admin/*`, which this table excludes by
- * design, and splitting one list between a registry and literals reads worse
- * than keeping it uniform.
- *
- * **What this guarantees, exactly.** Collection paths are mounted from here,
- * so producer and consumer cannot diverge. Item paths are declared here and
- * consumed by clients, but the API spells them relative to their mount
- * (`/:deployment/config`), so the table does not *generate* them — it is
- * held to them by `api/tests/architecture/api-paths.test.ts`, which fails if
- * any entry names a path no route answers. Some entries have no client yet
- * (`DEPLOYMENT_CONFIG`, `DOMAIN_PROPAGATION` — endpoints the SDK
- * deliberately does not reach); the fence is what keeps those honest rather
- * than merely asserted.
- *
- * **The operator surface is deliberately absent.** `/admin/*` paths belong
- * to `web/my`, for the same reason its row types do: this package is
- * published, and the operator surface is not public (see `CLAUDE.md`, "Admin
- * types"). A path here is a promise to every npm consumer; `/admin` is a
- * promise to one dashboard.
- *
- * Item paths are functions rather than templates so the key is interpolated
- * in one place, encoded the same way by every caller.
- */
-declare const API_PATHS: {
-    readonly DEPLOYMENTS: "/deployments";
-    readonly DEPLOYMENT: (deployment: string) => string;
-    readonly DEPLOYMENT_CONFIG: (deployment: string) => string;
-    readonly DOMAINS: "/domains";
-    readonly DOMAIN: (domain: string) => string;
-    readonly DOMAIN_VERIFY: (domain: string) => string;
-    readonly DOMAIN_DNS: (domain: string) => string;
-    readonly DOMAIN_RECORDS: (domain: string) => string;
-    readonly DOMAIN_SHARE: (domain: string) => string;
-    readonly DOMAIN_PROPAGATION: (domain: string) => string;
-    readonly DOMAINS_VALIDATE: "/domains/validate";
-    readonly TOKENS: "/tokens";
-    readonly TOKEN: (token: string) => string;
-    readonly ACCOUNT: "/account";
-    readonly ACCOUNT_KEY: "/account/key";
-    readonly ACCOUNT_CLAIM: "/account/claim";
-    readonly ACTIVITIES: "/activities";
-    readonly LABELS: "/labels";
-    readonly LIMITS: "/limits";
-    readonly PING: "/ping";
-    readonly SETUP: "/setup";
-    readonly SPA_CHECK: "/spa-check";
-    readonly UPLOAD: "/upload";
-};
 /**
  * The half of a list response that is identical on every list.
  *
@@ -123,6 +97,28 @@ interface ListResponse {
     /** Opaque cursor from this page; `null` on the last page. */
     cursor: string | null;
 }
+/**
+ * Pagination options for every list endpoint. The response's `cursor` feeds
+ * the next request; a `null` cursor means the last page. Omitting both
+ * returns the server's default first page.
+ *
+ * A list answers `{ <collection>, cursor }` and nothing else — `cursor`
+ * carries the entire has-more signal, so no redundant boolean, and no
+ * `total`. **A count is an aggregate over a collection, not a property of a
+ * page:** including one makes every read pay for a full scan it did not ask
+ * for, which is precisely the cost keyset pagination exists to avoid.
+ *
+ * Counts therefore live on the summary resource that owns them —
+ * `GET /account` (`usage`) for a caller's own totals, `GET /admin/stats` for
+ * platform-wide ones. Ask for a count when you want a count; ask for a page
+ * when you want a page.
+ */
+interface ListOptions {
+    /** Maximum number of items to return in one page. */
+    limit?: number;
+    /** Opaque cursor from the previous page's response. */
+    cursor?: string;
+}
 /**
  * Response for listing deployments
  */
@@ -324,10 +320,33 @@ interface DomainRecordsResponse {
  * API would reject the same value the same way.
  */
 declare const IDEMPOTENCY_KEY_CONSTRAINTS: {
+    /**
+     * HTTP header name. Here for the same reason {@link CALLER.HEADER} is: a
+     * wire header has two ends, and the package that owns the value's format
+     * is the only place both ends can read its name from.
+     */
+    readonly HEADER: "Idempotency-Key";
     readonly MAX_LENGTH: 256;
     /** How long a stored 201 stays replayable. */
     readonly WINDOW_SECONDS: number;
 };
+/**
+ * Normalize a `via` value from any transport — trimmed, lowercased, and a
+ * member of {@link DeploymentVia}, or `undefined`.
+ *
+ * A format rule by this package's own test: a client can decide offline
+ * whether a value is well-formed, and the API reaches the same verdict on the
+ * same input. It lived server-side until 2026-08-06, which meant clients could
+ * only learn their label was unusable by noticing analytics had gone quiet.
+ *
+ * **Not knowing your `via` is not an error** — an unrecognized value yields
+ * `undefined` rather than throwing, because origin tracking is telemetry and a
+ * deploy must never fail over it. A caller that has an honest default should
+ * prefer it (`normalizeVia(process.env.SHIP_VIA) ?? DeploymentVia.CLI`): the
+ * deploy really did come from the CLI, so recording that beats recording
+ * nothing.
+ */
+declare function normalizeVia(value: unknown): DeploymentViaType | undefined;
 /**
  * Validate an idempotency key, returning the trimmed value or `undefined`
  * when none was supplied. Throws {@link ShipError.validation} when the value
@@ -570,6 +589,97 @@ interface AccountOverrides {
     /** Override for maximum total deployment size in bytes */
     totalSize?: number;
 }
+/**
+ * Every path the public API answers on, declared once.
+ *
+ * The URL surface was written out in four places — the API's mounts, the
+ * SDK's client, the dashboard's client, and the post-deploy smoke — so a
+ * rename meant finding all four. The first three now read this table.
+ *
+ * The smoke (`cloudflare/api/smoke.mjs`) deliberately still spells its own:
+ * five of its nine paths are `/admin/*`, which this table excludes by
+ * design, and splitting one list between a registry and literals reads worse
+ * than keeping it uniform.
+ *
+ * **What this guarantees, exactly.** Collection paths are mounted from here,
+ * so producer and consumer cannot diverge. Item paths are declared here and
+ * consumed by clients, but the API spells them relative to their mount
+ * (`/:deployment/config`), so the table does not *generate* them — it is
+ * held to them by `api/tests/architecture/api-paths.test.ts`, which fails if
+ * any entry names a path no route answers. Some entries have no client yet
+ * (`DEPLOYMENT_CONFIG`, `DOMAIN_PROPAGATION` — endpoints the SDK
+ * deliberately does not reach); the fence is what keeps those honest rather
+ * than merely asserted.
+ *
+ * **The operator surface is deliberately absent.** `/admin/*` paths belong
+ * to `web/my`, for the same reason its row types do: this package is
+ * published, and the operator surface is not public (see `CLAUDE.md`, "Admin
+ * types"). A path here is a promise to every npm consumer; `/admin` is a
+ * promise to one dashboard.
+ *
+ * Item paths are functions rather than templates so the key is interpolated
+ * in one place, encoded the same way by every caller.
+ */
+declare const API_PATHS: {
+    readonly DEPLOYMENTS: "/deployments";
+    readonly DEPLOYMENT: (deployment: string) => string;
+    readonly DEPLOYMENT_CONFIG: (deployment: string) => string;
+    readonly DOMAINS: "/domains";
+    readonly DOMAIN: (domain: string) => string;
+    readonly DOMAIN_VERIFY: (domain: string) => string;
+    readonly DOMAIN_DNS: (domain: string) => string;
+    readonly DOMAIN_RECORDS: (domain: string) => string;
+    readonly DOMAIN_SHARE: (domain: string) => string;
+    readonly DOMAIN_PROPAGATION: (domain: string) => string;
+    readonly DOMAINS_VALIDATE: "/domains/validate";
+    readonly TOKENS: "/tokens";
+    readonly TOKEN: (token: string) => string;
+    readonly ACCOUNT: "/account";
+    readonly ACCOUNT_KEY: "/account/key";
+    readonly ACCOUNT_CLAIM: "/account/claim";
+    readonly ACTIVITIES: "/activities";
+    readonly LABELS: "/labels";
+    readonly LIMITS: "/limits";
+    readonly PING: "/ping";
+    readonly SETUP: "/setup";
+    readonly SPA_CHECK: "/spa-check";
+    readonly UPLOAD: "/upload";
+};
+/**
+ * The deploy request's multipart field names — the other half of the wire
+ * surface beside {@link API_PATHS}. `POST /deployments` (and the first-party
+ * `/upload`) is multipart/form-data, and these are the names the API reads.
+ *
+ * Declared once because the body has three independent WRITERS — the SDK's
+ * Node and browser body builders, and the n8n community node's hand-rolled
+ * client (which cannot import this under n8n Cloud's zero-dependency rule,
+ * and fences its restated copy instead) — and until this export every writer
+ * restated the strings the API parses, with nothing comparing them.
+ *
+ * `FILES` carries one entry per file (the API reads it with `getAll`); every
+ * other field is single. The `@internal` flags are serialized as the literal
+ * string `'true'` and belong to first-party surfaces only.
+ */
+declare const DEPLOY_FIELDS: {
+    /** One entry per file — read with `getAll`. */
+    readonly FILES: "files[]";
+    /** JSON array of MD5 hex digests, index-aligned with `FILES`. */
+    readonly CHECKSUMS: "checksums";
+    /** JSON array of label strings. */
+    readonly LABELS: "labels";
+    /** The deploying surface's {@link DeploymentVia} member. */
+    readonly VIA: "via";
+    /** Plaintext password — the API hashes it server-side. */
+    readonly PASSWORD: "password";
+    /** @internal Server-processing flag — first-party `/upload` only. */
+    readonly BUILD: "build";
+    /** @internal Server-processing flag — first-party `/upload` only. */
+    readonly PRERENDER: "prerender";
+    /** @internal Server-processing flag — first-party `/upload` only. */
+    readonly SPA: "spa";
+    /** @internal reCAPTCHA proof — `web/www`'s public uploader only. */
+    readonly CAPTCHA: "captcha";
+};
 /**
  * All possible error types in the ShipStatic platform.
  *
@@ -602,6 +712,17 @@ declare const ErrorType: {
     readonly Business: "business_logic_error";
     /** API server error (500). Generic server-side fault. */
     readonly Api: "internal_server_error";
+    /**
+     * The platform is closed for maintenance (503). A deliberate operator
+     * state, not a fault — nothing errored; the API is refusing work on
+     * purpose, and deployed sites keep serving throughout.
+     *
+     * Distinct from `Api` at 503, which the platform already uses for a
+     * dependency that failed (moderation unavailable). A consumer has to tell
+     * "we closed the door" from "something broke": the two get opposite words
+     * and opposite retry behaviour.
+     */
+    readonly Maintenance: "maintenance";
     /** Network/connection error. Client-side only — set by HTTP clients on fetch failure; never produced server-side. */
     readonly Network: "network_error";
     /** Operation was cancelled. Client-side only — set on `AbortSignal` abort; never produced server-side. */
@@ -668,7 +789,8 @@ 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, ...)`
      *
@@ -701,6 +823,16 @@ declare class ShipError extends Error {
     static file(message: string, details?: unknown): ShipError;
     static config(message: string, details?: unknown): ShipError;
     static api(message: string, status?: number, details?: unknown): ShipError;
+    /**
+     * The platform is closed for maintenance (503).
+     *
+     * `message` is REQUIRED and has no default here. The API is the only
+     * producer of that sentence, and a default in this file would be a second
+     * owner of one fact — see CLAUDE.md, "The Constellation Law" (stopping
+     * rule). It is also the one factory whose status is fixed rather than
+     * defaulted: a maintenance refusal is 503 or it is not this error.
+     */
+    static maintenance(message: string, details?: unknown): ShipError;
     /**
      * The caller is at fault — by HTTP's own definition of a 4xx, or by a type
      * that is client-attributable without ever having a status (`Config`,
@@ -775,6 +907,28 @@ declare const BLOCKED_EXTENSIONS: ReadonlySet<string>;
  * isBlockedExtension('README')        // false
  */
 declare function isBlockedExtension(filename: string): boolean;
+/**
+ * The `accept` attribute value for a browser file picker offering web files.
+ *
+ * **This is a hint, never a rule.** `BLOCKED_EXTENSIONS` is the platform's
+ * gate and the only thing that decides what may be hosted; this constant
+ * decides what a *file dialog* shows first. The two are not two halves of one
+ * policy, and this one must never be consulted to accept or reject a file.
+ *
+ * The distinction is structural, not stylistic. `accept` can express only an
+ * allowlist, while the platform's rule is a blocklist — so this list is
+ * necessarily *narrower* than what the platform hosts, and reading it as
+ * authority would reject files the platform serves happily. It is also not
+ * enforcement in the browser's own terms: every file dialog offers an
+ * all-files escape, and **drag-and-drop ignores `accept` entirely**. The
+ * dropzone and the picker must reach the same verdict on the same files, and
+ * they do — because the verdict is `validateFiles`, downstream of both.
+ *
+ * Kept beside `BLOCKED_EXTENSIONS` so one file holds both, which is what lets
+ * `tests/validation-constants.test.ts` fence the invariant that matters: the
+ * picker must never offer a file the platform will refuse.
+ */
+declare const WEB_FILE_ACCEPT: string;
 /**
  * Characters that are unsafe in filenames for static hosting.
  *
@@ -855,30 +1009,35 @@ declare const AuthMethod: {
 };
 type AuthMethodType = (typeof AuthMethod)[keyof typeof AuthMethod];
 /**
- * Shape constants for API keys (`ship-{64 hex chars}`).
+ * Shape constants for API keys (`ship-{32 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
  */
 declare const API_KEY: {
     /** Prefix that identifies an API key. */
     readonly PREFIX: "ship-";
     /** Number of hex characters following the prefix. */
-    readonly HEX_LENGTH: 64;
-    /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 69`). */
-    readonly TOTAL_LENGTH: 69;
+    readonly HEX_LENGTH: 32;
+    /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 37`). */
+    readonly TOTAL_LENGTH: 37;
     /** Number of trailing characters used to display a redacted hint (e.g. last 4). */
     readonly HINT_LENGTH: 4;
 };
 /**
- * Shape constants for deploy tokens (`deploy-{64 hex chars}`).
+ * Shape constants for deploy tokens (`deploy-{32 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
+ *
+ * Deliberately the same width as `API_KEY`: both are minted by one generator
+ * and classified by prefix alone, so a length that differed between them
+ * would be a second thing to know about a credential whose prefix already
+ * says what it is.
  */
 declare const DEPLOY_TOKEN: {
     /** Prefix that identifies a deploy token. */
     readonly PREFIX: "deploy-";
     /** Number of hex characters following the prefix. */
-    readonly HEX_LENGTH: 64;
-    /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 71`). */
-    readonly TOTAL_LENGTH: 71;
+    readonly HEX_LENGTH: 32;
+    /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 39`). */
+    readonly TOTAL_LENGTH: 39;
 };
 /**
  * Shape constants for caller identifiers (the `X-Caller` instance-identity
@@ -947,6 +1106,26 @@ declare const SPA_DEFAULT_CONFIG: {
         readonly destination: "/index.html";
     }];
 };
+/**
+ * The `/spa-check` pre-flight's client-side envelope: which file is the
+ * check's subject, and how large it may be before a client skips the call.
+ *
+ * One fact with three holders until this export — the API's config declared
+ * the cap, the SDK's `checkSPA` hardcoded `100 * 1024`, and prose restated
+ * "100KB". `INDEX_FILE` is the selection rule (the file whose content rides
+ * `SPACheckRequest.index`), restated by every client that builds the request.
+ *
+ * Neither member is a validation boundary: a client over the cap simply
+ * skips the pre-flight, because the server answers an oversized index
+ * `isSPA: false` anyway. A consumer that cannot import this (n8n) needs no
+ * size copy at all — outcome parity is the server's, not the client's.
+ */
+declare const SPA_CHECK_CONSTRAINTS: {
+    /** The file whose content is the check's subject. */
+    readonly INDEX_FILE: "index.html";
+    /** Skip the pre-flight above this size — the server would answer false. */
+    readonly MAX_INDEX_BYTES: number;
+};
 /**
  * Assert that a ship.json file is *syntactically* loadable. Syntax only —
  * never schema.
@@ -1071,6 +1250,50 @@ interface StaticFile {
 }
 /** Default API URL if not otherwise configured. */
 declare const DEFAULT_API = "https://api.shipstatic.com";
+/**
+ * The Node SDK's ambient configuration pair — the ONLY environment variables
+ * the SDK reads, and therefore the COMPLETE list an embedding host must
+ * scrub (per `npm/ship`'s strict-isolation contract, scrubbing is the host's
+ * job, not the SDK's). A host that derives its scrub from this object's
+ * values — as the VS Code extension's child-process env block does — picks
+ * up a grown contract at the next pin bump instead of by remembered prose.
+ *
+ * Browser builds read no environment at all, and the CLI-only variables
+ * (`SHIP_PASSWORD`, `SHIP_VIA`) are deliberately NOT here: they are the
+ * CLI's operational levers, not the SDK's ambient contract — see
+ * `npm/ship/CLAUDE.md`, "CLI-only env vars".
+ */
+declare const SHIP_ENV: {
+    /** The one credential slot — any platform token. */
+    readonly TOKEN: "SHIP_TOKEN";
+    /** The API endpoint override. */
+    readonly API_URL: "SHIP_API_URL";
+};
+/**
+ * Where a human creates an API key — the console deep link quoted by every
+ * surface that teaches authentication (the CLI's config wizard, the VS Code
+ * and n8n listings, the n8n rate-limit hint and credential copy). Written
+ * out in five files across three repos until this export.
+ *
+ * Production-branded by design: published artifacts name the product, never
+ * an environment (root `CLAUDE.md`, "Environment-Aware URLs").
+ */
+declare const MY_API_KEY_URL = "https://my.shipstatic.com/api-key";
+/**
+ * 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.
+ */
+declare const PUBLIC_DEPLOYMENT_TTL_SECONDS: number;
 /**
  * Universal deploy input — the union of every shape the SDK accepts.
  *
@@ -1089,8 +1312,12 @@ type DeployInput = File[] | string | string[];
 interface DeploymentUploadOptions {
     /** Optional labels for categorization and filtering */
     labels?: string[];
-    /** Client identifier (e.g., 'cli', 'sdk', 'web') */
-    via?: string;
+    /**
+     * Which client is making this deploy. Closed, because the server silently
+     * ignores anything outside the set — so an unchecked string turned a typo
+     * into missing analytics rather than an error. See {@link DeploymentVia}.
+     */
+    via?: DeploymentViaType;
     /**
      * Optional password that protects this deployment.
      *
@@ -1122,36 +1349,14 @@ 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.
      */
     idempotencyKey?: string;
 }
-/**
- * Pagination options for every list endpoint. The response's `cursor` feeds
- * the next request; a `null` cursor means the last page. Omitting both
- * returns the server's default first page.
- *
- * A list answers `{ <collection>, cursor }` and nothing else — `cursor`
- * carries the entire has-more signal, so no redundant boolean, and no
- * `total`. **A count is an aggregate over a collection, not a property of a
- * page:** including one makes every read pay for a full scan it did not ask
- * for, which is precisely the cost keyset pagination exists to avoid.
- *
- * Counts therefore live on the summary resource that owns them —
- * `GET /account` (`usage`) for a caller's own totals, `GET /admin/stats` for
- * platform-wide ones. Ask for a count when you want a count; ask for a page
- * when you want a page.
- */
-interface ListOptions {
-    /** Maximum number of items to return in one page. */
-    limit?: number;
-    /** Opaque cursor from the previous page's response. */
-    cursor?: string;
-}
 /**
  * What a caller may change on an existing deployment.
  *
@@ -1569,8 +1774,13 @@ interface DeployBodyContext {
      * `LABEL_CONSTRAINTS` (length and pattern, lowercased+trimmed).
      */
     labels?: string[];
-    /** Client identifier (`cli`, `sdk`, `web`). */
-    via?: string;
+    /**
+     * Which client is deploying — the same closed vocabulary the public option
+     * carries, not a second `string`. This context receives an already-narrowed
+     * value and passed it on widened, which made the narrowing stop one seam
+     * short of the wire.
+     */
+    via?: DeploymentViaType;
     /**
      * Optional plaintext password to protect the deployment.
      * Length: `PASSWORD_CONSTRAINTS.MIN_LENGTH` to `PASSWORD_CONSTRAINTS.MAX_LENGTH`
@@ -2238,4 +2448,4 @@ declare class Ship extends Ship$1 {
     protected getDeployBodyCreator(): DeployBodyCreator;
 }
 
-export { API_KEY, API_PATHS, AUTH_BASE_PATH, type Account, type AccountDeleteResponse, type AccountGetResponse, type AccountKeyResponse, type AccountOverrides, AccountPlan, type AccountPlanType, type AccountResource, type AccountUsage, type Activity, type ActivityEvent, type ActivityListResponse, type ActivityMeta, type ApiDeployOptions, ApiHttp, type ApiHttpOptions, AuthMethod, type AuthMethodType, BLOCKED_EXTENSIONS, type BillingCancelResponse, type BillingStatus, CALLER, type CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_TOKEN, type DeployBody, type DeployBodyContext, type DeployBodyCreator, type DeployFile, type DeployInput, type Deployment, type DeploymentCreateResponse, type DeploymentDeleteResponse, type DeploymentListResponse, type DeploymentOptions, type DeploymentResource, type DeploymentResourceContext, type DeploymentSetOptions, DeploymentStatus, type DeploymentStatusType, type DeploymentUploadOptions, type DnsLookup, type DnsProvider, type DnsRecord, type DnsRecordType, type Domain, type DomainDeleteResponse, type DomainDnsResponse, type DomainListResponse, type DomainRecordsResponse, type DomainResource, type DomainSetOptions, type DomainSetResult, type DomainShareResponse, DomainStatus, type DomainStatusType, type DomainValidateResponse, type DomainVerifyResponse, type ErrorResponse, ErrorType, type ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, type Fetch, type FileValidationResult, FileValidationStatus, type FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, type LabelsResponse, type ListOptions, type ListResponse, type MD5Result, OAuthScope, type OAuthScopeType, PASSWORD_CONSTRAINTS, type PingResponse, type PlatformLimits, type ResourceContext, type SPACheckDebug, type SPACheckRequest, type SPACheckResponse, SPA_DEFAULT_CONFIG, type SetupInstructionsResponse, Ship, type ShipClientOptions, ShipError, type ShipEvents, type StaticFile, type Token, type TokenCreateOptions, type TokenCreateResponse, type TokenDeleteResponse, TokenKind, type TokenKindType, type TokenListResponse, type TokenProvider, type TokenResource, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, type UploadedFile, type UserVisibleActivityEvent, type ValidatableFile, type ValidationIssue, __setTestEnvironment, allValidFilesReady, assertShipJsonSyntax, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, optimizeDeployPaths, pluralize, processFilesForBrowser, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validatePassword, validateToken };
+export { API_KEY, API_PATHS, AUTH_BASE_PATH, type Account, type AccountDeleteResponse, type AccountGetResponse, type AccountKeyResponse, type AccountOverrides, AccountPlan, type AccountPlanType, type AccountResource, type AccountUsage, type Activity, type ActivityEvent, type ActivityListResponse, type ActivityMeta, type ApiDeployOptions, ApiHttp, type ApiHttpOptions, AuthMethod, type AuthMethodType, BLOCKED_EXTENSIONS, type BillingCancelResponse, type BillingStatus, CALLER, type CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_TOKEN, type DeployBody, type DeployBodyContext, type DeployBodyCreator, type DeployFile, type DeployInput, type Deployment, type DeploymentCreateResponse, type DeploymentDeleteResponse, type DeploymentListResponse, type DeploymentOptions, type DeploymentResource, type DeploymentResourceContext, type DeploymentSetOptions, DeploymentStatus, type DeploymentStatusType, type DeploymentUploadOptions, DeploymentVia, type DeploymentViaType, type DnsLookup, type DnsProvider, type DnsRecord, type DnsRecordType, type Domain, type DomainDeleteResponse, type DomainDnsResponse, type DomainListResponse, type DomainRecordsResponse, type DomainResource, type DomainSetOptions, type DomainSetResult, type DomainShareResponse, DomainStatus, type DomainStatusType, type DomainValidateResponse, type DomainVerifyResponse, type ErrorResponse, ErrorType, type ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, type Fetch, type FileValidationResult, FileValidationStatus, type FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, type LabelsResponse, type ListOptions, type ListResponse, type MD5Result, MY_API_KEY_URL, OAuthScope, type OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, type PingResponse, type PlatformLimits, type ResourceContext, SHIP_ENV, type SPACheckDebug, type SPACheckRequest, type SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, type SetupInstructionsResponse, Ship, type ShipClientOptions, ShipError, type ShipEvents, type StaticFile, type Token, type TokenCreateOptions, type TokenCreateResponse, type TokenDeleteResponse, TokenKind, type TokenKindType, type TokenListResponse, type TokenProvider, type TokenResource, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, type UploadedFile, type UserVisibleActivityEvent, type ValidatableFile, type ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, allValidFilesReady, assertShipJsonSyntax, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, normalizeVia, optimizeDeployPaths, pluralize, processFilesForBrowser, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validatePassword, validateToken };