@shipstatic/ship 0.1.26 → 0.2.0

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import * as _shipstatic_types from '@shipstatic/types';
-import { Deployment, DeploymentListResponse, Alias, AliasListResponse, Account } from '@shipstatic/types';
-export { PingResponse, ShipError, ShipErrorType } 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
@@ -8,10 +9,6 @@ export { PingResponse, ShipError, ShipErrorType } from '@shipstatic/types';
  * Core types come from @shipstatic/types, while SDK-specific types are defined here.
  */
 
-/**
- * Consolidated input type for all environments
- */
-type DeployInput = FileList | File[] | HTMLInputElement | string[];
 /**
  * Universal deploy options for both Node.js and Browser environments
  */
@@ -87,92 +84,282 @@ interface ShipClientOptions {
      * Used if an deploy operation doesn't specify its own `maxConcurrency`.
      * Defaults to 4 if not set here or in the specific deploy call.
      */
-    maxConcurrentDeploys?: number | undefined;
+    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;
 }
+
 /**
- * Represents a file that has been processed and is ready for deploy.
- * Used internally by the SDK and in advanced/manual deploy scenarios.
+ * Handles direct HTTP communication with the Ship API, including deploys and health checks.
+ * Responsible for constructing requests, managing authentication, and error translation.
+ * @internal
  */
