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

package/dist/index.js

@@ -14,6 +14,83 @@ 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',
+};
+/**
+ * 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 +108,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
 // =============================================================================
@@ -59,7 +198,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',
@@ -100,11 +247,26 @@ const CLIENT_ONLY_ERROR_TYPES = new Set([
  * union so `.has(error.type)` accepts any value from the union.
  */
 const ERROR_CATEGORIES = {
+    /**
+     * Client-attributable types. Exhaustive over the 4xx-carrying types, and
+     * 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,
+        ErrorType.NotFound,
+        ErrorType.RateLimit,
         ErrorType.Validation,
     ]),
     network: new Set([ErrorType.Network]),
@@ -118,6 +280,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
  */
@@ -189,9 +395,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 {
@@ -235,7 +449,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, ...)`
      *
@@ -251,7 +466,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}`);
@@ -309,10 +524,24 @@ export class ShipError extends Error {
     static api(message, status = 500, details) {
         return new ShipError(ErrorType.Api, message, status, details);
     }
-    // Semantic-category type guards. For specific-type checks, use
+    // Semantic-category guards. For specific-type checks, use
     // `error.type === ErrorType.X` directly or the generic `isType(t)`.
+    /**
+     * The caller is at fault — by HTTP's own definition of a 4xx, or by a type
+     * that is client-attributable without ever having a status (`Config`,
+     * `File`, raised locally by the SDK).
+     *
+     * Both arms are load-bearing, because type and status are independent
+     * axes. `fromHttpResponse` trusts `body.error` only when it names a
+     * server-producible type; a non-OK response without one is status-derived,
+     * so a CDN 404 or any intermediary error arrives as `Api` — a server-fault
+     * *type* carrying a client *status*. Judging by type alone would report it
+     * as a platform failure and bury the server's own message.
+     */
     isClientError() {
-        return ERROR_CATEGORIES.client.has(this.type);
+        if (ERROR_CATEGORIES.client.has(this.type))
+            return true;
+        return this.status !== undefined && this.status >= 400 && this.status < 500;
     }
     isNetworkError() {
         return ERROR_CATEGORIES.network.has(this.type);
@@ -419,6 +648,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
 // =============================================================================
 /**
@@ -600,6 +948,52 @@ export const DEPLOYMENT_CONFIG_FILENAME = 'ship.json';
 export const SPA_DEFAULT_CONFIG = {
     rewrites: [{ source: '/(.*)', destination: '/index.html' }],
 };
+/**
+ * Assert that a ship.json file is *syntactically* loadable. Syntax only —
+ * never schema.
+ *
+ * ship.json is validated and compiled on the server, deliberately: the schema
+ * and the compiler evolve, and a client that judged them would reject configs
+ * a newer platform accepts. That reasoning bounds what a client may check to
+ * the properties which are true of *every* past and future schema:
+ *
+ *   1. it parses as JSON — JSON syntax is frozen (RFC 8259), so text that
+ *      does not parse can never be a valid config;
+ *   2. its top level is an object — ship.json is `{ ... }` in every version.
+ *
+ * Both are monotonic: neither can ever reject something the server would
+ * accept. Everything beyond them (field names, types, rule semantics, which
+ * keys are permitted) stays server-side, where it can change.
+ *
+ * The payoff is the common case. Hand-edited JSON fails on a trailing comma,
+ * a `//` comment, single quotes, unquoted keys, or smart quotes pasted from
+ * documentation — mistakes that otherwise cost a full upload round-trip to
+ * discover. A UTF-8 BOM (Windows editors, PowerShell redirects) is stripped
+ * before parsing rather than rejected, because the server accepts it too;
+ * diverging there would reintroduce exactly the false rejection this
+ * function exists to avoid.
+ *
+ * @throws {ShipError} `ErrorType.Config` — the same type the server's own
+ * config rejection carries, so the error contract is identical wherever the
+ * failure is detected.
+ */
+export function assertShipJsonSyntax(text) {
+    const withoutBom = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    let parsed;
+    try {
+        parsed = JSON.parse(withoutBom);
+    }
+    catch (error) {
+        throw ShipError.config(`invalid JSON format in config: ${error.message}`, {
+            filePath: DEPLOYMENT_CONFIG_FILENAME,
+        });
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw ShipError.config(`${DEPLOYMENT_CONFIG_FILENAME} must contain a JSON object`, {
+            filePath: DEPLOYMENT_CONFIG_FILENAME,
+        });
+    }
+}
 // =============================================================================
 // VALIDATION UTILITIES
 // =============================================================================
@@ -696,6 +1090,21 @@ export function isDeployment(input) {
 // =============================================================================
 /** Default API URL if not otherwise configured. */
 export const DEFAULT_API = 'https://api.shipstatic.com';
+/**
+ * How long an anonymous deployment lives before it expires.
+ *
+ * The lifetime of the public tier, and one fact with several readers. The API
+ * stamps a deployment's `expires` from it and gives a claim code exactly the
+ * same window — a live site with a dead claim link is a coherence bug, so the
+ * two are one constant rather than two that agree. Both MCP transports quote
+ * the duration in prose an agent reads, and derive it from here rather than
+ * writing it out, which they did in eight places until this export existed.
+ *
+ * Seconds, spelled in the name: this platform has both second- and
+ * millisecond-valued durations, and the pair is only safe when each says which
+ * it is.
+ */
+export 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.2",
+  "version": "2.5.0-beta.20",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,7 @@
     "lint": "biome check .",
     "format": "biome format --write .",
     "prepare": "git config core.hooksPath scripts/githooks",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc -p tsconfig.check.json --noEmit"
   },
   "packageManager": "pnpm@10.12.4",
   "files": [
@@ -44,8 +44,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.5",
-    "@types/node": "^24.10.9",
+    "@types/node": "^24.13.3",
     "typescript": "^5.9.3",
-    "vitest": "^2.1.8"
+    "vitest": "^2.1.9"
   }
 }