@shipstatic/types 2.7.0-beta.3 → 2.7.0

package/dist/index.d.ts

@@ -671,6 +671,12 @@ export declare const DEPLOY_FIELDS: {
     readonly VIA: "via";
     /** Plaintext password — the API hashes it server-side. */
     readonly PASSWORD: "password";
+    /**
+     * Requested lifetime in SECONDS — a duration, never an instant. The API
+     * computes and stores the expiry, so the wire carries no client clock.
+     * See {@link validateTtl}.
+     */
+    readonly TTL: "ttl";
     /** @internal Server-processing flag — first-party `/upload` only. */
     readonly BUILD: "build";
     /** @internal Server-processing flag — first-party `/upload` only. */
@@ -1259,6 +1265,47 @@ export declare function validateApiUrl(apiUrl: string): void;
  * Example: "happy-cat-abc1234.shipstatic.com"
  */
 export declare function isDeployment(input: string): boolean;
+/**
+ * The envelope a requested lifetime must fit — one word, one grammar, wherever
+ * the platform lets a caller choose how long something lives.
+ *
+ * Two resources wear it: `TokenCreateOptions.ttl` and
+ * `DeploymentUploadOptions.ttl`. It lives here rather than on the server by
+ * the format-vs-policy rule — a client can decide offline whether a duration
+ * is well-formed, and the API rejects the same value the same way. What is
+ * NOT here is any per-plan ceiling: no such policy exists, and one delivered
+ * speculatively through `/limits` would be an owner for a decision nobody has
+ * made.
+ */
+export declare const TTL_CONSTRAINTS: {
+    /**
+     * Shortest requestable lifetime, in seconds. One rather than zero: a
+     * deployment that expires the instant it is created is not a shorter lease,
+     * it is a deploy that was never live, and `0` is how an unset variable
+     * arrives.
+     */
+    readonly MIN_SECONDS: 1;
+    /** Longest requestable lifetime, in seconds — one year. */
+    readonly MAX_SECONDS: number;
+};
+/**
+ * Validate a requested lifetime in SECONDS and return it, or `undefined` when
+ * none was asked for.
+ *
+ * **A duration, never an instant.** The caller says how long; the server owns
+ * what time it is and stamps the expiry — so a client's clock, however wrong,
+ * cannot shorten or extend a lease. That is the tokens precedent, and it is
+ * why this rule measures a count of seconds rather than checking a timestamp
+ * against `now`.
+ *
+ * Fractions are refused rather than rounded: a caller who wrote `1.5` meant
+ * something the wire cannot carry, and silently choosing `1` or `2` for them
+ * is a decision the platform has no standing to make.
+ *
+ * Single source of truth shared by the API (the tokens route and the deploy
+ * schema), the SDK's request boundary, and the CLI's parser.
+ */
+export declare function validateTtl(value: unknown): number | undefined;
 /**
  * Request payload for SPA check endpoint
  */
@@ -1391,6 +1438,27 @@ export interface DeploymentUploadOptions {
      * into missing analytics rather than an error. See {@link DeploymentVia}.
      */
     via?: DeploymentViaType;
+    /**
+     * Seconds until this deployment expires; omit for one that never does.
+     *
+     * The platform reclaims it when the time is up — an ephemeral deployment,
+     * chosen by the deployer rather than by the identity. The same word and the
+     * same grammar as {@link TokenCreateOptions.ttl}, bounded by
+     * {@link TTL_CONSTRAINTS}.
+     *
+     * **Requires a credential.** An anonymous deploy has no deployer, and the
+     * platform owns anonymous lifetime as policy
+     * ({@link PUBLIC_DEPLOYMENT_TTL_SECONDS}) — so a ttl on one is refused
+     * rather than honoured or ignored.
+     *
+     * **A deployment carrying one cannot be linked to a domain.** A domain is a
+     * commitment and a deadline is its opposite; the API refuses the link, which
+     * is what keeps the reaper from tearing a live domain's target away.
+     *
+     * Immutable, like every other field of a deployment: to keep something
+     * longer, redeploy.
+     */
+    ttl?: number;
     /**
      * Optional password that protects this deployment.
      *

package/dist/index.js

@@ -214,6 +214,12 @@ export const DEPLOY_FIELDS = {
     VIA: 'via',
     /** Plaintext password — the API hashes it server-side. */
     PASSWORD: 'password',
+    /**
+     * Requested lifetime in SECONDS — a duration, never an instant. The API
+     * computes and stores the expiry, so the wire carries no client clock.
+     * See {@link validateTtl}.
+     */
+    TTL: 'ttl',
     /** @internal Server-processing flag — first-party `/upload` only. */
     BUILD: 'build',
     /** @internal Server-processing flag — first-party `/upload` only. */
@@ -415,9 +421,24 @@ const MAX_FOREIGN_MESSAGE_LENGTH = 200;
  * that runtime (`cloudflare/mcp`) reaches the API through a service BINDING,
  * which is in-process and does not produce transport rejections at all.
  *
- * The accepted trade is unchanged: 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.
+ * **The `TokenProvider` case stopped being a trade when clients gained
+ * retries.** A caller's provider that throws a coded error is typed `Network`
+ * here, which was recorded as "both are wrong for it; `Network` is the cheaper
+ * wrong" — written when the classification decided only what a surface would
+ * SAY. It now also decides whether the call is retried, and that turns the
+ * cheaper wrong into the right answer: a `TokenProvider` is where minting and
+ * refresh live, so the common one is an OAuth refresh over the network, and a
+ * transient failure there is precisely what another attempt repairs.
+ *
+ * The residual cost is a deterministic provider fault — a genuinely missing
+ * keychain entry — invoking the provider three times over a few hundred
+ * milliseconds before failing with the same error. No request leaves the
+ * process on any of them. That is the cheap direction of a bet whose other
+ * side is a refused deploy, and suppressing it would need a way to mark
+ * credential faults non-retryable: machinery with one holder, refused by the
+ * estate's stopping rule. Provider failures that carry no code are `Api` and
+ * are not retried at all, and a provider yielding nothing is `Authentication`
+ * by the fail-closed invariant, which is likewise terminal.
  */
 function isTransportFailure(cause) {
     const code = cause.code;
@@ -1311,6 +1332,60 @@ export function validateApiUrl(apiUrl) {
 export function isDeployment(input) {
     return /^[a-z]+-[a-z]+-[a-z0-9]{7}(\.[a-z0-9.-]+)?$/i.test(input);
 }
+/**
+ * The envelope a requested lifetime must fit — one word, one grammar, wherever
+ * the platform lets a caller choose how long something lives.
+ *
+ * Two resources wear it: `TokenCreateOptions.ttl` and
+ * `DeploymentUploadOptions.ttl`. It lives here rather than on the server by
+ * the format-vs-policy rule — a client can decide offline whether a duration
+ * is well-formed, and the API rejects the same value the same way. What is
+ * NOT here is any per-plan ceiling: no such policy exists, and one delivered
+ * speculatively through `/limits` would be an owner for a decision nobody has
+ * made.
+ */
+export const TTL_CONSTRAINTS = {
+    /**
+     * Shortest requestable lifetime, in seconds. One rather than zero: a
+     * deployment that expires the instant it is created is not a shorter lease,
+     * it is a deploy that was never live, and `0` is how an unset variable
+     * arrives.
+     */
+    MIN_SECONDS: 1,
+    /** Longest requestable lifetime, in seconds — one year. */
+    MAX_SECONDS: 365 * 24 * 60 * 60,
+};
+/**
+ * Validate a requested lifetime in SECONDS and return it, or `undefined` when
+ * none was asked for.
+ *
+ * **A duration, never an instant.** The caller says how long; the server owns
+ * what time it is and stamps the expiry — so a client's clock, however wrong,
+ * cannot shorten or extend a lease. That is the tokens precedent, and it is
+ * why this rule measures a count of seconds rather than checking a timestamp
+ * against `now`.
+ *
+ * Fractions are refused rather than rounded: a caller who wrote `1.5` meant
+ * something the wire cannot carry, and silently choosing `1` or `2` for them
+ * is a decision the platform has no standing to make.
+ *
+ * Single source of truth shared by the API (the tokens route and the deploy
+ * schema), the SDK's request boundary, and the CLI's parser.
+ */
+export function validateTtl(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw ShipError.validation('TTL must be a number of seconds');
+    }
+    if (!Number.isInteger(value)) {
+        throw ShipError.validation('TTL must be a whole number of seconds');
+    }
+    if (value < TTL_CONSTRAINTS.MIN_SECONDS || value > TTL_CONSTRAINTS.MAX_SECONDS) {
+        throw ShipError.validation(`TTL must be between ${TTL_CONSTRAINTS.MIN_SECONDS} and ${TTL_CONSTRAINTS.MAX_SECONDS} seconds`);
+    }
+    return value;
+}
 // =============================================================================
 // PLATFORM CONSTANTS
 // =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "2.7.0-beta.3",
+  "version": "2.7.0",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",
@@ -41,7 +41,7 @@
     "url": "https://github.com/shipstatic/types/issues"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=20.19.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.5",

package/src/index.ts

@@ -756,6 +756,12 @@ export const DEPLOY_FIELDS = {
   VIA: 'via',
   /** Plaintext password — the API hashes it server-side. */
   PASSWORD: 'password',
+  /**
+   * Requested lifetime in SECONDS — a duration, never an instant. The API
+   * computes and stores the expiry, so the wire carries no client clock.
+   * See {@link validateTtl}.
+   */
+  TTL: 'ttl',
   /** @internal Server-processing flag — first-party `/upload` only. */
   BUILD: 'build',
   /** @internal Server-processing flag — first-party `/upload` only. */
@@ -968,9 +974,24 @@ const MAX_FOREIGN_MESSAGE_LENGTH = 200;
  * that runtime (`cloudflare/mcp`) reaches the API through a service BINDING,
  * which is in-process and does not produce transport rejections at all.
  *
- * The accepted trade is unchanged: 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.
+ * **The `TokenProvider` case stopped being a trade when clients gained
+ * retries.** A caller's provider that throws a coded error is typed `Network`
+ * here, which was recorded as "both are wrong for it; `Network` is the cheaper
+ * wrong" — written when the classification decided only what a surface would
+ * SAY. It now also decides whether the call is retried, and that turns the
+ * cheaper wrong into the right answer: a `TokenProvider` is where minting and
+ * refresh live, so the common one is an OAuth refresh over the network, and a
+ * transient failure there is precisely what another attempt repairs.
+ *
+ * The residual cost is a deterministic provider fault — a genuinely missing
+ * keychain entry — invoking the provider three times over a few hundred
+ * milliseconds before failing with the same error. No request leaves the
+ * process on any of them. That is the cheap direction of a bet whose other
+ * side is a refused deploy, and suppressing it would need a way to mark
+ * credential faults non-retryable: machinery with one holder, refused by the
+ * estate's stopping rule. Provider failures that carry no code are `Api` and
+ * are not retried at all, and a provider yielding nothing is `Authentication`
+ * by the fail-closed invariant, which is likewise terminal.
  */
 function isTransportFailure(cause: Error): boolean {
   const code = (cause as { code?: unknown }).code;
@@ -2033,6 +2054,63 @@ export function isDeployment(input: string): boolean {
   return /^[a-z]+-[a-z]+-[a-z0-9]{7}(\.[a-z0-9.-]+)?$/i.test(input);
 }
 
+/**
+ * The envelope a requested lifetime must fit — one word, one grammar, wherever
+ * the platform lets a caller choose how long something lives.
+ *
+ * Two resources wear it: `TokenCreateOptions.ttl` and
+ * `DeploymentUploadOptions.ttl`. It lives here rather than on the server by
+ * the format-vs-policy rule — a client can decide offline whether a duration
+ * is well-formed, and the API rejects the same value the same way. What is
+ * NOT here is any per-plan ceiling: no such policy exists, and one delivered
+ * speculatively through `/limits` would be an owner for a decision nobody has
+ * made.
+ */
+export const TTL_CONSTRAINTS = {
+  /**
+   * Shortest requestable lifetime, in seconds. One rather than zero: a
+   * deployment that expires the instant it is created is not a shorter lease,
+   * it is a deploy that was never live, and `0` is how an unset variable
+   * arrives.
+   */
+  MIN_SECONDS: 1,
+  /** Longest requestable lifetime, in seconds — one year. */
+  MAX_SECONDS: 365 * 24 * 60 * 60,
+} as const;
+
+/**
+ * Validate a requested lifetime in SECONDS and return it, or `undefined` when
+ * none was asked for.
+ *
+ * **A duration, never an instant.** The caller says how long; the server owns
+ * what time it is and stamps the expiry — so a client's clock, however wrong,
+ * cannot shorten or extend a lease. That is the tokens precedent, and it is
+ * why this rule measures a count of seconds rather than checking a timestamp
+ * against `now`.
+ *
+ * Fractions are refused rather than rounded: a caller who wrote `1.5` meant
+ * something the wire cannot carry, and silently choosing `1` or `2` for them
+ * is a decision the platform has no standing to make.
+ *
+ * Single source of truth shared by the API (the tokens route and the deploy
+ * schema), the SDK's request boundary, and the CLI's parser.
+ */
+export function validateTtl(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw ShipError.validation('TTL must be a number of seconds');
+  }
+  if (!Number.isInteger(value)) {
+    throw ShipError.validation('TTL must be a whole number of seconds');
+  }
+  if (value < TTL_CONSTRAINTS.MIN_SECONDS || value > TTL_CONSTRAINTS.MAX_SECONDS) {
+    throw ShipError.validation(
+      `TTL must be between ${TTL_CONSTRAINTS.MIN_SECONDS} and ${TTL_CONSTRAINTS.MAX_SECONDS} seconds`,
+    );
+  }
+  return value;
+}
+
 // =============================================================================
 // SPA CHECK TYPES
 // =============================================================================
@@ -2190,6 +2268,27 @@ export interface DeploymentUploadOptions {
    * into missing analytics rather than an error. See {@link DeploymentVia}.
    */
   via?: DeploymentViaType;
+  /**
+   * Seconds until this deployment expires; omit for one that never does.
+   *
+   * The platform reclaims it when the time is up — an ephemeral deployment,
+   * chosen by the deployer rather than by the identity. The same word and the
+   * same grammar as {@link TokenCreateOptions.ttl}, bounded by
+   * {@link TTL_CONSTRAINTS}.
+   *
+   * **Requires a credential.** An anonymous deploy has no deployer, and the
+   * platform owns anonymous lifetime as policy
+   * ({@link PUBLIC_DEPLOYMENT_TTL_SECONDS}) — so a ttl on one is refused
+   * rather than honoured or ignored.
+   *
+   * **A deployment carrying one cannot be linked to a domain.** A domain is a
+   * commitment and a deadline is its opposite; the API refuses the link, which
+   * is what keeps the reaper from tearing a live domain's target away.
+   *
+   * Immutable, like every other field of a deployment: to keep something
+   * longer, redeploy.
+   */
+  ttl?: number;
   /**
    * Optional password that protects this deployment.
    *