@shipstatic/types 2.4.2-beta.0 → 2.5.0-beta.1

package/dist/index.d.ts

@@ -522,7 +522,7 @@ export declare function hasUnbuiltMarker(filePath: string): boolean;
 export interface PingResponse {
     /** Always true if service is healthy */
     success: boolean;
-    /** Optional timestamp */
+    /** Server time in unix seconds — the one wire unit for timestamps. */
     timestamp?: number;
 }
 /**
@@ -727,20 +727,6 @@ export interface StaticFile {
     /** The size of the file in bytes. */
     size: number;
 }
-/**
- * Progress information for deploy/upload operations.
- * Provides consistent percentage-based progress with byte-level details.
- */
-export interface ProgressInfo {
-    /** Progress percentage (0-100) */
-    percent: number;
-    /** Number of bytes loaded so far */
-    loaded: number;
-    /** Total number of bytes to load. May be 0 if unknown initially */
-    total: number;
-    /** Current file being processed (optional) */
-    file?: string;
-}
 /** Default API URL if not otherwise configured. */
 export declare const DEFAULT_API = "https://api.shipstatic.com";
 /**
@@ -784,11 +770,28 @@ export interface DeploymentUploadOptions {
     captcha?: string;
 }
 /**
- * Deployment resource interface - the contract all implementations must follow
+ * 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.
  */
