@shipstatic/types 2.5.0-beta.1 → 2.5.0-beta.10

package/dist/index.d.ts

@@ -49,16 +49,30 @@ export interface DeploymentCreateResponse extends Deployment {
     /** Claim URL for public deployments. Present when deployed without credentials. */
     readonly claim?: string;
 }
+/**
+ * The half of a list response that is identical on every list.
+ *
+ * `GET /<collection>` answers exactly two fields — the collection under its
+ * own plural noun, and this cursor — so the cursor is declared once here and
+ * each response below adds only its noun. `cursor: null` means last page and
+ * is the ENTIRE has-more signal, which is why there is no `has_more`.
+ *
+ * There is deliberately no `total`. A count is an aggregate over a
+ * collection, not a property of a page; producing one would cost a COUNT
+ * beside every page read, which is precisely what keyset pagination exists
+ * to avoid. Counts live on the resource that summarises the collection —
+ * `GET /account`'s `usage` for one caller, `GET /admin/stats` platform-wide.
+ */
+export interface ListResponse {
+    /** Opaque cursor from this page; `null` on the last page. */
+    cursor: string | null;
+}
 /**
  * Response for listing deployments
  */
-export interface DeploymentListResponse {
+export interface DeploymentListResponse extends ListResponse {
     /** Array of deployments */
     deployments: Deployment[];
-    /** Cursor for pagination, null if no more pages */
-    cursor: string | null;
-    /** Total number of deployments */
-    total: number;
 }
 /**
  * Domain status constants
@@ -91,7 +105,7 @@ export interface Domain {
     labels: string[];
     /** Unix timestamp (seconds) when domain was created */
     readonly created: number;
-    /** When deployment was last linked (Unix timestamp), null if never linked */
+    /** Unix timestamp (seconds) when deployment was last linked, null if never linked */
     linked: number | null;
     /** Total deployment links */
     links: number;
@@ -113,13 +127,9 @@ export interface DomainSetResult extends Domain {
 /**
  * Response for listing domains
  */
-export interface DomainListResponse {
+export interface DomainListResponse extends ListResponse {
     /** Array of domains */
     domains: Domain[];
-    /** Cursor for pagination, null if no more pages */
-    cursor: string | null;
-    /** Total number of domains */
-    total: number;
 }
 /**
  * DNS record types supported for domain configuration
@@ -179,11 +189,13 @@ export interface DomainValidateResponse {
     error: string | null;
 }
 /**
- * Token as returned by the list endpoint.
- * The secret is shown once at creation and never again — listings carry
- * only the management identifier and lifecycle metadata.
+ * Core deploy token object - used in both API responses and SDK.
+ *
+ * The secret is never here: it is shown once at creation
+ * ({@link TokenCreateResponse.secret}) and never again, so an entity read
+ * carries only the management identifier and lifecycle metadata.
  */
-export interface TokenListItem {
+export interface Token {
     /** 7-char management identifier (e.g., "a1b2c3d") */
     readonly token: string;
     /** Labels for categorization and filtering. Always present, empty array when none. */
@@ -198,24 +210,19 @@ export interface TokenListItem {
 /**
  * Response for listing tokens
  */
-export interface TokenListResponse {
-    /** Array of tokens (security-redacted for list display) */
-    tokens: TokenListItem[];
-    /** Total number of tokens */
-    total: number;
+export interface TokenListResponse extends ListResponse {
+    /** Array of tokens (the secret is never among them) */
+    tokens: Token[];
 }
 /**
- * Response for token creation
+ * Response from token creation. Extends Token with the one field that
+ * exists only on creation — the same shape as
+ * {@link DeploymentCreateResponse}, because a 201 returns the resource it
+ * created plus whatever is knowable only once.
  */
-export interface TokenCreateResponse {
-    /** 7-char management identifier */
-    token: string;
+export interface TokenCreateResponse extends Token {
     /** The raw credential value (shown once at creation, then never again) */
-    secret: string;
-    /** Labels for categorization and filtering. Always present, empty array when none. */
-    labels: string[];
-    /** Unix timestamp (seconds) when token expires, null for never */
-    expires: number | null;
+    readonly secret: string;
 }
 /**
  * Account plan constants
@@ -232,10 +239,34 @@ export declare const AccountPlan: {
 export type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
 /**
  * Account usage metrics — always available regardless of billing provider.
+ *
+ * This is where a caller's own totals live. Lists answer pages and carry no
+ * `total` (see {@link ListOptions}); a count is an aggregate over a
+ * collection, so it belongs to the summary resource that owns the
+ * collection. `GET /account` is that resource for one caller, `GET
+ * /admin/stats` for the platform.
+ *
+ * The counted dimensions are the ones the plan caps — deployments and
+ * domains (`PlatformLimits`) — plus the billable custom-domain subset, so a
+ * surface can render "3 of 10" without a second request.
  */
 export interface AccountUsage {
     /** Number of active custom domains (excludes paused) */
     customDomains: number;
+    /**
+     * Deployments counted against the plan's deployment cap — every row
+     * whatever its status, because that is what the cap counts, so a surface
+     * renders "3 of 10" against the denominator the 403 divides by. (`GET
+     * /deployments` lists successful ones only; that is a different question
+     * asked of a different resource.) Optional by the additive-evolution law:
+     * an API predating this field omits it.
+     */
+    deployments?: number;
+    /**
+     * Domains counted against the plan's domain cap — every domain, platform
+     * and custom alike, unlike `customDomains`. Optional for the same reason.
+     */
+    domains?: number;
 }
 /**
  * Core account object - used in both API responses and SDK
@@ -421,6 +452,18 @@ 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 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(): boolean;
     isNetworkError(): boolean;
     isAuthError(): boolean;
@@ -645,6 +688,36 @@ export declare const SPA_DEFAULT_CONFIG: {
         readonly 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 declare function assertShipJsonSyntax(text: string): void;
 /**
  * Validate API key format
  */
@@ -770,10 +843,20 @@ export interface DeploymentUploadOptions {
     captcha?: string;
 }
 /**
- * Pagination options for the paginated list endpoints (`GET /deployments`,
- * `GET /domains`). The response's `cursor` feeds the next request; a `null`
- * cursor on the response means the last page. Omitting both returns the
- * server's default first page.
+ * 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. */
@@ -834,7 +917,7 @@ export interface TokenResource {
         ttl?: number;
         labels?: string[];
     }) => Promise<TokenCreateResponse>;
-    list: () => Promise<TokenListResponse>;
+    list: (options?: ListOptions) => Promise<TokenListResponse>;
     remove: (token: string) => Promise<void>;
 }
 /**
@@ -929,7 +1012,7 @@ export interface ActivityMeta {
 /**
  * Response from GET /activities endpoint
  */
-export interface ActivityListResponse {
+export interface ActivityListResponse extends ListResponse {
     /** Array of activities */
     activities: Activity[];
 }

package/dist/index.js

@@ -100,11 +100,19 @@ 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
+     * 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.
+     */
     client: new Set([
         ErrorType.Business,
         ErrorType.Config,
         ErrorType.File,
         ErrorType.Forbidden,
+        ErrorType.NotFound,
+        ErrorType.RateLimit,
         ErrorType.Validation,
     ]),
     network: new Set([ErrorType.Network]),
@@ -309,10 +317,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);
@@ -600,6 +622,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
 // =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "2.5.0-beta.1",
+  "version": "2.5.0-beta.10",
   "description": "Shared types for ShipStatic platform",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,16 @@
       "default": "./dist/index.js"
     }
   },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "prepare": "git config core.hooksPath scripts/githooks",
+    "typecheck": "tsc -p tsconfig.check.json --noEmit"
+  },
+  "packageManager": "pnpm@10.12.4",
   "files": [
     "dist",
     "src"
@@ -34,16 +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"
-  },
-  "scripts": {
-    "build": "tsc",
-    "clean": "rm -rf dist",
-    "test": "vitest",
-    "lint": "biome check .",
-    "format": "biome format --write .",
-    "typecheck": "tsc --noEmit"
+    "vitest": "^2.1.9"
   }
-}
+}

package/src/index.ts

@@ -58,16 +58,31 @@ export interface DeploymentCreateResponse extends Deployment {
   readonly claim?: string;
 }
 
+/**
+ * The half of a list response that is identical on every list.
+ *
+ * `GET /<collection>` answers exactly two fields — the collection under its
+ * own plural noun, and this cursor — so the cursor is declared once here and
+ * each response below adds only its noun. `cursor: null` means last page and
+ * is the ENTIRE has-more signal, which is why there is no `has_more`.
+ *
+ * There is deliberately no `total`. A count is an aggregate over a
+ * collection, not a property of a page; producing one would cost a COUNT
+ * beside every page read, which is precisely what keyset pagination exists
+ * to avoid. Counts live on the resource that summarises the collection —
+ * `GET /account`'s `usage` for one caller, `GET /admin/stats` platform-wide.
+ */
+export interface ListResponse {
+  /** Opaque cursor from this page; `null` on the last page. */
+  cursor: string | null;
+}
+
 /**
  * Response for listing deployments
  */
-export interface DeploymentListResponse {
+export interface DeploymentListResponse extends ListResponse {
   /** Array of deployments */
   deployments: Deployment[];
-  /** Cursor for pagination, null if no more pages */
-  cursor: string | null;
-  /** Total number of deployments */
-  total: number;
 }
 
 // =============================================================================
@@ -107,7 +122,7 @@ export interface Domain {
   labels: string[];
   /** Unix timestamp (seconds) when domain was created */
   readonly created: number;
-  /** When deployment was last linked (Unix timestamp), null if never linked */
+  /** Unix timestamp (seconds) when deployment was last linked, null if never linked */
   linked: number | null;
   /** Total deployment links */
   links: number;
@@ -131,13 +146,9 @@ export interface DomainSetResult extends Domain {
 /**
  * Response for listing domains
  */
-export interface DomainListResponse {
+export interface DomainListResponse extends ListResponse {
   /** Array of domains */
   domains: Domain[];
-  /** Cursor for pagination, null if no more pages */
-  cursor: string | null;
-  /** Total number of domains */
-  total: number;
 }
 
 /**
@@ -206,11 +217,13 @@ export interface DomainValidateResponse {
 // =============================================================================
 
 /**
- * Token as returned by the list endpoint.
- * The secret is shown once at creation and never again — listings carry
- * only the management identifier and lifecycle metadata.
+ * Core deploy token object - used in both API responses and SDK.
+ *
+ * The secret is never here: it is shown once at creation
+ * ({@link TokenCreateResponse.secret}) and never again, so an entity read
+ * carries only the management identifier and lifecycle metadata.
  */
-export interface TokenListItem {
+export interface Token {
   /** 7-char management identifier (e.g., "a1b2c3d") */
   readonly token: string;
   /** Labels for categorization and filtering. Always present, empty array when none. */
@@ -226,25 +239,20 @@ export interface TokenListItem {
 /**
  * Response for listing tokens
  */
-export interface TokenListResponse {
-  /** Array of tokens (security-redacted for list display) */
-  tokens: TokenListItem[];
-  /** Total number of tokens */
-  total: number;
+export interface TokenListResponse extends ListResponse {
+  /** Array of tokens (the secret is never among them) */
+  tokens: Token[];
 }
 
 /**
- * Response for token creation
+ * Response from token creation. Extends Token with the one field that
+ * exists only on creation — the same shape as
+ * {@link DeploymentCreateResponse}, because a 201 returns the resource it
+ * created plus whatever is knowable only once.
  */
-export interface TokenCreateResponse {
-  /** 7-char management identifier */
-  token: string;
+export interface TokenCreateResponse extends Token {
   /** The raw credential value (shown once at creation, then never again) */
-  secret: string;
-  /** Labels for categorization and filtering. Always present, empty array when none. */
-  labels: string[];
-  /** Unix timestamp (seconds) when token expires, null for never */
-  expires: number | null;
+  readonly secret: string;
 }
 
 // =============================================================================
@@ -268,10 +276,34 @@ export type AccountPlanType = (typeof AccountPlan)[keyof typeof AccountPlan];
 
 /**
  * Account usage metrics — always available regardless of billing provider.
+ *
+ * This is where a caller's own totals live. Lists answer pages and carry no
+ * `total` (see {@link ListOptions}); a count is an aggregate over a
+ * collection, so it belongs to the summary resource that owns the
+ * collection. `GET /account` is that resource for one caller, `GET
+ * /admin/stats` for the platform.
+ *
+ * The counted dimensions are the ones the plan caps — deployments and
+ * domains (`PlatformLimits`) — plus the billable custom-domain subset, so a
+ * surface can render "3 of 10" without a second request.
  */
 export interface AccountUsage {
   /** Number of active custom domains (excludes paused) */
   customDomains: number;
+  /**
+   * Deployments counted against the plan's deployment cap — every row
+   * whatever its status, because that is what the cap counts, so a surface
+   * renders "3 of 10" against the denominator the 403 divides by. (`GET
+   * /deployments` lists successful ones only; that is a different question
+   * asked of a different resource.) Optional by the additive-evolution law:
+   * an API predating this field omits it.
+   */
+  deployments?: number;
+  /**
+   * Domains counted against the plan's domain cap — every domain, platform
+   * and custom alike, unlike `customDomains`. Optional for the same reason.
+   */
+  domains?: number;
 }
 
 /**
@@ -397,11 +429,19 @@ const CLIENT_ONLY_ERROR_TYPES = new Set<string>([
  * union so `.has(error.type)` accepts any value from the union.
  */
 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.
+   */
   client: new Set<ErrorType>([
     ErrorType.Business,
     ErrorType.Config,
     ErrorType.File,
     ErrorType.Forbidden,
+    ErrorType.NotFound,
+    ErrorType.RateLimit,
     ErrorType.Validation,
   ]),
   network: new Set<ErrorType>([ErrorType.Network]),
@@ -645,10 +685,24 @@ export class ShipError extends Error {
     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(): boolean {
-    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(): boolean {
@@ -1004,6 +1058,54 @@ export const SPA_DEFAULT_CONFIG = {
   rewrites: [{ source: '/(.*)', destination: '/index.html' }],
 } as const;
 
+/**
+ * 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: string): void {
+  const withoutBom = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(withoutBom);
+  } catch (error) {
+    throw ShipError.config(`invalid JSON format in config: ${(error as 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
 // =============================================================================
@@ -1233,10 +1335,20 @@ export interface DeploymentUploadOptions {
 }
 
 /**
- * Pagination options for the paginated list endpoints (`GET /deployments`,
- * `GET /domains`). The response's `cursor` feeds the next request; a `null`
- * cursor on the response means the last page. Omitting both returns the
- * server's default first page.
+ * 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. */
@@ -1293,7 +1405,7 @@ export interface AccountResource {
  */
 export interface TokenResource {
   create: (options?: { ttl?: number; labels?: string[] }) => Promise<TokenCreateResponse>;
-  list: () => Promise<TokenListResponse>;
+  list: (options?: ListOptions) => Promise<TokenListResponse>;
   remove: (token: string) => Promise<void>;
 }
 
@@ -1477,7 +1589,7 @@ export interface ActivityMeta {
 /**
  * Response from GET /activities endpoint
  */
-export interface ActivityListResponse {
+export interface ActivityListResponse extends ListResponse {
   /** Array of activities */
   activities: Activity[];
 }