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

package/dist/index.d.ts

@@ -49,14 +49,33 @@ 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.
+ *
+ * The operator lists (`/admin/*`) answer this same shape behind the prefix;
+ * their types live in `web/my`, not here — see `CLAUDE.md`, "Admin types".
+ */
+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;
 }
 /**
  * Domain status constants
@@ -89,7 +108,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;
@@ -111,11 +130,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;
 }
 /**
  * DNS record types supported for domain configuration
@@ -175,11 +192,19 @@ 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.
+ *
+ * A single noun, like every other entity here: the platform's unit types are
+ * `Deployment`, `Domain`, `Account`, `Activity` and this. It was once called
+ * `TokenListItem`, named for the surface that returned it rather than for
+ * what it is, which is exactly why {@link TokenCreateResponse} used to
+ * restate its fields instead of extending it.
+ *
+ * The token itself is never here. The secret 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. */
@@ -194,24 +219,19 @@ export interface TokenListItem {
 /**
  * Response for listing tokens
  */
-export interface TokenListResponse {
-    /** Array of tokens (security-redacted for list display) */
-    tokens: TokenListItem[];
-    /** Cursor for pagination, null if no more pages */
-    cursor: string | null;
+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
@@ -228,10 +248,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
@@ -977,11 +1021,9 @@ export interface ActivityMeta {
 /**
  * Response from GET /activities endpoint
  */
-export interface ActivityListResponse {
+export interface ActivityListResponse extends ListResponse {
     /** Array of activities */
     activities: Activity[];
-    /** Cursor for pagination, null if no more pages */
-    cursor: string | null;
 }
 /**
  * File status constants for validation state tracking

package/package.json

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

package/src/index.ts

@@ -58,14 +58,34 @@ 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.
+ *
+ * The operator lists (`/admin/*`) answer this same shape behind the prefix;
+ * their types live in `web/my`, not here — see `CLAUDE.md`, "Admin types".
+ */
+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;
 }
 
 // =============================================================================
@@ -105,7 +125,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;
@@ -129,11 +149,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;
 }
 
 /**
@@ -202,11 +220,19 @@ 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.
+ *
+ * A single noun, like every other entity here: the platform's unit types are
+ * `Deployment`, `Domain`, `Account`, `Activity` and this. It was once called
+ * `TokenListItem`, named for the surface that returned it rather than for
+ * what it is, which is exactly why {@link TokenCreateResponse} used to
+ * restate its fields instead of extending it.
+ *
+ * The token itself is never here. The secret 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. */
@@ -222,25 +248,20 @@ export interface TokenListItem {
 /**
  * Response for listing tokens
  */
-export interface TokenListResponse {
-  /** Array of tokens (security-redacted for list display) */
-  tokens: TokenListItem[];
-  /** Cursor for pagination, null if no more pages */
-  cursor: string | null;
+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;
 }
 
 // =============================================================================
@@ -264,10 +285,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;
 }
 
 /**
@@ -1553,11 +1598,9 @@ export interface ActivityMeta {
 /**
  * Response from GET /activities endpoint
  */
-export interface ActivityListResponse {
+export interface ActivityListResponse extends ListResponse {
   /** Array of activities */
   activities: Activity[];
-  /** Cursor for pagination, null if no more pages */
-  cursor: string | null;
 }
 
 // =============================================================================