@shipstatic/types 2.5.0-beta.5 → 2.5.0-beta.7

package/dist/index.d.ts

@@ -57,8 +57,6 @@ export interface DeploymentListResponse {
     deployments: Deployment[];
     /** Cursor for pagination, null if no more pages */
     cursor: string | null;
-    /** Total number of deployments */
-    total: number;
 }
 /**
  * Domain status constants
@@ -118,8 +116,6 @@ export interface DomainListResponse {
     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
@@ -203,8 +199,6 @@ export interface TokenListResponse {
     tokens: TokenListItem[];
     /** Cursor for pagination, null if no more pages */
     cursor: string | null;
-    /** Total number of tokens */
-    total: number;
 }
 /**
  * Response for token creation
@@ -423,6 +417,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;
@@ -802,10 +808,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. */
@@ -966,8 +982,6 @@ export interface ActivityListResponse {
     activities: Activity[];
     /** Cursor for pagination, null if no more pages */
     cursor: string | null;
-    /** Total number of activities */
-    total: number;
 }
 /**
  * File status constants for validation state tracking

package/dist/index.js

@@ -101,10 +101,10 @@ const CLIENT_ONLY_ERROR_TYPES = new Set([
  */
 const ERROR_CATEGORIES = {
     /**
-     * Every 4xx-class type — the caller's request or state is at fault, and
-     * the authored message is safe to surface verbatim. The set is exhaustive
-     * on purpose: a partial one forces consumers to add a status-range check
-     * beside every `isClientError()` call for the types it forgot.
+     * 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,
@@ -317,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);

package/package.json

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

package/src/index.ts

@@ -66,8 +66,6 @@ export interface DeploymentListResponse {
   deployments: Deployment[];
   /** Cursor for pagination, null if no more pages */
   cursor: string | null;
-  /** Total number of deployments */
-  total: number;
 }
 
 // =============================================================================
@@ -136,8 +134,6 @@ export interface DomainListResponse {
   domains: Domain[];
   /** Cursor for pagination, null if no more pages */
   cursor: string | null;
-  /** Total number of domains */
-  total: number;
 }
 
 /**
@@ -231,8 +227,6 @@ export interface TokenListResponse {
   tokens: TokenListItem[];
   /** Cursor for pagination, null if no more pages */
   cursor: string | null;
-  /** Total number of tokens */
-  total: number;
 }
 
 /**
@@ -400,10 +394,10 @@ const CLIENT_ONLY_ERROR_TYPES = new Set<string>([
  */
 const ERROR_CATEGORIES = {
   /**
-   * Every 4xx-class type — the caller's request or state is at fault, and
-   * the authored message is safe to surface verbatim. The set is exhaustive
-   * on purpose: a partial one forces consumers to add a status-range check
-   * beside every `isClientError()` call for the types it forgot.
+   * 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,
@@ -655,10 +649,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 {
@@ -1291,10 +1299,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. */
@@ -1540,8 +1558,6 @@ export interface ActivityListResponse {
   activities: Activity[];
   /** Cursor for pagination, null if no more pages */
   cursor: string | null;
-  /** Total number of activities */
-  total: number;
 }
 
 // =============================================================================