@shipstatic/ship 0.1.25 → 0.2.0

package/dist/browser.d.ts

@@ -0,0 +1,454 @@
+import * as _shipstatic_types from '@shipstatic/types';
+import { PingResponse, ConfigResponse, StaticFile, Deployment, DeploymentListResponse, Alias, AliasListResponse, Account, DeployInput, DeploymentResource, AliasResource, AccountResource, KeysResource, PlatformConfig } from '@shipstatic/types';
+export * from '@shipstatic/types';
+export { Account, Alias, DEFAULT_API, DeployInput, Deployment, PingResponse, ShipError, ShipErrorType } from '@shipstatic/types';
+
+/**
+ * @file SDK-specific type definitions
+ * Consolidates all Ship SDK types into a single file for clarity.
+ * Core types come from @shipstatic/types, while SDK-specific types are defined here.
+ */
+
+/**
+ * Universal deploy options for both Node.js and Browser environments
+ */
+interface DeploymentOptions {
+    /** 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;
+    /** An optional subdomain to suggest for the deployment. Availability is subject to the API. */
+    subdomain?: string;
+    /** 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;
+    /** API key for this specific deploy. Overrides client's default. */
+    apiKey?: string;
+    /** Deploy token for this specific deploy. Overrides client's default. */
+    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 overall deploy progress (0-100). */
+    onProgress?: (progress: number) => void;
+    /** Callback for detailed progress statistics. */
+    onProgressStats?: (progressStats: ProgressStats) => void;
+}
+/**
+ * Options for configuring an deploy operation via `apiClient.deployFiles`.
+ * Derived from DeploymentOptions but excludes client-side only options.
+ */
+type ApiDeployOptions = Omit<DeploymentOptions, 'pathDetect'>;
+/**
+ * Detailed statistics about the progress of an deploy operation.
+ */
+interface ProgressStats {
+    /** The number of bytes loaded so far. */
+    loaded: number;
+    /** The total number of bytes to be loaded. May be 0 if unknown initially. */
+    total: number;
+    /** The progress as a fraction (loaded/total). Value is between 0 and 1. */
+    progress: number;
+    /** Optional identifier for the file this progress pertains to, if applicable. */
+    file?: string;
+}
+/**
+ * Options for configuring a `Ship` instance.
+ * Sets default API host, authentication credentials, 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. */
+    apiKey?: string | undefined;
+    /** Deploy token for single-use deployments. */
+    deployToken?: string | undefined;
+    /** Path to custom config file. */
+    configFile?: string | undefined;
+    /**
+     * Default callback for overall deploy progress for deploys made with this client.
+     * @param progress - A number between 0 and 100.
+     */
+    onProgress?: ((progress: number) => void) | undefined;
+    /**
+     * Default callback for detailed progress statistics for deploys made with this client.
+     * @param progressStats - Progress statistics object.
+     */
+    onProgressStats?: ((progressStats: ProgressStats) => 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?: number | undefined;
+}
+
+/**
+ * Handles direct HTTP communication with the Ship API, including deploys and health checks.
+ * Responsible for constructing requests, managing authentication, and error translation.
+ * @internal
+ */
+declare class ApiHttp {
+    #private;
+    private readonly apiUrl;
+    private readonly apiKey;
+    private readonly deployToken;
+    /**
+     * Constructs a new ApiHttp instance with the provided client options.
+     * @param options - Client options including API host, authentication credentials, and timeout settings.
+     */
+    constructor(options: ShipClientOptions);
+    /**
+     * Sends a ping request to the Ship API server to verify connectivity and authentication.
+     * @returns Promise resolving to `true` if the ping is successful, `false` otherwise.
+     * @throws {ShipApiError} If the API returns an error response (4xx, 5xx).
+     * @throws {ShipNetworkError} If a network error occurs (e.g., DNS failure, connection refused).
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Get full ping response from the API server
+     * @returns Promise resolving to the full PingResponse object.
+     */
+    getPingResponse(): Promise<PingResponse>;
+    /**
+     * Fetches platform configuration from the API.
+     * @returns Promise resolving to the config response.
+     * @throws {ShipError} If the config request fails.
+     */
+    getConfig(): Promise<ConfigResponse>;
+    /**
+     * Deploys an array of StaticFile objects to the Ship API.
+     * Constructs and sends a multipart/form-data POST request, handling both browser and Node.js environments.
+     * Validates files and manages deploy progress and error translation.
+     * @param files - Array of StaticFile objects to deploy (must include MD5 checksums).
+     * @param options - Optional per-deploy configuration (overrides instance defaults).
+     * @returns Promise resolving to a full Deployment object on success.
+     * @throws {ShipFileError} If a file is missing an MD5 checksum or content type is unsupported.
+     * @throws {ShipClientError} If no files are provided or if environment is unknown.
+     * @throws {ShipNetworkError} If a network error occurs during deploy.
+     * @throws {ShipApiError} If the API returns an error response.
+     * @throws {ShipCancelledError} If the deploy is cancelled via an AbortSignal.
+     */
+    deploy(files: StaticFile[], options?: ApiDeployOptions): Promise<Deployment>;
+    /**
+     * Lists all deployments for the authenticated account
+     * @returns Promise resolving to deployment list response
+     */
+    listDeployments(): Promise<DeploymentListResponse>;
+    /**
+     * Gets a specific deployment by ID
+     * @param id - Deployment ID to retrieve
+     * @returns Promise resolving to deployment details
+     */
+    getDeployment(id: string): Promise<Deployment>;
+    /**
+     * Removes a deployment by ID
+     * @param id - Deployment ID to remove
+     * @returns Promise resolving when removal is complete
+     */
+    removeDeployment(id: string): Promise<void>;
+    /**
+     * Sets an alias (create or update)
+     * @param name - Alias name
+     * @param deployment - Deployment name to point to
+     * @returns Promise resolving to the created/updated alias with operation context
+     */
+    setAlias(name: string, deployment: string): Promise<_shipstatic_types.Alias>;
+    /**
+     * Gets a specific alias by name
+     * @param name - Alias name to retrieve
+     * @returns Promise resolving to alias details
+     */
+    getAlias(name: string): Promise<Alias>;
+    /**
+     * Lists all aliases for the authenticated account
+     * @returns Promise resolving to alias list response
+     */
+    listAliases(): Promise<AliasListResponse>;
+    /**
+     * Removes an alias by name
+     * @param name - Alias name to remove
+     * @returns Promise resolving to removal confirmation
+     */
+    removeAlias(name: string): Promise<void>;
+    /**
+     * Triggers a manual DNS check for an external alias
+     * @param name - Alias name to check DNS for
+     * @returns Promise resolving to confirmation message
+     */
+    checkAlias(name: string): Promise<{
+        message: string;
+    }>;
+    /**
+     * Gets account details for the authenticated user
+     * @returns Promise resolving to account details
+     */
+    getAccount(): Promise<Account>;
+    /**
+     * Creates a new API key for the authenticated user
+     * @returns Promise resolving to the new API key
+     */
+    createApiKey(): Promise<{
+        apiKey: string;
+    }>;
+    /**
+     * Checks if files represent a SPA structure using AI analysis
+     * @param files - Array of StaticFile objects to analyze
+     * @returns Promise resolving to boolean indicating if it's a SPA
+     */
+    checkSPA(files: StaticFile[]): Promise<boolean>;
+}
+
+/**
+ * @file All Ship SDK resources in one place - impossibly simple.
+ */
+
+declare function createDeploymentResource(getApi: () => ApiHttp, clientDefaults?: ShipClientOptions, ensureInit?: () => Promise<void>, processInput?: (input: DeployInput, options: DeploymentOptions) => Promise<StaticFile[]>): DeploymentResource;
+declare function createAliasResource(getApi: () => ApiHttp, ensureInit?: () => Promise<void>): AliasResource;
+declare function createAccountResource(getApi: () => ApiHttp, ensureInit?: () => Promise<void>): AccountResource;
+declare function createKeysResource(getApi: () => ApiHttp, ensureInit?: () => Promise<void>): KeysResource;
+
+/**
+ * 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 _deployments: DeploymentResource;
+    protected _aliases: AliasResource;
+    protected _account: AccountResource;
+    protected _keys: KeysResource;
+    constructor(options?: ShipClientOptions);
+    protected abstract resolveInitialConfig(options: ShipClientOptions): any;
+    protected abstract loadFullConfig(): Promise<void>;
+    protected abstract processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
+    /**
+     * Ensure full initialization is complete - called lazily by resources
+     */
+    protected ensureInitialized(): Promise<void>;
+    /**
+     * Ping the API server to check connectivity
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Deploy project (convenience shortcut to ship.deployments.create())
+     */
+    deploy(input: DeployInput, options?: DeploymentOptions): Promise<Deployment>;
+    /**
+     * Get current account information (convenience shortcut to ship.account.get())
+     */
+    whoami(): Promise<_shipstatic_types.Account>;
+    /**
+     * Get deployments resource (environment-specific)
+     */
+    get deployments(): DeploymentResource;
+    /**
+     * Get aliases resource
+     */
+    get aliases(): AliasResource;
+    /**
+     * Get account resource
+     */
+    get account(): AccountResource;
+    /**
+     * Get keys resource
+     */
+    get keys(): KeysResource;
+}
+
+/**
+ * @file Shared configuration logic for both environments.
+ */
+
+type Config = PlatformConfig;
+/**
+ * Universal configuration resolver for all environments.
+ * This is the single source of truth for config resolution.
+ */
+declare function resolveConfig(userOptions?: ShipClientOptions, loadedConfig?: Partial<ShipClientOptions>): {
+    apiUrl: string;
+    apiKey?: string;
+    deployToken?: string;
+};
+/**
+ * Merge deployment options with client defaults.
+ * This is shared logic used by both environments.
+ */
+declare function mergeDeployOptions(options: DeploymentOptions, clientDefaults: ShipClientOptions): DeploymentOptions;
+
+interface MD5Result {
+    md5: string;
+}
+/**
+ * Unified MD5 calculation that delegates to environment-specific handlers
+ */
+declare function calculateMD5(input: Blob | Buffer | string): Promise<MD5Result>;
+
+/**
+ * Utility functions for string manipulation.
+ */
+/**
+ * Simple utility to pluralize a word based on a count.
+ * @param count The number to determine pluralization.
+ * @param singular The singular form of the word.
+ * @param plural The plural form of the word.
+ * @param includeCount Whether to include the count in the returned string. Defaults to true.
+ * @returns A string with the count and the correctly pluralized word.
+ */
+declare function pluralize(count: number, singular: string, plural: string, includeCount?: boolean): string;
+
+/**
+ * List of directory names considered as junk
+ *
+ * Files within these directories (at any level in the path hierarchy) will be excluded.
+ * The comparison is case-insensitive for cross-platform compatibility.
+ *
+ * @internal
+ */
+declare const JUNK_DIRECTORIES: readonly ["__MACOSX", ".Trashes", ".fseventsd", ".Spotlight-V100"];
+/**
+ * Filters an array of file paths, removing those considered junk
+ *
+ * A path is filtered out if either:
+ * 1. The basename is identified as junk by the 'junk' package (e.g., .DS_Store, Thumbs.db)
+ * 2. Any directory segment in the path matches an entry in JUNK_DIRECTORIES (case-insensitive)
+ *
+ * All path separators are normalized to forward slashes for consistent cross-platform behavior.
+ *
+ * @param filePaths - An array of file path strings to filter
+ * @returns A new array containing only non-junk file paths
+ */
+declare function filterJunk(filePaths: string[]): string[];
+
+/**
+ * @file Deploy path optimization - the core logic that makes Ship deployments clean and intuitive.
+ * Automatically strips common parent directories to create clean deployment URLs.
+ */
+/**
+ * Represents a file ready for deployment with its optimized path
+ */
+interface DeployFile {
+    /** The clean deployment path (e.g., "assets/style.css") */
+    path: string;
+    /** Original filename */
+    name: string;
+}
+/**
+ * Core path optimization logic.
+ * Transforms messy local paths into clean deployment paths.
+ *
+ * @example
+ * Input:  ["dist/index.html", "dist/assets/app.js"]
+ * Output: ["index.html", "assets/app.js"]
+ *
+ * @param filePaths - Raw file paths from the local filesystem
+ * @param options - Path processing options
+ */
+declare function optimizeDeployPaths(filePaths: string[], options?: {
+    flatten?: boolean;
+}): DeployFile[];
+
+/**
+ * @file Environment detection utilities for the Ship SDK.
+ * Helps in determining whether the SDK is running in a Node.js, browser, or unknown environment.
+ */
+/**
+ * Represents the detected or simulated JavaScript execution environment.
+ */
+type ExecutionEnvironment = 'browser' | 'node' | 'unknown';
+/**
+ * **FOR TESTING PURPOSES ONLY.**
+ *
+ * Allows tests to override the detected environment, forcing the SDK to behave
+ * as if it's running in the specified environment.
+ *
+ * @param env - The environment to simulate ('node', 'browser', 'unknown'),
+ *              or `null` to clear the override and revert to actual environment detection.
+ * @internal
+ */
+declare function __setTestEnvironment(env: ExecutionEnvironment | null): void;
+/**
+ * Gets the current effective execution environment.
+ *
+ * This function first checks if a test environment override is active via {@link __setTestEnvironment}.
+ * If not, it detects the actual environment (Node.js, browser, or unknown).
+ *
+ * @returns The current execution environment: 'browser', 'node', or 'unknown'.
+ * @public
+ */
+declare function getENV(): ExecutionEnvironment;
+
+/**
+ * @file Browser configuration implementation - no file system access.
+ */
+
+/**
+ * Browser config loading - only uses provided options.
+ */
+declare function loadConfig(configFile?: string): Promise<Config>;
+/**
+ * Set platform config in browser.
+ */
+declare function setConfig(config: any): void;
+
+/**
+ * @file Browser-specific file utilities for the Ship SDK.
+ * Provides helpers for processing browser files into deploy-ready objects and extracting common directory info.
+ */
+
+/**
+ * Processes browser files (FileList or File[]) into an array of StaticFile objects ready for deploy.
+ * Calculates MD5, filters junk files, and applies automatic path optimization.
+ *
+ * @param browserFiles - FileList or File[] to process for deploy.
+ * @param options - Processing options including pathDetect for automatic path optimization.
+ * @returns Promise resolving to an array of StaticFile objects.
+ * @throws {ShipClientError} If called outside a browser or with invalid input.
+ */
+declare function processFilesForBrowser(browserFiles: FileList | File[], options?: DeploymentOptions): Promise<StaticFile[]>;
+
+/**
+ * @file Ship SDK for browser environments with streamlined configuration.
+ */
+
+/**
+ * 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
+ * const ship = new Ship({
+ *   deployToken: "token-xxxx",
+ *   apiUrl: "https://api.shipstatic.dev"
+ * });
+ *
+ * // Deploy files from input element
+ * const files = fileInput.files;
+ * await ship.deploy(files);
+ * ```
+ */
+declare class Ship extends Ship$1 {
+    #private;
+    constructor(options?: ShipClientOptions);
+    protected resolveInitialConfig(options: ShipClientOptions): any;
+    protected loadFullConfig(): Promise<void>;
+    protected processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
+}
+
+export { type ApiDeployOptions, ApiHttp, type Config, type DeployFile, type DeploymentOptions, type ExecutionEnvironment, JUNK_DIRECTORIES, type MD5Result, type ProgressStats, Ship, type ShipClientOptions, __setTestEnvironment, calculateMD5, createAccountResource, createAliasResource, createDeploymentResource, createKeysResource, Ship as default, filterJunk, getENV, loadConfig, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForBrowser, resolveConfig, setConfig };