@shipstatic/ship 1.0.2 → 2.0.0-beta.0

package/dist/index.d.cts

@@ -1,7 +1,1102 @@
-import * as _shipstatic_types 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';
+/**
+ * @file Shared TypeScript types, constants, and utilities for the ShipStatic platform.
+ * This package is the single source of truth for all shared data structures.
+ */
+/**
+ * Deployment status constants
+ */
+declare const DeploymentStatus: {
+    readonly PENDING: "pending";
+    readonly SUCCESS: "success";
+    readonly FAILED: "failed";
+    readonly DELETING: "deleting";
+};
+type DeploymentStatusType = typeof DeploymentStatus[keyof typeof DeploymentStatus];
+/**
+ * Core deployment object - used in both API responses and SDK
+ */
+interface Deployment {
+    /** The deployment hostname (e.g., 'happy-cat-abc1234.shipstatic.com') */
+    readonly deployment: string;
+    /** Full URL to the deployment (e.g., 'https://happy-cat-abc1234.shipstatic.com') */
+    readonly url: string;
+    /** Number of files in this deployment */
+    readonly files: number;
+    /** Total size of all files in bytes */
+    readonly size: number;
+    /** Current deployment status */
+    status: DeploymentStatusType;
+    /** Whether deployment has a ship.json config */
+    readonly config: boolean;
+    /** Whether deployment has a password set */
+    readonly password: boolean;
+    /** Labels for categorization and filtering (lowercase, alphanumeric with separators). Always present, empty array when none. */
+    labels: string[];
+    /** The client/tool used to create this deployment (e.g., 'web', 'sdk', 'cli'), null if unknown */
+    readonly via: string | null;
+    /** Unix timestamp (seconds) when deployment was created */
+    readonly created: number;
+    /** Unix timestamp (seconds) when deployment expires, null if never */
+    expires: number | null;
+    /** Full URL to the deployment screenshot (e.g., 'https://screenshots.shipstatic.com/happy-cat-abc1234/a3f2c1b4d5e6f789') */
+    readonly screenshot: string;
+}
+/**
+ * Response from deployment creation. Extends Deployment with one-time fields
+ * only present on creation (not on subsequent GET requests).
+ */
+interface DeploymentCreateResponse extends Deployment {
+    /** Claim URL for public deployments. Present when deployed without credentials. */
+    readonly claim?: string;
+}
+/**
+ * Response for listing deployments
+ */
+interface DeploymentListResponse {
+    /** Array of deployments */
+    deployments: Deployment[];
+    /** Cursor for pagination, null if no more pages */
+    cursor: string | null;
+    /** Total number of deployments */
+    total: number;
+}
+/**
+ * Domain status constants
+ *
+ * - PENDING: DNS not configured
+ * - PARTIAL: DNS partially configured
+ * - SUCCESS: DNS fully verified
+ * - PAUSED: Domain paused due to plan enforcement (billing)
+ */
+declare const DomainStatus: {
+    readonly PENDING: "pending";
+    readonly PARTIAL: "partial";
+    readonly SUCCESS: "success";
+    readonly PAUSED: "paused";
+};
+type DomainStatusType = typeof DomainStatus[keyof typeof DomainStatus];
+/**
+ * Core domain object - used in both API responses and SDK
+ */
+interface Domain {
+    /** The domain name */
+    readonly domain: string;
+    /** Full URL to the domain (e.g., 'https://www.example.com') */
+    readonly url: string;
+    /** The deployment hostname this domain points to (null = domain added but not yet linked) */
+    deployment: string | null;
+    /** Current domain status */
+    status: DomainStatusType;
+    /** Labels for categorization and filtering (lowercase, alphanumeric with separators). Always present, empty array when none. */
+    labels: string[];
+    /** Unix timestamp (seconds) when domain was created */
+    readonly created: number;
+    /** When deployment was last linked (Unix timestamp), null if never linked */
+    linked: number | null;
+    /** Total deployment links */
+    links: number;
+}
+/**
+ * Return shape of `domains.set()` — `Domain` plus an SDK-derived flag indicating
+ * whether the underlying `PUT /domains/:name` created the record (HTTP 201) or
+ * updated an existing one (HTTP 200).
+ *
+ * `isCreate` is not part of the wire format — the API returns a plain `Domain`
+ * body. The SDK derives the flag from the HTTP status code so callers (notably
+ * the CLI) can format different output for the create vs repoint paths without
+ * a second round-trip.
+ */
+interface DomainSetResult extends Domain {
+    /** `true` when this call created a new domain; `false` when it updated an existing one. */
+    isCreate: boolean;
+}
+/**
+ * Response for listing domains
+ */
+interface DomainListResponse {
+    /** Array of domains */
+    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
+ */
+type DnsRecordType = 'A' | 'CNAME';
+/**
+ * DNS record required for domain configuration
+ */
+interface DnsRecord {
+    /** Record type (A for apex, CNAME for subdomains) */
+    type: DnsRecordType;
+    /** The DNS name to configure */
+    name: string;
+    /** The value to set (IP for A, hostname for CNAME) */
+    value: string;
+}
+/**
+ * DNS provider information for a domain
+ */
+interface DnsProvider {
+    /** Provider name (e.g., "Cloudflare", "GoDaddy"), null if unknown */
+    name: string | null;
+}
+/**
+ * Response for domain DNS provider lookup
+ */
+interface DomainDnsResponse {
+    /** The domain name */
+    domain: string;
+    /** DNS provider information, null if not yet looked up */
+    dns: {
+        provider?: DnsProvider;
+    } | null;
+}
+/**
+ * Response for domain DNS records
+ */
+interface DomainRecordsResponse {
+    /** The domain name */
+    domain: string;
+    /** The apex (registered) domain where DNS records are managed */
+    apex: string;
+    /** Required DNS records for configuration */
+    records: DnsRecord[];
+}
+/**
+ * Response for domain validation
+ */
+interface DomainValidateResponse {
+    /** Whether the domain is valid */
+    valid: boolean;
+    /** Normalized domain name, null when invalid */
+    normalized: string | null;
+    /** Whether the domain is available, null when invalid */
+    available: boolean | null;
+    /** Error message, null when valid */
+    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.
+ */
+interface TokenListItem {
+    /** 7-char management identifier (e.g., "a1b2c3d") */
+    readonly token: string;
+    /** Labels for categorization and filtering. Always present, empty array when none. */
+    labels: string[];
+    /** Unix timestamp (seconds) when token was created */
+    readonly created: number;
+    /** Unix timestamp (seconds) when token expires, null for never */
+    readonly expires: number | null;
+    /** Unix timestamp (seconds) of the last request authenticated with this token, null if never used */
+    readonly used: number | null;
+}
+/**
+ * Response for listing tokens
+ */
+interface TokenListResponse {
+    /** Array of tokens (security-redacted for list display) */
+    tokens: TokenListItem[];
+    /** Total number of tokens */
+    total: number;
+}
+/**
+ * Response for token creation
+ */
+interface TokenCreateResponse {
+    /** 7-char management identifier */
+    token: string;
+    /** 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;
+}
+/**
+ * Account plan constants
+ */
+declare const AccountPlan: {
+    readonly FREE: "free";
+    readonly STANDARD: "standard";
+    readonly SPONSORED: "sponsored";
+    readonly ENTERPRISE: "enterprise";
+    readonly SUSPENDED: "suspended";
+    readonly TERMINATING: "terminating";
+    readonly TERMINATED: "terminated";
+};
+type AccountPlanType = typeof AccountPlan[keyof typeof AccountPlan];
+/**
+ * Account usage metrics — always available regardless of billing provider.
+ */
+interface AccountUsage {
+    /** Number of active custom domains (excludes paused) */
+    customDomains: number;
+}
+/**
+ * Core account object - used in both API responses and SDK
+ * All fields are readonly to prevent accidental mutations
+ */
+interface Account {
+    /** User email address */
+    readonly email: string;
+    /** User display name, null if not set */
+    readonly name: string | null;
+    /** User profile picture URL, null if not set */
+    readonly picture: string | null;
+    /** Account plan status */
+    readonly plan: AccountPlanType;
+    /** Account usage metrics (custom domains, etc.) */
+    readonly usage: AccountUsage;
+    /** Unix timestamp (seconds) when account was created */
+    readonly created: number;
+    /** Unix timestamp (seconds) when account was activated (first deployment), null if not yet activated */
+    readonly activated: number | null;
+    /** Last 4 characters of the API key for identification, null when no key generated */
+    readonly hint: string | null;
+    /** Grace period expiration (unix seconds), null if no grace period active */
+    readonly grace: number | null;
+}
+/**
+ * Account as returned by `GET /account` — the entity plus how the request
+ * was authorized, so `whoami` can answer "what credential am I holding?".
+ * Request-scoped fields live on the response type, never on the entity
+ * (the `DeploymentCreateResponse` pattern).
+ */
+interface AccountGetResponse extends Account {
+    /** How the request that produced this response was authorized. */
+    readonly authMethod: AuthMethodType;
+    /** Present (and true) only when the caller is an operator acting as themselves. */
+    readonly isAdmin?: true;
+    /** Present only during read-only admin impersonation: the operator's account id. */
+    readonly impersonatedBy?: string;
+}
+/**
+ * Account-specific configuration overrides
+ * Allows per-account customization of limits without changing plan
+ */
+interface AccountOverrides {
+    /** Override for maximum number of domains */
+    domains?: number;
+    /** Override for maximum number of deployments */
+    deployments?: number;
+    /** Override for maximum individual file size in bytes */
+    fileSize?: number;
+    /** Override for maximum number of files per deployment */
+    filesCount?: number;
+    /** Override for maximum total deployment size in bytes */
+    totalSize?: number;
+}
+/**
+ * All possible error types in the ShipStatic platform.
+ *
+ * Developer-friendly key names map to stable wire-format string values.
+ * Both the value and the type are exported under the same name so callers
+ * can use `ErrorType.Validation` (value comparison) and `: ErrorType` (type
+ * annotation) without ceremony — matching the pattern other status objects
+ * (`DeploymentStatus`, `DomainStatus`, `AccountPlan`, `AuthMethod`) follow.
+ */
+declare const ErrorType: {
+    /** Validation failed (400). Input shape is wrong. */
+    readonly Validation: "validation_failed";
+    /** Resource not found (404). */
+    readonly NotFound: "not_found";
+    /** Authenticated but not allowed (403). User lacks permission for this action. */
+    readonly Forbidden: "forbidden";
+    /** Rate limit exceeded (429). */
+    readonly RateLimit: "rate_limit_exceeded";
+    /** Authentication required or failed (401). Missing/invalid credentials. */
+    readonly Authentication: "authentication_failed";
+    /** Business rule violation. Catch-all for 4xx state-rule errors that aren't more specific. */
+    readonly Business: "business_logic_error";
+    /** API server error (500). Generic server-side fault. */
+    readonly Api: "internal_server_error";
+    /** Network/connection error. Client-side only — set by HTTP clients on fetch failure; never produced server-side. */
+    readonly Network: "network_error";
+    /** Operation was cancelled. Client-side only — set on `AbortSignal` abort; never produced server-side. */
+    readonly Cancelled: "operation_cancelled";
+    /** File operation error. Client-side only — set by SDK during local file processing; never produced server-side. */
+    readonly File: "file_error";
+    /** Configuration error. Client-side only — set by SDK during config parsing/validation; never produced server-side. */
+    readonly Config: "config_error";
+};
+type ErrorType = typeof ErrorType[keyof typeof ErrorType];
+/**
+ * Standard error response format used everywhere
+ */
+interface ErrorResponse {
+    /** Error type identifier */
+    error: ErrorType;
+    /** Human-readable error message */
+    message: string;
+    /** HTTP status code (API contexts) */
+    status?: number;
+    /** Optional additional error details. Untyped by design — narrow at the read site. */
+    details?: unknown;
+}
+/**
+ * Simple unified error class for both API and SDK
+ */
+declare class ShipError extends Error {
+    readonly type: ErrorType;
+    readonly status?: number | undefined;
+    readonly details?: unknown | undefined;
+    constructor(type: ErrorType, message: string, status?: number | undefined, details?: unknown | undefined);
+    /** Convert to wire format */
+    toResponse(): ErrorResponse;
+    /**
+     * Construct a `ShipError` from an HTTP error response.
+     *
+     * Best-effort body parse for `{ message, error?, details? }`. Message
+     * resolution: `body.message` → `body.error` → `"<operationName> failed with
+     * status <N>"`.
+     *
+     * Type resolution: trusts `body.error` when it's a known server-producible
+     * `ErrorType` (preserves the wire's intent — server's
+     * `ShipError.validation(...)` round-trips back to `ErrorType.Validation`
+     * on the client). Falls back to status-derived (401 → Authentication,
+     * 403 → Forbidden, 429 → RateLimit, else → Api) for non-API responses
+     * (CDN errors, intermediaries) or malformed bodies. Client-only types
+     * (`Network`, `Cancelled`, `File`, `Config`) are filtered out of the
+     * trusted set — a misbehaving server claiming one of those is ignored.
+     *
+     * `operationName` (e.g. `"Get account"`) is used to compose the fallback
+     * message. Defaults to `"Request"`. Same convention as `fromFetchError`.
+     *
+     * Async because it reads the response body. Returns rather than throws so
+     * callers can compose; most will `throw await ShipError.fromHttpResponse(...)`.
+     */
+    static fromHttpResponse(response: Response, operationName?: string): Promise<ShipError>;
+    /**
+     * Construct a `ShipError` from an error caught around a `fetch()` call.
+     *
+     * The mirror of `fromHttpResponse` for the *other* side of the HTTP error
+     * story — the network layer failing (offline, CORS, abort) rather than the
+     * server returning a non-OK response.
+     *
+     * Routing:
+     * - Already a `ShipError` → returned as-is (caller's intent preserved)
+     * - `AbortError` → `ShipError.cancelled(...)`
+     * - `TypeError` whose message mentions "fetch" → `ShipError.network(...)`
+     * - Any other `Error` → `ShipError(Api, ...)` (no HTTP status — fetch never reached the server)
+     * - Anything else (string, undefined, etc.) → `ShipError(Api, ...)`
+     *
+     * The optional `operationName` is composed into the message for context:
+     * `"Get account was cancelled"`, `"Get account failed: ..."`. Defaults to
+     * `"Request"` when omitted.
+     */
+    static fromFetchError(cause: unknown, operationName?: string): ShipError;
+    static validation(message: string, details?: unknown): ShipError;
+    static notFound(resource: string, id?: string): ShipError;
+    static forbidden(message: string, details?: unknown): ShipError;
+    static rateLimit(message?: string, details?: unknown): ShipError;
+    /**
+     * Construct an Authentication (401) error.
+     *
+     * **Telemetry pattern — `details: { internal: '<tag>' }`.** When the
+     * server creates an auth error with an `internal` key in `details`
+     * (e.g. `{ internal: 'session_invalid' }`), `toResponse()` strips the
+     * entire `details` object before serialization. This keeps the wire
+     * response a clean "Authentication failed" while preserving granular
+     * server-side telemetry (which strategy/check failed) for logs and tests.
+     *
+     * Use this pattern in API auth code; do not put client-visible info under
+     * `internal`. Other `details` keys round-trip normally.
+     */
+    static authentication(message?: string, details?: unknown): ShipError;
+    static business(message: string, status?: number, details?: unknown): ShipError;
+    static network(message: string, details?: unknown): ShipError;
+    static cancelled(message: string, details?: unknown): ShipError;
+    static file(message: string, details?: unknown): ShipError;
+    static config(message: string, details?: unknown): ShipError;
+    static api(message: string, status?: number, details?: unknown): ShipError;
+    isClientError(): boolean;
+    isNetworkError(): boolean;
+    isAuthError(): boolean;
+    isType(errorType: ErrorType): boolean;
+}
+/**
+ * Type guard to check if an unknown value is a ShipError.
+ *
+ * Uses structural checking instead of instanceof to handle module duplication
+ * in bundled applications where multiple copies of the ShipError class may exist.
+ *
+ * @example
+ * if (isShipError(error)) {
+ *   console.log(error.status, error.message);
+ * }
+ */
+declare function isShipError(error: unknown): error is ShipError;
+/**
+ * Plan-based platform limits returned by the `/limits` endpoint.
+ *
+ * The SDK fetches these once on first API call to drive client-side
+ * file-size / file-count / total-size validation that mirrors what the API
+ * would enforce server-side. Limits vary by account plan.
+ *
+ * These are the *platform's* posted caps for the current account — server
+ * truth delivered at runtime, never hard-coded on the client.
+ */
+interface PlatformLimits {
+    /** Maximum size in bytes for a single file. */
+    maxFileSize: number;
+    /** Maximum number of files in a single deployment. */
+    maxFilesCount: number;
+    /** Maximum total size in bytes across all files in a deployment. */
+    maxTotalSize: number;
+}
+/**
+ * Blocked file extensions — files that cannot be uploaded.
+ *
+ * We accept any file type by default and derive Content-Type from the
+ * extension at serve time (via mime-db in the API worker). Unknown extensions
+ * are served as `application/octet-stream` with `X-Content-Type-Options: nosniff`.
+ *
+ * The blocklist targets file types that pose direct security risks when hosted:
+ * executables, disk images, malware vectors, dangerous scripts, and shortcuts.
+ */
+declare const BLOCKED_EXTENSIONS: ReadonlySet<string>;
+/**
+ * Check if a filename has a blocked extension.
+ * Extracts the extension from the filename and checks against the blocklist.
+ * Case-insensitive. Returns false for files without extensions.
+ *
+ * @example
+ * isBlockedExtension('virus.exe')     // true
+ * isBlockedExtension('app.dmg')       // true
+ * isBlockedExtension('style.css')     // false
+ * isBlockedExtension('data.custom')   // false
+ * isBlockedExtension('README')        // false
+ */
+declare function isBlockedExtension(filename: string): boolean;
+/**
+ * Characters that are unsafe in filenames for static hosting.
+ *
+ * Blocks only characters that genuinely break the upload→serve round-trip:
+ * - # ? %        URL round-trip breakers (fragment, query, encoding ambiguity)
+ * - \            Path separator confusion (upload splits on backslash)
+ * - < > "        XSS vectors with zero legitimate use in filenames
+ * - \x00-\x1f \x7f  Control characters (header injection, display corruption)
+ *
+ * Everything else is allowed — browser percent-encodes, Worker decodes, R2 matches.
+ */
+declare const UNSAFE_FILENAME_CHARS: RegExp;
+/**
+ * Check if a filename contains unsafe characters.
+ *
+ * @example
+ * hasUnsafeChars('saved_resource(1).html')  // false — parentheses are safe
+ * hasUnsafeChars('page[slug].js')           // false — brackets are safe
+ * hasUnsafeChars('file#anchor.html')        // true  — # breaks URL resolution
+ * hasUnsafeChars('file<tag>.html')          // true  — < is an XSS vector
+ */
+declare function hasUnsafeChars(filename: string): boolean;
+/**
+ * Path segment names that indicate an unbuilt project was uploaded instead of build output.
+ * Used for early detection in CLI, browser, and server validation.
+ */
+declare const UNBUILT_PROJECT_MARKERS: ReadonlySet<string>;
+/**
+ * Check if a file path contains an unbuilt project marker.
+ *
+ * @example
+ * hasUnbuiltMarker('node_modules/react/index.js')  // true
+ * hasUnbuiltMarker('package.json')                  // true
+ * hasUnbuiltMarker('dist/index.html')               // false
+ */
+declare function hasUnbuiltMarker(filePath: string): boolean;
+/**
+ * Simple ping response for health checks
+ */
+interface PingResponse {
+    /** Always true if service is healthy */
+    success: boolean;
+    /** Optional timestamp */
+    timestamp?: number;
+}
+/**
+ * How a request (or recorded activity) was authorized.
+ *
+ * Client populations: `SESSION` (first-party cookie), `API_KEY` (`ship-`
+ * key), `TOKEN` (`deploy-` deploy token), `AGENT` (anonymous public deploy —
+ * no credential; the platform grants the public-account identity per
+ * request), `OAUTH` (delegated access token). Server populations: `WEBHOOK`
+ * (signed webhook processing), `SYSTEM` (scheduled/background jobs).
+ */
+declare const AuthMethod: {
+    readonly SESSION: "session";
+    readonly API_KEY: "apiKey";
+    readonly TOKEN: "token";
+    readonly AGENT: "agent";
+    readonly OAUTH: "oauth";
+    readonly WEBHOOK: "webhook";
+    readonly SYSTEM: "system";
+};
+type AuthMethodType = typeof AuthMethod[keyof typeof AuthMethod];
+/**
+ * Shape constants for API keys (`ship-{64 hex chars}`).
+ * Single source of truth used by validation utilities and auth middleware.
+ */
+declare const API_KEY: {
+    /** Prefix that identifies an API key. */
+    readonly PREFIX: "ship-";
+    /** Number of hex characters following the prefix. */
+    readonly HEX_LENGTH: 64;
+    /** Total length of an API key including prefix (`PREFIX.length + HEX_LENGTH = 69`). */
+    readonly TOTAL_LENGTH: 69;
+    /** Number of trailing characters used to display a redacted hint (e.g. last 4). */
+    readonly HINT_LENGTH: 4;
+};
+/**
+ * Shape constants for deploy tokens (`deploy-{64 hex chars}`).
+ * Single source of truth used by validation utilities and auth middleware.
+ */
+declare const DEPLOY_TOKEN: {
+    /** Prefix that identifies a deploy token. */
+    readonly PREFIX: "deploy-";
+    /** Number of hex characters following the prefix. */
+    readonly HEX_LENGTH: 64;
+    /** Total length of a deploy token including prefix (`PREFIX.length + HEX_LENGTH = 71`). */
+    readonly TOTAL_LENGTH: 71;
+};
+/**
+ * Shape constants for caller identifiers (the `X-Caller` instance-identity
+ * header — rate-limit bucketing for multi-tenant orchestrators). The API
+ * normalizes case and silently ignores malformed values (the header is
+ * unauthenticated); clients validate at the boundary via `validateCaller`,
+ * so a value the server would drop fails fast instead.
+ */
+declare const CALLER: {
+    /** HTTP header name. */
+    readonly HEADER: "X-Caller";
+    /** Maximum identifier length. */
+    readonly MAX_LENGTH: 128;
+    /** Allowed characters: alphanumeric, dot, underscore, hyphen. */
+    readonly PATTERN: RegExp;
+};
+/**
+ * Token populations distinguishable by shape. The platform carries every
+ * client token in one wire slot (`Authorization: Bearer <value>`) and
+ * classifies by value, never by a side channel — this is the classifier.
+ *
+ * `API_KEY` and `DEPLOY_TOKEN` *are* `AuthMethod.API_KEY` and
+ * `AuthMethod.TOKEN` — the equality is structural, so a classification flows
+ * straight into an auth method and the pair can never drift. `OPAQUE` is any
+ * other value — shape says nothing about it, so only a lookup can. Today the
+ * server refuses every opaque bearer; the OAuth access-token population
+ * resolves there when the authorization server ships.
+ */
+declare const TokenKind: {
+    readonly API_KEY: "apiKey";
+    readonly DEPLOY_TOKEN: "token";
+    readonly OPAQUE: "opaque";
+};
+type TokenKindType = typeof TokenKind[keyof typeof TokenKind];
+/**
+ * Classify a client token by shape. The single dispatch used by both sides
+ * of the wire: API auth middleware (which population is this credential?)
+ * and SDK validation (which format rules apply before sending?). Sharing it
+ * is what guarantees client and server can never disagree on dispatch.
+ */
+declare function classifyToken(token: string): TokenKindType;
+/**
+ * OAuth scope vocabulary for delegated third-party access tokens.
+ * Single source of truth used by the authorization server (advertised in
+ * `scopes_supported`), the API's scope-enforcement middleware, and consent UI
+ * copy. The standard `offline_access` scope (refresh tokens) is not platform
+ * vocabulary and is deliberately absent — the middleware never checks it.
+ *
+ * Deliberately absent by design: any `tokens:*` scope, `account:write`, or
+ * admin scope — a delegated app must never mint credentials, delete the
+ * account, or act as admin.
+ */
+declare const OAuthScope: {
+    readonly ACCOUNT_READ: "account:read";
+    readonly DEPLOYMENTS_READ: "deployments:read";
+    readonly DEPLOYMENTS_WRITE: "deployments:write";
+    readonly DOMAINS_READ: "domains:read";
+    readonly DOMAINS_WRITE: "domains:write";
+};
+type OAuthScopeType = typeof OAuthScope[keyof typeof OAuthScope];
+declare const DEPLOYMENT_CONFIG_FILENAME = "ship.json";
+/** Default ship.json config for SPA routing. Single source of truth — used by both API and SDK. */
+declare const SPA_DEFAULT_CONFIG: {
+    readonly rewrites: readonly [{
+        readonly source: "/(.*)";
+        readonly destination: "/index.html";
+    }];
+};
+/**
+ * Validate API key format
+ */
+declare function validateApiKey(apiKey: string): void;
+/**
+ * Validate deploy token format
+ */
+declare function validateDeployToken(deployToken: string): void;
+/**
+ * Validate a client token of any population. Classifies by shape and applies
+ * the matching format rules: `ship-` keys and `deploy-` deploy tokens are
+ * validated strictly; opaque tokens (OAuth access tokens, future populations)
+ * only need to be non-empty — their validity is the server's to decide.
+ */
+declare function validateToken(token: string): void;
+/**
+ * Validate a caller identifier against the `CALLER` shape. The server
+ * silently ignores malformed values (the header is unauthenticated); clients
+ * call this at configuration time so the drop never silently happens.
+ */
+declare function validateCaller(caller: string): void;
+/**
+ * Validate API URL format
+ */
+declare function validateApiUrl(apiUrl: string): void;
+/**
+ * Check if a string matches the deployment identifier pattern (word-word-alphanumeric7).
+ * Example: "happy-cat-abc1234.shipstatic.com"
+ */
+declare function isDeployment(input: string): boolean;
+/**
+ * Request payload for SPA check endpoint
+ */
+interface SPACheckRequest {
+    /** Array of file paths */
+    files: string[];
+    /** HTML content of index.html file */
+    index: string;
+}
+/**
+ * Response from SPA check endpoint
+ */
+interface SPACheckResponse {
+    /** Whether the project is detected as a Single Page Application */
+    isSPA: boolean;
+    /** Debugging information about detection */
+    debug: {
+        /** Which tier made the detection: 'exclusions', 'inclusions', 'scoring', 'ai', or 'fallback' */
+        tier: 'exclusions' | 'inclusions' | 'scoring' | 'ai' | 'fallback';
+        /** The reason for the detection result */
+        reason: string;
+    };
+}
+/**
+ * Represents a file that has been processed and is ready for deploy.
+ * Used across the platform (API, SDK, CLI) for file operations.
+ */
+interface StaticFile {
+    /**
+     * The content of the file.
+     * In Node.js, this is typically a `Buffer`.
+     * In the browser, this is typically a `File` or `Blob` object.
+     */
+    content: File | Buffer | Blob;
+    /**
+     * The desired path for the file on the server, relative to the deployment root.
+     * Should include the filename, e.g., `images/photo.jpg`.
+     */
+    path: string;
+    /**
+     * The original absolute file system path (primarily used in Node.js environments).
+     * This helps in debugging or associating the server path back to its source.
+     */
+    filePath?: string;
+    /**
+     * The MD5 hash (checksum) of the file's content.
+     * This is calculated by the SDK before deploy if not provided.
+     */
+    md5?: string;
+    /** 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";
+/**
+ * Universal deploy input — the union of every shape the SDK accepts.
+ *
+ * - **Browser**: `File[]` (typically from `<input type="file">` or drag-and-drop)
+ * - **Node**: `string | string[]` (file or directory path(s) on disk; directories are walked)
+ *
+ * Each platform's SDK narrows its `deploy()` signature to the relevant shape
+ * and rejects anything else at runtime. Use the structural types directly
+ * (`File[]`, `string | string[]`) when writing platform-specific code.
+ */
+type DeployInput = File[] | string | string[];
+/**
+ * Options for deployment creation at the API contract level.
+ * SDK implementations may extend with additional options (timeout, signal, callbacks, etc.).
+ */
+interface DeploymentUploadOptions {
+    /** Optional labels for categorization and filtering */
+    labels?: string[];
+    /** Client identifier (e.g., 'cli', 'sdk', 'web') */
+    via?: string;
+    /**
+     * Optional password that protects this deployment.
+     *
+     * Length: {@link PASSWORD_CONSTRAINTS.MIN_LENGTH} to
+     * {@link PASSWORD_CONSTRAINTS.MAX_LENGTH} characters. Leading and trailing
+     * whitespace is trimmed before validation; internal whitespace is
+     * significant. Visitors are prompted to enter the password before they can
+     * view the deployment — including on any custom domains pointing at it.
+     * To remove protection, redeploy without a password.
+     */
+    password?: string;
+    /** @internal Trigger server-side build. Only available via /upload endpoint. */
+    build?: boolean;
+    /** @internal Trigger server-side prerender. Only available via /upload endpoint. */
+    prerender?: boolean;
+    /** @internal Trigger server-side SPA detection. Only available via /upload endpoint. */
+    spa?: boolean;
+    /** @internal reCAPTCHA proof for the anonymous human deploy channel. Only available via /upload endpoint. */
+    captcha?: string;
+}
+/**
+ * Deployment resource interface - the contract all implementations must follow
+ */
+interface DeploymentResource {
+    upload: (input: DeployInput, options?: DeploymentUploadOptions) => Promise<DeploymentCreateResponse>;
+    list: () => Promise<DeploymentListResponse>;
+    get: (id: string) => Promise<Deployment>;
+    set: (id: string, options: {
+        labels: string[];
+    }) => Promise<Deployment>;
+    remove: (id: string) => Promise<void>;
+}
+/**
+ * Domain resource interface - the contract all implementations must follow
+ */
+interface DomainResource {
+    set: (name: string, options?: {
+        deployment?: string;
+        labels?: string[];
+    }) => Promise<DomainSetResult>;
+    list: () => Promise<DomainListResponse>;
+    get: (name: string) => Promise<Domain>;
+    remove: (name: string) => Promise<void>;
+    verify: (name: string) => Promise<{
+        message: string;
+    }>;
+    validate: (name: string) => Promise<DomainValidateResponse>;
+    dns: (name: string) => Promise<DomainDnsResponse>;
+    records: (name: string) => Promise<DomainRecordsResponse>;
+    share: (name: string) => Promise<{
+        domain: string;
+        hash: string;
+    }>;
+}
+/**
+ * Account resource interface - the contract all implementations must follow
+ */
+interface AccountResource {
+    get: () => Promise<AccountGetResponse>;
+}
+/**
+ * Token resource interface - the contract all implementations must follow
+ */
+interface TokenResource {
+    create: (options?: {
+        ttl?: number;
+        labels?: string[];
+    }) => Promise<TokenCreateResponse>;
+    list: () => Promise<TokenListResponse>;
+    remove: (token: string) => Promise<void>;
+}
+/**
+ * Billing status response from GET /billing/status
+ *
+ * Note: The user's `plan` comes from Account, not here.
+ * This endpoint only returns billing-specific data (usage, portal, etc.)
+ *
+ * If `billing` is null, the user has no active billing.
+ */
+interface BillingStatus {
+    /** Creem billing ID, or null if no active billing */
+    billing: string | null;
+    /** Number of billing units (1 unit = 1 custom domain), null if no billing */
+    units: number | null;
+    /** Billing status from Creem (active, trialing, canceled, etc.), null if no billing */
+    status: string | null;
+    /** Link to Creem customer portal for billing management, null if unavailable */
+    portal: string | null;
+}
+/**
+ * Checkout session response from POST /billing/checkout
+ */
+interface CheckoutSession {
+    /** URL to redirect user to Creem checkout page */
+    url: string;
+}
+/**
+ * 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';
+/**
+ * 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';
+/**
+ * Activity record returned from the API
+ */
+interface Activity {
+    /** The event type */
+    event: ActivityEvent;
+    /** Unix timestamp (seconds) when the activity occurred */
+    created: number;
+    /** Associated deployment ID (if applicable) */
+    deployment?: string;
+    /** Associated domain name (if applicable) */
+    domain?: string;
+    /** JSON-encoded metadata (parse with JSON.parse) */
+    meta?: string;
+}
+/**
+ * Parsed activity metadata.
+ * Different events populate different fields.
+ */
+interface ActivityMeta {
+    /** Number of files in deployment */
+    files?: number;
+    /** Total size in bytes */
+    size?: number;
+    /** Whether deployment has a ship.json config */
+    hasConfig?: boolean;
+    /** Whether deployment has a password set */
+    hasPassword?: boolean;
+    /** Whether this was an update (vs create) */
+    isUpdate?: boolean;
+    /** Whether domain was already verified */
+    wasVerified?: boolean;
+    /** Previous deployment ID before relinking */
+    previousDeployment?: string;
+    /** Labels that were set/updated */
+    labels?: string[];
+    /** OAuth provider name */
+    provider?: string;
+    /** Account email */
+    email?: string;
+    /** Account display name */
+    name?: string;
+    /** Previous plan */
+    from?: string;
+    /** New plan */
+    to?: string;
+    /** Allow additional fields for future use */
+    [key: string]: unknown;
+}
+/**
+ * Response from GET /activities endpoint
+ */
+interface ActivityListResponse {
+    /** Array of activities */
+    activities: Activity[];
+}
+/**
+ * File status constants for validation state tracking
+ */
+declare const FileValidationStatus: {
+    /** File is pending validation */
+    readonly PENDING: "pending";
+    /** File failed during processing (before validation) */
+    readonly PROCESSING_ERROR: "processing_error";
+    /** File was excluded by validation warning (not an error) */
+    readonly EXCLUDED: "excluded";
+    /** File failed validation (blocks deployment) */
+    readonly VALIDATION_FAILED: "validation_failed";
+    /** File passed validation and is ready for deployment */
+    readonly READY: "ready";
+};
+type FileValidationStatusType = typeof FileValidationStatus[keyof typeof FileValidationStatus];
+/**
+ * A validation issue with a display-ready message
+ *
+ * Issues are either errors (in errors[] array) or warnings (in warnings[] array).
+ * The array position determines severity - no need to duplicate it in the object.
+ */
+interface ValidationIssue {
+    /** File path that triggered this issue */
+    file: string;
+    /** Display-ready message explaining the issue */
+    message: string;
+}
+/**
+ * Minimal file interface required for validation
+ */
+interface ValidatableFile {
+    name: string;
+    size: number;
+    status?: FileValidationStatusType;
+    statusMessage?: string;
+}
+/**
+ * File validation result with severity-based issue reporting
+ *
+ * Validation checks files against constraints and categorizes issues by severity:
+ * - **Errors**: Block deployment (file too large, invalid type, etc.)
+ * - **Warnings**: Exclude files but allow deployment (empty files, etc.)
+ *
+ * @example
+ * ```typescript
+ * const result = validateFiles(files, config);
+ *
+ * if (!result.canDeploy) {
+ *   // Has errors - must fix before deploying
+ *   console.error('Deployment blocked:', result.errors);
+ * } else if (result.warnings.length > 0) {
+ *   // Has warnings - deployment proceeds, some files excluded
+ *   console.warn('Files excluded:', result.warnings);
+ *   deploy(result.validFiles);
+ * } else {
+ *   // All files valid
+ *   deploy(result.validFiles);
+ * }
+ * ```
+ */
+interface FileValidationResult<T extends ValidatableFile> {
+    /** All files with updated status */
+    files: T[];
+    /** Files ready for deployment (status: 'ready') */
+    validFiles: T[];
+    /** Blocking errors that prevent deployment */
+    errors: ValidationIssue[];
+    /** Non-blocking warnings (files excluded but deployment allowed) */
+    warnings: ValidationIssue[];
+    /** Whether deployment can proceed (true if errors.length === 0) */
+    canDeploy: boolean;
+}
+/**
+ * Represents a file that has been uploaded and stored
+ */
+interface UploadedFile {
+    key: string;
+    etag: string;
+    size: number;
+    validated?: boolean;
+}
+/**
+ * Check if a domain is a platform domain (subdomain of our platform).
+ * Platform domains are free and don't require DNS verification.
+ *
+ * @example isPlatformDomain("www.shipstatic.com", "shipstatic.com") → true
+ * @example isPlatformDomain("example.com", "shipstatic.com") → false
+ */
+declare function isPlatformDomain(domain: string, platformDomain: string): boolean;
+/**
+ * Check if a domain is a custom domain (not a platform subdomain).
+ * Custom domains are billable and require DNS verification.
+ *
+ * @example isCustomDomain("example.com", "shipstatic.com") → true
+ * @example isCustomDomain("www.shipstatic.com", "shipstatic.com") → false
+ */
+declare function isCustomDomain(domain: string, platformDomain: string): boolean;
+/**
+ * Extract subdomain from a platform domain.
+ * Returns null if not a platform domain.
+ *
+ * @example extractSubdomain("www.shipstatic.com", "shipstatic.com") → "www"
+ * @example extractSubdomain("example.com", "shipstatic.com") → null
+ */
+declare function extractSubdomain(domain: string, platformDomain: string): string | null;
+/**
+ * Generate HTTPS URL for a deployment hostname.
+ */
+declare function generateDeploymentUrl(deployment: string): string;
+/**
+ * Generate HTTPS URL for a domain.
+ */
+declare function generateDomainUrl(domain: string): string;
+/**
+ * Label validation constraints shared across UI and API.
+ * These rules define the single source of truth for label validation.
+ */
+declare const LABEL_CONSTRAINTS: {
+    /** Minimum label length in characters */
+    readonly MIN_LENGTH: 3;
+    /** Maximum label length in characters (concise labels, matches Stack Overflow's original limit) */
+    readonly MAX_LENGTH: 25;
+    /** Maximum number of labels allowed per resource */
+    readonly MAX_COUNT: 10;
+    /** Allowed separator characters between label segments */
+    readonly SEPARATORS: "._-";
+};
+/**
+ * Label validation pattern.
+ * Must start and end with alphanumeric (a-z, 0-9).
+ * Can contain separators (. _ -) between segments, but not consecutive.
+ *
+ * Valid examples: 'production', 'v1.2.3', 'api_v2', 'us-east-1'
+ * Invalid examples: 'ab' (too short), '-prod' (starts with separator), 'foo--bar' (consecutive separators)
+ */
+declare const LABEL_PATTERN: RegExp;
+/**
+ * Serialize labels array to JSON string for database storage.
+ * Returns null for empty or undefined arrays.
+ *
+ * @example serializeLabels(['web', 'production']) → '["web","production"]'
+ * @example serializeLabels([]) → null
+ * @example serializeLabels(undefined) → null
+ */
+declare function serializeLabels(labels: string[] | undefined): string | null;
+/**
+ * Deserialize labels from JSON string to array.
+ * Always returns an array — empty array for null/empty/invalid input.
+ *
+ * @example deserializeLabels('["web","production"]') → ['web', 'production']
+ * @example deserializeLabels(null) → []
+ * @example deserializeLabels('') → []
+ */
+declare function deserializeLabels(labelsJson: string | null): string[];
+/**
+ * Length constraints for the optional deployment password
+ * (`DeploymentUploadOptions.password`). Single source of truth shared across
+ * platform consumers.
+ */
+declare const PASSWORD_CONSTRAINTS: {
+    /** Minimum password length in characters */
+    readonly MIN_LENGTH: 6;
+    /** Maximum password length in characters */
+    readonly MAX_LENGTH: 128;
+};
+/**
+ * Validate an optional deployment password and return it normalized.
+ *
+ * Absent (`undefined` / `null`) → returns `undefined`. Present → trim
+ * leading/trailing whitespace, then validate against `PASSWORD_CONSTRAINTS`
+ * length bounds (internal whitespace is significant and counts toward
+ * length). Throws `ShipError.validation` on breach; returns the trimmed
+ * value.
+ *
+ * The trim is canonical: at upload, the API hashes the trimmed value; at
+ * unlock, the router trims submissions before hashing. Submission and storage
+ * agree byte-for-byte. Length validation runs on the trimmed value because
+ * that's the user's actual intent — and it disarms a class of invisible
+ * foot-guns (trailing newlines from copy/paste, mobile auto-spacing,
+ * password-manager artifacts).
+ *
+ * Single source of truth shared by SDK (client-side validation, return
+ * ignored) and API (server-side enforcement, return threaded into config).
+ * Length is part of the wire-format contract; strength rules, if added later,
+ * stay server-side. See `CLAUDE.md` "Validation: format vs policy".
+ */
+declare function validatePassword(value: unknown): string | undefined;
 
 /**
  * @file SDK-specific type definitions
@@ -14,8 +1109,6 @@ export { Account, AccountResource, DEFAULT_API, DeployInput, Deployment, Deploym
  * Extends the API contract (DeploymentUploadOptions) with SDK-specific options.
  */
 interface DeploymentOptions extends DeploymentUploadOptions {
-    /** The API URL to use for this specific deploy. Overrides client's default. */
-    apiUrl?: string;
     /** An AbortSignal to allow cancellation of the deploy operation. */
     signal?: AbortSignal;
     /** Callback invoked if the deploy is cancelled via the AbortSignal. */
@@ -24,18 +1117,12 @@ interface DeploymentOptions extends DeploymentUploadOptions {
     maxConcurrency?: number;
     /** Timeout in milliseconds for the deploy request. */
     timeout?: number;
-    /** API key for this specific deploy. Overrides client's default (format: ship-<64-char-hex>, total 69 chars). */
-    apiKey?: string;
-    /** Deploy token for this specific deploy. Overrides client's default (format: token-<64-char-hex>, total 70 chars). */
-    deployToken?: string;
     /** 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;
-    /** Caller identifier for multi-tenant deployments (alphanumeric, dot, underscore, hyphen). */
-    caller?: string;
 }
 type ApiDeployOptions = Omit<DeploymentOptions, 'pathDetect'>;
 /**
@@ -70,6 +1157,8 @@ interface DeployBodyContext {
         prerender?: boolean;
         spa?: boolean;
     };
+    /** @internal reCAPTCHA proof for the anonymous human deploy channel (/upload). */
+    captcha?: string;
 }
 /**
  * Function that creates a deploy request body from files.
@@ -78,17 +1167,36 @@ interface DeployBodyContext {
 type DeployBodyCreator = (files: StaticFile[], context?: DeployBodyContext) => Promise<DeployBody>;
 /** Standard `fetch` signature — the type of the `fetch` client option. */
 type Fetch = typeof fetch;
+/**
+ * Supplies the client token per request — synchronously or asynchronously.
+ * The provider owns freshness: callers holding short-lived credentials
+ * (e.g. OAuth access tokens) refresh inside the provider; the SDK just asks.
+ * A provider that yields nothing fails the request — a configured provider
+ * is credential intent, and intent never degrades to an anonymous request.
+ */
+type TokenProvider = () => string | Promise<string>;
 /**
  * Options for configuring a `Ship` instance.
- * Sets default API host, authentication credentials, progress callbacks, concurrency, and timeouts for the client.
+ * Sets default API host, the client credential, progress callbacks, concurrency, and timeouts for the client.
  */
 interface ShipClientOptions {
     /** Default API URL for the client instance. */
     apiUrl?: string | undefined;
-    /** API key for authenticated deployments (format: ship-<64-char-hex>, total 69 chars). */
-    apiKey?: string | undefined;
-    /** Deploy token for authenticated deployments (format: token-<64-char-hex>, total 70 chars). */
-    deployToken?: string | undefined;
+    /**
+     * The client credential — any platform token, sent verbatim as
+     * `Authorization: Bearer <value>` on every request. The token's prefix says
+     * what it is: `ship-` API key (durable, full account), `deploy-` deploy
+     * token (deploy-scoped, revocable, optional TTL), anything else an opaque
+     * pre-issued bearer such as an OAuth access token. The server classifies by
+     * value — the client never has to say which kind it holds.
+     *
+     * Pass a {@link TokenProvider} function instead of a string when the token
+     * must be minted or refreshed per request.
+     *
+     * Omitted entirely: deploys still work — they land in the public account
+     * with a claim URL and an expiry; every other operation requires a token.
+     */
+    token?: string | TokenProvider | undefined;
     /**
      * Default callback for deploy progress for deploys made with this client.
      * @param info - Progress information including percentage and byte counts.
@@ -106,14 +1214,19 @@ interface ShipClientOptions {
      */
     timeout?: number | undefined;
     /**
-     * When true, indicates the client should use HTTP-only cookies for authentication
-     * instead of explicit tokens. This is useful for internal browser applications
-     * where authentication is handled via secure cookies set by the API.
+     * When true, the client authenticates with the first-party cookie session
+     * (`AuthMethod.SESSION`) — requests are sent with `credentials: 'include'`
+     * and carry no `Authorization` header. For browser apps living on the
+     * platform's own domains, where the API sets HTTP-only session cookies.
+     * Mutually exclusive with `token`: a client holds one identity.
      *
-     * When set, the pre-request authentication check is skipped, allowing requests
-     * to proceed with cookie-based credentials.
+     * Requires a cookie-capable transport. Browsers send first-party cookies
+     * natively; in Node, pair it with an injected `fetch` that forwards the
+     * session cookie (the default fetch has no cookie jar, and `session: true`
+     * deliberately suppresses the `SHIP_TOKEN` fallback — a session client
+     * never silently switches identity).
      */
-    useCredentials?: boolean | undefined;
+    session?: boolean | undefined;
     /**
      * Custom `fetch` implementation. Defaults to `globalThis.fetch`.
      *
@@ -123,14 +1236,19 @@ interface ShipClientOptions {
      */
     fetch?: Fetch | undefined;
     /**
-     * Default caller identifier for multi-tenant deployments.
-     * Alphanumeric characters, dots, underscores, and hyphens allowed (max 128 chars).
+     * Caller identifier for multi-tenant orchestration — sent as `X-Caller`
+     * on every request. Validated at construction against the shared `CALLER`
+     * shape (`validateCaller` in `@shipstatic/types`: alphanumeric, dots,
+     * underscores, hyphens; max 128 chars) — a value the API would silently
+     * drop throws here instead.
      *
-     * 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 every CLI invocation belongs to one human; a per-tenant
-     * rate-limit bucket would defeat the purpose.
+     * Used by orchestrators (e.g. the hosted MCP Worker processing many end
+     * users from one egress) so the API's rate-limit buckets key per caller
+     * rather than per shared IP. Instance identity metadata, like the
+     * credential: one client speaks for one end user, and every write the
+     * client makes is bucketed the same way. **Programmatic-only by design**
+     * — there is no `--caller` CLI flag because every CLI invocation belongs
+     * to one human; a per-tenant rate-limit bucket would defeat the purpose.
      *
      * Distinct from `via` (the client identifier — `'cli'`, `'sdk'`, `'web'`,
      * `'git'`, etc.). `via` is for analytics/origin tracking and is
@@ -197,13 +1315,15 @@ declare class SimpleEvents {
  */
 
 interface ApiHttpOptions extends ShipClientOptions {
-    getAuthHeaders: () => Record<string, string>;
+    /** Resolves the credential slot per request — async so token providers can mint/refresh. */
+    getAuthHeaders: () => Record<string, string> | Promise<Record<string, string>>;
     createDeployBody: DeployBodyCreator;
 }
 declare class ApiHttp extends SimpleEvents {
     private readonly apiUrl;
     private readonly getAuthHeadersCallback;
-    private readonly useCredentials;
+    private readonly session;
+    private readonly caller;
     private readonly timeout;
     private readonly fetch;
     private readonly createDeployBody;
@@ -253,8 +1373,7 @@ declare class ApiHttp extends SimpleEvents {
     createToken(ttl?: number, labels?: string[]): Promise<TokenCreateResponse>;
     listTokens(): Promise<TokenListResponse>;
     removeToken(token: string): Promise<void>;
-    fetchAgentToken(): Promise<TokenCreateResponse>;
-    getAccount(): Promise<Account>;
+    getAccount(): Promise<AccountGetResponse>;
     getLimits(): Promise<PlatformLimits>;
     ping(): Promise<boolean>;
     checkSPA(files: StaticFile[], options?: ApiDeployOptions): Promise<boolean>;
@@ -277,10 +1396,14 @@ interface ResourceContext {
 interface DeploymentResourceContext extends ResourceContext {
     processInput: (input: DeployInput, options: DeploymentOptions) => Promise<StaticFile[]>;
     clientDefaults?: ShipClientOptions;
-    hasAuth?: () => boolean;
 }
 /**
  * Upload deployment resource with all CRUD operations.
+ *
+ * There is no client-side auth branching: an upload from a credential-less
+ * client simply carries no `Authorization` header, and the API grants the
+ * 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;
 /**
@@ -312,7 +1435,7 @@ declare abstract class Ship$1 {
     private readonly clientOptions;
     private initPromise;
     protected platformLimits: PlatformLimits | null;
-    private auth;
+    private credential;
     constructor(options?: ShipClientOptions);
     protected abstract processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
     protected abstract getDeployBodyCreator(): DeployBodyCreator;
@@ -333,7 +1456,7 @@ declare abstract class Ship$1 {
     /**
      * Get current account information (convenience shortcut to `ship.account.get()`).
      */
-    whoami(): Promise<_shipstatic_types.Account>;
+    whoami(): Promise<AccountGetResponse>;
     /**
      * Get platform limits (max file size, file count, total size).
      * Reuses the response fetched during initialization. Per-instance state —
@@ -352,50 +1475,40 @@ declare abstract class Ship$1 {
      */
     clearHeaders(): void;
     /**
-     * Sets the deploy token for authentication.
-     * Overrides any previously set API key or deploy token.
-     * @param token Deploy token (format: `token-<64-char-hex>`)
+     * Sets the client token — any platform token (API key, deploy token, OAuth
+     * access token) or a {@link TokenProvider} invoked per request. Replaces
+     * whatever credential the client held before.
+     * @param token A platform token, sent verbatim, or a provider function
      */
-    setDeployToken(token: string): void;
+    setToken(token: string | TokenProvider): void;
     /**
-     * Sets the API key for authentication.
-     * Overrides any previously set API key or deploy token.
-     * @param key API key (format: `ship-<64-char-hex>`)
+     * Resolve the credential slot into request headers. Async because a
+     * provider may mint or refresh its token per request.
+     *
+     * Anonymity requires proven absence of credentials: a configured provider
+     * that yields nothing is an error — the request fails typed rather than
+     * silently proceeding as an anonymous public deploy. Empty-string
+     * normalization at the constructor is the same invariant's boundary
+     * condition: `''` is absence of intent, so it never reaches this point.
      */
-    setApiKey(key: string): void;
     private getAuthHeaders;
-    /**
-     * 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:
+ * One pure helper used by the deployment resource:
  *
- *   - `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`)
+ * 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.
  */
 
-/**
- * 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.
  *
@@ -663,9 +1776,9 @@ declare function processFilesForNode(paths: string[], options?: DeploymentOption
  *
  * The Node-side `Ship` adds two things on top of the base class:
  *   1. Environment detection — refuses to construct outside Node.
- *   2. `SHIP_*` env-var resolution as the universal "process boundary" credential
- *      source, mirroring the OpenAI / Anthropic SDK convention. Constructor
- *      arguments win over env vars.
+ *   2. `SHIP_TOKEN` / `SHIP_API_URL` env-var resolution as the universal
+ *      "process boundary" credential source — the industry's one-token
+ *      convention. Constructor arguments win over env vars.
  *
  * The SDK does NOT read `~/.shiprc` or `package.json` `"ship"` keys — that's
  * the CLI's job (see `cli/shiprc.ts`). Keeping file resolution out of the SDK
@@ -679,13 +1792,13 @@ declare function processFilesForNode(paths: string[], options?: DeploymentOption
  *
  * @example
  * ```typescript
- * // Authenticated — explicit API key
- * const ship = new Ship({ apiKey: 'ship-xxxx' });
+ * // Authenticated — explicit token (API key, deploy token, or OAuth bearer)
+ * const ship = new Ship({ token: 'ship-xxxx' });
  *
- * // Authenticated — picks up SHIP_API_KEY from env
+ * // Authenticated — picks up SHIP_TOKEN from env
  * const ship = new Ship({});
  *
- * // Anonymous public deploy — works when neither constructor nor env provides creds
+ * // Anonymous public deploy — works when neither constructor nor env provides a token
  * const ship = new Ship({});
  * await ship.deploy('./dist');
  * ```
@@ -707,4 +1820,4 @@ declare class Ship extends Ship$1 {
     protected getDeployBodyCreator(): DeployBodyCreator;
 }
 
-export { type ApiDeployOptions, ApiHttp, type ApiHttpOptions, type DeployBody, type DeployBodyContext, type DeployBodyCreator, type DeployFile, type DeploymentOptions, type DeploymentResourceContext, type ExecutionEnvironment, type Fetch, 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, processFilesForNode, resolveConfig, validateDeployFile, validateDeployPath, validateFileName, validateFiles };
+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 };