@shipstatic/ship 2.0.0-beta.2 → 2.0.0-beta.20

package/dist/index.d.cts

@@ -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,16 +79,88 @@ interface DeploymentCreateResponse extends Deployment {
     /** Claim URL for public deployments. Present when deployed without credentials. */
     readonly claim?: string;
 }
+/**
+ * The half of a list response that is identical on every list.
+ *
+ * `GET /<collection>` answers exactly two fields — the collection under its
+ * own plural noun, and this cursor — so the cursor is declared once here and
+ * each response below adds only its noun. `cursor: null` means last page and
+ * is the ENTIRE has-more signal, which is why there is no `has_more`.
+ *
+ * There is deliberately no `total`. A count is an aggregate over a
+ * collection, not a property of a page; producing one would cost a COUNT
+ * beside every page read, which is precisely what keyset pagination exists
+ * to avoid. Counts live on the resource that summarises the collection —
+ * `GET /account`'s `usage` for one caller, `GET /admin/stats` platform-wide.
+ */
+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
  */
-interface DeploymentListResponse {
+interface DeploymentListResponse extends ListResponse {
     /** Array of deployments */
     deployments: Deployment[];
-    /** Cursor for pagination, null if no more pages */
-    cursor: string | null;
-    /** Total number of deployments */
-    total: number;
+}
+/**
+ * Acknowledgement of `DELETE /deployments/:deployment` — and the shape every
+ * mutation with no entity left to return follows.
+ *
+ * **The law:** a mutation answers with the resource it affected. If the
+ * resource still exists, that means the entity itself (`Deployment`,
+ * `Domain`, …). Otherwise it means this: the resource noun carrying the
+ * item's canonical key, plus the resource's own state field — and ONLY when
+ * the resource survived in a transitional state, as an async deletion's does.
+ * Where the resource is simply gone, the key alone is the whole answer
+ * ({@link DomainDeleteResponse}, {@link TokenDeleteResponse}).
+ *
+ * Put positively: **an acknowledgement is a projection of the resource** —
+ * its key, plus its own state field where the state changed. That is the
+ * test to apply, and it is sharper than "no constant", which this shape
+ * would fail on its own terms: `status` here is the literal `'deleting'` on
+ * every success, exactly as fixed as a `changed: true` would be.
+ *
+ * The difference is not how predictable the value is, it is what the field
+ * IS. `status` is the deployment's own field — the same one `GET
+ * /deployments/:deployment` returns — so this response is `Deployment`
+ * narrowed to two members, and a client renders it with the code it already
+ * has. `changed: true`, `queued: true` and `success: true` are not fields of
+ * any entity; they exist only to assert that the call worked, which the
+ * status code already said. Sync versus accepted is likewise the status
+ * code's job — 200 versus 202 — not a boolean's.
+ *
+ * No prose either (`message`): an acknowledgement is data, and each surface
+ * composes its own copy.
+ */
+interface DeploymentDeleteResponse {
+    /** The deployment hostname that was marked for removal */
+    readonly deployment: string;
+    /** The state the deployment is in while background cleanup runs */
+    readonly status: DeploymentStatusType;
 }
 /**
  * Domain status constants
@@ -91,7 +193,7 @@ interface Domain {
     labels: string[];
     /** Unix timestamp (seconds) when domain was created */
     readonly created: number;
-    /** When deployment was last linked (Unix timestamp), null if never linked */
+    /** Unix timestamp (seconds) when deployment was last linked, null if never linked */
     linked: number | null;
     /** Total deployment links */
     links: number;
@@ -113,13 +215,28 @@ interface DomainSetResult extends Domain {
 /**
  * Response for listing domains
  */
-interface DomainListResponse {
+interface DomainListResponse extends ListResponse {
     /** Array of domains */
     domains: Domain[];
-    /** Cursor for pagination, null if no more pages */
-    cursor: string | null;
-    /** Total number of domains */
-    total: number;
+}
+/**
+ * Acknowledgement of `DELETE /domains/:domain`. The row is gone, so there is
+ * no state to state — the canonical domain name is the whole answer. See
+ * {@link DeploymentDeleteResponse} for the law.
+ */
+interface DomainDeleteResponse {
+    /** The domain name that was removed, normalized */
+    readonly domain: string;
+}
+/**
+ * Acknowledgement of `POST /domains/:domain/verify` (202). The DNS check is
+ * queued, not performed — the accepted status code says so, and the domain's
+ * own status is unchanged until the check runs, which is why none is stated
+ * here. See {@link DeploymentDeleteResponse} for the law.
+ */
+interface DomainVerifyResponse {
+    /** The domain whose DNS verification was queued, normalized */
+    readonly domain: string;
 }
 /**
  * DNS record types supported for domain configuration
@@ -146,16 +263,46 @@ interface DnsProvider {
 /**
  * Response for domain DNS provider lookup
  */
+/**
+ * What a DNS lookup found for a domain. An envelope rather than a bare
+ * {@link DnsProvider} because a lookup can succeed and learn more than the
+ * provider later; the shape is named so a consumer can hold one.
+ */
+interface DnsLookup {
+    /** The provider serving this domain's DNS, absent when unidentified */
+    provider?: DnsProvider;
+}
+/**
+ * A report: it answers a question and carries only the answer (`CLAUDE.md`,
+ * "A report answers a question").
+ */
 interface DomainDnsResponse {
     /** The domain name */
     domain: string;
     /** DNS provider information, null if not yet looked up */
-    dns: {
-        provider?: DnsProvider;
-    } | null;
+    dns: DnsLookup | null;
+}
+/**
+ * Response for `GET /domains/:domain/share` — the domain plus the salted
+ * hash that lets someone else complete its DNS setup without an account.
+ *
+ * `/admin/domains/:domain/share` answers the same shape, which is the admin
+ * law working: the operator surface is the public grammar with a prefix.
+ *
+ * A report: it answers a question and carries only the answer (`CLAUDE.md`,
+ * "A report answers a question").
+ */
+interface DomainShareResponse {
+    /** The domain the setup link is for */
+    readonly domain: string;
+    /** The salted setup hash that authorizes the share */
+    readonly hash: string;
 }
 /**
  * Response for domain DNS records
+ *
+ * A report: it answers a question and carries only the answer (`CLAUDE.md`,
+ * "A report answers a question").
  */
 interface DomainRecordsResponse {
     /** The domain name */
@@ -166,7 +313,92 @@ interface DomainRecordsResponse {
     records: DnsRecord[];
 }
 /**
- * Response for domain validation
+ * The envelope an `Idempotency-Key` must fit, and how long a replay lasts.
+ *
+ * Format lives here rather than on the server alone by the format-vs-policy
+ * rule: a client can decide offline whether a key is well-formed, and the
+ * 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
+ * cannot be sent — the same verdict the API would reach, reached earlier.
+ */
+declare function validateIdempotencyKey(value: unknown): string | undefined;
+/**
+ * Response for `GET /labels` — every label in use across the caller's
+ * deployments, domains and tokens, grouped and ordered by last use.
+ *
+ * The one plural noun outside the list contract, deliberately: labels have
+ * no identity, no row and no `created`, so there is nothing for a keyset
+ * cursor to resume after, and its consumer is an autocomplete that wants the
+ * whole set. Bounded by `PAGINATION.GLOBAL_LIMIT` rather than paginated.
+ *
+ * A report: it answers a question and carries only the answer (`CLAUDE.md`,
+ * "A report answers a question").
+ */
+interface LabelsResponse {
+    readonly labels: string[];
+}
+/**
+ * Response for `POST /setup` — the DNS instructions for one domain, written
+ * for a human to follow at their registrar.
+ *
+ * `custom` is the provider-specific walkthrough when the provider is known;
+ * `generic` always answers, so a caller never has nothing to show.
+ *
+ * A report: it answers a question and carries only the answer (`CLAUDE.md`,
+ * "A report answers a question").
+ */
+interface SetupInstructionsResponse {
+    /** The domain the instructions are for — a report names its subject */
+    readonly domain: string;
+    /** One-line summary of what to do */
+    readonly tldr: string;
+    /** Provider-specific instructions, null when the provider is unknown */
+    readonly custom: string | null;
+    /** Provider-agnostic instructions — always present */
+    readonly generic: string;
+    /** The identified DNS provider, null when unknown */
+    readonly provider: string | null;
+}
+/**
+ * `POST /domains/validate` — a report answering "is this name usable, and if
+ * not, why".
+ *
+ * An unusable name is a legitimate ANSWER, not a failure, so this is a 200 and
+ * the verdict rides the body. `reason` was named `error` until 2026-07-29,
+ * which collided with {@link ErrorResponse}'s reserved key — there `error` is
+ * an `ErrorType` a client branches on, here it is prose a client displays, and
+ * one key cannot mean both. See {@link DeploymentDeleteResponse} for the law.
  */
 interface DomainValidateResponse {
     /** Whether the domain is valid */
@@ -175,15 +407,17 @@ interface DomainValidateResponse {
     normalized: string | null;
     /** Whether the domain is available, null when invalid */
     available: boolean | null;
-    /** Error message, null when valid */
-    error: string | null;
+    /** Why the name is unusable, null when valid — displayed verbatim. */
+    reason: string | null;
 }
 /**
- * Token as returned by the list endpoint.
- * The secret is shown once at creation and never again — listings carry
- * only the management identifier and lifecycle metadata.
+ * Core deploy token object - used in both API responses and SDK.
+ *
+ * The secret is never here: it is shown once at creation
+ * ({@link TokenCreateResponse.secret}) and never again, so an entity read
+ * carries only the management identifier and lifecycle metadata.
  */
-interface TokenListItem {
+interface Token {
     /** 7-char management identifier (e.g., "a1b2c3d") */
     readonly token: string;
     /** Labels for categorization and filtering. Always present, empty array when none. */
@@ -198,24 +432,28 @@ interface TokenListItem {
 /**
  * Response for listing tokens
  */
-interface TokenListResponse {
-    /** Array of tokens (security-redacted for list display) */
-    tokens: TokenListItem[];
-    /** Total number of tokens */
-    total: number;
+interface TokenListResponse extends ListResponse {
+    /** Array of tokens (the secret is never among them) */
+    tokens: Token[];
 }
 /**
- * Response for token creation
+ * Response from token creation. Extends Token with the one field that
+ * exists only on creation — the same shape as
+ * {@link DeploymentCreateResponse}, because a 201 returns the resource it
+ * created plus whatever is knowable only once.
  */
-interface TokenCreateResponse {
-    /** 7-char management identifier */
-    token: string;
+interface TokenCreateResponse extends Token {
     /** The raw credential value (shown once at creation, then never again) */
-    secret: string;
-    /** Labels for categorization and filtering. Always present, empty array when none. */
-    labels: string[];
-    /** Unix timestamp (seconds) when token expires, null for never */
-    expires: number | null;
+    readonly secret: string;
+}
+/**
+ * Acknowledgement of `DELETE /tokens/:token`. The credential is revoked and
+ * its row is gone, so the management identifier is the whole answer. See
+ * {@link DeploymentDeleteResponse} for the law.
+ */
+interface TokenDeleteResponse {
+    /** The 7-char management identifier that was revoked */
+    readonly token: string;
 }
 /**
  * Account plan constants
@@ -232,10 +470,34 @@ declare const AccountPlan: {
 type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
 /**
  * Account usage metrics — always available regardless of billing provider.
+ *
+ * This is where a caller's own totals live. Lists answer pages and carry no
+ * `total` (see {@link ListOptions}); a count is an aggregate over a
+ * collection, so it belongs to the summary resource that owns the
+ * collection. `GET /account` is that resource for one caller, `GET
+ * /admin/stats` for the platform.
+ *
+ * The counted dimensions are the ones the plan caps — deployments and
+ * domains (`PlatformLimits`) — plus the billable custom-domain subset, so a
+ * surface can render "3 of 10" without a second request.
  */
 interface AccountUsage {
     /** Number of active custom domains (excludes paused) */
     customDomains: number;
+    /**
+     * Deployments counted against the plan's deployment cap — every row
+     * whatever its status, because that is what the cap counts, so a surface
+     * renders "3 of 10" against the denominator the 403 divides by. (`GET
+     * /deployments` lists successful ones only; that is a different question
+     * asked of a different resource.) Optional by the additive-evolution law:
+     * an API predating this field omits it.
+     */
+    deployments?: number;
+    /**
+     * Domains counted against the plan's domain cap — every domain, platform
+     * and custom alike, unlike `customDomains`. Optional for the same reason.
+     */
+    domains?: number;
 }
 /**
  * Core account object - used in both API responses and SDK
@@ -258,6 +520,13 @@ interface Account {
     readonly activated: number | null;
     /** Last 4 characters of the API key for identification, null when no key generated */
     readonly hint: string | null;
+    /**
+     * Unix timestamp (seconds) of the API key's last use, null when never
+     * used or no key generated. Optional on the type by the additive-evolution
+     * law: published SDK versions may predate the field, so consumers read it
+     * when present rather than forcing a lockstep SDK release.
+     */
+    readonly used?: number | null;
     /** Grace period expiration (unix seconds), null if no grace period active */
     readonly grace: number | null;
 }
@@ -275,6 +544,35 @@ interface AccountGetResponse extends Account {
     /** Present only during read-only admin impersonation: the operator's account id. */
     readonly impersonatedBy?: string;
 }
+/**
+ * Acknowledgement of `DELETE /account` (202). Termination is asynchronous —
+ * a cleanup consumer finishes the job — so the account survives long enough
+ * to state the plan it is transitioning through. `plan` is the account's
+ * state field, the way `status` is a deployment's. See
+ * {@link DeploymentDeleteResponse} for the law.
+ */
+interface AccountDeleteResponse {
+    /** The account that was marked for termination */
+    readonly account: string;
+    /** The plan the account is in while cleanup runs */
+    readonly plan: AccountPlanType;
+}
+/**
+ * Response from `PUT /account/key` — the account's single API key, minted in
+ * place of whatever was there before.
+ *
+ * There is no entity to return: only the key's last-4 `hint` is durable
+ * (`Account.hint`), and the plaintext exists exactly once, in this response.
+ * The raw credential is `secret` on every surface that mints one — the same
+ * field `TokenCreateResponse` carries — because one concept gets one name.
+ *
+ * A report: it answers a question and carries only the answer (`CLAUDE.md`,
+ * "A report answers a question").
+ */
+interface AccountKeyResponse {
+    /** The raw API key (shown once at mint, then never again) */
+    readonly secret: string;
+}
 /**
  * Account-specific configuration overrides
  * Allows per-account customization of limits without changing plan
@@ -291,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.
  *
@@ -301,7 +690,15 @@ interface AccountOverrides {
  * (`DeploymentStatus`, `DomainStatus`, `AccountPlan`, `AuthMethod`) follow.
  */
 declare const ErrorType: {
-    /** Validation failed (400). Input shape is wrong. */
+    /**
+     * Validation failed. Input shape is wrong.
+     *
+     * Carries 400 when an API judged it — including a client-side pre-check of a
+     * rule the server enforces too, which keeps the error identical wherever it
+     * was caught. **Statusless** when a client rejects something no API judges,
+     * such as a CLI's own command grammar: `status` is documented "(API
+     * contexts)" on `ErrorResponse`, so there is none to report.
+     */
     readonly Validation: "validation_failed";
     /** Resource not found (404). */
     readonly NotFound: "not_found";
@@ -315,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. */
@@ -381,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, ...)`
      *
@@ -414,6 +823,28 @@ 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`,
+     * `File`, raised locally by the SDK).
+     *
+     * Both arms are load-bearing, because type and status are independent
+     * axes. `fromHttpResponse` trusts `body.error` only when it names a
+     * server-producible type; a non-OK response without one is status-derived,
+     * so a CDN 404 or any intermediary error arrives as `Api` — a server-fault
+     * *type* carrying a client *status*. Judging by type alone would report it
+     * as a platform failure and bury the server's own message.
+     */
     isClientError(): boolean;
     isNetworkError(): boolean;
     isAuthError(): boolean;
@@ -440,6 +871,9 @@ declare function isShipError(error: unknown): error is ShipError;
  *
  * These are the *platform's* posted caps for the current account — server
  * truth delivered at runtime, never hard-coded on the client.
+ *
+ * A report: it answers a question and carries only the answer (`CLAUDE.md`,
+ * "A report answers a question").
  */
 interface PlatformLimits {
     /** Maximum size in bytes for a single file. */
@@ -473,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.
  *
@@ -510,14 +966,29 @@ declare const UNBUILT_PROJECT_MARKERS: ReadonlySet<string>;
  */
 declare function hasUnbuiltMarker(filePath: string): boolean;
 /**
- * Simple ping response for health checks
+ * `GET /ping` — a report of the server clock.
+ *
+ * Liveness is the STATUS CODE's answer, not a field's: a 200 means reachable,
+ * and any other outcome throws before a body is read. So the body carries the
+ * one thing a status code cannot — the server's own clock, which is what lets a
+ * client detect skew against a token expiry. It read `{ success: true,
+ * timestamp? }` until 2026-07-29, where `success` was a literal constant in the
+ * route (zero bits, and the platform's own named anti-pattern) while the field
+ * that IS the payload was optional. See {@link DeploymentDeleteResponse} for
+ * the law, and `tests/response-shapes.test.ts` for the fence that holds it.
  */
 interface PingResponse {
-    /** Always true if service is healthy */
-    success: boolean;
-    /** Optional timestamp */
-    timestamp?: number;
+    /** Server time in unix seconds — the one wire unit for timestamps. */
+    readonly timestamp: number;
 }
+/**
+ * Where human identity is mounted on the API host. The API mounts Better
+ * Auth at this path (sign-in, sign-out, session reads, admin impersonation)
+ * and the web console's auth client posts to it — shared here so the two
+ * halves of the auth pair agree by construction, the same way both sides
+ * already share the credential prefixes below.
+ */
+declare const AUTH_BASE_PATH = "/auth";
 /**
  * How a request (or recorded activity) was authorized.
  *
@@ -630,6 +1101,56 @@ 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.
+ *
+ * ship.json is validated and compiled on the server, deliberately: the schema
+ * and the compiler evolve, and a client that judged them would reject configs
+ * a newer platform accepts. That reasoning bounds what a client may check to
+ * the properties which are true of *every* past and future schema:
+ *
+ *   1. it parses as JSON — JSON syntax is frozen (RFC 8259), so text that
+ *      does not parse can never be a valid config;
+ *   2. its top level is an object — ship.json is `{ ... }` in every version.
+ *
+ * Both are monotonic: neither can ever reject something the server would
+ * accept. Everything beyond them (field names, types, rule semantics, which
+ * keys are permitted) stays server-side, where it can change.
+ *
+ * The payoff is the common case. Hand-edited JSON fails on a trailing comma,
+ * a `//` comment, single quotes, unquoted keys, or smart quotes pasted from
+ * documentation — mistakes that otherwise cost a full upload round-trip to
+ * discover. A UTF-8 BOM (Windows editors, PowerShell redirects) is stripped
+ * before parsing rather than rejected, because the server accepts it too;
+ * diverging there would reintroduce exactly the false rejection this
+ * function exists to avoid.
+ *
+ * @throws {ShipError} `ErrorType.Config` — the same type the server's own
+ * config rejection carries, so the error contract is identical wherever the
+ * failure is detected.
+ */
+declare function assertShipJsonSyntax(text: string): void;
 /**
  * Validate API key format
  */
@@ -672,16 +1193,26 @@ interface SPACheckRequest {
 /**
  * Response from SPA check endpoint
  */
+/**
+ * Which of the classifier's tiers reached the verdict, and why. Named rather
+ * than inline so the API's own `checkSPA` can return `SPACheckResponse`
+ * instead of restating its shape.
+ */
+interface SPACheckDebug {
+    /** Which tier made the detection */
+    tier: 'exclusions' | 'inclusions' | 'scoring' | 'ai' | 'fallback';
+    /** The reason for the detection result */
+    reason: string;
+}
+/**
+ * A report: it answers a question and carries only the answer (`CLAUDE.md`,
+ * "A report answers a question").
+ */
 interface SPACheckResponse {
     /** Whether the project is detected as a Single Page Application */
     isSPA: boolean;
     /** Debugging information about detection */
-    debug: {
-        /** Which tier made the detection: 'exclusions', 'inclusions', 'scoring', 'ai', or 'fallback' */
-        tier: 'exclusions' | 'inclusions' | 'scoring' | 'ai' | 'fallback';
-        /** The reason for the detection result */
-        reason: string;
-    };
+    debug: SPACheckDebug;
 }
 /**
  * Represents a file that has been processed and is ready for deploy.
@@ -712,22 +1243,52 @@ interface StaticFile {
     /** The size of the file in bytes. */
     size: number;
 }
-/**
- * Progress information for deploy/upload operations.
- * Provides consistent percentage-based progress with byte-level details.
- */
-interface ProgressInfo {
-    /** Progress percentage (0-100) */
-    percent: number;
-    /** Number of bytes loaded so far */
-    loaded: number;
-    /** Total number of bytes to load. May be 0 if unknown initially */
-    total: number;
-    /** Current file being processed (optional) */
-    file?: string;
-}
 /** 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.
  *
@@ -746,8 +1307,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.
      *
@@ -767,40 +1332,81 @@ interface DeploymentUploadOptions {
     spa?: boolean;
     /** @internal reCAPTCHA proof for the anonymous human deploy channel. Only available via /upload endpoint. */
     captcha?: string;
+    /**
+     * Makes this deploy replayable instead of repeatable.
+     *
+     * A deploy is not naturally idempotent: a client-side timeout on a slow
+     * one leaves the caller unable to tell "it never landed" from "it landed
+     * and the response was lost", and retrying produces a second deployment.
+     * Send the same key on the retry and the platform replays the original
+     * 201 verbatim rather than creating anything
+     * ({@link IDEMPOTENCY_KEY_CONSTRAINTS.WINDOW_SECONDS}).
+     *
+     * **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 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;
 }
 /**
- * Deployment resource interface - the contract all implementations must follow
+ * What a caller may change on an existing deployment.
+ *
+ * Labels and nothing else: a deployment's content is immutable by design, so
+ * this is the whole mutable surface rather than a subset someone chose.
  */
-interface DeploymentResource {
-    upload: (input: DeployInput, options?: DeploymentUploadOptions) => Promise<DeploymentCreateResponse>;
-    list: () => Promise<DeploymentListResponse>;
+interface DeploymentSetOptions {
+    labels: string[];
+}
+/**
+ * What `domains.set()` may create or change. Every field is optional because
+ * the call is a natural-key upsert: omitting `deployment` reserves the
+ * domain, naming one links or re-points it, and labels travel either way.
+ *
+ * `deployment` is deliberately not nullable — unlinking is refused (400).
+ * See `npm/ship/CLAUDE.md`, "Domain Write Semantics".
+ */
+interface DomainSetOptions {
+    deployment?: string;
+    labels?: string[];
+}
+/** What a caller may set when minting a deploy token. */
+interface TokenCreateOptions {
+    /** Seconds until expiry; omit for a token that never expires. */
+    ttl?: number;
+    labels?: string[];
+}
+/**
+ * Deployment resource interface - the contract all implementations must follow.
+ *
+ * The interface defines the minimal wire contract; SDK implementations may
+ * extend the upload options with runtime concerns (timeout, signal, progress
+ * callbacks) by parameterizing: `DeploymentResource<MyUploadOptions>`. The
+ * default keeps plain `DeploymentResource` valid for wire-only consumers.
+ */
+interface DeploymentResource<UploadOptions extends DeploymentUploadOptions = DeploymentUploadOptions> {
+    upload: (input: DeployInput, options?: UploadOptions) => Promise<DeploymentCreateResponse>;
+    list: (options?: ListOptions) => Promise<DeploymentListResponse>;
     get: (id: string) => Promise<Deployment>;
-    set: (id: string, options: {
-        labels: string[];
-    }) => Promise<Deployment>;
-    remove: (id: string) => Promise<void>;
+    set: (id: string, options: DeploymentSetOptions) => Promise<Deployment>;
+    delete: (id: string) => Promise<DeploymentDeleteResponse>;
 }
 /**
  * Domain resource interface - the contract all implementations must follow
  */
 interface DomainResource {
-    set: (name: string, options?: {
-        deployment?: string;
-        labels?: string[];
-    }) => Promise<DomainSetResult>;
-    list: () => Promise<DomainListResponse>;
+    set: (name: string, options?: DomainSetOptions) => Promise<DomainSetResult>;
+    list: (options?: ListOptions) => Promise<DomainListResponse>;
     get: (name: string) => Promise<Domain>;
-    remove: (name: string) => Promise<void>;
-    verify: (name: string) => Promise<{
-        message: string;
-    }>;
+    delete: (name: string) => Promise<DomainDeleteResponse>;
+    verify: (name: string) => Promise<DomainVerifyResponse>;
     validate: (name: string) => Promise<DomainValidateResponse>;
     dns: (name: string) => Promise<DomainDnsResponse>;
     records: (name: string) => Promise<DomainRecordsResponse>;
-    share: (name: string) => Promise<{
-        domain: string;
-        hash: string;
-    }>;
+    share: (name: string) => Promise<DomainShareResponse>;
 }
 /**
  * Account resource interface - the contract all implementations must follow
@@ -812,12 +1418,10 @@ interface AccountResource {
  * Token resource interface - the contract all implementations must follow
  */
 interface TokenResource {
-    create: (options?: {
-        ttl?: number;
-        labels?: string[];
-    }) => Promise<TokenCreateResponse>;
-    list: () => Promise<TokenListResponse>;
-    remove: (token: string) => Promise<void>;
+    create: (options?: TokenCreateOptions) => Promise<TokenCreateResponse>;
+    list: (options?: ListOptions) => Promise<TokenListResponse>;
+    get: (token: string) => Promise<Token>;
+    delete: (token: string) => Promise<TokenDeleteResponse>;
 }
 /**
  * Billing status response from GET /billing/status
@@ -837,6 +1441,25 @@ interface BillingStatus {
     /** Link to Creem customer portal for billing management, null if unavailable */
     portal: string | null;
 }
+/**
+ * Acknowledgement of `POST /billing/cancel`.
+ *
+ * Cancelling leaves no billing entity to return, so it answers with the
+ * account and the one field of the account the call changed — the plan it
+ * landed on. See {@link DeploymentDeleteResponse} for the law.
+ *
+ * This read `{ success: true, message: 'Subscription canceled successfully…' }`
+ * until 2026-07-29, an anonymous shape that `web/my` redeclared inline and
+ * whose prose no surface ever displayed: both callers await the promise and
+ * discard the body, then compose their own toast. The message was written,
+ * serialized, and thrown away on every cancellation.
+ */
+interface BillingCancelResponse {
+    /** The account whose subscription was cancelled */
+    readonly account: string;
+    /** The plan the account now holds — `free` on a successful cancellation */
+    readonly plan: AccountPlanType;
+}
 /**
  * Checkout session response from POST /billing/checkout
  */
@@ -848,11 +1471,11 @@ interface CheckoutSession {
  * All activity event types logged in the system.
  * Uses dot notation consistently: {resource}.{action}
  */
-type ActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.paid' | 'account.plan.transition' | 'account.suspended' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'deployment.flagged' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'admin.account.plan.update' | 'admin.account.ref.update' | 'admin.account.billing.update' | 'admin.account.labels.update' | 'admin.deployment.delete' | 'admin.domain.delete' | 'admin.billing.sync' | 'admin.billing.terminated' | 'admin.impersonate' | 'billing.active' | 'billing.canceled' | 'billing.paused' | 'billing.expired' | 'billing.paid' | 'billing.trialing' | 'billing.scheduled_cancel' | 'billing.unpaid' | 'billing.update' | 'billing.past_due' | 'refund.created' | 'dispute.created' | 'billing.sync' | 'billing.stale' | 'billing.race';
+type ActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.paid' | 'account.plan.transition' | 'account.suspended' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'deployment.flagged' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete' | 'admin.account.plan.update' | 'admin.account.ref.update' | 'admin.account.billing.update' | 'admin.account.labels.update' | 'admin.deployment.delete' | 'admin.domain.delete' | 'admin.billing.sync' | 'admin.billing.terminated' | 'admin.impersonate' | 'billing.active' | 'billing.canceled' | 'billing.paused' | 'billing.expired' | 'billing.paid' | 'billing.trialing' | 'billing.scheduled_cancel' | 'billing.unpaid' | 'billing.update' | 'billing.past_due' | 'refund.created' | 'dispute.created' | 'billing.sync' | 'billing.stale' | 'billing.race';
 /**
  * Activity events visible to users in the dashboard
  */
-type UserVisibleActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.transition' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume';
+type UserVisibleActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.transition' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete';
 /**
  * Activity record returned from the API
  */
@@ -871,6 +1494,12 @@ interface Activity {
 /**
  * Parsed activity metadata.
  * Different events populate different fields.
+ *
+ * Naming convention: meta booleans are event-scoped predicates and carry
+ * their prefix (`isUpdate`, `wasVerified`, `hasConfig`, `hasPassword`),
+ * while entity booleans are bare nouns (`Deployment.config`,
+ * `Deployment.password`). Two vocabularies, each internally consistent —
+ * deliberate, not drift.
  */
 interface ActivityMeta {
     /** Number of files in deployment */
@@ -905,7 +1534,7 @@ interface ActivityMeta {
 /**
  * Response from GET /activities endpoint
  */
-interface ActivityListResponse {
+interface ActivityListResponse extends ListResponse {
     /** Array of activities */
     activities: Activity[];
 }
@@ -1109,20 +1738,17 @@ declare function validatePassword(value: unknown): string | undefined;
  * Extends the API contract (DeploymentUploadOptions) with SDK-specific options.
  */
 interface DeploymentOptions extends DeploymentUploadOptions {
-    /** An AbortSignal to allow cancellation of the deploy operation. */
+    /**
+     * An AbortSignal to allow cancellation of the deploy operation. The one
+     * cancellation mechanism — abort the signal and the request rejects with
+     * a typed `Cancelled` error. Request timeouts are a client concern
+     * (`ShipClientOptions.timeout`), not a per-deploy one.
+     */
     signal?: AbortSignal;
-    /** Callback invoked if the deploy is cancelled via the AbortSignal. */
-    onCancel?: () => void;
-    /** Maximum number of concurrent operations. */
-    maxConcurrency?: number;
-    /** Timeout in milliseconds for the deploy request. */
-    timeout?: number;
     /** Whether to auto-detect and optimize file paths by flattening common directories. Defaults to true. */
     pathDetect?: boolean;
     /** Whether to auto-detect SPAs and generate ship.json configuration. Defaults to true. */
     spaDetect?: boolean;
-    /** Callback for deploy progress with detailed statistics. */
-    onProgress?: (info: ProgressInfo) => void;
 }
 type ApiDeployOptions = Omit<DeploymentOptions, 'pathDetect'>;
 /**
@@ -1143,8 +1769,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`
@@ -1177,7 +1808,7 @@ type Fetch = typeof fetch;
 type TokenProvider = () => string | Promise<string>;
 /**
  * Options for configuring a `Ship` instance.
- * Sets default API host, the client credential, progress callbacks, concurrency, and timeouts for the client.
+ * Sets the API host, the client credential, the request timeout, and the transport.
  */
 interface ShipClientOptions {
     /** Default API URL for the client instance. */
@@ -1198,19 +1829,8 @@ interface ShipClientOptions {
      */
     token?: string | TokenProvider | undefined;
     /**
-     * Default callback for deploy progress for deploys made with this client.
-     * @param info - Progress information including percentage and byte counts.
-     */
-    onProgress?: ((info: ProgressInfo) => void) | undefined;
-    /**
-     * Default for maximum concurrent deploys.
-     * Used if an deploy operation doesn't specify its own `maxConcurrency`.
-     * Defaults to 4 if not set here or in the specific deploy call.
-     */
-    maxConcurrency?: number | undefined;
-    /**
-     * Default timeout in milliseconds for API requests made by this client instance.
-     * Used if an deploy operation doesn't specify its own timeout.
+     * Timeout in milliseconds for every API request made by this client
+     * instance. Defaults to 30 seconds.
      */
     timeout?: number | undefined;
     /**
@@ -1277,7 +1897,19 @@ interface ShipEvents {
     request: [url: string, init: RequestInit];
     /** Emitted after successful API response */
     response: [response: Response, url: string];
-    /** Emitted when API request fails */
+    /**
+     * Emitted when something fails. 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
+     *    `isShipError(error)` narrows and `.type` / `.status` are readable;
+     *  - a THROWING HANDLER of yours — `SimpleEvents.emit` evicts it and
+     *    re-emits the raw failure here, which is a plain `Error`.
+     *
+     * Narrowing this to `ShipError` was tried on 2026-07-27 and reverted: it
+     * made the second population a lie.
+     */
     error: [error: Error, url: string];
 }
 
@@ -1325,6 +1957,8 @@ declare class ApiHttp extends SimpleEvents {
     private readonly session;
     private readonly caller;
     private readonly timeout;
+    private readonly deployTimeout;
+    private readonly deployBuildTimeout;
     private readonly fetch;
     private readonly createDeployBody;
     private readonly deployEndpoint;
@@ -1352,30 +1986,26 @@ declare class ApiHttp extends SimpleEvents {
     private safeClone;
     private parseResponse;
     deploy(files: StaticFile[], options?: ApiDeployOptions): Promise<DeploymentCreateResponse>;
-    listDeployments(): Promise<DeploymentListResponse>;
+    listDeployments(options?: ListOptions): Promise<DeploymentListResponse>;
     getDeployment(id: string): Promise<Deployment>;
     updateDeploymentLabels(id: string, labels: string[]): Promise<Deployment>;
-    removeDeployment(id: string): Promise<void>;
+    deleteDeployment(id: string): Promise<DeploymentDeleteResponse>;
     setDomain(name: string, deployment?: string, labels?: string[]): Promise<DomainSetResult>;
-    listDomains(): Promise<DomainListResponse>;
+    listDomains(options?: ListOptions): Promise<DomainListResponse>;
     getDomain(name: string): Promise<Domain>;
-    removeDomain(name: string): Promise<void>;
-    verifyDomain(name: string): Promise<{
-        message: string;
-    }>;
+    deleteDomain(name: string): Promise<DomainDeleteResponse>;
+    verifyDomain(name: string): Promise<DomainVerifyResponse>;
     getDomainDns(name: string): Promise<DomainDnsResponse>;
     getDomainRecords(name: string): Promise<DomainRecordsResponse>;
-    getDomainShare(name: string): Promise<{
-        domain: string;
-        hash: string;
-    }>;
+    getDomainShare(name: string): Promise<DomainShareResponse>;
     validateDomain(name: string): Promise<DomainValidateResponse>;
     createToken(ttl?: number, labels?: string[]): Promise<TokenCreateResponse>;
-    listTokens(): Promise<TokenListResponse>;
-    removeToken(token: string): Promise<void>;
+    listTokens(options?: ListOptions): Promise<TokenListResponse>;
+    deleteToken(token: string): Promise<TokenDeleteResponse>;
+    getToken(token: string): Promise<Token>;
     getAccount(): Promise<AccountGetResponse>;
     getLimits(): Promise<PlatformLimits>;
-    ping(): Promise<boolean>;
+    ping(): Promise<PingResponse>;
     checkSPA(files: StaticFile[], _options?: ApiDeployOptions): Promise<boolean>;
 }
 
@@ -1395,7 +2025,6 @@ interface ResourceContext {
  */
 interface DeploymentResourceContext extends ResourceContext {
     processInput: (input: DeployInput, options: DeploymentOptions) => Promise<StaticFile[]>;
-    clientDefaults?: ShipClientOptions;
 }
 /**
  * Upload deployment resource with all CRUD operations.
@@ -1405,7 +2034,7 @@ interface DeploymentResourceContext extends ResourceContext {
  * public-account agent identity per request (claim URL + expiry on the
  * response). The SDK stays a transparent pipe either way.
  */
-declare function createDeploymentResource(ctx: DeploymentResourceContext): DeploymentResource;
+declare function createDeploymentResource(ctx: DeploymentResourceContext): DeploymentResource<DeploymentOptions>;
 /**
  * Create domain resource with all CRUD operations.
  *
@@ -1427,7 +2056,7 @@ declare function createTokenResource(ctx: ResourceContext): TokenResource;
  * Abstract base class for Ship SDK implementations.
  */
 declare abstract class Ship$1 {
-    readonly deployments: DeploymentResource;
+    readonly deployments: DeploymentResource<DeploymentOptions>;
     readonly domains: DomainResource;
     readonly account: AccountResource;
     readonly tokens: TokenResource;
@@ -1446,13 +2075,20 @@ declare abstract class Ship$1 {
     protected ensureInitialized(): Promise<void>;
     private fetchPlatformLimits;
     /**
-     * Ping the API server to check connectivity.
+     * Ping the API server, resolving its answer: `{ success, timestamp }`, where
+     * `timestamp` is the server clock in unix SECONDS.
+     *
+     * It resolves the response rather than a bare `true` because every other
+     * method here does — narrowing to a boolean discarded the one thing ping
+     * carries beyond liveness, and made `success` mean a boolean on the wire and
+     * something else by the time it reached a caller. A non-OK response throws in
+     * transport, so a resolved value always means the API answered.
      */
-    ping(): Promise<boolean>;
+    ping(): Promise<PingResponse>;
     /**
      * Deploy project (convenience shortcut to `ship.deployments.upload()`).
      */
-    deploy(input: DeployInput, options?: DeploymentOptions): Promise<Deployment>;
+    deploy(input: DeployInput, options?: DeploymentOptions): Promise<DeploymentCreateResponse>;
     /**
      * Get current account information (convenience shortcut to `ship.account.get()`).
      */
@@ -1494,30 +2130,6 @@ declare abstract class Ship$1 {
     private getAuthHeaders;
 }
 
-/**
- * @file Cross-platform configuration helpers.
- *
- * One pure helper used by the deployment resource:
- *
- *   - `mergeDeployOptions(perCallOptions, clientDefaults)` — overlays
- *     instance-level defaults under per-call overrides for a single deploy.
- *
- * Deploy options are pure deploy concerns (progress, timeout, concurrency).
- * Credentials, the API URL, and the caller identifier are client identity —
- * they live on the instance, never per call: one client is one principal
- * speaking for one end user against one API. Callers that need a different
- * identity construct another Ship.
- */
-
-/**
- * Overlay client-level defaults under per-call deploy options.
- *
- * Per-call options always win — they're the explicit override for a single
- * `deployments.upload()`. Defaults fill in only when the per-call option is
- * `undefined` (an explicit `null` / empty value passes through).
- */
-declare function mergeDeployOptions(options: DeploymentOptions, clientDefaults: ShipClientOptions): DeploymentOptions;
-
 /**
  * @file Deploy path optimization - the core logic that makes Ship deployments clean and intuitive.
  * Automatically strips common parent directories to create clean deployment URLs.
@@ -1775,7 +2387,7 @@ declare function pluralize(count: number, singular: string, plural: string, incl
  * @param paths - File or directory paths to scan and process.
  * @param options - Processing options (pathDetect, etc.).
  * @param platformLimits - Per-instance platform limits (file-size / count /
- *   total-size caps) from the originating Ship's `GET /config` fetch. Passed
+ *   total-size caps) from the originating Ship's `GET /limits` fetch. Passed
  *   in rather than read from a module global so concurrent Ships against
  *   different API URLs cannot clobber each other's caps.
  * @returns Promise resolving to an array of StaticFile objects.
@@ -1827,9 +2439,12 @@ declare class Ship extends Ship$1 {
      * intentional: the convenience shortcut narrows; the resource-layer
      * contract stays platform-neutral.
      */
-    deploy(input: string | string[], options?: DeploymentOptions): Promise<Deployment>;
+    deploy(input: string | string[], options?: DeploymentOptions): Promise<DeploymentCreateResponse>;
     protected processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
     protected getDeployBodyCreator(): DeployBodyCreator;
 }
 
-export { API_KEY, type Account, type AccountGetResponse, 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 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 DeploymentListResponse, type DeploymentOptions, type DeploymentResource, type DeploymentResourceContext, DeploymentStatus, type DeploymentStatusType, type DeploymentUploadOptions, type DnsProvider, type DnsRecord, type DnsRecordType, type Domain, type DomainDnsResponse, type DomainListResponse, type DomainRecordsResponse, type DomainResource, type DomainSetResult, DomainStatus, type DomainStatusType, type DomainValidateResponse, type ErrorResponse, ErrorType, type ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, type Fetch, type FileValidationResult, FileValidationStatus, type FileValidationStatusType, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, type MD5Result, OAuthScope, type OAuthScopeType, PASSWORD_CONSTRAINTS, type PingResponse, type PlatformLimits, type ProgressInfo, type ResourceContext, type SPACheckRequest, type SPACheckResponse, SPA_DEFAULT_CONFIG, Ship, type ShipClientOptions, ShipError, type ShipEvents, type StaticFile, type TokenCreateResponse, TokenKind, type TokenKindType, type TokenListItem, type TokenListResponse, type TokenProvider, type TokenResource, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, type UploadedFile, type UserVisibleActivityEvent, type ValidatableFile, type ValidationIssue, __setTestEnvironment, allValidFilesReady, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForNode, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validatePassword, validateToken };
+declare namespace Ship {
+  export { API_KEY, API_PATHS, AUTH_BASE_PATH, Account, AccountDeleteResponse, AccountGetResponse, AccountKeyResponse, AccountOverrides, AccountPlan, AccountPlanType, AccountResource, AccountUsage, Activity, ActivityEvent, ActivityListResponse, ActivityMeta, ApiDeployOptions, ApiHttp, ApiHttpOptions, AuthMethod, AuthMethodType, BLOCKED_EXTENSIONS, BillingCancelResponse, BillingStatus, CALLER, CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_FIELDS, DEPLOY_TOKEN, DeployBody, DeployBodyContext, DeployBodyCreator, DeployFile, DeployInput, Deployment, DeploymentCreateResponse, DeploymentDeleteResponse, DeploymentListResponse, DeploymentOptions, DeploymentResource, DeploymentResourceContext, DeploymentSetOptions, DeploymentStatus, DeploymentStatusType, DeploymentUploadOptions, DeploymentVia, DeploymentViaType, DnsLookup, DnsProvider, DnsRecord, DnsRecordType, Domain, DomainDeleteResponse, DomainDnsResponse, DomainListResponse, DomainRecordsResponse, DomainResource, DomainSetOptions, DomainSetResult, DomainShareResponse, DomainStatus, DomainStatusType, DomainValidateResponse, DomainVerifyResponse, ErrorResponse, ErrorType, ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, Fetch, FileValidationResult, FileValidationStatus, FileValidationStatusType, IDEMPOTENCY_KEY_CONSTRAINTS, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, LabelsResponse, ListOptions, ListResponse, MD5Result, MY_API_KEY_URL, OAuthScope, OAuthScopeType, PASSWORD_CONSTRAINTS, PUBLIC_DEPLOYMENT_TTL_SECONDS, PingResponse, PlatformLimits, ResourceContext, SHIP_ENV, SPACheckDebug, SPACheckRequest, SPACheckResponse, SPA_CHECK_CONSTRAINTS, SPA_DEFAULT_CONFIG, SetupInstructionsResponse, ShipClientOptions, ShipError, ShipEvents, StaticFile, Token, TokenCreateOptions, TokenCreateResponse, TokenDeleteResponse, TokenKind, TokenKindType, TokenListResponse, TokenProvider, TokenResource, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, WEB_FILE_ACCEPT, __setTestEnvironment, allValidFilesReady, assertShipJsonSyntax, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, normalizeVia, optimizeDeployPaths, pluralize, processFilesForNode, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validateIdempotencyKey, validatePassword, validateToken };
+}
+export = Ship;