@shipstatic/types 2.5.0-beta.21 → 2.5.0-beta.23

package/dist/index.d.ts

@@ -79,97 +79,6 @@ 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 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 declare const DEPLOY_FIELDS: {
-    /** One entry per file — read with `getAll`. */
-    readonly FILES: "files[]";
-    /** JSON array of MD5 hex digests, index-aligned with `FILES`. */
-    readonly CHECKSUMS: "checksums";
-    /** JSON array of label strings. */
-    readonly LABELS: "labels";
-    /** The deploying surface's {@link DeploymentVia} member. */
-    readonly VIA: "via";
-    /** Plaintext password — the API hashes it server-side. */
-    readonly PASSWORD: "password";
-    /** @internal Server-processing flag — first-party `/upload` only. */
-    readonly BUILD: "build";
-    /** @internal Server-processing flag — first-party `/upload` only. */
-    readonly PRERENDER: "prerender";
-    /** @internal Server-processing flag — first-party `/upload` only. */
-    readonly SPA: "spa";
-    /** @internal reCAPTCHA proof — `web/www`'s public uploader only. */
-    readonly CAPTCHA: "captcha";
-};
 /**
  * The half of a list response that is identical on every list.
  *
@@ -188,6 +97,28 @@ 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
  */
@@ -658,6 +589,97 @@ export interface AccountOverrides {
     /** Override for maximum total deployment size in bytes */
     totalSize?: number;
 }
+/**
+ * Every path the public API answers on, declared once.
+ *
+ * The URL surface was written out in four places — the API's mounts, the
+ * SDK's client, the dashboard's client, and the post-deploy smoke — so a
+ * rename meant finding all four. The first three now read this table.
+ *
+ * The smoke (`cloudflare/api/smoke.mjs`) deliberately still spells its own:
+ * five of its nine paths are `/admin/*`, which this table excludes by
+ * design, and splitting one list between a registry and literals reads worse
+ * than keeping it uniform.
+ *
+ * **What this guarantees, exactly.** Collection paths are mounted from here,
+ * so producer and consumer cannot diverge. Item paths are declared here and
+ * consumed by clients, but the API spells them relative to their mount
+ * (`/:deployment/config`), so the table does not *generate* them — it is
+ * held to them by `api/tests/architecture/api-paths.test.ts`, which fails if
+ * any entry names a path no route answers. Some entries have no client yet
+ * (`DEPLOYMENT_CONFIG`, `DOMAIN_PROPAGATION` — endpoints the SDK
+ * deliberately does not reach); the fence is what keeps those honest rather
+ * than merely asserted.
+ *
+ * **The operator surface is deliberately absent.** `/admin/*` paths belong
+ * to `web/my`, for the same reason its row types do: this package is
+ * published, and the operator surface is not public (see `CLAUDE.md`, "Admin
+ * types"). A path here is a promise to every npm consumer; `/admin` is a
+ * promise to one dashboard.
+ *
+ * Item paths are functions rather than templates so the key is interpolated
+ * in one place, encoded the same way by every caller.
+ */
+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 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 declare const DEPLOY_FIELDS: {
+    /** One entry per file — read with `getAll`. */
+    readonly FILES: "files[]";
+    /** JSON array of MD5 hex digests, index-aligned with `FILES`. */
+    readonly CHECKSUMS: "checksums";
+    /** JSON array of label strings. */
+    readonly LABELS: "labels";
+    /** The deploying surface's {@link DeploymentVia} member. */
+    readonly VIA: "via";
+    /** Plaintext password — the API hashes it server-side. */
+    readonly PASSWORD: "password";
+    /** @internal Server-processing flag — first-party `/upload` only. */
+    readonly BUILD: "build";
+    /** @internal Server-processing flag — first-party `/upload` only. */
+    readonly PRERENDER: "prerender";
+    /** @internal Server-processing flag — first-party `/upload` only. */
+    readonly SPA: "spa";
+    /** @internal reCAPTCHA proof — `web/www`'s public uploader only. */
+    readonly CAPTCHA: "captcha";
+};
 /**
  * All possible error types in the ShipStatic platform.
  *
@@ -690,6 +712,17 @@ export declare const ErrorType: {
     readonly Business: "business_logic_error";
     /** API server error (500). Generic server-side fault. */
     readonly Api: "internal_server_error";
+    /**
+     * The platform is closed for maintenance (503). A deliberate operator
+     * state, not a fault — nothing errored; the API is refusing work on
+     * purpose, and deployed sites keep serving throughout.
+     *
+     * Distinct from `Api` at 503, which the platform already uses for a
+     * dependency that failed (moderation unavailable). A consumer has to tell
+     * "we closed the door" from "something broke": the two get opposite words
+     * and opposite retry behaviour.
+     */
+    readonly Maintenance: "maintenance";
     /** Network/connection error. Client-side only — set by HTTP clients on fetch failure; never produced server-side. */
     readonly Network: "network_error";
     /** Operation was cancelled. Client-side only — set on `AbortSignal` abort; never produced server-side. */
