@shipstatic/types 2.5.0-beta.12 → 2.5.0-beta.14

package/README.md

@@ -127,6 +127,7 @@ import type {
 import {
   validateApiKey,
   validateDeployToken,
+  validateIdempotencyKey,
   validateApiUrl,
   isDeployment,
   isBlockedExtension,

package/dist/index.d.ts

@@ -52,11 +52,24 @@ export interface DeploymentCreateResponse extends Deployment {
 /**
  * Every path the public API answers on, declared once.
  *
- * The URL surface used to be 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. Here it is one table that the producer
- * mounts from and the consumers request against, which is the only way a
- * path and its handler cannot drift apart.
+ * 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
@@ -293,6 +306,24 @@ export interface DomainRecordsResponse {
     /** Required DNS records for configuration */
     records: DnsRecord[];
 }
+/**
+ * The envelope an `Idempotency-Key` must fit, and how long a replay lasts.
+ *
+ * Format lives here rather than on the server alone by the format-vs-policy
+ * rule: a client can decide offline whether a key is well-formed, and the
+ * API would reject the same value the same way.
+ */
+export declare const IDEMPOTENCY_KEY_CONSTRAINTS: {
+    readonly MAX_LENGTH: 256;
+    /** How long a stored 201 stays replayable. */
+    readonly WINDOW_SECONDS: number;
+};
+/**
+ * Validate an idempotency key, returning the trimmed value or `undefined`
+ * when none was supplied. Throws {@link ShipError.validation} when the value
+ * cannot be sent — the same verdict the API would reach, reached earlier.
+ */
+export declare function validateIdempotencyKey(value: unknown): string | undefined;
 /**
  * Response for `GET /labels` — every label in use across the caller's
  * deployments, domains and tokens, grouped and ordered by last use.
@@ -1029,6 +1060,25 @@ export interface DeploymentUploadOptions {
     spa?: boolean;
     /** @internal reCAPTCHA proof for the anonymous human deploy channel. Only available via /upload endpoint. */
     captcha?: string;
+    /**
+     * Makes this deploy replayable instead of repeatable.
+     *
+     * A deploy is not naturally idempotent: a client-side timeout on a slow
+     * one leaves the caller unable to tell "it never landed" from "it landed
+     * and the response was lost", and retrying produces a second deployment.
+     * Send the same key on the retry and the platform replays the original
+     * 201 verbatim rather than creating anything
+     * ({@link IDEMPOTENCY_KEY_CONSTRAINTS.WINDOW_SECONDS}).
+     *
+     * **Agents are the audience.** A human notices a duplicate; an automated
+     * retry does not. Pick a key that identifies the ATTEMPT — a run id, a
+     * commit sha, a uuid minted before the first try — never one that varies
+     * per attempt, which would defeat the point.
+     *
+     * The replay is per-caller, and it stores successes only: a failed deploy
+     * retries fresh under the same key.
+     */
+    idempotencyKey?: string;
 }
 /**
  * Pagination options for every list endpoint. The response's `cursor` feeds

package/dist/index.js

@@ -17,11 +17,24 @@ export const DeploymentStatus = {
 /**
  * Every path the public API answers on, declared once.
  *
- * The URL surface used to be 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. Here it is one table that the producer
- * mounts from and the consumers request against, which is the only way a
- * path and its handler cannot drift apart.
+ * 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
@@ -74,6 +87,38 @@ export const DomainStatus = {
     SUCCESS: 'success',
     PAUSED: 'paused',
 };
+/**
+ * The envelope an `Idempotency-Key` must fit, and how long a replay lasts.
+ *
+ * Format lives here rather than on the server alone by the format-vs-policy
+ * rule: a client can decide offline whether a key is well-formed, and the
+ * API would reject the same value the same way.
+ */
+export const IDEMPOTENCY_KEY_CONSTRAINTS = {
+    MAX_LENGTH: 256,
+    /** How long a stored 201 stays replayable. */
+    WINDOW_SECONDS: 24 * 60 * 60,
+};
+/**
+ * Validate an idempotency key, returning the trimmed value or `undefined`
+ * when none was supplied. Throws {@link ShipError.validation} when the value
+ * cannot be sent — the same verdict the API would reach, reached earlier.
+ */
+export function validateIdempotencyKey(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw ShipError.validation('Idempotency key must be a string.');
+    }
+    const key = value.trim();
+    if (!key) {
+        throw ShipError.validation('Idempotency key must not be empty.');
+    }
+    if (key.length > IDEMPOTENCY_KEY_CONSTRAINTS.MAX_LENGTH) {
+        throw ShipError.validation(`Idempotency key must be at most ${IDEMPOTENCY_KEY_CONSTRAINTS.MAX_LENGTH} characters.`);
+    }
+    return key;
+}
 // =============================================================================
 // ACCOUNT TYPES
 // =============================================================================
