@shipstatic/types 2.5.0-beta.9 → 2.6.0

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
@@ -14,6 +14,27 @@ export const DeploymentStatus = {
     FAILED: 'failed',
     DELETING: 'deleting',
 };
+/**
+ * Which client made a deployment — the origin-tracking vocabulary.
+ *
+ * A closed set with many authors: the CLI, the SDK, the dashboard, both MCP
+ * transports, the GitHub Action, the n8n node and the VS Code extension each
+ * name themselves here. It lived in the API's config until 2026-08-06, where
+ * being server-side made it unenforceable in the one direction that matters —
+ * every client wrote a bare string, and a value outside the set was **silently
+ * dropped** by the server, so a typo did not fail anywhere. It stopped
+ * recording where deploys came from and said nothing.
+ */
+export const DeploymentVia = {
+    WEB: 'web',
+    SDK: 'sdk',
+    CLI: 'cli',
+    MCP: 'mcp',
+    GIT: 'git',
+    N8N: 'n8n',
+    GPT: 'gpt',
+    VSC: 'vsc',
+};
 // =============================================================================
 // DOMAIN TYPES
 // =============================================================================
@@ -31,6 +52,68 @@ 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 = {
+    /**
+     * HTTP header name. Here for the same reason {@link CALLER.HEADER} is: a
+     * wire header has two ends, and the package that owns the value's format
+     * is the only place both ends can read its name from.
+     */
+    HEADER: 'Idempotency-Key',
+    MAX_LENGTH: 256,
+    /** How long a stored 201 stays replayable. */
+    WINDOW_SECONDS: 24 * 60 * 60,
+};
+/**
+ * Normalize a `via` value from any transport — trimmed, lowercased, and a
+ * member of {@link DeploymentVia}, or `undefined`.
+ *
+ * A format rule by this package's own test: a client can decide offline
+ * whether a value is well-formed, and the API reaches the same verdict on the
+ * same input. It lived server-side until 2026-08-06, which meant clients could
+ * only learn their label was unusable by noticing analytics had gone quiet.
+ *
+ * **Not knowing your `via` is not an error** — an unrecognized value yields
+ * `undefined` rather than throwing, because origin tracking is telemetry and a
+ * deploy must never fail over it. A caller that has an honest default should
+ * prefer it (`normalizeVia(process.env.SHIP_VIA) ?? DeploymentVia.CLI`): the
+ * deploy really did come from the CLI, so recording that beats recording
+ * nothing.
+ */
+export function normalizeVia(value) {
+    if (!value || typeof value !== 'string')
+        return undefined;
+    const via = value.trim().toLowerCase();
+    return Object.values(DeploymentVia).includes(via)
+        ? via
+        : undefined;
+}
+/**
+ * Validate an idempotency key, returning the trimmed value or `undefined`
+ * when none was supplied. Throws {@link ShipError.validation} when the value
+ * cannot be sent — the same verdict the API would reach, reached earlier.
+ */
+export function validateIdempotencyKey(value) {
+    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
 // =============================================================================
@@ -47,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
 // =============================================================================
 /**
@@ -59,7 +236,15 @@ export const AccountPlan = {
  * (`DeploymentStatus`, `DomainStatus`, `AccountPlan`, `AuthMethod`) follow.
  */
 export const ErrorType = {
-    /** Validation failed (400). Input shape is wrong. */
+    /**
+     * Validation failed. Input shape is wrong.
+     *
+     * Carries 400 when an API judged it — including a client-side pre-check of a
+     * rule the server enforces too, which keeps the error identical wherever it
+     * was caught. **Statusless** when a client rejects something no API judges,
+     * such as a CLI's own command grammar: `status` is documented "(API
+     * contexts)" on `ErrorResponse`, so there is none to report.
+     */
     Validation: 'validation_failed',
     /** Resource not found (404). */
     NotFound: 'not_found',
@@ -73,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. */
@@ -102,12 +298,19 @@ const CLIENT_ONLY_ERROR_TYPES = new Set([
 const ERROR_CATEGORIES = {
     /**
      * Client-attributable types. Exhaustive over the 4xx-carrying types, and
-     * it must include the statusless ones (`Config`, `File`) — those are
-     * raised locally by the SDK and have no status for `isClientError`'s
-     * second arm to read.
+     * over the statusless ones too — those are raised locally and have no
+     * status for `isClientError`'s second arm to read, so omitting one makes it
+     * read as a server fault. The rule is the membership test: every type in
+     * `CLIENT_ONLY_ERROR_TYPES` except `Network` (which `isNetworkError` owns)
+     * belongs here.
+     *
+     * `Cancelled` was missing until 2026-07-29, which is exactly that failure:
+     * a caller who aborted their own deploy was told "server error: please try
+     * again" — the CLI's fallback for everything this set does not claim.
      */
     client: new Set([
         ErrorType.Business,
+        ErrorType.Cancelled,
         ErrorType.Config,
         ErrorType.File,
         ErrorType.Forbidden,
@@ -126,6 +329,50 @@ const ERROR_CATEGORIES = {
  * `ErrorType` is automatically picked up.
  */
 const SERVER_PRODUCIBLE_ERROR_TYPES = new Set(Object.values(ErrorType).filter((t) => !CLIENT_ONLY_ERROR_TYPES.has(t)));
+/**
+ * Ceiling on a message adopted from a **non-JSON** error body — a foreign
+ * responder's, never this platform's. Generous for the plain-text one-liners
+ * intermediaries actually send (`error code: 1015`), far below a document.
+ * Our own messages are never measured against it: a JSON body is the API's
+ * contract, and truncating a long validation message would be the bug.
+ */
+const MAX_FOREIGN_MESSAGE_LENGTH = 200;
+/**
+ * Did the runtime say the exchange never completed?
+ *
+ * WHATWG has `fetch` reject with a **TypeError** on network error, and undici,
+ * Chromium and Firefox comply. Bun does not: it rejects with a plain `Error`
+ * carrying a system `code` string. Captured 2026-08-05 (the capture script is
+ * in `tests/errors.test.ts`, "runtime failure shapes"):
+ *
+ * | failure       | Node 22 / undici          | Bun 1.3.14                                   |
+ * |---------------|---------------------------|----------------------------------------------|
+ * | refused       | `TypeError: fetch failed` | `Error` `code: 'ConnectionRefused'`          |
+ * | DNS failure   | `TypeError: fetch failed` | `Error` `code: 'ConnectionRefused'`          |
+ * | reset         | `TypeError: fetch failed` | `Error` `code: 'ECONNRESET'`                 |
+ * | TLS rejected  | `TypeError: fetch failed` | `Error` `code: 'UNKNOWN_CERTIFICATE_…ERROR'` |
+ *
+ * So the test is the **evidence, not a list of dialect strings**: a string
+ * `code` is a runtime naming a transport-level failure. An allowlist of codes
+ * was written first and rejected — the TLS row alone would mean enumerating
+ * BoringSSL's certificate table, and a code nobody guessed is precisely the bug
+ * this closes. Two kinds of error are deliberately NOT caught: ordinary JS
+ * faults carry no `code` at all, and a `DOMException`'s is a **number**, so
+ * aborts and timeouts fall through to their own arms.
+ *
+ * The accepted trade: a caller's `TokenProvider` that throws a coded error
+ * (`ENOENT` from a keychain read) is typed `Network` rather than `Api`. Both
+ * are wrong for it, `Network` is the cheaper wrong — it says "nothing was
+ * exchanged", which is true, where `Api` claims a server answered.
+ */
+function isTransportFailure(cause) {
+    if (typeof cause.code === 'string')
+        return true;
+    // Spec runtimes put no code on the rejection itself. The message test is what
+    // keeps fetch's ARGUMENT errors out — `Failed to parse URL from …` is a
+    // caller's config mistake, not a transport failure.
+    return cause instanceof TypeError && cause.message.includes('fetch');
+}
 /**
  * Simple unified error class for both API and SDK
  */
@@ -197,9 +444,17 @@ export class ShipError extends Error {
                 }
             }
             else {
-                const text = await response.text();
-                if (text)
+                // A non-JSON body did not come from this platform — every API error
+                // is `ErrorResponse` JSON — so it is an intermediary's output, and
+                // the two kinds it produces need opposite treatment. A CDN's plain
+                // `error code: 1015` is the most useful thing there is to say. A
+                // proxy's HTML error page is a *document*, not a message: adopting it
+                // verbatim made a misconfigured `apiUrl` print 2,059 characters of
+                // markup as the error. Trust it only when it reads as a message.
+                const text = (await response.text()).trim();
+                if (text && !text.startsWith('<') && text.length <= MAX_FOREIGN_MESSAGE_LENGTH) {
                     message = text;
+                }
             }
         }
         catch {
@@ -243,7 +498,8 @@ export class ShipError extends Error {
      * Routing:
      * - Already a `ShipError` → returned as-is (caller's intent preserved)
      * - `AbortError` → `ShipError.cancelled(...)`
-     * - `TypeError` whose message mentions "fetch" → `ShipError.network(...)`
+     * - A transport failure → `ShipError.network(...)` — see `isTransportFailure`
+     *   for what each runtime offers as evidence
      * - Any other `Error` → `ShipError(Api, ...)` (no HTTP status — fetch never reached the server)
      * - Anything else (string, undefined, etc.) → `ShipError(Api, ...)`
      *
@@ -259,7 +515,7 @@ export class ShipError extends Error {
             if (cause.name === 'AbortError') {
                 return ShipError.cancelled(`${op} was cancelled`);
             }
-            if (cause instanceof TypeError && cause.message.includes('fetch')) {
+            if (isTransportFailure(cause)) {
                 return ShipError.network(`${op} failed: ${cause.message}`, { cause });
             }
             return new ShipError(ErrorType.Api, `${op} failed: ${cause.message}`);
@@ -317,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)`.
     /**
@@ -441,6 +709,125 @@ export function isBlockedExtension(filename) {
     return BLOCKED_EXTENSIONS.has(ext);
 }
 // =============================================================================
+// PICKER ACCEPT HINT
+// =============================================================================
+/**
+ * The extensions a browser file picker offers by default, grouped by role.
+ *
+ * Private on purpose: the only published form is `WEB_FILE_ACCEPT`, the
+ * attribute value itself. A published set would invite a call site to ask it
+ * whether a file is allowed — which is the one thing this list must never
+ * answer. See `WEB_FILE_ACCEPT`.
+ *
+ * Extensionless files (`LICENSE`, most `.well-known` entries) are inexpressible
+ * in `accept`, and reach a deployment by folder pick, ZIP, or drag-and-drop.
+ */
+const WEB_FILE_EXTENSIONS = [
+    // Markup & documents
+    'html',
+    'htm',
+    'xhtml',
+    'xml',
+    'txt',
+    'md',
+    'markdown',
+    'pdf',
+    'csv',
+    // Data & config
+    'json',
+    'jsonc',
+    'webmanifest',
+    'map',
+    'toml',
+    'yaml',
+    'yml',
+    'rss',
+    'atom',
+    // Styles
+    'css',
+    'scss',
+    'sass',
+    'less',
+    // Scripts & modules
+    'js',
+    'mjs',
+    'cjs',
+    'jsx',
+    'ts',
+    'tsx',
+    'wasm',
+    'vue',
+    'svelte',
+    // Images
+    'png',
+    'jpg',
+    'jpeg',
+    'gif',
+    'webp',
+    'avif',
+    'svg',
+    'ico',
+    'bmp',
+    'tif',
+    'tiff',
+    'heic',
+    'heif',
+    // Fonts
+    'woff',
+    'woff2',
+    'ttf',
+    'otf',
+    'eot',
+    // Audio
+    'mp3',
+    'wav',
+    'ogg',
+    'oga',
+    'opus',
+    'm4a',
+    'aac',
+    'flac',
+    'weba',
+    // Video
+    'mp4',
+    'webm',
+    'ogv',
+    'mov',
+    'm4v',
+    'avi',
+    // 3D models
+    'glb',
+    'gltf',
+    'usdz',
+    // Text tracks
+    'vtt',
+    'srt',
+    // Archive — a whole site in one file
+    'zip',
+];
+/**
+ * The `accept` attribute value for a browser file picker offering web files.
+ *
+ * **This is a hint, never a rule.** `BLOCKED_EXTENSIONS` is the platform's
+ * gate and the only thing that decides what may be hosted; this constant
+ * decides what a *file dialog* shows first. The two are not two halves of one
+ * policy, and this one must never be consulted to accept or reject a file.
+ *
+ * The distinction is structural, not stylistic. `accept` can express only an
+ * allowlist, while the platform's rule is a blocklist — so this list is
+ * necessarily *narrower* than what the platform hosts, and reading it as
+ * authority would reject files the platform serves happily. It is also not
+ * enforcement in the browser's own terms: every file dialog offers an
+ * all-files escape, and **drag-and-drop ignores `accept` entirely**. The
+ * dropzone and the picker must reach the same verdict on the same files, and
+ * they do — because the verdict is `validateFiles`, downstream of both.
+ *
+ * Kept beside `BLOCKED_EXTENSIONS` so one file holds both, which is what lets
+ * `tests/validation-constants.test.ts` fence the invariant that matters: the
+ * picker must never offer a file the platform will refuse.
+ */
+export const WEB_FILE_ACCEPT = WEB_FILE_EXTENSIONS.map((ext) => `.${ext}`).join(',');
+// =============================================================================
 // FILENAME CHARACTER VALIDATION
 // =============================================================================
 /**
@@ -499,6 +886,28 @@ export function hasUnbuiltMarker(filePath) {
 // that distinguish populations on the wire (API_KEY, DEPLOY_TOKEN, CALLER),
 // the single dispatch over them (TokenKind, classifyToken), and the
 // delegated-access scopes (OAuthScope).
+//
+// THE SHAPE LAW, in three clauses. Every secret the platform mints obeys it,
+// and `tests/validation-constants.test.ts` holds all three mechanically.
+//
+//  1. ONE ENTROPY STANDARD. Every minted random secret is `HEX_LENGTH` hex
+//     characters — one width for the whole platform, so "how long is a
+//     credential" has a single answer rather than one per population.
+//
+//  2. A PREFIX MARKS A SHARED SLOT, AND NOTHING ELSE. API keys and deploy
+//     tokens both arrive as `Authorization: Bearer`, so something must say
+//     which population a value belongs to: that is what the prefix IS, and
+//     `classifyToken` below is its only reader. Secrets that arrive somewhere
+//     unambiguous carry none — the deployment claim code reaches its own
+//     route in its own field, inside a URL whose path already says `/claim/`,
+//     so a prefix there would be a second name for what the route states.
+//
+//  3. NO PREFIX IS A PREFIX OF ANOTHER. This is what makes the dispatch
+//     order-independent, and it is the reason the populations are named on
+//     different axes (`ship-` for the product, `deploy-` for the capability)
+//     rather than sharing a stem. A `ship-` / `ship-deploy-` pair reads tidier
+//     and is a trap: every deploy token would also match the API-key branch,
+//     leaving correctness resting on the order of two `if`s.
 /**
  * Where human identity is mounted on the API host. The API mounts Better
  * Auth at this path (sign-in, sign-out, session reads, admin impersonation)
@@ -526,30 +935,35 @@ export const AuthMethod = {
     SYSTEM: 'system',
 };
 /**
- * Shape constants for API keys (`ship-{64 hex chars}`).
+ * Shape constants for API keys (`ship-{32 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
  */
 export const API_KEY = {
     /** Prefix that identifies an API key. */
     PREFIX: 'ship-',
     /** Number of hex characters following the prefix. */
-    HEX_LENGTH: 64,
-    /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 69`). */
-    TOTAL_LENGTH: 69,
+    HEX_LENGTH: 32,
+    /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 37`). */
+    TOTAL_LENGTH: 37,
     /** Number of trailing characters used to display a redacted hint (e.g. last 4). */
     HINT_LENGTH: 4,
 };
 /**
- * Shape constants for deploy tokens (`deploy-{64 hex chars}`).
+ * Shape constants for deploy tokens (`deploy-{32 hex chars}`).
  * Single source of truth used by validation utilities and auth middleware.
+ *
+ * Deliberately the same width as `API_KEY`: both are minted by one generator
+ * and classified by prefix alone, so a length that differed between them
+ * would be a second thing to know about a credential whose prefix already
+ * says what it is.
  */
 export const DEPLOY_TOKEN = {
     /** Prefix that identifies a deploy token. */
     PREFIX: 'deploy-',
     /** Number of hex characters following the prefix. */
-    HEX_LENGTH: 64,
-    /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 71`). */
-    TOTAL_LENGTH: 71,
+    HEX_LENGTH: 32,
+    /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 39`). */
+    TOTAL_LENGTH: 39,
 };
 /**
  * Shape constants for caller identifiers (the `X-Caller` instance-identity
@@ -622,6 +1036,26 @@ export const DEPLOYMENT_CONFIG_FILENAME = 'ship.json';
 export const SPA_DEFAULT_CONFIG = {
     rewrites: [{ source: '/(.*)', destination: '/index.html' }],
 };
+/**
+ * The `/spa-check` pre-flight's client-side envelope: which file is the
+ * check's subject, and how large it may be before a client skips the call.
+ *
+ * One fact with three holders until this export — the API's config declared
+ * the cap, the SDK's `checkSPA` hardcoded `100 * 1024`, and prose restated
+ * "100KB". `INDEX_FILE` is the selection rule (the file whose content rides
+ * `SPACheckRequest.index`), restated by every client that builds the request.
+ *
+ * Neither member is a validation boundary: a client over the cap simply
+ * skips the pre-flight, because the server answers an oversized index
+ * `isSPA: false` anyway. A consumer that cannot import this (n8n) needs no
+ * size copy at all — outcome parity is the server's, not the client's.
+ */
+export const SPA_CHECK_CONSTRAINTS = {
+    /** The file whose content is the check's subject. */
+    INDEX_FILE: 'index.html',
+    /** Skip the pre-flight above this size — the server would answer false. */
+    MAX_INDEX_BYTES: 100 * 1024,
+};
 /**
  * Assert that a ship.json file is *syntactically* loadable. Syntax only —
  * never schema.
@@ -764,6 +1198,50 @@ export function isDeployment(input) {
 // =============================================================================
 /** Default API URL if not otherwise configured. */
 export const DEFAULT_API = 'https://api.shipstatic.com';
+/**
+ * The Node SDK's ambient configuration pair — the ONLY environment variables
+ * the SDK reads, and therefore the COMPLETE list an embedding host must
+ * scrub (per `npm/ship`'s strict-isolation contract, scrubbing is the host's
+ * job, not the SDK's). A host that derives its scrub from this object's
+ * values — as the VS Code extension's child-process env block does — picks
+ * up a grown contract at the next pin bump instead of by remembered prose.
+ *
+ * Browser builds read no environment at all, and the CLI-only variables
+ * (`SHIP_PASSWORD`, `SHIP_VIA`) are deliberately NOT here: they are the
+ * CLI's operational levers, not the SDK's ambient contract — see
+ * `npm/ship/CLAUDE.md`, "CLI-only env vars".
+ */
+export const SHIP_ENV = {
+    /** The one credential slot — any platform token. */
+    TOKEN: 'SHIP_TOKEN',
+    /** The API endpoint override. */
+    API_URL: 'SHIP_API_URL',
+};
+/**
+ * Where a human creates an API key — the console deep link quoted by every
+ * surface that teaches authentication (the CLI's config wizard, the VS Code
+ * and n8n listings, the n8n rate-limit hint and credential copy). Written
+ * out in five files across three repos until this export.
+ *
+ * Production-branded by design: published artifacts name the product, never
+ * an environment (root `CLAUDE.md`, "Environment-Aware URLs").
+ */
+export const MY_API_KEY_URL = 'https://my.shipstatic.com/api-key';
+/**
+ * How long an anonymous deployment lives before it expires.
+ *
+ * The lifetime of the public tier, and one fact with several readers. The API
+ * stamps a deployment's `expires` from it and gives a claim code exactly the
+ * same window — a live site with a dead claim link is a coherence bug, so the
+ * two are one constant rather than two that agree. Both MCP transports quote
+ * the duration in prose an agent reads, and derive it from here rather than
+ * writing it out, which they did in eight places until this export existed.
+ *
+ * Seconds, spelled in the name: this platform has both second- and
+ * millisecond-valued durations, and the pair is only safe when each says which
+ * it is.
+ */
+export const PUBLIC_DEPLOYMENT_TTL_SECONDS = 3 * 24 * 60 * 60;
 // =============================================================================
 // FILE UPLOAD TYPES
 // =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "2.5.0-beta.9",
+  "version": "2.6.0",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,6 +13,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "prepack": "pnpm run build",
     "clean": "rm -rf dist",
     "test": "vitest",
     "lint": "biome check .",
@@ -47,5 +48,9 @@
     "@types/node": "^24.13.3",
     "typescript": "^5.9.3",
     "vitest": "^2.1.9"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
   }
 }