@@ -790,6 +823,16 @@ 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 platform is closed for maintenance (503).
+     *
+     * `message` is REQUIRED and has no default here. The API is the only
+     * producer of that sentence, and a default in this file would be a second
+     * owner of one fact — see CLAUDE.md, "The Constellation Law" (stopping
+     * rule). It is also the one factory whose status is fixed rather than
+     * defaulted: a maintenance refusal is 503 or it is not this error.
+     */
+    static maintenance(message: string, details?: unknown): ShipError;
     /**
      * The caller is at fault — by HTTP's own definition of a 4xx, or by a type
      * that is client-attributable without ever having a status (`Config`,
@@ -1309,28 +1352,6 @@ export interface DeploymentUploadOptions {
      */
     idempotencyKey?: string;
 }
-/**
- * Pagination options for every list endpoint. The response's `cursor` feeds
- * the next request; a `null` cursor means the last page. Omitting both
- * returns the server's default first page.
- *
- * A list answers `{ <collection>, cursor }` and nothing else — `cursor`
- * carries the entire has-more signal, so no redundant boolean, and no
- * `total`. **A count is an aggregate over a collection, not a property of a
- * page:** including one makes every read pay for a full scan it did not ask
- * for, which is precisely the cost keyset pagination exists to avoid.
- *
- * Counts therefore live on the summary resource that owns them —
- * `GET /account` (`usage`) for a caller's own totals, `GET /admin/stats` for
- * platform-wide ones. Ask for a count when you want a count; ask for a page
- * when you want a page.
- */
-export interface ListOptions {
-    /** Maximum number of items to return in one page. */
-    limit?: number;
-    /** Opaque cursor from the previous page's response. */
-    cursor?: string;
-}
 /**
  * What a caller may change on an existing deployment.
  *

package/dist/index.js

@@ -3,7 +3,7 @@
  * This package is the single source of truth for all shared data structures.
  */
 // =============================================================================
-// I. CORE ENTITIES
+// DEPLOYMENT TYPES
 // =============================================================================
 /**
  * Deployment status constants
@@ -35,97 +35,6 @@ export const DeploymentVia = {
     GPT: 'gpt',
     VSC: 'vsc',
 };
-/**
- * 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',
-};
-/**
- * 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',
-};
 // =============================================================================
 // DOMAIN TYPES
 // =============================================================================
@@ -221,6 +130,100 @@ export const AccountPlan = {
     TERMINATED: 'terminated',
 };
 // =============================================================================
+// 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) => `/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',
+};
+/**
+ * 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',
+};
+// =============================================================================
 // ERROR SYSTEM
 // =============================================================================
 /**
@@ -255,6 +258,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. */
@@ -559,6 +573,18 @@ export class ShipError extends Error {
     static api(message, status = 500, details) {
         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, details) {
+        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)`.
     /**

package/package.json

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

package/src/index.ts

@@ -4,7 +4,7 @@
  */
 
 // =============================================================================
-// I. CORE ENTITIES
+// DEPLOYMENT TYPES
 // =============================================================================
 
 /**
@@ -90,99 +90,6 @@ 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 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;
-
 /**
  * The half of a list response that is identical on every list.
  *
@@ -202,6 +109,29 @@ export interface ListResponse {
   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
  */
@@ -739,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
 // =============================================================================
@@ -775,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. */
@@ -1124,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)`.
 
@@ -1179,7 +1230,7 @@ export function isShipError(error: unknown): error is ShipError {
 }
 
 // =============================================================================
-// CONFIG TYPES
+// PLATFORM LIMITS
 // =============================================================================
 
 /**
@@ -2007,29 +2058,6 @@ export interface DeploymentUploadOptions {
   idempotencyKey?: string;
 }
 
-/**
- * Pagination options for every list endpoint. The response's `cursor` feeds
- * the next request; a `null` cursor means the last page. Omitting both
- * returns the server's default first page.
- *
- * A list answers `{ <collection>, cursor }` and nothing else — `cursor`
- * carries the entire has-more signal, so no redundant boolean, and no
- * `total`. **A count is an aggregate over a collection, not a property of a
- * page:** including one makes every read pay for a full scan it did not ask
- * for, which is precisely the cost keyset pagination exists to avoid.
- *
- * Counts therefore live on the summary resource that owns them —
- * `GET /account` (`usage`) for a caller's own totals, `GET /admin/stats` for
- * platform-wide ones. Ask for a count when you want a count; ask for a page
- * when you want a page.
- */
-export interface ListOptions {
-  /** Maximum number of items to return in one page. */
-  limit?: number;
-  /** Opaque cursor from the previous page's response. */
-  cursor?: string;
-}
-
 /**
  * What a caller may change on an existing deployment.
  *