@@ -169,6 +214,14 @@ 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;
 /**
  * Simple unified error class for both API and SDK
  */
@@ -240,9 +293,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 {

package/package.json

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

package/src/index.ts

@@ -61,11 +61,24 @@ export interface DeploymentCreateResponse extends Deployment {
 /**
  * Every path the public API answers on, declared once.
  *
- * The URL surface used to be 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. Here it is one table that the producer
- * mounts from and the consumers request against, which is the only way a
- * path and its handler cannot drift apart.
+ * 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
@@ -324,6 +337,41 @@ export interface DomainRecordsResponse {
   records: DnsRecord[];
 }
 
+/**
+ * The envelope an `Idempotency-Key` must fit, and how long a replay lasts.
+ *
+ * Format lives here rather than on the server alone by the format-vs-policy
+ * rule: a client can decide offline whether a key is well-formed, and the
+ * API would reject the same value the same way.
+ */
+export const IDEMPOTENCY_KEY_CONSTRAINTS = {
+  MAX_LENGTH: 256,
+  /** How long a stored 201 stays replayable. */
+  WINDOW_SECONDS: 24 * 60 * 60,
+} as const;
+
+/**
+ * Validate an idempotency key, returning the trimmed value or `undefined`
+ * when none was supplied. Throws {@link ShipError.validation} when the value
+ * cannot be sent — the same verdict the API would reach, reached earlier.
+ */
+export function validateIdempotencyKey(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'string') {
+    throw ShipError.validation('Idempotency key must be a string.');
+  }
+  const key = value.trim();
+  if (!key) {
+    throw ShipError.validation('Idempotency key must not be empty.');
+  }
+  if (key.length > IDEMPOTENCY_KEY_CONSTRAINTS.MAX_LENGTH) {
+    throw ShipError.validation(
+      `Idempotency key must be at most ${IDEMPOTENCY_KEY_CONSTRAINTS.MAX_LENGTH} characters.`,
+    );
+  }
+  return key;
+}
+
 /**
  * Response for `GET /labels` — every label in use across the caller's
  * deployments, domains and tokens, grouped and ordered by last use.
@@ -654,6 +702,15 @@ const SERVER_PRODUCIBLE_ERROR_TYPES = new Set<string>(
   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;
+
 /**
  * Standard error response format used everywhere
  */
@@ -740,8 +797,17 @@ export class ShipError extends Error {
           }
         }
       } else {
-        const text = await response.text();
-        if (text) message = 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 {
       // Body unreadable; fall through to operationName-derived message.
@@ -1534,6 +1600,25 @@ export interface DeploymentUploadOptions {
   spa?: boolean;
   /** @internal reCAPTCHA proof for the anonymous human deploy channel. Only available via /upload endpoint. */
   captcha?: string;
+  /**
+   * Makes this deploy replayable instead of repeatable.
+   *
+   * A deploy is not naturally idempotent: a client-side timeout on a slow
+   * one leaves the caller unable to tell "it never landed" from "it landed
+   * and the response was lost", and retrying produces a second deployment.
+   * Send the same key on the retry and the platform replays the original
+   * 201 verbatim rather than creating anything
+   * ({@link IDEMPOTENCY_KEY_CONSTRAINTS.WINDOW_SECONDS}).
+   *
+   * **Agents are the audience.** A human notices a duplicate; an automated
+   * retry does not. Pick a key that identifies the ATTEMPT — a run id, a
+   * commit sha, a uuid minted before the first try — never one that varies
+   * per attempt, which would defeat the point.
+   *
+   * The replay is per-caller, and it stores successes only: a failed deploy
+   * retries fresh under the same key.
+   */
+  idempotencyKey?: string;
 }
 
 /**