@shipstatic/types 2.5.0-beta.2 → 2.5.0-beta.20

package/dist/index.d.ts

@@ -12,6 +12,28 @@ export declare const DeploymentStatus: {
     readonly DELETING: "deleting";
 };
 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 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";
+};
+export type DeploymentViaType = (typeof DeploymentVia)[keyof typeof DeploymentVia];
 /**
  * Core deployment object - used in both API responses and SDK
  */
@@ -32,7 +54,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;
@@ -49,16 +79,122 @@ export interface DeploymentCreateResponse extends Deployment {
     /** Claim URL for public deployments. Present when deployed without credentials. */
     readonly claim?: string;
 }
+/**
+ * Every path the public API answers on, declared once.
+ *
+ * The URL surface was written out in four places — the API's mounts, the
+ * SDK's client, the dashboard's client, and the post-deploy smoke — so a
+ * rename meant finding all four. The first three now read this table.
+ *
+ * The smoke (`cloudflare/api/smoke.mjs`) deliberately still spells its own:
+ * five of its nine paths are `/admin/*`, which this table excludes by
+ * design, and splitting one list between a registry and literals reads worse
+ * than keeping it uniform.
+ *
+ * **What this guarantees, exactly.** Collection paths are mounted from here,
+ * so producer and consumer cannot diverge. Item paths are declared here and
+ * consumed by clients, but the API spells them relative to their mount
+ * (`/:deployment/config`), so the table does not *generate* them — it is
+ * held to them by `api/tests/architecture/api-paths.test.ts`, which fails if
+ * any entry names a path no route answers. Some entries have no client yet
+ * (`DEPLOYMENT_CONFIG`, `DOMAIN_PROPAGATION` — endpoints the SDK
+ * deliberately does not reach); the fence is what keeps those honest rather
+ * than merely asserted.
+ *
+ * **The operator surface is deliberately absent.** `/admin/*` paths belong
+ * to `web/my`, for the same reason its row types do: this package is
+ * published, and the operator surface is not public (see `CLAUDE.md`, "Admin
+ * types"). A path here is a promise to every npm consumer; `/admin` is a
+ * promise to one dashboard.
+ *
+ * Item paths are functions rather than templates so the key is interpolated
+ * in one place, encoded the same way by every caller.
+ */
+export declare const API_PATHS: {
+    readonly DEPLOYMENTS: "/deployments";
+    readonly DEPLOYMENT: (deployment: string) => string;
+    readonly DEPLOYMENT_CONFIG: (deployment: string) => string;
+    readonly DOMAINS: "/domains";
+    readonly DOMAIN: (domain: string) => string;
+    readonly DOMAIN_VERIFY: (domain: string) => string;
+    readonly DOMAIN_DNS: (domain: string) => string;
+    readonly DOMAIN_RECORDS: (domain: string) => string;
+    readonly DOMAIN_SHARE: (domain: string) => string;
+    readonly DOMAIN_PROPAGATION: (domain: string) => string;
+    readonly DOMAINS_VALIDATE: "/domains/validate";
+    readonly TOKENS: "/tokens";
+    readonly TOKEN: (token: string) => string;
+    readonly ACCOUNT: "/account";
+    readonly ACCOUNT_KEY: "/account/key";
+    readonly ACCOUNT_CLAIM: "/account/claim";
+    readonly ACTIVITIES: "/activities";
+    readonly LABELS: "/labels";
+    readonly LIMITS: "/limits";
+    readonly PING: "/ping";
+    readonly SETUP: "/setup";
+    readonly SPA_CHECK: "/spa-check";
+    readonly UPLOAD: "/upload";
+};
+/**
+ * The half of a list response that is identical on every list.
+ *
+ * `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.
+ */
+export interface ListResponse {
+    /** Opaque cursor from this page; `null` on the last page. */
+    cursor: string | null;
+}
 /**
  * Response for listing deployments
  */
