@shipstatic/types 2.5.0-beta.9 → 2.5.0

package/src/index.ts

@@ -4,7 +4,7 @@
  */
 
 // =============================================================================
-// I. CORE ENTITIES
+// DEPLOYMENT TYPES
 // =============================================================================
 
 /**
@@ -19,6 +19,30 @@ export const DeploymentStatus = {
 
 export 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.
+ */
+export const DeploymentVia = {
+  WEB: 'web',
+  SDK: 'sdk',
+  CLI: 'cli',
+  MCP: 'mcp',
+  GIT: 'git',
+  N8N: 'n8n',
+  GPT: 'gpt',
+  VSC: 'vsc',
+} as const;
+
+export type DeploymentViaType = (typeof DeploymentVia)[keyof typeof DeploymentVia];
+
 /**
  * Core deployment object - used in both API responses and SDK
  */
@@ -39,7 +63,15 @@ export 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;
@@ -71,15 +103,35 @@ export interface DeploymentCreateResponse extends Deployment {
  * 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.
- *
- * The operator lists (`/admin/*`) answer this same shape behind the prefix;
- * their types live in `web/my`, not here — see `CLAUDE.md`, "Admin types".
  */
 export 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.
+ */
+export 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
  */
@@ -88,6 +140,43 @@ export interface DeploymentListResponse extends ListResponse {
   deployments: Deployment[];
 }
 
+/**
+ * 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.
+ */
+export 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 TYPES
 // =============================================================================
@@ -154,6 +243,27 @@ export interface DomainListResponse extends ListResponse {
   domains: Domain[];
 }
 
+/**
+ * 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.
+ */
+export 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.
+ */
+export interface DomainVerifyResponse {
+  /** The domain whose DNS verification was queued, normalized */
+  readonly domain: string;
+}
+
 /**
  * DNS record types supported for domain configuration
  */
@@ -182,15 +292,49 @@ export 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.
+ */
+export 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").
+ */
 export 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").
+ */
+export 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").
  */
 export interface DomainRecordsResponse {
   /** The domain name */
@@ -202,7 +346,118 @@ export interface DomainRecordsResponse {
 }
 
 /**
- * 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.
+ */
+export 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.
+   */
+  HEADER: 'Idempotency-Key',
+  MAX_LENGTH: 256,
+  /** How long a stored 201 stays replayable. */
+  WINDOW_SECONDS: 24 * 60 * 60,
+} as const;
+
+/**
+ * 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.
+ */
+export function normalizeVia(value: unknown): DeploymentViaType | undefined {
+  if (!value || typeof value !== 'string') return undefined;
+  const via = value.trim().toLowerCase();
+  return (Object.values(DeploymentVia) as string[]).includes(via)
+    ? (via as 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.
+ */
+export function validateIdempotencyKey(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string') {
+    throw ShipError.validation('Idempotency key must be a string.');
+  }
+  const key = value.trim();
+  if (!key) {
+    throw ShipError.validation('Idempotency key must not be empty.');
+  }
+  if (key.length > IDEMPOTENCY_KEY_CONSTRAINTS.MAX_LENGTH) {
+    throw ShipError.validation(
+      `Idempotency key must be at most ${IDEMPOTENCY_KEY_CONSTRAINTS.MAX_LENGTH} characters.`,
+    );
+  }
+  return key;
+}
+
+/**
+ * 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").
+ */
+export 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").
+ */
+export 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.
  */
 export interface DomainValidateResponse {
   /** Whether the domain is valid */
@@ -211,8 +466,8 @@ export 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;
 }
 
 // =============================================================================
@@ -222,13 +477,7 @@ export interface DomainValidateResponse {
 /**
  * Core deploy token object - used in both API responses and SDK.
  *
- * A single noun, like every other entity here: the platform's unit types are
- * `Deployment`, `Domain`, `Account`, `Activity` and this. It was once called
- * `TokenListItem`, named for the surface that returned it rather than for
- * what it is, which is exactly why {@link TokenCreateResponse} used to
- * restate its fields instead of extending it.
- *
- * The token itself is never here. The secret is shown once at creation
+ * 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.
  */
@@ -264,6 +513,16 @@ export interface TokenCreateResponse extends Token {
   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.
+ */
+export interface TokenDeleteResponse {
+  /** The 7-char management identifier that was revoked */
+  readonly token: string;
+}
+
 // =============================================================================
 // ACCOUNT TYPES
 // =============================================================================
@@ -362,6 +621,37 @@ export interface AccountGetResponse extends Account {
   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.
+ */
+export 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").
+ */
+export 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
@@ -379,6 +669,103 @@ export interface AccountOverrides {
   totalSize?: number;
 }
 
+// =============================================================================
+// WIRE SURFACE
+// =============================================================================
+
+/**
+ * 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.
+ */
+export const API_PATHS = {
+  DEPLOYMENTS: '/deployments',
+  DEPLOYMENT: (deployment: string) => `/deployments/${deployment}`,
+  DEPLOYMENT_CONFIG: (deployment: string) => `/deployments/${deployment}/config`,
+  DOMAINS: '/domains',
+  DOMAIN: (domain: string) => `/domains/${domain}`,
+  DOMAIN_VERIFY: (domain: string) => `/domains/${domain}/verify`,
+  DOMAIN_DNS: (domain: string) => `/domains/${domain}/dns`,
+  DOMAIN_RECORDS: (domain: string) => `/domains/${domain}/records`,
+  DOMAIN_SHARE: (domain: string) => `/domains/${domain}/share`,
+  DOMAIN_PROPAGATION: (domain: string) => `/domains/${domain}/propagation`,
+  DOMAINS_VALIDATE: '/domains/validate',
+  TOKENS: '/tokens',
+  TOKEN: (token: string) => `/tokens/${token}`,
+  ACCOUNT: '/account',
+  ACCOUNT_KEY: '/account/key',
+  ACCOUNT_CLAIM: '/account/claim',
+  ACTIVITIES: '/activities',
+  LABELS: '/labels',
+  LIMITS: '/limits',
+  PING: '/ping',
+  SETUP: '/setup',
+  SPA_CHECK: '/spa-check',
+  UPLOAD: '/upload',
+} as const;
+
+/**
+ * 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.
+ */
+export const DEPLOY_FIELDS = {
+  /** One entry per file — read with `getAll`. */
+  FILES: 'files[]',
+  /** JSON array of MD5 hex digests, index-aligned with `FILES`. */
+  CHECKSUMS: 'checksums',
+  /** JSON array of label strings. */
+  LABELS: 'labels',
+  /** The deploying surface's {@link DeploymentVia} member. */
+  VIA: 'via',
+  /** Plaintext password — the API hashes it server-side. */
+  PASSWORD: 'password',
+  /** @internal Server-processing flag — first-party `/upload` only. */
+  BUILD: 'build',
+  /** @internal Server-processing flag — first-party `/upload` only. */
+  PRERENDER: 'prerender',
+  /** @internal Server-processing flag — first-party `/upload` only. */
+  SPA: 'spa',
+  /** @internal reCAPTCHA proof — `web/www`'s public uploader only. */
+  CAPTCHA: 'captcha',
+} as const;
+
 // =============================================================================
 // ERROR SYSTEM
 // =============================================================================
@@ -393,7 +780,15 @@ export interface AccountOverrides {
  * (`DeploymentStatus`, `DomainStatus`, `AccountPlan`, `AuthMethod`) follow.
  */
 export 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.
+   */
   Validation: 'validation_failed',
   /** Resource not found (404). */
   NotFound: 'not_found',
@@ -407,6 +802,17 @@ export const ErrorType = {
   Business: 'business_logic_error',
   /** API server error (500). Generic server-side fault. */
   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.
+   */
+  Maintenance: 'maintenance',
   /** Network/connection error. Client-side only — set by HTTP clients on fetch failure; never produced server-side. */
   Network: 'network_error',
   /** Operation was cancelled. Client-side only — set on `AbortSignal` abort; never produced server-side. */
@@ -440,12 +846,19 @@ const CLIENT_ONLY_ERROR_TYPES = new Set<string>([
 const ERROR_CATEGORIES = {
   /**
    * Client-attributable types. Exhaustive over the 4xx-carrying types, and
-   * it must include the statusless ones (`Config`, `File`) — those are
-   * raised locally by the SDK and have no status for `isClientError`'s
-   * second arm to read.
+   * over the statusless ones too — those are raised locally and have no
+   * status for `isClientError`'s second arm to read, so omitting one makes it
+   * read as a server fault. The rule is the membership test: every type in
+   * `CLIENT_ONLY_ERROR_TYPES` except `Network` (which `isNetworkError` owns)
+   * belongs here.
+   *
+   * `Cancelled` was missing until 2026-07-29, which is exactly that failure:
+   * a caller who aborted their own deploy was told "server error: please try
+   * again" — the CLI's fallback for everything this set does not claim.
    */
   client: new Set<ErrorType>([
     ErrorType.Business,
+    ErrorType.Cancelled,
     ErrorType.Config,
     ErrorType.File,
     ErrorType.Forbidden,
@@ -468,6 +881,51 @@ const SERVER_PRODUCIBLE_ERROR_TYPES = new Set<string>(
   Object.values(ErrorType).filter((t) => !CLIENT_ONLY_ERROR_TYPES.has(t)),
 );
 
+/**
+ * Ceiling on a message adopted from a **non-JSON** error body — a foreign
+ * responder's, never this platform's. Generous for the plain-text one-liners
+ * intermediaries actually send (`error code: 1015`), far below a document.
+ * Our own messages are never measured against it: a JSON body is the API's
+ * contract, and truncating a long validation message would be the bug.
+ */
+const MAX_FOREIGN_MESSAGE_LENGTH = 200;
+
+/**
+ * Did the runtime say the exchange never completed?
+ *
+ * WHATWG has `fetch` reject with a **TypeError** on network error, and undici,
+ * Chromium and Firefox comply. Bun does not: it rejects with a plain `Error`
+ * carrying a system `code` string. Captured 2026-08-05 (the capture script is
+ * in `tests/errors.test.ts`, "runtime failure shapes"):
+ *
+ * | failure       | Node 22 / undici          | Bun 1.3.14                                   |
+ * |---------------|---------------------------|----------------------------------------------|
+ * | refused       | `TypeError: fetch failed` | `Error` `code: 'ConnectionRefused'`          |
+ * | DNS failure   | `TypeError: fetch failed` | `Error` `code: 'ConnectionRefused'`          |
+ * | reset         | `TypeError: fetch failed` | `Error` `code: 'ECONNRESET'`                 |
+ * | TLS rejected  | `TypeError: fetch failed` | `Error` `code: 'UNKNOWN_CERTIFICATE_…ERROR'` |
+ *
+ * So the test is the **evidence, not a list of dialect strings**: a string
+ * `code` is a runtime naming a transport-level failure. An allowlist of codes
+ * was written first and rejected — the TLS row alone would mean enumerating
+ * BoringSSL's certificate table, and a code nobody guessed is precisely the bug
+ * this closes. Two kinds of error are deliberately NOT caught: ordinary JS
+ * faults carry no `code` at all, and a `DOMException`'s is a **number**, so
+ * aborts and timeouts fall through to their own arms.
+ *
+ * The accepted trade: a caller's `TokenProvider` that throws a coded error
+ * (`ENOENT` from a keychain read) is typed `Network` rather than `Api`. Both
+ * are wrong for it, `Network` is the cheaper wrong — it says "nothing was
+ * exchanged", which is true, where `Api` claims a server answered.
+ */
+function isTransportFailure(cause: Error): boolean {
+  if (typeof (cause as { code?: unknown }).code === 'string') return true;
+  // Spec runtimes put no code on the rejection itself. The message test is what
+  // keeps fetch's ARGUMENT errors out — `Failed to parse URL from …` is a
+  // caller's config mistake, not a transport failure.
+  return cause instanceof TypeError && cause.message.includes('fetch');
+}
+
 /**
  * Standard error response format used everywhere
  */
@@ -554,8 +1012,17 @@ export class ShipError extends Error {
           }
         }
       } else {
-        const text = await response.text();
-        if (text) message = text;
+        // A non-JSON body did not come from this platform — every API error
+        // is `ErrorResponse` JSON — so it is an intermediary's output, and
+        // the two kinds it produces need opposite treatment. A CDN's plain
+        // `error code: 1015` is the most useful thing there is to say. A
+        // proxy's HTML error page is a *document*, not a message: adopting it
+        // verbatim made a misconfigured `apiUrl` print 2,059 characters of
+        // markup as the error. Trust it only when it reads as a message.
+        const text = (await response.text()).trim();
+        if (text && !text.startsWith('<') && text.length <= MAX_FOREIGN_MESSAGE_LENGTH) {
+          message = text;
+        }
       }
     } catch {
       // Body unreadable; fall through to operationName-derived message.
@@ -605,7 +1072,8 @@ export class ShipError extends Error {
    * Routing:
    * - Already a `ShipError` → returned as-is (caller's intent preserved)
    * - `AbortError` → `ShipError.cancelled(...)`
-   * - `TypeError` whose message mentions "fetch" → `ShipError.network(...)`
+   * - A transport failure → `ShipError.network(...)` — see `isTransportFailure`
+   *   for what each runtime offers as evidence
    * - Any other `Error` → `ShipError(Api, ...)` (no HTTP status — fetch never reached the server)
    * - Anything else (string, undefined, etc.) → `ShipError(Api, ...)`
    *
@@ -622,7 +1090,7 @@ export class ShipError extends Error {
       if (cause.name === 'AbortError') {
         return ShipError.cancelled(`${op} was cancelled`);
       }
-      if (cause instanceof TypeError && cause.message.includes('fetch')) {
+      if (isTransportFailure(cause)) {
         return ShipError.network(`${op} failed: ${cause.message}`, { cause });
       }
       return new ShipError(ErrorType.Api, `${op} failed: ${cause.message}`);
@@ -694,6 +1162,19 @@ export class ShipError extends Error {
     return new ShipError(ErrorType.Api, message, status, details);
   }
 
+  /**
+   * 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 {
+    return new ShipError(ErrorType.Maintenance, message, 503, details);
+  }
+
   // Semantic-category guards. For specific-type checks, use
   // `error.type === ErrorType.X` directly or the generic `isType(t)`.
 
@@ -749,7 +1230,7 @@ export function isShipError(error: unknown): error is ShipError {
 }
 
 // =============================================================================
-// CONFIG TYPES
+// PLATFORM LIMITS
 // =============================================================================
 
 /**
@@ -761,6 +1242,9 @@ export 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").
  */
 export interface PlatformLimits {
   /** Maximum size in bytes for a single file. */
@@ -849,6 +1333,128 @@ export function isBlockedExtension(filename: string): boolean {
   return BLOCKED_EXTENSIONS.has(ext);
 }
 
+// =============================================================================
+// PICKER ACCEPT HINT
+// =============================================================================
+
+/**
+ * The extensions a browser file picker offers by default, grouped by role.
+ *
+ * Private on purpose: the only published form is `WEB_FILE_ACCEPT`, the
+ * attribute value itself. A published set would invite a call site to ask it
+ * whether a file is allowed — which is the one thing this list must never
+ * answer. See `WEB_FILE_ACCEPT`.
+ *
+ * Extensionless files (`LICENSE`, most `.well-known` entries) are inexpressible
+ * in `accept`, and reach a deployment by folder pick, ZIP, or drag-and-drop.
+ */
+const WEB_FILE_EXTENSIONS = [
+  // Markup & documents
+  'html',
+  'htm',
+  'xhtml',
+  'xml',
+  'txt',
+  'md',
+  'markdown',
+  'pdf',
+  'csv',
+  // Data & config
+  'json',
+  'jsonc',
+  'webmanifest',
+  'map',
+  'toml',
+  'yaml',
+  'yml',
+  'rss',
+  'atom',
+  // Styles
+  'css',
+  'scss',
+  'sass',
+  'less',
+  // Scripts & modules
+  'js',
+  'mjs',
+  'cjs',
+  'jsx',
+  'ts',
+  'tsx',
+  'wasm',
+  'vue',
+  'svelte',
+  // Images
+  'png',
+  'jpg',
+  'jpeg',
+  'gif',
+  'webp',
+  'avif',
+  'svg',
+  'ico',
+  'bmp',
+  'tif',
+  'tiff',
+  'heic',
+  'heif',
+  // Fonts
+  'woff',
+  'woff2',
+  'ttf',
+  'otf',
+  'eot',
+  // Audio
+  'mp3',
+  'wav',
+  'ogg',
+  'oga',
+  'opus',
+  'm4a',
+  'aac',
+  'flac',
+  'weba',
+  // Video
+  'mp4',
+  'webm',
+  'ogv',
+  'mov',
+  'm4v',
+  'avi',
+  // 3D models
+  'glb',
+  'gltf',
+  'usdz',
+  // Text tracks
+  'vtt',
+  'srt',
+  // Archive — a whole site in one file
+  'zip',
+] as const;
+
+/**
+ * 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.
+ */
+export const WEB_FILE_ACCEPT: string = WEB_FILE_EXTENSIONS.map((ext) => `.${ext}`).join(',');
+
 // =============================================================================
 // FILENAME CHARACTER VALIDATION
 // =============================================================================
@@ -911,13 +1517,20 @@ export 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.
  */
 export interface PingResponse {
-  /** Always true if service is healthy */
-  success: boolean;
   /** Server time in unix seconds — the one wire unit for timestamps. */
-  timestamp?: number;
+  readonly timestamp: number;
 }
 
 // =============================================================================
@@ -1067,6 +1680,27 @@ export const SPA_DEFAULT_CONFIG = {
   rewrites: [{ source: '/(.*)', destination: '/index.html' }],
 } as const;
 
+/**
+ * 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.
+ */
+export const SPA_CHECK_CONSTRAINTS = {
+  /** The file whose content is the check's subject. */
+  INDEX_FILE: 'index.html',
+  /** Skip the pre-flight above this size — the server would answer false. */
+  MAX_INDEX_BYTES: 100 * 1024,
+} as const;
+
 /**
  * Assert that a ship.json file is *syntactically* loadable. Syntax only —
  * never schema.
@@ -1244,16 +1878,27 @@ export 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.
+ */
+export 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").
+ */
 export 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;
 }
 
 // =============================================================================
@@ -1297,6 +1942,53 @@ export interface StaticFile {
 /** Default API URL if not otherwise configured. */
 export 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".
+ */
+export const SHIP_ENV = {
+  /** The one credential slot — any platform token. */
+  TOKEN: 'SHIP_TOKEN',
+  /** The API endpoint override. */
+  API_URL: 'SHIP_API_URL',
+} as const;
+
+/**
+ * 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").
+ */
+export 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.
+ */
+export const PUBLIC_DEPLOYMENT_TTL_SECONDS = 3 * 24 * 60 * 60;
+
 // =============================================================================
 // RESOURCE INTERFACE CONTRACTS
 // =============================================================================
@@ -1320,8 +2012,12 @@ export type DeployInput = File[] | string | string[];
 export 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.
    *
@@ -1341,29 +2037,55 @@ export 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;
 }
 
 /**
- * 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.
+ * What a caller may change on an existing deployment.
  *
- * 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.
+ * 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.
+ */
+export 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.
  *
- * 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.
+ * `deployment` is deliberately not nullable — unlinking is refused (400).
+ * See `npm/ship/CLAUDE.md`, "Domain Write Semantics".
  */
-export interface ListOptions {
-  /** Maximum number of items to return in one page. */
-  limit?: number;
-  /** Opaque cursor from the previous page's response. */
-  cursor?: string;
+export interface DomainSetOptions {
+  deployment?: string;
+  labels?: string[];
+}
+
+/** What a caller may set when minting a deploy token. */
+export interface TokenCreateOptions {
+  /** Seconds until expiry; omit for a token that never expires. */
+  ttl?: number;
+  labels?: string[];
 }
 
 /**
@@ -1380,26 +2102,23 @@ export interface DeploymentResource<
   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
  */
 export interface DomainResource {
-  set: (
-    name: string,
-    options?: { deployment?: string; labels?: string[] },
-  ) => Promise<DomainSetResult>;
+  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>;
 }
 
 /**
@@ -1413,9 +2132,10 @@ export interface AccountResource {
  * Token resource interface - the contract all implementations must follow
  */
 export interface TokenResource {
-  create: (options?: { ttl?: number; labels?: string[] }) => Promise<TokenCreateResponse>;
+  create: (options?: TokenCreateOptions) => Promise<TokenCreateResponse>;
   list: (options?: ListOptions) => Promise<TokenListResponse>;
-  remove: (token: string) => Promise<void>;
+  get: (token: string) => Promise<Token>;
+  delete: (token: string) => Promise<TokenDeleteResponse>;
 }
 
 // =============================================================================
@@ -1441,6 +2161,26 @@ export interface BillingStatus {
   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.
+ */
+export 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
  */