-interface StaticFile {
+declare class ApiHttp {
+    #private;
+    private readonly apiUrl;
+    private readonly apiKey;
+    private readonly deployToken;
     /**
-     * The content of the file.
-     * In Node.js, this is typically a `Buffer`.
-     * In the browser, this is typically a `File` or `Blob` object.
+     * Constructs a new ApiHttp instance with the provided client options.
+     * @param options - Client options including API host, authentication credentials, and timeout settings.
      */
-    content: File | Buffer | Blob;
+    constructor(options: ShipClientOptions);
     /**
-     * The desired path for the file on the server, relative to the deployment root.
-     * Should include the filename, e.g., `images/photo.jpg`.
+     * 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).
      */
-    path: string;
+    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>;
     /**
-     * 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.
+     * Creates a new API key for the authenticated user
+     * @returns Promise resolving to the new API key
      */
-    filePath?: string;
+    createApiKey(): Promise<{
+        apiKey: string;
+    }>;
     /**
-     * The MD5 hash (checksum) of the file's content.
-     * This is calculated by the SDK before deploy if not provided.
+     * 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
      */
-    md5?: string;
-    /** The size of the file in bytes. */
-    size: number;
+    checkSPA(files: StaticFile[]): Promise<boolean>;
 }
 
 /**
  * @file All Ship SDK resources in one place - impossibly simple.
  */
 
-interface DeploymentResource {
-    create: (input: DeployInput, options?: DeploymentOptions) => Promise<Deployment>;
-    list: () => Promise<DeploymentListResponse>;
-    remove: (id: string) => Promise<void>;
-    get: (id: string) => Promise<Deployment>;
-}
-interface AliasResource {
-    set: (aliasName: string, deployment: string) => Promise<Alias>;
-    get: (aliasName: string) => Promise<Alias>;
-    list: () => Promise<AliasListResponse>;
-    remove: (aliasName: string) => Promise<void>;
-    check: (aliasName: string) => Promise<{
-        message: string;
-    }>;
-}
-interface AccountResource {
-    get: () => Promise<Account>;
+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;
 }
-interface KeysResource {
-    create: () => Promise<{
-        apiKey: string;
-    }>;
+
+/**
+ * @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>;
 
 /**
- * Processes Node.js file and directory paths into an array of StaticFile objects ready for deploy.
- * Now uses the simplified, declarative approach suggested in the feedback.
+ * 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
  *
- * @param paths - File or directory paths to scan and process.
- * @param options - Processing options (basePath, preserveDirs).
- * @returns Promise resolving to an array of StaticFile objects.
- * @throws {ShipClientError} If called outside Node.js or if fs/path modules fail.
+ * 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 function processFilesForNode(paths: string[], options?: DeploymentOptions): Promise<StaticFile[]>;
+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[];
 
 /**
- * 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.
+ * @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.
  *
- * @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.
+ * @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 processFilesForBrowser(browserFiles: FileList | File[], options?: DeploymentOptions): Promise<StaticFile[]>;
+declare function optimizeDeployPaths(filePaths: string[], options?: {
+    flatten?: boolean;
+}): DeployFile[];
 
 /**
  * @file Environment detection utilities for the Ship SDK.
@@ -193,73 +380,89 @@ type ExecutionEnvironment = 'browser' | 'node' | 'unknown';
  * @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 Manages loading and validation of client configuration.
+ * This module uses `cosmiconfig` to find and load configuration from various
+ * file sources (e.g., `.shiprc`, `package.json`) and environment variables.
+ * Configuration values are validated using Zod schemas.
+ */
 
 /**
- * Ship SDK Client - Universal class-based interface for both Node.js and browser environments.
+ * Simplified configuration loading prioritizing environment variables.
+ * Only loads file config if environment variables are not set.
+ * Only available in Node.js environments.
  *
- * Authentication Options:
- * ```
+ * @param configFile - Optional specific config file path to load
+ * @returns Configuration object with loaded values
+ * @throws {ShipInvalidConfigError} If the configuration is invalid.
+ */
+declare function loadConfig(configFile?: string): Promise<Partial<ShipClientOptions>>;
+
+/**
+ * @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;
+
+/**
+ * Processes Node.js file and directory paths into an array of StaticFile objects ready for deploy.
+ * Uses corrected logic to properly handle common parent directory stripping.
+ *
+ * @param paths - File or directory paths to scan and process.
+ * @param options - Processing options (pathDetect, etc.).
+ * @returns Promise resolving to an array of StaticFile objects.
+ * @throws {ShipClientError} If called outside Node.js or if fs/path modules fail.
+ */
+declare function processFilesForNode(paths: string[], options?: DeploymentOptions): Promise<StaticFile[]>;
+
+/**
+ * @file Ship SDK for Node.js environments with full file system support.
+ */
+
+/**
+ * Ship SDK Client for Node.js environments.
+ *
+ * Provides full file system access, configuration file loading,
+ * and environment variable support.
+ *
+ * @example
+ * ```typescript
  * // Authenticated deployments with API key
  * const ship = new Ship({ apiKey: "ship-xxxx" });
  *
  * // Single-use deployments with deploy token
  * const ship = new Ship({ deployToken: "token-xxxx" });
- * ```
  *
- * Automatically detects the environment and handles Node.js and browser deploys directly.
- * In Node.js environments, loads configuration from files and environment variables.
- * In browser environments, uses only the provided options.
+ * // Deploy a directory
+ * await ship.deploy('./dist');
+ * ```
  */
-declare class Ship {
-    private http;
-    private environment;
-    private readonly clientOptions;
-    private initPromise;
-    private _deployments;
-    private _aliases;
-    private _account;
-    private _keys;
+declare class Ship extends Ship$1 {
+    #private;
     constructor(options?: ShipClientOptions);
-    /**
-     * Ensure full initialization is complete - called lazily by resources
-     */
-    private ensureInitialized;
-    /**
-     * Helper method to create initialization callback for resources
-     */
-    private getInitCallback;
-    /**
-     * Initialize config from file/env and platform config from API
-     */
-    private initializeConfig;
-    /**
-     * 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;
+    protected resolveInitialConfig(options: ShipClientOptions): any;
+    protected loadFullConfig(): Promise<void>;
+    protected processInput(input: DeployInput, options: DeploymentOptions): Promise<StaticFile[]>;
 }
 
-export { type AccountResource, type AliasResource, type ApiDeployOptions, type DeployInput, type DeploymentOptions, type DeploymentResource, type KeysResource, type ProgressStats, Ship, type ShipClientOptions, type StaticFile, __setTestEnvironment, Ship as default, processFilesForBrowser, processFilesForNode };
+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, getCurrentConfig, getENV, loadConfig, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForNode, resolveConfig, setConfig };