-export interface DeploymentResource {
-    upload: (input: DeployInput, options?: DeploymentUploadOptions) => Promise<DeploymentCreateResponse>;
-    list: () => Promise<DeploymentListResponse>;
+export interface ListOptions {
+    /** Maximum number of items to return in one page. */
+    limit?: number;
+    /** Opaque cursor from the previous page's response. */
+    cursor?: string;
+}
+/**
+ * Deployment resource interface - the contract all implementations must follow.
+ *
+ * The interface defines the minimal wire contract; SDK implementations may
+ * extend the upload options with runtime concerns (timeout, signal, progress
+ * callbacks) by parameterizing: `DeploymentResource<MyUploadOptions>`. The
+ * default keeps plain `DeploymentResource` valid for wire-only consumers.
+ */
+export interface DeploymentResource<UploadOptions extends DeploymentUploadOptions = DeploymentUploadOptions> {
+    upload: (input: DeployInput, options?: UploadOptions) => Promise<DeploymentCreateResponse>;
+    list: (options?: ListOptions) => Promise<DeploymentListResponse>;
     get: (id: string) => Promise<Deployment>;
     set: (id: string, options: {
         labels: string[];
@@ -803,7 +806,7 @@ export interface DomainResource {
         deployment?: string;
         labels?: string[];
     }) => Promise<DomainSetResult>;
-    list: () => Promise<DomainListResponse>;
+    list: (options?: ListOptions) => Promise<DomainListResponse>;
     get: (name: string) => Promise<Domain>;
     remove: (name: string) => Promise<void>;
     verify: (name: string) => Promise<{
@@ -886,6 +889,12 @@ export interface Activity {
 /**
  * Parsed activity metadata.
  * Different events populate different fields.
+ *
+ * Naming convention: meta booleans are event-scoped predicates and carry
+ * their prefix (`isUpdate`, `wasVerified`, `hasConfig`, `hasPassword`),
+ * while entity booleans are bare nouns (`Deployment.config`,
+ * `Deployment.password`). Two vocabularies, each internally consistent —
+ * deliberate, not drift.
  */
 export interface ActivityMeta {
     /** Number of files in deployment */

package/dist/index.js

@@ -197,6 +197,23 @@ export class ShipError extends Error {
         catch {
             // Body unreadable; fall through to operationName-derived message.
         }
+        // Rate-limit (and 503) timing rides the `Retry-After` HEADER, which a
+        // body-only reader would drop. Lift it into `details` as seconds so
+        // consumers can back off from the typed error alone, without keeping the
+        // raw Response around. Body-carried fields are preserved and win.
+        const retryAfterHeader = response.headers.get('retry-after');
+        if (retryAfterHeader !== null) {
+            const value = retryAfterHeader.trim();
+            const seconds = /^\d+$/.test(value)
+                ? Number(value)
+                : Math.ceil((Date.parse(value) - Date.now()) / 1000);
+            if (Number.isFinite(seconds) && seconds >= 0) {
+                const existing = details && typeof details === 'object' ? details : {};
+                if (existing.retryAfter === undefined) {
+                    details = { ...existing, retryAfter: seconds };
+                }
+            }
+        }
         message = message || `${operationName || 'Request'} failed with status ${response.status}`;
         const type = bodyType ??
             (response.status === 401

package/package.json

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

package/src/index.ts

@@ -512,6 +512,25 @@ export class ShipError extends Error {
       // Body unreadable; fall through to operationName-derived message.
     }
 
+    // Rate-limit (and 503) timing rides the `Retry-After` HEADER, which a
+    // body-only reader would drop. Lift it into `details` as seconds so
+    // consumers can back off from the typed error alone, without keeping the
+    // raw Response around. Body-carried fields are preserved and win.
+    const retryAfterHeader = response.headers.get('retry-after');
+    if (retryAfterHeader !== null) {
+      const value = retryAfterHeader.trim();
+      const seconds = /^\d+$/.test(value)
+        ? Number(value)
+        : Math.ceil((Date.parse(value) - Date.now()) / 1000);
+      if (Number.isFinite(seconds) && seconds >= 0) {
+        const existing =
+          details && typeof details === 'object' ? (details as Record<string, unknown>) : {};
+        if (existing.retryAfter === undefined) {
+          details = { ...existing, retryAfter: seconds };
+        }
+      }
+    }
+
     message = message || `${operationName || 'Request'} failed with status ${response.status}`;
 
     const type =
@@ -834,7 +853,7 @@ export function hasUnbuiltMarker(filePath: string): boolean {
 export interface PingResponse {
   /** Always true if service is healthy */
   success: boolean;
-  /** Optional timestamp */
+  /** Server time in unix seconds — the one wire unit for timestamps. */
   timestamp?: number;
 }
 
@@ -1160,25 +1179,6 @@ export interface StaticFile {
   size: number;
 }
 
-// =============================================================================
-// PROGRESS TRACKING
-// =============================================================================
-
-/**
- * Progress information for deploy/upload operations.
- * Provides consistent percentage-based progress with byte-level details.
- */
-export interface ProgressInfo {
-  /** Progress percentage (0-100) */
-  percent: number;
-  /** Number of bytes loaded so far */
-  loaded: number;
-  /** Total number of bytes to load. May be 0 if unknown initially */
-  total: number;
-  /** Current file being processed (optional) */
-  file?: string;
-}
-
 // =============================================================================
 // PLATFORM CONSTANTS
 // =============================================================================
@@ -1233,14 +1233,31 @@ export interface DeploymentUploadOptions {
 }
 
 /**
- * Deployment resource interface - the contract all implementations must follow
+ * 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.
  */
-export interface DeploymentResource {
-  upload: (
-    input: DeployInput,
-    options?: DeploymentUploadOptions,
-  ) => Promise<DeploymentCreateResponse>;
-  list: () => Promise<DeploymentListResponse>;
+export interface ListOptions {
+  /** Maximum number of items to return in one page. */
+  limit?: number;
+  /** Opaque cursor from the previous page's response. */
+  cursor?: string;
+}
+
+/**
+ * Deployment resource interface - the contract all implementations must follow.
+ *
+ * The interface defines the minimal wire contract; SDK implementations may
+ * extend the upload options with runtime concerns (timeout, signal, progress
+ * callbacks) by parameterizing: `DeploymentResource<MyUploadOptions>`. The
+ * default keeps plain `DeploymentResource` valid for wire-only consumers.
+ */
+export interface DeploymentResource<
+  UploadOptions extends DeploymentUploadOptions = DeploymentUploadOptions,
+> {
+  upload: (input: DeployInput, options?: UploadOptions) => Promise<DeploymentCreateResponse>;
+  list: (options?: ListOptions) => Promise<DeploymentListResponse>;
   get: (id: string) => Promise<Deployment>;
   set: (id: string, options: { labels: string[] }) => Promise<Deployment>;
   remove: (id: string) => Promise<void>;
@@ -1254,7 +1271,7 @@ export interface DomainResource {
     name: string,
     options?: { deployment?: string; labels?: string[] },
   ) => Promise<DomainSetResult>;
-  list: () => Promise<DomainListResponse>;
+  list: (options?: ListOptions) => Promise<DomainListResponse>;
   get: (name: string) => Promise<Domain>;
   remove: (name: string) => Promise<void>;
   verify: (name: string) => Promise<{ message: string }>;
@@ -1411,6 +1428,12 @@ export interface Activity {
 /**
  * Parsed activity metadata.
  * Different events populate different fields.
+ *
+ * Naming convention: meta booleans are event-scoped predicates and carry
+ * their prefix (`isUpdate`, `wasVerified`, `hasConfig`, `hasPassword`),
+ * while entity booleans are bare nouns (`Deployment.config`,
+ * `Deployment.password`). Two vocabularies, each internally consistent —
+ * deliberate, not drift.
  */
 export interface ActivityMeta {
   // Deployment events