@shipstatic/types 2.5.0-beta.11 → 2.5.0-beta.13

package/README.md

@@ -20,13 +20,17 @@ npm install @shipstatic/types
 
 ```typescript
 import type {
-  ListResponse,
-  Deployment, DeploymentListResponse, DeploymentDeleteResponse,
-  Domain, DomainSetResult, DomainListResponse, DnsRecord, DomainDnsResponse, DomainRecordsResponse, DomainValidateResponse, DomainDeleteResponse, DomainVerifyResponse,
-  Token, TokenListResponse, TokenCreateResponse, TokenDeleteResponse,
+  ListResponse, ListOptions,
+  Deployment, DeploymentListResponse, DeploymentDeleteResponse, DeploymentSetOptions,
+  Domain, DomainSetResult, DomainSetOptions, DomainListResponse, DnsRecord, DnsLookup, DomainDnsResponse, DomainRecordsResponse, DomainShareResponse, DomainValidateResponse, DomainDeleteResponse, DomainVerifyResponse,
+  Token, TokenListResponse, TokenCreateResponse, TokenCreateOptions, TokenDeleteResponse,
   Account, AccountUsage, AccountOverrides, AccountDeleteResponse, AccountKeyResponse,
+  LabelsResponse, SetupInstructionsResponse,
   StaticFile
 } from '@shipstatic/types';
+
+// Every public path, declared once — the API mounts from it, clients request against it.
+import { API_PATHS } from '@shipstatic/types';
 ```
 
 A mutation answers with the resource it affected — the entity when it
@@ -123,6 +127,7 @@ import type {
 import {
   validateApiKey,
   validateDeployToken,
+  validateIdempotencyKey,
   validateApiUrl,
   isDeployment,
   isBlockedExtension,

package/dist/index.d.ts

@@ -49,6 +49,62 @@ 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.
  *
@@ -86,12 +142,23 @@ export interface DeploymentListResponse extends ListResponse {
  * Where the resource is simply gone, the key alone is the whole answer
  * ({@link DomainDeleteResponse}, {@link TokenDeleteResponse}).
  *
- * Nothing else rides along. No prose (`message`), because an acknowledgement
- * is data and each surface composes its own copy; and no constant
- * (`changed: true`, `queued: true`, `success: true`), because a field whose
- * value the type already fixes tells a caller nothing it did not know before
- * it made the request. Sync versus accepted is the HTTP status code's job —
- * 200 versus 202 — not a boolean's.
+ * 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 */
@@ -200,13 +267,33 @@ 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;
+}
 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.
+ */
+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
@@ -219,6 +306,53 @@ export interface DomainRecordsResponse {
     /** Required DNS records for configuration */
     records: DnsRecord[];
 }
+/**
+ * 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: {
+    readonly MAX_LENGTH: 256;
+    /** How long a stored 201 stays replayable. */
+    readonly WINDOW_SECONDS: number;
+};
+/**
+ * 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.
+ */
+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.
+ */
+export interface SetupInstructionsResponse {
+    /** 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;
+}
 /**
  * Response for domain validation
  */
@@ -839,16 +973,22 @@ 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;
+}
 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.
@@ -920,6 +1060,25 @@ 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 that varies
+     * per attempt, 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
@@ -943,6 +1102,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.
  *
@@ -955,30 +1141,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>;
+    remove: (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>;
+    remove: (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
@@ -990,12 +1168,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>;
+    remove: (token: string) => Promise<TokenDeleteResponse>;
 }
 /**
  * Billing status response from GET /billing/status

package/dist/index.js

@@ -14,6 +14,62 @@ export const DeploymentStatus = {
     FAILED: 'failed',
     DELETING: 'deleting',
 };
+/**
+ * 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) => `/deployments/${deployment}`,
+    DEPLOYMENT_CONFIG: (deployment) => `/deployments/${deployment}/config`,
+    DOMAINS: '/domains',
+    DOMAIN: (domain) => `/domains/${domain}`,
+    DOMAIN_VERIFY: (domain) => `/domains/${domain}/verify`,
+    DOMAIN_DNS: (domain) => `/domains/${domain}/dns`,
+    DOMAIN_RECORDS: (domain) => `/domains/${domain}/records`,
+    DOMAIN_SHARE: (domain) => `/domains/${domain}/share`,
+    DOMAIN_PROPAGATION: (domain) => `/domains/${domain}/propagation`,
+    DOMAINS_VALIDATE: '/domains/validate',
+    TOKENS: '/tokens',
+    TOKEN: (token) => `/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',
+};
 // =============================================================================
 // DOMAIN TYPES
 // =============================================================================
@@ -31,6 +87,38 @@ export const DomainStatus = {
     SUCCESS: 'success',
     PAUSED: 'paused',
 };
+/**
+ * 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 = {
+    MAX_LENGTH: 256,
+    /** How long a stored 201 stays replayable. */
+    WINDOW_SECONDS: 24 * 60 * 60,
+};
+/**
+ * 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) {
+    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;
+}
 // =============================================================================
 // ACCOUNT TYPES
 // =============================================================================

package/package.json

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

package/src/index.ts

@@ -58,6 +58,63 @@ export interface DeploymentCreateResponse extends Deployment {
   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 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 half of a list response that is identical on every list.
  *
@@ -97,12 +154,23 @@ export interface DeploymentListResponse extends ListResponse {
  * Where the resource is simply gone, the key alone is the whole answer
  * ({@link DomainDeleteResponse}, {@link TokenDeleteResponse}).
  *
- * Nothing else rides along. No prose (`message`), because an acknowledgement
- * is data and each surface composes its own copy; and no constant
- * (`changed: true`, `queued: true`, `success: true`), because a field whose
- * value the type already fixes tells a caller nothing it did not know before
- * it made the request. Sync versus accepted is the HTTP status code's job —
- * 200 versus 202 — not a boolean's.
+ * 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 */
@@ -226,11 +294,35 @@ 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;
+}
+
 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.
+ */
+export interface DomainShareResponse {
+  /** The domain the setup link is for */
+  readonly domain: string;
+  /** The salted setup hash that authorizes the share */
+  readonly hash: string;
 }
 
 /**
@@ -245,6 +337,72 @@ export interface DomainRecordsResponse {
   records: DnsRecord[];
 }
 
+/**
+ * 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 = {
+  MAX_LENGTH: 256,
+  /** How long a stored 201 stays replayable. */
+  WINDOW_SECONDS: 24 * 60 * 60,
+} as const;
+
+/**
+ * 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.
+ */
+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.
+ */
+export interface SetupInstructionsResponse {
+  /** 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;
+}
+
 /**
  * Response for domain validation
  */
@@ -1320,16 +1478,23 @@ 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;
+}
+
 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;
 }
 
 // =============================================================================
@@ -1417,6 +1582,25 @@ 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 that varies
+   * per attempt, 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;
 }
 
 /**
@@ -1442,6 +1626,36 @@ export interface ListOptions {
   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.
  *
@@ -1456,26 +1670,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>;
+  remove: (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>;
+  remove: (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>;
 }
 
 /**
@@ -1489,9 +1700,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>;
+  remove: (token: string) => Promise<TokenDeleteResponse>;
 }
 
 // =============================================================================