@shipstatic/ship 0.8.17 → 0.9.1

package/README.md

@@ -123,7 +123,7 @@ ship ping
 ```typescript
 ship.account.get()            // → whoami
 ship.ping()                   // → boolean
-ship.getConfig()              // → platform config and plan limits (cached)
+ship.getLimits()              // → platform plan limits (cached)
 ```
 
 ## CLI Reference
@@ -260,11 +260,18 @@ try {
 
 ## Configuration
 
-Resolved in order of precedence:
+The **CLI** (`ship`) resolves credentials in this order:
 
-1. **Constructor options**: `new Ship({ apiUrl, apiKey })`
-2. **Environment variables**: `SHIP_API_URL`, `SHIP_API_KEY`
-3. **Config files**: `.shiprc` or `package.json` `"ship"` key
+1. CLI flags: `--api-key`, `--api-url`, `--deploy-token`
+2. Environment variables: `SHIP_API_KEY`, `SHIP_API_URL`, `SHIP_DEPLOY_TOKEN`
+3. Config files: `.shiprc` or `package.json` `"ship"` key (run `ship config` to create one)
+
+The **SDK** (`new Ship(...)`) resolves credentials in this order:
+
+1. Constructor options: `new Ship({ apiUrl, apiKey })`
+2. Environment variables: `SHIP_API_KEY`, `SHIP_API_URL`, `SHIP_DEPLOY_TOKEN`
+
+The SDK never reads `.shiprc` or `package.json` — file resolution is a CLI feature, not an SDK feature. This keeps `new Ship({})` safe to use from embedded contexts (MCP, n8n, library wrappers) without inheriting the host developer's personal credentials.
 
 ```bash
 SHIP_API_KEY=ship-... ship deployments list

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
 import * as _shipstatic_types from '@shipstatic/types';
-import { DeploymentUploadOptions, ProgressInfo, StaticFile, Domain, DeploymentCreateResponse, DeploymentListResponse, Deployment, DomainListResponse, DomainDnsResponse, DomainRecordsResponse, DomainValidateResponse, TokenCreateResponse, TokenListResponse, Account, ConfigResponse, ResolvedConfig, DeployInput, AccountResource, DeploymentResource, DomainResource, TokenResource, ValidatableFile, FileValidationResult } from '@shipstatic/types';
+import { DeploymentUploadOptions, ProgressInfo, StaticFile, DeploymentCreateResponse, DeploymentListResponse, Deployment, DomainSetResult, DomainListResponse, Domain, DomainDnsResponse, DomainRecordsResponse, DomainValidateResponse, TokenCreateResponse, TokenListResponse, Account, PlatformLimits, DeployInput, AccountResource, DeploymentResource, DomainResource, TokenResource, ResolvedConfig, ValidatableFile, FileValidationResult } from '@shipstatic/types';
 export * from '@shipstatic/types';
 export { Account, AccountResource, DEFAULT_API, DeployInput, Deployment, DeploymentResource, Domain, DomainResource, ErrorType, FileValidationStatus as FILE_VALIDATION_STATUS, PingResponse, ResolvedConfig, ShipError, StaticFile, TokenResource } from '@shipstatic/types';
 
@@ -9,14 +9,6 @@ export { Account, AccountResource, DEFAULT_API, DeployInput, Deployment, Deploym
  * Core types come from @shipstatic/types, while SDK-specific types are defined here.
  */
 
-/**
- * Domain set result with SDK-injected isCreate flag.
- * isCreate is derived from HTTP status code (201 = create, 200 = update)
- * and is not part of the Domain entity contract.
- */
-type DomainSetResult = Domain & {
-    isCreate: boolean;
-};
 /**
  * Universal deploy options for both Node.js and Browser environments.
  * Extends the API contract (DeploymentUploadOptions) with SDK-specific options.
@@ -95,8 +87,6 @@ interface ShipClientOptions {
     apiKey?: string | undefined;
     /** Deploy token for single-use deployments (format: token-<64-char-hex>, total 70 chars). */
     deployToken?: string | undefined;
-    /** Path to custom config file. */
-    configFile?: string | undefined;
     /**
      * Default callback for deploy progress for deploys made with this client.
      * @param info - Progress information including percentage and byte counts.
@@ -125,11 +115,23 @@ interface ShipClientOptions {
     /**
      * Default caller identifier for multi-tenant deployments.
      * Alphanumeric characters, dots, underscores, and hyphens allowed (max 128 chars).
+     *
+     * Used by orchestrators (e.g. n8n nodes processing many tenants from one
+     * worker) so the API's rate-limit bucket keys per caller rather than per
+     * shared IP. **Programmatic-only by design** — there is no `--caller`
+     * CLI flag because the CLI is a single-user tool (`via: 'cli'` is hardcoded
+     * in `performDeploy`); every CLI invocation belongs to one human, and
+     * a per-tenant rate-limit bucket would defeat the purpose.
      */
     caller?: string | undefined;
     /**
-     * Override the deploy endpoint path. Defaults to '/deployments'.
-     * Used by first-party clients to target alternative upload routes (e.g., '/upload').
+     * Override the deploy endpoint path. Defaults to `/deployments`.
+     *
+     * @internal First-party hook used by `web/my` and `web/www` to target the
+     * `/upload` route (which runs server-side build / SPA detection). External
+     * SDK consumers must not set this — the `/deployments` endpoint is the
+     * stable public contract. See `cloudflare/api/CLAUDE.md` for why the two
+     * endpoints exist and what `/upload` does that `/deployments` doesn't.
      */
     deployEndpoint?: string | undefined;
 }
@@ -152,12 +154,11 @@ interface ShipEvents {
  */
 
 /**
- * Lightweight event system
- * - Add handler: on()
- * - Remove handler: off()
- * - Emit events: emit() [internal]
- * - Transfer events: transfer() [internal]
- * - Reliable error handling and cleanup
+ * Lightweight typed event emitter.
+ *
+ * Public API: `on()` / `off()`. `emit()` is internal — only the SDK
+ * publishes events. Throwing handlers are evicted automatically and
+ * surfaced as `error` events on the next tick.
  */
 declare class SimpleEvents {
     private handlers;
@@ -174,16 +175,6 @@ declare class SimpleEvents {
      * @internal
      */
     emit<K extends keyof ShipEvents>(event: K, ...args: ShipEvents[K]): void;
-    /**
-     * Transfer all handlers to another events instance
-     * @internal
-     */
-    transfer(target: SimpleEvents): void;
-    /**
-     * Clear all handlers (for cleanup)
-     * @internal
-     */
-    clear(): void;
 }
 
 /**
@@ -208,10 +199,6 @@ declare class ApiHttp extends SimpleEvents {
      * Priority: globalHeaders (lowest) < instance auth < per-request headers (highest)
      */
     setGlobalHeaders(headers: Record<string, string>): void;
-    /**
-     * Transfer events to another client
-     */
-    transferEventsTo(target: ApiHttp): void;
     /**
      * Execute HTTP request with timeout, events, and error handling
      */
@@ -254,34 +241,11 @@ declare class ApiHttp extends SimpleEvents {
     removeToken(token: string): Promise<void>;
     fetchAgentToken(): Promise<TokenCreateResponse>;
     getAccount(): Promise<Account>;
-    getConfig(): Promise<ConfigResponse>;
+    getLimits(): Promise<PlatformLimits>;
     ping(): Promise<boolean>;
     checkSPA(files: StaticFile[], options?: ApiDeployOptions): Promise<boolean>;
 }
 
-/**
- * @file Shared configuration logic for both environments.
- *
- * CONFIGURATION PRECEDENCE (highest to lowest):
- * 1. Constructor options / CLI flags (passed directly to Ship())
- * 2. Environment variables (SHIP_API_KEY, SHIP_DEPLOY_TOKEN, SHIP_API_URL)
- * 3. Config file (.shiprc or package.json "ship" key)
- * 4. Default values (DEFAULT_API)
- *
- * This means CLI flags always win, followed by env vars, then config files.
- */
-
-/**
- * Universal configuration resolver for all environments.
- * This is the single source of truth for config resolution.
- */
-declare function resolveConfig(userOptions?: ShipClientOptions, loadedConfig?: Partial<ShipClientOptions>): ResolvedConfig;
-/**
- * Merge deployment options with client defaults.
- * This is shared logic used by both environments.
- */
-declare function mergeDeployOptions(options: DeploymentOptions, clientDefaults: ShipClientOptions): DeploymentOptions;
-
 /**
  * Ship SDK resource factory functions.
  */
@@ -324,75 +288,45 @@ declare function createTokenResource(ctx: ResourceContext): TokenResource;
 
 /**
  * Abstract base class for Ship SDK implementations.
- *
- * Provides shared functionality while allowing environment-specific
- * implementations to handle configuration loading and deployment processing.
  */
 declare abstract class Ship$1 {
-    protected http: ApiHttp;
-    protected readonly clientOptions: ShipClientOptions;
-    protected initPromise: Promise<void> | null;
-    protected _config: ConfigResponse | null;
+    readonly deployments: DeploymentResource;
+    readonly domains: DomainResource;
+    readonly account: AccountResource;
+    readonly tokens: TokenResource;
+    private readonly http;
+    private readonly clientOptions;
+    private initPromise;
+    protected platformLimits: PlatformLimits | null;
     private auth;
-    private customHeaders;
-    protected readonly authHeadersCallback: () => Record<string, string>;
-    protected _deployments: DeploymentResource;
-    protected _domains: DomainResource;
-    protected _account: AccountResource;
-    protected _tokens: TokenResource;
     constructor(options?: ShipClientOptions);
-    protected abstract resolveInitialConfig(options: ShipClientOptions): ResolvedConfig;
-    protected abstract loadFullConfig(): Promise<void>;
     protected abstract processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
     protected abstract getDeployBodyCreator(): DeployBodyCreator;
     /**
-     * Ensure full initialization is complete - called lazily by resources
+     * Lazy initialization — fetches platform limits (file size / count caps) once,
+     * on the first API call. Subsequent calls reuse the resolved promise.
      */
     protected ensureInitialized(): Promise<void>;
+    private fetchPlatformLimits;
     /**
-     * Ping the API server to check connectivity
+     * Ping the API server to check connectivity.
      */
     ping(): Promise<boolean>;
     /**
-     * Deploy project (convenience shortcut to ship.deployments.upload())
+     * Deploy project (convenience shortcut to `ship.deployments.upload()`).
      */
     deploy(input: DeployInput, options?: DeploymentOptions): Promise<Deployment>;
     /**
-     * Get current account information (convenience shortcut to ship.account.get())
+     * Get current account information (convenience shortcut to `ship.account.get()`).
      */
     whoami(): Promise<_shipstatic_types.Account>;
     /**
-     * Get deployments resource (environment-specific)
-     */
-    get deployments(): DeploymentResource;
-    /**
-     * Get domains resource
-     */
-    get domains(): DomainResource;
-    /**
-     * Get account resource
-     */
-    get account(): AccountResource;
-    /**
-     * Get tokens resource
-     */
-    get tokens(): TokenResource;
-    /**
-     * Get API configuration (file upload limits, etc.)
-     * Reuses platform config fetched during initialization, then caches the result
-     */
-    getConfig(): Promise<ConfigResponse>;
-    /**
-     * Add event listener
-     * @param event - Event name
-     * @param handler - Event handler function
+     * Get platform limits (max file size, file count, total size).
+     * Reuses the response fetched during initialization. Per-instance state —
+     * does not leak between concurrent Ships against different API URLs.
      */
+    getLimits(): Promise<PlatformLimits>;
     on<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
-    /**
-     * Remove event listener
-     * @param event - Event name
-     * @param handler - Event handler function
-     */
     off<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
     /**
      * Set global headers included in every request.
@@ -403,38 +337,60 @@ declare abstract class Ship$1 {
      * Clear all custom global headers.
      */
     clearHeaders(): void;
-    /**
-     * Replace HTTP client while preserving event listeners
-     * Used during initialization to maintain user event subscriptions
-     * @protected
-     */
-    protected replaceHttpClient(newClient: ApiHttp): void;
     /**
      * Sets the deploy token for authentication.
-     * This will override any previously set API key or deploy token.
-     * @param token The deploy token (format: token-<64-char-hex>)
+     * Overrides any previously set API key or deploy token.
+     * @param token Deploy token (format: `token-<64-char-hex>`)
      */
     setDeployToken(token: string): void;
     /**
      * Sets the API key for authentication.
-     * This will override any previously set API key or deploy token.
-     * @param key The API key (format: ship-<64-char-hex>)
+     * Overrides any previously set API key or deploy token.
+     * @param key API key (format: `ship-<64-char-hex>`)
      */
     setApiKey(key: string): void;
-    /**
-     * Generate authorization headers based on current auth state
-     * Called dynamically on each request to ensure latest credentials are used
-     * @private
-     */
     private getAuthHeaders;
     /**
-     * Check if authentication credentials are configured
-     * Used by resources to fail fast if auth is required
-     * @private
+     * Check whether authentication credentials are configured.
+     * Used by resources to fail fast (or trigger the agent-token fallback) when
+     * auth is required.
      */
     private hasAuth;
 }
 
+/**
+ * @file Cross-platform configuration helpers.
+ *
+ * Two pure helpers used by both Node and Browser:
+ *
+ *   - `resolveConfig(options)` — applies the API-URL default. The Node Ship
+ *     calls this after merging env vars under the user's options; the Browser
+ *     Ship calls it directly (no ambient sources).
+ *   - `mergeDeployOptions(perCallOptions, clientDefaults)` — overlays
+ *     instance-level defaults under per-call overrides for a single deploy.
+ *
+ * Credential precedence is owned by callers, not this file:
+ *
+ *   - SDK (Node): constructor args > `SHIP_*` env vars (see `node/index.ts`)
+ *   - SDK (Browser): constructor args only
+ *   - CLI: `--flag` > env > `.shiprc` / `package.json` (see `cli/create-client.ts`)
+ */
+
+/**
+ * Apply the API-URL default and project the credential triplet into a
+ * `ResolvedConfig` shape. Optional fields are omitted (rather than set to
+ * `undefined`) so spread merges downstream behave predictably.
+ */
+declare function resolveConfig(options?: ShipClientOptions): ResolvedConfig;
+/**
+ * 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;
+
 interface MD5Result {
     md5: string;
 }
@@ -615,12 +571,12 @@ declare function validateFileName(filename: string): {
  * - **Warnings**: Exclude files but allow deployment (empty files, etc.)
  *
  * @param files - Array of files to validate
- * @param config - Validation configuration from ship.getConfig()
+ * @param config - Validation configuration from ship.getLimits()
  * @returns Validation result with errors and warnings
  *
  * @example
  * ```typescript
- * const config = await ship.getConfig();
+ * const config = await ship.getLimits();
  * const result = validateFiles(files, config);
  *
  * if (!result.canDeploy) {
@@ -636,7 +592,7 @@ declare function validateFileName(filename: string): {
  * }
  * ```
  */
-declare function validateFiles<T extends ValidatableFile>(files: T[], config: ConfigResponse): FileValidationResult<T>;
+declare function validateFiles<T extends ValidatableFile>(files: T[], config: PlatformLimits): FileValidationResult<T>;
 /**
  * Get only the valid files from validation results
  */
@@ -675,21 +631,6 @@ declare function validateDeployPath(deployPath: string, sourceIdentifier: string
  */
 declare function validateDeployFile(deployPath: string, sourceIdentifier: string): void;
 
-/**
- * @file Platform configuration management for the Ship SDK.
- * Implements fail-fast dynamic configuration with mandatory API fetch.
- */
-
-/**
- * Set the current config (called after fetching from API)
- */
-declare function setConfig(config: ConfigResponse): void;
-/**
- * Get current config - throws if not initialized (fail-fast approach)
- * @throws {ShipError.config} If configuration hasn't been fetched from API
- */
-declare function getCurrentConfig(): ConfigResponse;
-
 /**
  * @file Browser-specific file utilities for the Ship SDK.
  * Provides helpers for processing browser files into deploy-ready objects.
@@ -711,42 +652,52 @@ declare function getCurrentConfig(): ConfigResponse;
  *
  * @param browserFiles - File[] to process for deploy.
  * @param options - Processing options including pathDetect for automatic path optimization.
+ * @param platformLimits - Per-instance platform limits (file-size / count / total-size caps)
+ *   from the originating Ship's `GET /config` 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.
  * @throws {ShipError} If called outside a browser or with invalid input.
  */
-declare function processFilesForBrowser(browserFiles: File[], options?: DeploymentOptions): Promise<StaticFile[]>;
+declare function processFilesForBrowser(browserFiles: File[], options?: DeploymentOptions, platformLimits?: PlatformLimits): Promise<StaticFile[]>;
 
 /**
- * @file Ship SDK for browser environments with streamlined configuration.
+ * @file Ship SDK for browser environments.
+ *
+ * Configuration is fully explicit — the browser has no env vars or config files
+ * to inherit. All credentials are supplied via constructor options (or, for
+ * first-party browser apps, an HTTP-only cookie via `useCredentials: true`).
  */
 
 /**
  * Ship SDK Client for browser environments.
  *
- * Optimized for browser compatibility with no Node.js dependencies.
- * Configuration is provided explicitly through constructor options.
- *
  * @example
  * ```typescript
- * // Deploy with token obtained from server
+ * // Deploy with a token obtained from your server
  * const ship = new Ship({
- *   deployToken: "token-xxxx",
- *   apiUrl: "https://api.shipstatic.com"
+ *   deployToken: 'token-xxxx',
+ *   apiUrl: 'https://api.shipstatic.com',
  * });
  *
- * // Deploy files from input element
  * const files = Array.from(fileInput.files);
  * await ship.deploy(files);
  * ```
  */
 declare class Ship extends Ship$1 {
-    constructor(options?: ShipClientOptions);
-    protected resolveInitialConfig(options: ShipClientOptions): ResolvedConfig;
-    protected loadFullConfig(): Promise<void>;
+    /**
+     * Deploy `File[]` (typically from `<input type="file">` or drag-and-drop)
+     * to ShipStatic. Convenience shortcut for `ship.deployments.upload()`.
+     *
+     * Wrong-platform inputs (e.g. string paths) fail at compile time. For
+     * platform-neutral code, use `ship.deployments.upload()`, which accepts
+     * the wider `DeployInput` and validates at runtime — that asymmetry is
+     * intentional: the convenience shortcut narrows; the resource-layer
+     * contract stays platform-neutral.
+     */
+    deploy(input: File[], options?: DeploymentOptions): Promise<Deployment>;
     protected processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
-    /** Type guard that validates all elements are File objects */
-    private isFileArray;
     protected getDeployBodyCreator(): DeployBodyCreator;
 }
 
-export { type ApiDeployOptions, ApiHttp, type ApiHttpOptions, type DeployBody, type DeployBodyContext, type DeployBodyCreator, type DeployFile, type DeploymentOptions, type DeploymentResourceContext, type DomainSetResult, type ExecutionEnvironment, JUNK_DIRECTORIES, type MD5Result, type ResourceContext, Ship, type ShipClientOptions, type ShipEvents, __setTestEnvironment, allValidFilesReady, calculateMD5, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, filterJunk, formatFileSize, getCurrentConfig, getENV, getValidFiles, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForBrowser, resolveConfig, setConfig as setPlatformConfig, validateDeployFile, validateDeployPath, validateFileName, validateFiles };
+export { type ApiDeployOptions, ApiHttp, type ApiHttpOptions, type DeployBody, type DeployBodyContext, type DeployBodyCreator, type DeployFile, type DeploymentOptions, type DeploymentResourceContext, type ExecutionEnvironment, JUNK_DIRECTORIES, type MD5Result, type ResourceContext, Ship, type ShipClientOptions, type ShipEvents, __setTestEnvironment, allValidFilesReady, calculateMD5, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, filterJunk, formatFileSize, getENV, getValidFiles, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForBrowser, resolveConfig, validateDeployFile, validateDeployPath, validateFileName, validateFiles };