@shipstatic/ship 0.2.4 → 0.2.6

package/dist/index.d.cts

@@ -25,14 +25,16 @@ interface DeploymentOptions {
     maxConcurrency?: number;
     /** Timeout in milliseconds for the deploy request. */
     timeout?: number;
-    /** API key for this specific deploy. Overrides client's default. */
+    /** 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. */
+    /** 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;
+    /** Optional array of tags for categorization and filtering (lowercase, alphanumeric with separators). */
+    tags?: string[];
     /** Callback for overall deploy progress (0-100). */
     onProgress?: (progress: number) => void;
     /** Callback for detailed progress statistics. */
@@ -63,9 +65,9 @@ interface ProgressStats {
 interface ShipClientOptions {
     /** Default API URL for the client instance. */
     apiUrl?: string | undefined;
-    /** API key for authenticated deployments. */
+    /** API key for authenticated deployments (format: ship-<64-char-hex>, total 69 chars). */
     apiKey?: string | undefined;
-    /** Deploy token for single-use deployments. */
+    /** Deploy token for single-use deployments (format: token-<64-char-hex>, total 70 chars). */
     deployToken?: string | undefined;
     /** Path to custom config file. */
     configFile?: string | undefined;
@@ -91,118 +93,144 @@ interface ShipClientOptions {
      */
     timeout?: number | undefined;
 }
+/**
+ * Event map for Ship SDK events
+ * Core events for observability: request, response, error
+ */
+interface ShipEvents extends Record<string, any[]> {
+    /** Emitted before each API request */
+    request: [url: string, init: RequestInit];
+    /** Emitted after successful API response */
+    response: [response: Response, url: string];
+    /** Emitted when API request fails */
+    error: [error: Error, url: string];
+}
 
 /**
- * Handles direct HTTP communication with the Ship API, including deploys and health checks.
- * Responsible for constructing requests, managing authentication, and error translation.
- * @internal
+ * Event system for Ship SDK
+ * Lightweight, reliable event handling with proper error boundaries
  */
-declare class ApiHttp {
-    #private;
-    private readonly apiUrl;
-    private readonly apiKey;
-    private readonly deployToken;
+
+/**
+ * Lightweight event system
+ * - Add handler: on()
+ * - Remove handler: off()
+ * - Emit events: emit() [internal]
+ * - Transfer events: transfer() [internal]
+ * - Reliable error handling and cleanup
+ */
+declare class SimpleEvents {
+    private handlers;
     /**
-     * Constructs a new ApiHttp instance with the provided client options.
-     * @param options - Client options including API host, authentication credentials, and timeout settings.
+     * Add event handler
      */
-    constructor(options: ShipClientOptions);
+    on<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
     /**
-     * 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).
+     * Remove event handler
      */
-    ping(): Promise<boolean>;
+    off<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
     /**
-     * Get full ping response from the API server
-     * @returns Promise resolving to the full PingResponse object.
+     * Emit event (internal use only)
+     * @internal
      */
-    getPingResponse(): Promise<PingResponse>;
+    emit<K extends keyof ShipEvents>(event: K, ...args: ShipEvents[K]): void;
     /**
-     * Fetches platform configuration from the API.
-     * @returns Promise resolving to the config response.
-     * @throws {ShipError} If the config request fails.
+     * Transfer all handlers to another events instance
+     * @internal
      */
-    getConfig(): Promise<ConfigResponse>;
+    transfer(target: SimpleEvents): void;
     /**
-     * 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.
+     * Clear all handlers (for cleanup)
+     * @internal
      */
-    deploy(files: StaticFile[], options?: ApiDeployOptions): Promise<Deployment>;
+    clear(): void;
+}
+
+/**
+ * @file HTTP client with integrated event system
+ * Clean, direct implementation with reliable error handling
+ */
+
+/**
+ * HTTP client with integrated event system
+ * - Direct event integration
+ * - Clean inheritance from SimpleEvents
+ * - Reliable error handling
+ */
+declare class ApiHttp extends SimpleEvents {
+    private readonly apiUrl;
+    private readonly apiKey;
+    private readonly deployToken;
+    constructor(options: ShipClientOptions);
     /**
-     * Lists all deployments for the authenticated account
-     * @returns Promise resolving to deployment list response
+     * Transfer events to another client (clean intentional API)
      */
-    listDeployments(): Promise<DeploymentListResponse>;
+    transferEventsTo(target: ApiHttp): void;
     /**
-     * Gets a specific deployment by ID
-     * @param id - Deployment ID to retrieve
-     * @returns Promise resolving to deployment details
+     * Make authenticated HTTP request with events
      */
-    getDeployment(id: string): Promise<Deployment>;
+    private request;
     /**
-     * Removes a deployment by ID
-     * @param id - Deployment ID to remove
-     * @returns Promise resolving when removal is complete
+     * Generate auth headers
      */
-    removeDeployment(id: string): Promise<void>;
+    private getAuthHeaders;
     /**
-     * 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
+     * Check if credentials are needed
      */
-    setAlias(name: string, deployment: string): Promise<_shipstatic_types.Alias>;
+    private needsCredentials;
     /**
-     * Gets a specific alias by name
-     * @param name - Alias name to retrieve
-     * @returns Promise resolving to alias details
+     * Safely clone response for events
      */
-    getAlias(name: string): Promise<Alias>;
+    private safeClone;
     /**
-     * Lists all aliases for the authenticated account
-     * @returns Promise resolving to alias list response
+     * Parse JSON response
      */
-    listAliases(): Promise<AliasListResponse>;
+    private parseResponse;
     /**
-     * Removes an alias by name
-     * @param name - Alias name to remove
-     * @returns Promise resolving to removal confirmation
+     * Handle response errors
      */
-    removeAlias(name: string): Promise<void>;
+    private handleResponseError;
     /**
-     * Triggers a manual DNS check for an external alias
-     * @param name - Alias name to check DNS for
-     * @returns Promise resolving to confirmation message
+     * Handle fetch errors
      */
-    checkAlias(name: string): Promise<{
+    private handleFetchError;
+    ping(): Promise<boolean>;
+    getPingResponse(): Promise<PingResponse>;
+    getConfig(): Promise<ConfigResponse>;
+    deploy(files: StaticFile[], options?: ApiDeployOptions): Promise<Deployment>;
+    listDeployments(): Promise<DeploymentListResponse>;
+    getDeployment(id: string): Promise<Deployment>;
+    removeDeployment(id: string): Promise<void>;
+    setAlias(name: string, deployment: string, tags?: string[]): Promise<Alias>;
+    getAlias(name: string): Promise<Alias>;
+    listAliases(): Promise<AliasListResponse>;
+    removeAlias(name: string): Promise<void>;
+    confirmAlias(name: string): Promise<{
         message: string;
     }>;
-    /**
-     * Gets account details for the authenticated user
-     * @returns Promise resolving to account details
-     */
+    getAliasDns(name: string): Promise<{
+        alias: string;
+        dns: any;
+    }>;
+    getAliasRecords(name: string): Promise<{
+        alias: string;
+        records: any[];
+    }>;
+    getAliasShare(name: string): Promise<{
+        alias: string;
+        hash: string;
+    }>;
     getAccount(): Promise<Account>;
-    /**
-     * 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>;
+    private validateFiles;
+    private prepareRequestPayload;
+    private createBrowserBody;
+    private createNodeBody;
+    private getBrowserContentType;
 }
 
 /**
- * @file All Ship SDK resources in one place - impossibly simple.
+ * @file Ship SDK resource implementations for deployments, aliases, and accounts.
  */
 
 declare function createDeploymentResource(getApi: () => ApiHttp, clientDefaults?: ShipClientOptions, ensureInit?: () => Promise<void>, processInput?: (input: DeployInput, options: DeploymentOptions) => Promise<StaticFile[]>): DeploymentResource;
@@ -254,6 +282,24 @@ declare abstract class Ship$1 {
      * Get account resource
      */
     get account(): AccountResource;
+    /**
+     * Add event listener
+     * @param event - Event name
+     * @param handler - Event handler function
+     */
+    on<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
+    /**
+     * Remove event listener
+     * @param event - Event name
+     * @param handler - Event handler function
+     */
+    off<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
+    /**
+     * Replace HTTP client while preserving event listeners
+     * Used during initialization to maintain user event subscriptions
+     * @protected
+     */
+    protected replaceHttpClient(newClient: ApiHttp): void;
 }
 
 /**
@@ -452,4 +498,4 @@ declare class Ship extends Ship$1 {
     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, Ship as default, filterJunk, getCurrentConfig, getENV, loadConfig, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForNode, resolveConfig, setConfig };
+export { type ApiDeployOptions, ApiHttp, type Config, type DeployFile, type DeploymentOptions, type ExecutionEnvironment, JUNK_DIRECTORIES, type MD5Result, type ProgressStats, Ship, type ShipClientOptions, type ShipEvents, __setTestEnvironment, calculateMD5, createAccountResource, createAliasResource, createDeploymentResource, Ship as default, filterJunk, getCurrentConfig, getENV, loadConfig, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForNode, resolveConfig, setConfig, setConfig as setPlatformConfig };

package/dist/index.d.ts

@@ -25,14 +25,16 @@ interface DeploymentOptions {
     maxConcurrency?: number;
     /** Timeout in milliseconds for the deploy request. */
     timeout?: number;
-    /** API key for this specific deploy. Overrides client's default. */
+    /** 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. */
+    /** 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;
+    /** Optional array of tags for categorization and filtering (lowercase, alphanumeric with separators). */
+    tags?: string[];
     /** Callback for overall deploy progress (0-100). */
     onProgress?: (progress: number) => void;
     /** Callback for detailed progress statistics. */
@@ -63,9 +65,9 @@ interface ProgressStats {
 interface ShipClientOptions {
     /** Default API URL for the client instance. */
     apiUrl?: string | undefined;
-    /** API key for authenticated deployments. */
+    /** API key for authenticated deployments (format: ship-<64-char-hex>, total 69 chars). */
     apiKey?: string | undefined;
-    /** Deploy token for single-use deployments. */
+    /** Deploy token for single-use deployments (format: token-<64-char-hex>, total 70 chars). */
     deployToken?: string | undefined;
     /** Path to custom config file. */
     configFile?: string | undefined;
@@ -91,118 +93,144 @@ interface ShipClientOptions {
      */
     timeout?: number | undefined;
 }
+/**
+ * Event map for Ship SDK events
+ * Core events for observability: request, response, error
+ */
+interface ShipEvents extends Record<string, any[]> {
+    /** Emitted before each API request */
+    request: [url: string, init: RequestInit];
+    /** Emitted after successful API response */
+    response: [response: Response, url: string];
+    /** Emitted when API request fails */
+    error: [error: Error, url: string];
+}
 
 /**
- * Handles direct HTTP communication with the Ship API, including deploys and health checks.
- * Responsible for constructing requests, managing authentication, and error translation.
- * @internal
+ * Event system for Ship SDK
+ * Lightweight, reliable event handling with proper error boundaries
  */
-declare class ApiHttp {
-    #private;
-    private readonly apiUrl;
-    private readonly apiKey;
-    private readonly deployToken;
+
+/**
+ * Lightweight event system
+ * - Add handler: on()
+ * - Remove handler: off()
+ * - Emit events: emit() [internal]
+ * - Transfer events: transfer() [internal]
+ * - Reliable error handling and cleanup
+ */
+declare class SimpleEvents {
+    private handlers;
     /**
-     * Constructs a new ApiHttp instance with the provided client options.
-     * @param options - Client options including API host, authentication credentials, and timeout settings.
+     * Add event handler
      */
-    constructor(options: ShipClientOptions);
+    on<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
     /**
-     * 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).
+     * Remove event handler
      */
-    ping(): Promise<boolean>;
+    off<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
     /**
-     * Get full ping response from the API server
-     * @returns Promise resolving to the full PingResponse object.
+     * Emit event (internal use only)
+     * @internal
      */
-    getPingResponse(): Promise<PingResponse>;
+    emit<K extends keyof ShipEvents>(event: K, ...args: ShipEvents[K]): void;
     /**
-     * Fetches platform configuration from the API.
-     * @returns Promise resolving to the config response.
-     * @throws {ShipError} If the config request fails.
+     * Transfer all handlers to another events instance
+     * @internal
      */
-    getConfig(): Promise<ConfigResponse>;
+    transfer(target: SimpleEvents): void;
     /**
-     * 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.
+     * Clear all handlers (for cleanup)
+     * @internal
      */
-    deploy(files: StaticFile[], options?: ApiDeployOptions): Promise<Deployment>;
+    clear(): void;
+}
+
+/**
+ * @file HTTP client with integrated event system
+ * Clean, direct implementation with reliable error handling
+ */
+
+/**
+ * HTTP client with integrated event system
+ * - Direct event integration
+ * - Clean inheritance from SimpleEvents
+ * - Reliable error handling
+ */
+declare class ApiHttp extends SimpleEvents {
+    private readonly apiUrl;
+    private readonly apiKey;
+    private readonly deployToken;
+    constructor(options: ShipClientOptions);
     /**
-     * Lists all deployments for the authenticated account
-     * @returns Promise resolving to deployment list response
+     * Transfer events to another client (clean intentional API)
      */
-    listDeployments(): Promise<DeploymentListResponse>;
+    transferEventsTo(target: ApiHttp): void;
     /**
-     * Gets a specific deployment by ID
-     * @param id - Deployment ID to retrieve
-     * @returns Promise resolving to deployment details
+     * Make authenticated HTTP request with events
      */
-    getDeployment(id: string): Promise<Deployment>;
+    private request;
     /**
-     * Removes a deployment by ID
-     * @param id - Deployment ID to remove
-     * @returns Promise resolving when removal is complete
+     * Generate auth headers
      */
-    removeDeployment(id: string): Promise<void>;
+    private getAuthHeaders;
     /**
-     * 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
+     * Check if credentials are needed
      */
-    setAlias(name: string, deployment: string): Promise<_shipstatic_types.Alias>;
+    private needsCredentials;
     /**
-     * Gets a specific alias by name
-     * @param name - Alias name to retrieve
-     * @returns Promise resolving to alias details
+     * Safely clone response for events
      */
-    getAlias(name: string): Promise<Alias>;
+    private safeClone;
     /**
-     * Lists all aliases for the authenticated account
-     * @returns Promise resolving to alias list response
+     * Parse JSON response
      */
-    listAliases(): Promise<AliasListResponse>;
+    private parseResponse;
     /**
-     * Removes an alias by name
-     * @param name - Alias name to remove
-     * @returns Promise resolving to removal confirmation
+     * Handle response errors
      */
-    removeAlias(name: string): Promise<void>;
+    private handleResponseError;
     /**
-     * Triggers a manual DNS check for an external alias
-     * @param name - Alias name to check DNS for
-     * @returns Promise resolving to confirmation message
+     * Handle fetch errors
      */
-    checkAlias(name: string): Promise<{
+    private handleFetchError;
+    ping(): Promise<boolean>;
+    getPingResponse(): Promise<PingResponse>;
+    getConfig(): Promise<ConfigResponse>;
+    deploy(files: StaticFile[], options?: ApiDeployOptions): Promise<Deployment>;
+    listDeployments(): Promise<DeploymentListResponse>;
+    getDeployment(id: string): Promise<Deployment>;
+    removeDeployment(id: string): Promise<void>;
+    setAlias(name: string, deployment: string, tags?: string[]): Promise<Alias>;
+    getAlias(name: string): Promise<Alias>;
+    listAliases(): Promise<AliasListResponse>;
+    removeAlias(name: string): Promise<void>;
+    confirmAlias(name: string): Promise<{
         message: string;
     }>;
-    /**
-     * Gets account details for the authenticated user
-     * @returns Promise resolving to account details
-     */
+    getAliasDns(name: string): Promise<{
+        alias: string;
+        dns: any;
+    }>;
+    getAliasRecords(name: string): Promise<{
+        alias: string;
+        records: any[];
+    }>;
+    getAliasShare(name: string): Promise<{
+        alias: string;
+        hash: string;
+    }>;
     getAccount(): Promise<Account>;
-    /**
-     * 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>;
+    private validateFiles;
+    private prepareRequestPayload;
+    private createBrowserBody;
+    private createNodeBody;
+    private getBrowserContentType;
 }
 
 /**
- * @file All Ship SDK resources in one place - impossibly simple.
+ * @file Ship SDK resource implementations for deployments, aliases, and accounts.
  */
 
 declare function createDeploymentResource(getApi: () => ApiHttp, clientDefaults?: ShipClientOptions, ensureInit?: () => Promise<void>, processInput?: (input: DeployInput, options: DeploymentOptions) => Promise<StaticFile[]>): DeploymentResource;
@@ -254,6 +282,24 @@ declare abstract class Ship$1 {
      * Get account resource
      */
     get account(): AccountResource;
+    /**
+     * Add event listener
+     * @param event - Event name
+     * @param handler - Event handler function
+     */
+    on<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
+    /**
+     * Remove event listener
+     * @param event - Event name
+     * @param handler - Event handler function
+     */
+    off<K extends keyof ShipEvents>(event: K, handler: (...args: ShipEvents[K]) => void): void;
+    /**
+     * Replace HTTP client while preserving event listeners
+     * Used during initialization to maintain user event subscriptions
+     * @protected
+     */
+    protected replaceHttpClient(newClient: ApiHttp): void;
 }
 
 /**
@@ -452,4 +498,4 @@ declare class Ship extends Ship$1 {
     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, Ship as default, filterJunk, getCurrentConfig, getENV, loadConfig, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForNode, resolveConfig, setConfig };
+export { type ApiDeployOptions, ApiHttp, type Config, type DeployFile, type DeploymentOptions, type ExecutionEnvironment, JUNK_DIRECTORIES, type MD5Result, type ProgressStats, Ship, type ShipClientOptions, type ShipEvents, __setTestEnvironment, calculateMD5, createAccountResource, createAliasResource, createDeploymentResource, Ship as default, filterJunk, getCurrentConfig, getENV, loadConfig, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForNode, resolveConfig, setConfig, setConfig as setPlatformConfig };