@shipstatic/ship 2.0.0-beta.1 → 2.0.0-beta.3

package/dist/index.d.cts

@@ -258,6 +258,13 @@ interface Account {
     readonly activated: number | null;
     /** Last 4 characters of the API key for identification, null when no key generated */
     readonly hint: string | null;
+    /**
+     * Unix timestamp (seconds) of the API key's last use, null when never
+     * used or no key generated. Optional on the type by the additive-evolution
+     * law: published SDK versions may predate the field, so consumers read it
+     * when present rather than forcing a lockstep SDK release.
+     */
+    readonly used?: number | null;
     /** Grace period expiration (unix seconds), null if no grace period active */
     readonly grace: number | null;
 }
@@ -515,9 +522,17 @@ declare function hasUnbuiltMarker(filePath: string): boolean;
 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;
 }
+/**
+ * Where human identity is mounted on the API host. The API mounts Better
+ * Auth at this path (sign-in, sign-out, session reads, admin impersonation)
+ * and the web console's auth client posts to it — shared here so the two
+ * halves of the auth pair agree by construction, the same way both sides
+ * already share the credential prefixes below.
+ */
+declare const AUTH_BASE_PATH = "/auth";
 /**
  * How a request (or recorded activity) was authorized.
  *
@@ -712,20 +727,6 @@ 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.
- */
-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. */
 declare const DEFAULT_API = "https://api.shipstatic.com";
 /**
@@ -769,11 +770,28 @@ 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.
  */
