@shipstatic/types 2.5.0-beta.6 → 2.5.0-beta.8

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
@@ -234,10 +228,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
@@ -814,10 +832,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. */
@@ -978,8 +1006,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipstatic/types",
-  "version": "2.5.0-beta.6",
+  "version": "2.5.0-beta.8",
   "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;
 }
 
 /**
@@ -270,10 +264,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;
 }
 
 /**
@@ -1305,10 +1323,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. */
@@ -1554,8 +1582,6 @@ export interface ActivityListResponse {
   activities: Activity[];
   /** Cursor for pagination, null if no more pages */
   cursor: string | null;
-  /** Total number of activities */
-  total: number;
 }
 
 // =============================================================================