-export interface DeploymentListResponse {
+export 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.
+ */
+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 status constants
@@ -91,7 +227,7 @@ export 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 +249,28 @@ export interface DomainSetResult extends Domain {
 /**
  * Response for listing domains
  */
-export interface DomainListResponse {
+export 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.
+ */
+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
@@ -146,16 +297,46 @@ 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 */
@@ -166,7 +347,92 @@ export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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").
+ */
+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 */
@@ -175,15 +441,17 @@ 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;
 }
 /**
- * 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.
  */
-export interface TokenListItem {
+export 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 +466,28 @@ export interface TokenListItem {
 /**
  * Response for listing tokens
  */
-export interface TokenListResponse {
-    /** Array of tokens (security-redacted for list display) */
-    tokens: TokenListItem[];
-    /** Total number of tokens */
-    total: number;
+export 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.
  */
-export interface TokenCreateResponse {
-    /** 7-char management identifier */
-    token: string;
+export 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.
+ */
+export interface TokenDeleteResponse {
+    /** The 7-char management identifier that was revoked */
+    readonly token: string;
 }
 /**
  * Account plan constants
@@ -232,10 +504,34 @@ export declare const AccountPlan: {
 export 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.
  */
 export 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
@@ -282,6 +578,35 @@ export 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.
+ */
+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
@@ -308,7 +633,15 @@ export interface AccountOverrides {
  * (`DeploymentStatus`, `DomainStatus`, `AccountPlan`, `AuthMethod`) follow.
  */
 export 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";
@@ -388,7 +721,8 @@ export declare class ShipError extends Error {
      * Routing:
      * - Already a `ShipError` → returned as-is (caller's intent preserved)
      * - `AbortError` → `ShipError.cancelled(...)`
-     * - `TypeError` whose message mentions "fetch" → `ShipError.network(...)`
+     * - A transport failure → `ShipError.network(...)` — see `isTransportFailure`
+     *   for what each runtime offers as evidence
      * - Any other `Error` → `ShipError(Api, ...)` (no HTTP status — fetch never reached the server)
      * - Anything else (string, undefined, etc.) → `ShipError(Api, ...)`
      *
@@ -421,6 +755,18 @@ export 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 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;
@@ -447,6 +793,9 @@ export 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").
  */
 export interface PlatformLimits {
     /** Maximum size in bytes for a single file. */
@@ -480,6 +829,28 @@ export declare const BLOCKED_EXTENSIONS: ReadonlySet<string>;
  * isBlockedExtension('README')        // false
  */
 export 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.
+ */
+export declare const WEB_FILE_ACCEPT: string;
 /**
  * Characters that are unsafe in filenames for static hosting.
  *
@@ -517,13 +888,20 @@ export declare const UNBUILT_PROJECT_MARKERS: ReadonlySet<string>;
  */
 export 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.
  */
 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;
 }
 /**
  * Where human identity is mounted on the API host. The API mounts Better
@@ -645,6 +1023,36 @@ export declare const SPA_DEFAULT_CONFIG: {
         readonly destination: "/index.html";
     }];
 };
+/**
+ * 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.
+ */
+export declare function assertShipJsonSyntax(text: string): void;
 /**
  * Validate API key format
  */
@@ -687,16 +1095,26 @@ 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;
 }
 /**
  * Represents a file that has been processed and is ready for deploy.
@@ -729,6 +1147,21 @@ export interface StaticFile {
 }
 /** Default API URL if not otherwise configured. */
 export declare const DEFAULT_API = "https://api.shipstatic.com";
+/**
+ * How long an anonymous deployment lives before it expires.
+ *
+ * The lifetime of the public tier, and one fact with several readers. The API
+ * stamps a deployment's `expires` from it and gives a claim code exactly the
+ * same window — a live site with a dead claim link is a coherence bug, so the
+ * two are one constant rather than two that agree. Both MCP transports quote
+ * the duration in prose an agent reads, and derive it from here rather than
+ * writing it out, which they did in eight places until this export existed.
+ *
+ * Seconds, spelled in the name: this platform has both second- and
+ * millisecond-valued durations, and the pair is only safe when each says which
+ * it is.
+ */
+export declare const PUBLIC_DEPLOYMENT_TTL_SECONDS: number;
 /**
  * Universal deploy input — the union of every shape the SDK accepts.
  *
@@ -747,8 +1180,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.
      *
@@ -768,12 +1205,41 @@ 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 the paginated list endpoints (`GET /deployments`,
- * `GET /domains`). The response's `cursor` feeds the next request; a `null`
- * cursor on the response means the last page. Omitting both returns the
- * server's default first page.
+ * 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. */
@@ -781,6 +1247,33 @@ export interface ListOptions {
     /** Opaque cursor from the previous page's response. */
     cursor?: string;
 }
+/**
+ * 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.
+ */
+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.
+ *
+ * `deployment` is deliberately not nullable — unlinking is refused (400).
+ * See `npm/ship/CLAUDE.md`, "Domain Write Semantics".
+ */
+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[];
+}
 /**
  * Deployment resource interface - the contract all implementations must follow.
  *
@@ -793,32 +1286,22 @@ export interface DeploymentResource<UploadOptions extends DeploymentUploadOption
     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>;
 }
 /**
  * Account resource interface - the contract all implementations must follow
@@ -830,12 +1313,10 @@ export interface AccountResource {
  * Token resource interface - the contract all implementations must follow
  */
 export 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
@@ -855,6 +1336,25 @@ export 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.
+ */
+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
  */
@@ -929,7 +1429,7 @@ export interface ActivityMeta {
 /**
  * Response from GET /activities endpoint
  */
-export interface ActivityListResponse {
+export interface ActivityListResponse extends ListResponse {
     /** Array of activities */
     activities: Activity[];
 }