-interface DeploymentResource {
-    upload: (input: DeployInput, options?: DeploymentUploadOptions) => Promise<DeploymentCreateResponse>;
-    list: () => Promise<DeploymentListResponse>;
+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.
+ */
+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[];
@@ -788,7 +806,7 @@ 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<{
@@ -848,11 +866,11 @@ interface CheckoutSession {
  * All activity event types logged in the system.
  * Uses dot notation consistently: {resource}.{action}
  */
-type ActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.paid' | 'account.plan.transition' | 'account.suspended' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'deployment.flagged' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'admin.account.plan.update' | 'admin.account.ref.update' | 'admin.account.billing.update' | 'admin.account.labels.update' | 'admin.deployment.delete' | 'admin.domain.delete' | 'admin.billing.sync' | 'admin.billing.terminated' | 'admin.impersonate' | 'billing.active' | 'billing.canceled' | 'billing.paused' | 'billing.expired' | 'billing.paid' | 'billing.trialing' | 'billing.scheduled_cancel' | 'billing.unpaid' | 'billing.update' | 'billing.past_due' | 'refund.created' | 'dispute.created' | 'billing.sync' | 'billing.stale' | 'billing.race';
+type ActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.paid' | 'account.plan.transition' | 'account.suspended' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'deployment.flagged' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete' | 'admin.account.plan.update' | 'admin.account.ref.update' | 'admin.account.billing.update' | 'admin.account.labels.update' | 'admin.deployment.delete' | 'admin.domain.delete' | 'admin.billing.sync' | 'admin.billing.terminated' | 'admin.impersonate' | 'billing.active' | 'billing.canceled' | 'billing.paused' | 'billing.expired' | 'billing.paid' | 'billing.trialing' | 'billing.scheduled_cancel' | 'billing.unpaid' | 'billing.update' | 'billing.past_due' | 'refund.created' | 'dispute.created' | 'billing.sync' | 'billing.stale' | 'billing.race';
 /**
  * Activity events visible to users in the dashboard
  */
-type UserVisibleActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.transition' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume';
+type UserVisibleActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.transition' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete';
 /**
  * Activity record returned from the API
  */
@@ -871,6 +889,12 @@ 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.
  */
 interface ActivityMeta {
     /** Number of files in deployment */
@@ -1109,20 +1133,17 @@ declare function validatePassword(value: unknown): string | undefined;
  * Extends the API contract (DeploymentUploadOptions) with SDK-specific options.
  */
 interface DeploymentOptions extends DeploymentUploadOptions {
-    /** An AbortSignal to allow cancellation of the deploy operation. */
+    /**
+     * An AbortSignal to allow cancellation of the deploy operation. The one
+     * cancellation mechanism — abort the signal and the request rejects with
+     * a typed `Cancelled` error. Request timeouts are a client concern
+     * (`ShipClientOptions.timeout`), not a per-deploy one.
+     */
     signal?: AbortSignal;
-    /** Callback invoked if the deploy is cancelled via the AbortSignal. */
-    onCancel?: () => void;
-    /** Maximum number of concurrent operations. */
-    maxConcurrency?: number;
-    /** Timeout in milliseconds for the deploy request. */
-    timeout?: number;
     /** Whether to auto-detect and optimize file paths by flattening common directories. Defaults to true. */
     pathDetect?: boolean;
     /** Whether to auto-detect SPAs and generate ship.json configuration. Defaults to true. */
     spaDetect?: boolean;
-    /** Callback for deploy progress with detailed statistics. */
-    onProgress?: (info: ProgressInfo) => void;
 }
 type ApiDeployOptions = Omit<DeploymentOptions, 'pathDetect'>;
 /**
@@ -1177,7 +1198,7 @@ type Fetch = typeof fetch;
 type TokenProvider = () => string | Promise<string>;
 /**
  * Options for configuring a `Ship` instance.
- * Sets default API host, the client credential, progress callbacks, concurrency, and timeouts for the client.
+ * Sets the API host, the client credential, the request timeout, and the transport.
  */
 interface ShipClientOptions {
     /** Default API URL for the client instance. */
@@ -1198,19 +1219,8 @@ interface ShipClientOptions {
      */
     token?: string | TokenProvider | undefined;
     /**
-     * Default callback for deploy progress for deploys made with this client.
-     * @param info - Progress information including percentage and byte counts.
-     */
-    onProgress?: ((info: ProgressInfo) => void) | undefined;
-    /**
-     * Default for maximum concurrent deploys.
-     * Used if an deploy operation doesn't specify its own `maxConcurrency`.
-     * Defaults to 4 if not set here or in the specific deploy call.
-     */
-    maxConcurrency?: number | undefined;
-    /**
-     * Default timeout in milliseconds for API requests made by this client instance.
-     * Used if an deploy operation doesn't specify its own timeout.
+     * Timeout in milliseconds for every API request made by this client
+     * instance. Defaults to 30 seconds.
      */
     timeout?: number | undefined;
     /**
@@ -1277,7 +1287,19 @@ interface ShipEvents {
     request: [url: string, init: RequestInit];
     /** Emitted after successful API response */
     response: [response: Response, url: string];
-    /** Emitted when API request fails */
+    /**
+     * Emitted when something fails. TWO populations arrive here, which is why
+     * the type is `Error` and not `ShipError`:
+     *
+     *  - a failed request — always a `ShipError` (`executeRequest` normalizes
+     *    every failure through `ShipError.fromFetchError` before emitting), so
+     *    `isShipError(error)` narrows and `.type` / `.status` are readable;
+     *  - a THROWING HANDLER of yours — `SimpleEvents.emit` evicts it and
+     *    re-emits the raw failure here, which is a plain `Error`.
+     *
+     * Narrowing this to `ShipError` was tried on 2026-07-27 and reverted: it
+     * made the second population a lie.
+     */
     error: [error: Error, url: string];
 }
 
@@ -1352,12 +1374,12 @@ declare class ApiHttp extends SimpleEvents {
     private safeClone;
     private parseResponse;
     deploy(files: StaticFile[], options?: ApiDeployOptions): Promise<DeploymentCreateResponse>;
-    listDeployments(): Promise<DeploymentListResponse>;
+    listDeployments(options?: ListOptions): Promise<DeploymentListResponse>;
     getDeployment(id: string): Promise<Deployment>;
     updateDeploymentLabels(id: string, labels: string[]): Promise<Deployment>;
     removeDeployment(id: string): Promise<void>;
     setDomain(name: string, deployment?: string, labels?: string[]): Promise<DomainSetResult>;
-    listDomains(): Promise<DomainListResponse>;
+    listDomains(options?: ListOptions): Promise<DomainListResponse>;
     getDomain(name: string): Promise<Domain>;
     removeDomain(name: string): Promise<void>;
     verifyDomain(name: string): Promise<{
@@ -1395,7 +1417,6 @@ interface ResourceContext {
  */
 interface DeploymentResourceContext extends ResourceContext {
     processInput: (input: DeployInput, options: DeploymentOptions) => Promise<StaticFile[]>;
-    clientDefaults?: ShipClientOptions;
 }
 /**
  * Upload deployment resource with all CRUD operations.
@@ -1405,7 +1426,7 @@ interface DeploymentResourceContext extends ResourceContext {
  * public-account agent identity per request (claim URL + expiry on the
  * response). The SDK stays a transparent pipe either way.
  */
-declare function createDeploymentResource(ctx: DeploymentResourceContext): DeploymentResource;
+declare function createDeploymentResource(ctx: DeploymentResourceContext): DeploymentResource<DeploymentOptions>;
 /**
  * Create domain resource with all CRUD operations.
  *
@@ -1427,7 +1448,7 @@ declare function createTokenResource(ctx: ResourceContext): TokenResource;
  * Abstract base class for Ship SDK implementations.
  */
 declare abstract class Ship$1 {
-    readonly deployments: DeploymentResource;
+    readonly deployments: DeploymentResource<DeploymentOptions>;
     readonly domains: DomainResource;
     readonly account: AccountResource;
     readonly tokens: TokenResource;
@@ -1452,7 +1473,7 @@ declare abstract class Ship$1 {
     /**
      * Deploy project (convenience shortcut to `ship.deployments.upload()`).
      */
-    deploy(input: DeployInput, options?: DeploymentOptions): Promise<Deployment>;
+    deploy(input: DeployInput, options?: DeploymentOptions): Promise<DeploymentCreateResponse>;
     /**
      * Get current account information (convenience shortcut to `ship.account.get()`).
      */
@@ -1494,30 +1515,6 @@ declare abstract class Ship$1 {
     private getAuthHeaders;
 }
 
-/**
- * @file Cross-platform configuration helpers.
- *
- * One pure helper used by the deployment resource:
- *
- *   - `mergeDeployOptions(perCallOptions, clientDefaults)` — overlays
- *     instance-level defaults under per-call overrides for a single deploy.
- *
- * Deploy options are pure deploy concerns (progress, timeout, concurrency).
- * Credentials, the API URL, and the caller identifier are client identity —
- * they live on the instance, never per call: one client is one principal
- * speaking for one end user against one API. Callers that need a different
- * identity construct another Ship.
- */
-
-/**
- * Overlay client-level defaults under per-call deploy options.
- *
- * Per-call options always win — they're the explicit override for a single
- * `deployments.upload()`. Defaults fill in only when the per-call option is
- * `undefined` (an explicit `null` / empty value passes through).
- */
-declare function mergeDeployOptions(options: DeploymentOptions, clientDefaults: ShipClientOptions): DeploymentOptions;
-
 /**
  * @file Deploy path optimization - the core logic that makes Ship deployments clean and intuitive.
  * Automatically strips common parent directories to create clean deployment URLs.
@@ -1775,7 +1772,7 @@ declare function pluralize(count: number, singular: string, plural: string, incl
  * @param paths - File or directory paths to scan and process.
  * @param options - Processing options (pathDetect, etc.).
  * @param platformLimits - Per-instance platform limits (file-size / count /
- *   total-size caps) from the originating Ship's `GET /config` fetch. Passed
+ *   total-size caps) from the originating Ship's `GET /limits` fetch. Passed
  *   in rather than read from a module global so concurrent Ships against
  *   different API URLs cannot clobber each other's caps.
  * @returns Promise resolving to an array of StaticFile objects.
@@ -1827,9 +1824,12 @@ declare class Ship extends Ship$1 {
      * intentional: the convenience shortcut narrows; the resource-layer
      * contract stays platform-neutral.
      */
-    deploy(input: string | string[], options?: DeploymentOptions): Promise<Deployment>;
+    deploy(input: string | string[], options?: DeploymentOptions): Promise<DeploymentCreateResponse>;
     protected processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
     protected getDeployBodyCreator(): DeployBodyCreator;
 }
 
-export { API_KEY, type Account, type AccountGetResponse, type AccountOverrides, AccountPlan, type AccountPlanType, type AccountResource, type AccountUsage, type Activity, type ActivityEvent, type ActivityListResponse, type ActivityMeta, type ApiDeployOptions, ApiHttp, type ApiHttpOptions, AuthMethod, type AuthMethodType, BLOCKED_EXTENSIONS, type BillingStatus, CALLER, type CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_TOKEN, type DeployBody, type DeployBodyContext, type DeployBodyCreator, type DeployFile, type DeployInput, type Deployment, type DeploymentCreateResponse, type DeploymentListResponse, type DeploymentOptions, type DeploymentResource, type DeploymentResourceContext, DeploymentStatus, type DeploymentStatusType, type DeploymentUploadOptions, type DnsProvider, type DnsRecord, type DnsRecordType, type Domain, type DomainDnsResponse, type DomainListResponse, type DomainRecordsResponse, type DomainResource, type DomainSetResult, DomainStatus, type DomainStatusType, type DomainValidateResponse, type ErrorResponse, ErrorType, type ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, type Fetch, type FileValidationResult, FileValidationStatus, type FileValidationStatusType, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, type MD5Result, OAuthScope, type OAuthScopeType, PASSWORD_CONSTRAINTS, type PingResponse, type PlatformLimits, type ProgressInfo, type ResourceContext, type SPACheckRequest, type SPACheckResponse, SPA_DEFAULT_CONFIG, Ship, type ShipClientOptions, ShipError, type ShipEvents, type StaticFile, type TokenCreateResponse, TokenKind, type TokenKindType, type TokenListItem, type TokenListResponse, type TokenProvider, type TokenResource, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, type UploadedFile, type UserVisibleActivityEvent, type ValidatableFile, type ValidationIssue, __setTestEnvironment, allValidFilesReady, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForNode, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validatePassword, validateToken };
+declare namespace Ship {
+  export { API_KEY, AUTH_BASE_PATH, Account, AccountGetResponse, AccountOverrides, AccountPlan, AccountPlanType, AccountResource, AccountUsage, Activity, ActivityEvent, ActivityListResponse, ActivityMeta, ApiDeployOptions, ApiHttp, ApiHttpOptions, AuthMethod, AuthMethodType, BLOCKED_EXTENSIONS, BillingStatus, CALLER, CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_TOKEN, DeployBody, DeployBodyContext, DeployBodyCreator, DeployFile, DeployInput, Deployment, DeploymentCreateResponse, DeploymentListResponse, DeploymentOptions, DeploymentResource, DeploymentResourceContext, DeploymentStatus, DeploymentStatusType, DeploymentUploadOptions, DnsProvider, DnsRecord, DnsRecordType, Domain, DomainDnsResponse, DomainListResponse, DomainRecordsResponse, DomainResource, DomainSetResult, DomainStatus, DomainStatusType, DomainValidateResponse, ErrorResponse, ErrorType, ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, Fetch, FileValidationResult, FileValidationStatus, FileValidationStatusType, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, ListOptions, MD5Result, OAuthScope, OAuthScopeType, PASSWORD_CONSTRAINTS, PingResponse, PlatformLimits, ResourceContext, SPACheckRequest, SPACheckResponse, SPA_DEFAULT_CONFIG, ShipClientOptions, ShipError, ShipEvents, StaticFile, TokenCreateResponse, TokenKind, TokenKindType, TokenListItem, TokenListResponse, TokenProvider, TokenResource, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, UploadedFile, UserVisibleActivityEvent, ValidatableFile, ValidationIssue, __setTestEnvironment, allValidFilesReady, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, optimizeDeployPaths, pluralize, processFilesForNode, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validatePassword, validateToken };
+}
+export = Ship;

package/dist/index.d.ts

@@ -258,6 +258,13 @@ interface Account {
     readonly activated: number | null;
     /** Last 4 characters of the API key for identification, null when no key generated */
     readonly hint: string | null;
+    /**
+     * Unix timestamp (seconds) of the API key's last use, null when never
+     * used or no key generated. Optional on the type by the additive-evolution
+     * law: published SDK versions may predate the field, so consumers read it
+     * when present rather than forcing a lockstep SDK release.
+     */
+    readonly used?: number | null;
     /** Grace period expiration (unix seconds), null if no grace period active */
     readonly grace: number | null;
 }
@@ -515,9 +522,17 @@ declare function hasUnbuiltMarker(filePath: string): boolean;
 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;
 }
+/**
+ * Where human identity is mounted on the API host. The API mounts Better
+ * Auth at this path (sign-in, sign-out, session reads, admin impersonation)
+ * and the web console's auth client posts to it — shared here so the two
+ * halves of the auth pair agree by construction, the same way both sides
+ * already share the credential prefixes below.
+ */
+declare const AUTH_BASE_PATH = "/auth";
 /**
  * How a request (or recorded activity) was authorized.
  *
@@ -712,20 +727,6 @@ 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.
- */
-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. */
 declare const DEFAULT_API = "https://api.shipstatic.com";
 /**
@@ -769,11 +770,28 @@ 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.
  */
-interface DeploymentResource {
-    upload: (input: DeployInput, options?: DeploymentUploadOptions) => Promise<DeploymentCreateResponse>;
-    list: () => Promise<DeploymentListResponse>;
+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.
+ */
+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[];
@@ -788,7 +806,7 @@ 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<{
@@ -848,11 +866,11 @@ interface CheckoutSession {
  * All activity event types logged in the system.
  * Uses dot notation consistently: {resource}.{action}
  */
-type ActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.paid' | 'account.plan.transition' | 'account.suspended' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'deployment.flagged' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'admin.account.plan.update' | 'admin.account.ref.update' | 'admin.account.billing.update' | 'admin.account.labels.update' | 'admin.deployment.delete' | 'admin.domain.delete' | 'admin.billing.sync' | 'admin.billing.terminated' | 'admin.impersonate' | 'billing.active' | 'billing.canceled' | 'billing.paused' | 'billing.expired' | 'billing.paid' | 'billing.trialing' | 'billing.scheduled_cancel' | 'billing.unpaid' | 'billing.update' | 'billing.past_due' | 'refund.created' | 'dispute.created' | 'billing.sync' | 'billing.stale' | 'billing.race';
+type ActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.paid' | 'account.plan.transition' | 'account.suspended' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'deployment.flagged' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete' | 'admin.account.plan.update' | 'admin.account.ref.update' | 'admin.account.billing.update' | 'admin.account.labels.update' | 'admin.deployment.delete' | 'admin.domain.delete' | 'admin.billing.sync' | 'admin.billing.terminated' | 'admin.impersonate' | 'billing.active' | 'billing.canceled' | 'billing.paused' | 'billing.expired' | 'billing.paid' | 'billing.trialing' | 'billing.scheduled_cancel' | 'billing.unpaid' | 'billing.update' | 'billing.past_due' | 'refund.created' | 'dispute.created' | 'billing.sync' | 'billing.stale' | 'billing.race';
 /**
  * Activity events visible to users in the dashboard
  */
-type UserVisibleActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.transition' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume';
+type UserVisibleActivityEvent = 'account.create' | 'account.update' | 'account.delete' | 'account.key.generate' | 'account.plan.transition' | 'deployment.create' | 'deployment.update' | 'deployment.delete' | 'deployment.claim' | 'domain.create' | 'domain.update' | 'domain.delete' | 'domain.verify' | 'token.create' | 'token.consume' | 'token.delete';
 /**
  * Activity record returned from the API
  */
@@ -871,6 +889,12 @@ 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.
  */
 interface ActivityMeta {
     /** Number of files in deployment */
@@ -1109,20 +1133,17 @@ declare function validatePassword(value: unknown): string | undefined;
  * Extends the API contract (DeploymentUploadOptions) with SDK-specific options.
  */
 interface DeploymentOptions extends DeploymentUploadOptions {
-    /** An AbortSignal to allow cancellation of the deploy operation. */
+    /**
+     * An AbortSignal to allow cancellation of the deploy operation. The one
+     * cancellation mechanism — abort the signal and the request rejects with
+     * a typed `Cancelled` error. Request timeouts are a client concern
+     * (`ShipClientOptions.timeout`), not a per-deploy one.
+     */
     signal?: AbortSignal;
-    /** Callback invoked if the deploy is cancelled via the AbortSignal. */
-    onCancel?: () => void;
-    /** Maximum number of concurrent operations. */
-    maxConcurrency?: number;
-    /** Timeout in milliseconds for the deploy request. */
-    timeout?: number;
     /** Whether to auto-detect and optimize file paths by flattening common directories. Defaults to true. */
     pathDetect?: boolean;
     /** Whether to auto-detect SPAs and generate ship.json configuration. Defaults to true. */
     spaDetect?: boolean;
-    /** Callback for deploy progress with detailed statistics. */
-    onProgress?: (info: ProgressInfo) => void;
 }
 type ApiDeployOptions = Omit<DeploymentOptions, 'pathDetect'>;
 /**
@@ -1177,7 +1198,7 @@ type Fetch = typeof fetch;
 type TokenProvider = () => string | Promise<string>;
 /**
  * Options for configuring a `Ship` instance.
- * Sets default API host, the client credential, progress callbacks, concurrency, and timeouts for the client.
+ * Sets the API host, the client credential, the request timeout, and the transport.
  */
 interface ShipClientOptions {
     /** Default API URL for the client instance. */
@@ -1198,19 +1219,8 @@ interface ShipClientOptions {
      */
     token?: string | TokenProvider | undefined;
     /**
-     * Default callback for deploy progress for deploys made with this client.
-     * @param info - Progress information including percentage and byte counts.
-     */
-    onProgress?: ((info: ProgressInfo) => void) | undefined;
-    /**
-     * Default for maximum concurrent deploys.
-     * Used if an deploy operation doesn't specify its own `maxConcurrency`.
-     * Defaults to 4 if not set here or in the specific deploy call.
-     */
-    maxConcurrency?: number | undefined;
-    /**
-     * Default timeout in milliseconds for API requests made by this client instance.
-     * Used if an deploy operation doesn't specify its own timeout.
+     * Timeout in milliseconds for every API request made by this client
+     * instance. Defaults to 30 seconds.
      */
     timeout?: number | undefined;
     /**
@@ -1277,7 +1287,19 @@ interface ShipEvents {
     request: [url: string, init: RequestInit];
     /** Emitted after successful API response */
     response: [response: Response, url: string];
-    /** Emitted when API request fails */
+    /**
+     * Emitted when something fails. TWO populations arrive here, which is why
+     * the type is `Error` and not `ShipError`:
+     *
+     *  - a failed request — always a `ShipError` (`executeRequest` normalizes
+     *    every failure through `ShipError.fromFetchError` before emitting), so
+     *    `isShipError(error)` narrows and `.type` / `.status` are readable;
+     *  - a THROWING HANDLER of yours — `SimpleEvents.emit` evicts it and
+     *    re-emits the raw failure here, which is a plain `Error`.
+     *
+     * Narrowing this to `ShipError` was tried on 2026-07-27 and reverted: it
+     * made the second population a lie.
+     */
     error: [error: Error, url: string];
 }
 
@@ -1352,12 +1374,12 @@ declare class ApiHttp extends SimpleEvents {
     private safeClone;
     private parseResponse;
     deploy(files: StaticFile[], options?: ApiDeployOptions): Promise<DeploymentCreateResponse>;
-    listDeployments(): Promise<DeploymentListResponse>;
+    listDeployments(options?: ListOptions): Promise<DeploymentListResponse>;
     getDeployment(id: string): Promise<Deployment>;
     updateDeploymentLabels(id: string, labels: string[]): Promise<Deployment>;
     removeDeployment(id: string): Promise<void>;
     setDomain(name: string, deployment?: string, labels?: string[]): Promise<DomainSetResult>;
-    listDomains(): Promise<DomainListResponse>;
+    listDomains(options?: ListOptions): Promise<DomainListResponse>;
     getDomain(name: string): Promise<Domain>;
     removeDomain(name: string): Promise<void>;
     verifyDomain(name: string): Promise<{
@@ -1395,7 +1417,6 @@ interface ResourceContext {
  */
 interface DeploymentResourceContext extends ResourceContext {
     processInput: (input: DeployInput, options: DeploymentOptions) => Promise<StaticFile[]>;
-    clientDefaults?: ShipClientOptions;
 }
 /**
  * Upload deployment resource with all CRUD operations.
@@ -1405,7 +1426,7 @@ interface DeploymentResourceContext extends ResourceContext {
  * public-account agent identity per request (claim URL + expiry on the
  * response). The SDK stays a transparent pipe either way.
  */
-declare function createDeploymentResource(ctx: DeploymentResourceContext): DeploymentResource;
+declare function createDeploymentResource(ctx: DeploymentResourceContext): DeploymentResource<DeploymentOptions>;
 /**
  * Create domain resource with all CRUD operations.
  *
@@ -1427,7 +1448,7 @@ declare function createTokenResource(ctx: ResourceContext): TokenResource;
  * Abstract base class for Ship SDK implementations.
  */
 declare abstract class Ship$1 {
-    readonly deployments: DeploymentResource;
+    readonly deployments: DeploymentResource<DeploymentOptions>;
     readonly domains: DomainResource;
     readonly account: AccountResource;
     readonly tokens: TokenResource;
@@ -1452,7 +1473,7 @@ declare abstract class Ship$1 {
     /**
      * Deploy project (convenience shortcut to `ship.deployments.upload()`).
      */
-    deploy(input: DeployInput, options?: DeploymentOptions): Promise<Deployment>;
+    deploy(input: DeployInput, options?: DeploymentOptions): Promise<DeploymentCreateResponse>;
     /**
      * Get current account information (convenience shortcut to `ship.account.get()`).
      */
@@ -1494,30 +1515,6 @@ declare abstract class Ship$1 {
     private getAuthHeaders;
 }
 
-/**
- * @file Cross-platform configuration helpers.
- *
- * One pure helper used by the deployment resource:
- *
- *   - `mergeDeployOptions(perCallOptions, clientDefaults)` — overlays
- *     instance-level defaults under per-call overrides for a single deploy.
- *
- * Deploy options are pure deploy concerns (progress, timeout, concurrency).
- * Credentials, the API URL, and the caller identifier are client identity —
- * they live on the instance, never per call: one client is one principal
- * speaking for one end user against one API. Callers that need a different
- * identity construct another Ship.
- */
-
-/**
- * Overlay client-level defaults under per-call deploy options.
- *
- * Per-call options always win — they're the explicit override for a single
- * `deployments.upload()`. Defaults fill in only when the per-call option is
- * `undefined` (an explicit `null` / empty value passes through).
- */
-declare function mergeDeployOptions(options: DeploymentOptions, clientDefaults: ShipClientOptions): DeploymentOptions;
-
 /**
  * @file Deploy path optimization - the core logic that makes Ship deployments clean and intuitive.
  * Automatically strips common parent directories to create clean deployment URLs.
@@ -1775,7 +1772,7 @@ declare function pluralize(count: number, singular: string, plural: string, incl
  * @param paths - File or directory paths to scan and process.
  * @param options - Processing options (pathDetect, etc.).
  * @param platformLimits - Per-instance platform limits (file-size / count /
- *   total-size caps) from the originating Ship's `GET /config` fetch. Passed
+ *   total-size caps) from the originating Ship's `GET /limits` fetch. Passed
  *   in rather than read from a module global so concurrent Ships against
  *   different API URLs cannot clobber each other's caps.
  * @returns Promise resolving to an array of StaticFile objects.
@@ -1827,9 +1824,9 @@ declare class Ship extends Ship$1 {
      * intentional: the convenience shortcut narrows; the resource-layer
      * contract stays platform-neutral.
      */
-    deploy(input: string | string[], options?: DeploymentOptions): Promise<Deployment>;
+    deploy(input: string | string[], options?: DeploymentOptions): Promise<DeploymentCreateResponse>;
     protected processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
     protected getDeployBodyCreator(): DeployBodyCreator;
 }
 
-export { API_KEY, type Account, type AccountGetResponse, type AccountOverrides, AccountPlan, type AccountPlanType, type AccountResource, type AccountUsage, type Activity, type ActivityEvent, type ActivityListResponse, type ActivityMeta, type ApiDeployOptions, ApiHttp, type ApiHttpOptions, AuthMethod, type AuthMethodType, BLOCKED_EXTENSIONS, type BillingStatus, CALLER, type CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_TOKEN, type DeployBody, type DeployBodyContext, type DeployBodyCreator, type DeployFile, type DeployInput, type Deployment, type DeploymentCreateResponse, type DeploymentListResponse, type DeploymentOptions, type DeploymentResource, type DeploymentResourceContext, DeploymentStatus, type DeploymentStatusType, type DeploymentUploadOptions, type DnsProvider, type DnsRecord, type DnsRecordType, type Domain, type DomainDnsResponse, type DomainListResponse, type DomainRecordsResponse, type DomainResource, type DomainSetResult, DomainStatus, type DomainStatusType, type DomainValidateResponse, type ErrorResponse, ErrorType, type ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, type Fetch, type FileValidationResult, FileValidationStatus, type FileValidationStatusType, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, type MD5Result, OAuthScope, type OAuthScopeType, PASSWORD_CONSTRAINTS, type PingResponse, type PlatformLimits, type ProgressInfo, type ResourceContext, type SPACheckRequest, type SPACheckResponse, SPA_DEFAULT_CONFIG, Ship, type ShipClientOptions, ShipError, type ShipEvents, type StaticFile, type TokenCreateResponse, TokenKind, type TokenKindType, type TokenListItem, type TokenListResponse, type TokenProvider, type TokenResource, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, type UploadedFile, type UserVisibleActivityEvent, type ValidatableFile, type ValidationIssue, __setTestEnvironment, allValidFilesReady, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForNode, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validatePassword, validateToken };
+export { API_KEY, AUTH_BASE_PATH, type Account, type AccountGetResponse, type AccountOverrides, AccountPlan, type AccountPlanType, type AccountResource, type AccountUsage, type Activity, type ActivityEvent, type ActivityListResponse, type ActivityMeta, type ApiDeployOptions, ApiHttp, type ApiHttpOptions, AuthMethod, type AuthMethodType, BLOCKED_EXTENSIONS, type BillingStatus, CALLER, type CheckoutSession, DEFAULT_API, DEPLOYMENT_CONFIG_FILENAME, DEPLOY_TOKEN, type DeployBody, type DeployBodyContext, type DeployBodyCreator, type DeployFile, type DeployInput, type Deployment, type DeploymentCreateResponse, type DeploymentListResponse, type DeploymentOptions, type DeploymentResource, type DeploymentResourceContext, DeploymentStatus, type DeploymentStatusType, type DeploymentUploadOptions, type DnsProvider, type DnsRecord, type DnsRecordType, type Domain, type DomainDnsResponse, type DomainListResponse, type DomainRecordsResponse, type DomainResource, type DomainSetResult, DomainStatus, type DomainStatusType, type DomainValidateResponse, type ErrorResponse, ErrorType, type ExecutionEnvironment, FileValidationStatus as FILE_VALIDATION_STATUS, type Fetch, type FileValidationResult, FileValidationStatus, type FileValidationStatusType, JUNK_DIRECTORIES, LABEL_CONSTRAINTS, LABEL_PATTERN, type ListOptions, type MD5Result, OAuthScope, type OAuthScopeType, PASSWORD_CONSTRAINTS, type PingResponse, type PlatformLimits, type ResourceContext, type SPACheckRequest, type SPACheckResponse, SPA_DEFAULT_CONFIG, Ship, type ShipClientOptions, ShipError, type ShipEvents, type StaticFile, type TokenCreateResponse, TokenKind, type TokenKindType, type TokenListItem, type TokenListResponse, type TokenProvider, type TokenResource, UNBUILT_PROJECT_MARKERS, UNSAFE_FILENAME_CHARS, type UploadedFile, type UserVisibleActivityEvent, type ValidatableFile, type ValidationIssue, __setTestEnvironment, allValidFilesReady, calculateMD5, classifyToken, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, deserializeLabels, extractSubdomain, filterJunk, formatFileSize, generateDeploymentUrl, generateDomainUrl, getENV, getValidFiles, hasUnbuiltMarker, hasUnsafeChars, isBlockedExtension, isCustomDomain, isDeployment, isPlatformDomain, isShipError, optimizeDeployPaths, pluralize, processFilesForNode, serializeLabels, validateApiKey, validateApiUrl, validateCaller, validateDeployFile, validateDeployPath, validateDeployToken, validateFileName, validateFiles, validatePassword, validateToken };