@shipstatic/ship 0.2.4 → 0.2.5

package/README.md

@@ -1,11 +1,12 @@
 # 🚢 Ship CLI & SDK
 
-A modern, lightweight SDK and CLI for deploying static files, designed for both **Node.js** and **Browser** environments with a clean resource-based API.
+A modern, lightweight SDK and CLI for deploying static files, designed for both **Node.js** and **Browser** environments with a clean resource-based API and comprehensive event system for observability.
 
 ## Features
 
 - **🚀 Modern Resource API**: Clean `ship.deployments.create()` interface - no legacy wrappers
 - **🌍 Universal**: Automatic environment detection (Node.js/Browser) with optimized implementations  
+- **📡 Event System**: Complete observability with request, response, and error events
 - **🔧 Dynamic Configuration**: Automatically fetches platform limits from API
 - **📁 Flexible Input**: File paths (Node.js) or File objects (Browser/drag-drop)
 - **🔐 Secure**: MD5 checksums and data integrity validation
@@ -114,7 +115,7 @@ Ship SDK automatically fetches platform configuration from the API on initializa
 // SDK automatically calls GET /config and applies limits
 const ship = new Ship({ apiKey: 'ship-your-key' });
 
-// Platform limits are now available for validation:
+// Platform limits are available for validation:
 // - maxFileSize: Dynamic file size limit
 // - maxFilesCount: Dynamic file count limit  
 // - maxTotalSize: Dynamic total size limit
@@ -122,7 +123,7 @@ const ship = new Ship({ apiKey: 'ship-your-key' });
 
 **Benefits:**
 - **Single source of truth** - Limits only need to be changed on the API side
-- **Automatic updates** - SDK always uses current platform limits
+- **Always current** - SDK always uses current platform limits
 - **Fail fast** - SDK fails if unable to fetch valid configuration
 
 ## API Reference
@@ -151,6 +152,8 @@ interface ShipOptions {
 - `ship.deployments` - Access deployment resource
 - `ship.aliases` - Access alias resource  
 - `ship.account` - Access account resource
+- `ship.on(event, handler)` - Add event listener for API observability
+- `ship.off(event, handler)` - Remove event listener
 
 ### Deployments Resource
 
@@ -255,6 +258,161 @@ const files: File[] = Array.from(fileInput.files || []);
 const result2 = await ship.deployments.create(files);
 ```
 
+## Event System
+
+Ship SDK provides a comprehensive event system for complete observability of all API operations. The event system is lightweight, reliable, and provides detailed insights into requests, responses, and errors.
+
+### Event Types
+
+The SDK emits three core events:
+
+- **`request`** - Emitted before each API request
+- **`response`** - Emitted after successful API responses  
+- **`error`** - Emitted when API requests fail
+
+### Basic Event Usage
+
+```javascript
+import Ship from '@shipstatic/ship';
+
+const ship = new Ship({ apiKey: 'ship-your-api-key' });
+
+// Listen to all API requests
+ship.on('request', (url, requestInit) => {
+  console.log(`→ ${requestInit.method} ${url}`);
+});
+
+// Listen to all API responses
+ship.on('response', (response, url) => {
+  console.log(`← ${response.status} ${url}`);
+});
+
+// Listen to all API errors
+ship.on('error', (error, url) => {
+  console.error(`✗ Error at ${url}:`, error.message);
+});
+
+// Deploy with events
+const result = await ship.deployments.create('./dist');
+```
+
+### Advanced Event Patterns
+
+#### Request/Response Logging
+```javascript
+// Log all API traffic
+ship.on('request', (url, init) => {
+  console.log(`[${new Date().toISOString()}] → ${init.method} ${url}`);
+  if (init.body) {
+    console.log(`  Body: ${init.body instanceof FormData ? '[FormData]' : init.body}`);
+  }
+});
+
+ship.on('response', (response, url) => {
+  console.log(`[${new Date().toISOString()}] ← ${response.status} ${response.statusText} ${url}`);
+});
+```
+
+#### Error Monitoring
+```javascript
+// Comprehensive error tracking
+ship.on('error', (error, url) => {
+  // Send to monitoring service
+  analytics.track('ship_api_error', {
+    url,
+    error: error.message,
+    type: error.constructor.name,
+    timestamp: Date.now()
+  });
+});
+```
+
+#### Performance Monitoring
+```javascript
+const requestTimes = new Map();
+
+ship.on('request', (url, init) => {
+  requestTimes.set(url, Date.now());
+});
+
+ship.on('response', (response, url) => {
+  const startTime = requestTimes.get(url);
+  if (startTime) {
+    const duration = Date.now() - startTime;
+    console.log(`${url} took ${duration}ms`);
+    requestTimes.delete(url);
+  }
+});
+```
+
+#### Custom Analytics Integration
+```javascript
+// Google Analytics integration
+ship.on('request', (url, init) => {
+  gtag('event', 'api_request', {
+    'custom_url': url,
+    'method': init.method
+  });
+});
+
+ship.on('response', (response, url) => {
+  gtag('event', 'api_response', {
+    'custom_url': url,
+    'status_code': response.status
+  });
+});
+```
+
+### Event Handler Management
+
+```javascript
+// Add event handlers
+const requestHandler = (url, init) => console.log(`Request: ${url}`);
+ship.on('request', requestHandler);
+
+// Remove specific handlers
+ship.off('request', requestHandler);
+
+// Event handlers are automatically cleaned up when ship instance is garbage collected
+```
+
+### Event System Features
+
+- **Reliable**: Handlers that throw errors are automatically removed to prevent cascading failures
+- **Safe**: Response objects are safely cloned for event handlers to prevent body consumption conflicts
+- **Lightweight**: Minimal overhead - only 70 lines of code
+- **Type Safe**: Full TypeScript support with proper event argument typing
+- **Clean**: Automatic cleanup prevents memory leaks
+
+### TypeScript Event Types
+
+```typescript
+import Ship from '@shipstatic/ship';
+
+const ship = new Ship({ apiKey: 'ship-your-api-key' });
+
+// Fully typed event handlers
+ship.on('request', (url: string, init: RequestInit) => {
+  console.log(`Request to ${url}`);
+});
+
+ship.on('response', (response: Response, url: string) => {
+  console.log(`Response from ${url}: ${response.status}`);
+});
+
+ship.on('error', (error: Error, url: string) => {
+  console.error(`Error at ${url}:`, error);
+});
+```
+
+### Event System Architecture
+
+The event system is built directly into the HTTP client with:
+- **Direct Integration**: Events are emitted from the core HTTP operations
+- **Error Boundaries**: Failed event handlers don't crash API operations  
+- **Response Cloning**: Dedicated response clones for events and parsing
+- **Graceful Degradation**: Event system failures don't affect core functionality
+
 ## Unified Error Handling
 
 The Ship SDK uses a unified error system with a single `ShipError` class:
@@ -418,7 +576,7 @@ ship account            # Get account details
 - **Browser**: 185KB (ESM with dependencies)
 - **CLI**: 38KB (CJS)
 
-**Recent Optimizations:**
+**Key Optimizations:**
 - ✅ **Unified error system** - Single `ShipError` class for all components
 - ✅ **Dynamic platform configuration** - Fetches limits from API
 - ✅ **Replaced axios with native fetch** - Bundle size reduction
@@ -434,6 +592,7 @@ Full TypeScript support with exported types from shared `@shipstatic/types`:
 // TypeScript - works with both import styles
 import type { 
   ShipOptions,
+  ShipEvents,
   NodeDeployInput,
   BrowserDeployInput, 
   DeployOptions,
@@ -451,6 +610,7 @@ import type {
 - **Class-based API**: `new Ship()` with resource properties
 - **Environment detection**: Automatic Node.js/Browser optimizations
 - **Native dependencies**: Uses built-in `fetch`, `crypto`, and `fs` APIs
+- **Event system**: Comprehensive observability with lightweight, reliable events
 - **Type safety**: Strict TypeScript with comprehensive error types
 - **Dynamic configuration**: Platform limits fetched from API
 - **Unified DTOs**: Shared type definitions from `@shipstatic/types`
@@ -471,6 +631,7 @@ src/
 │   ├── api/               # HTTP client and API communication
 │   ├── base-ship.ts       # Base Ship class implementation
 │   ├── core/              # Configuration and constants
+│   ├── events.ts          # Event system implementation
 │   ├── lib/               # Utility libraries
 │   ├── resources.ts       # Resource implementations
 │   └── types.ts           # Shared type definitions
@@ -500,24 +661,24 @@ File Objects → Path Extraction → Junk Filtering → Content Processing → S
 - **Wire format support**: Automatic serialization/deserialization
 - **Helper methods**: Easy type checking with `is*Error()` methods
 
-## Development Status
-
-This is an **unlaunched project** optimized for modern development:
-
-- ✅ **Deployment Resource**: Full implementation (create, list, get, remove)
-- ✅ **Alias Resource**: Full implementation (set, get, list, remove)  
-- ✅ **Account Resource**: Full implementation (get account details)
-- ✅ **Unified Error System**: Single `ShipError` class with factory methods
-- ✅ **Dynamic Platform Config**: Automatic limit fetching from API
-- ✅ **Ultra-Simple CLI**: Deploy shortcut + explicit commands
-- ✅ **Streamlined Multipart**: `files[]` array + JSON checksums format
-- ✅ **Direct Validation**: Functions throw errors instead of returning results
-- ✅ **Shared DTOs**: All types from `@shipstatic/types` package
-- ✅ **Tree-shakeable**: `"sideEffects": false` for optimal bundling
-- ✅ **Impossible Simplicity**: Maximum functionality with minimal complexity
-- 🎯 No legacy compatibility constraints
-- 🔧 Native fetch API for optimal performance
-- ⚡ Modern ESM modules with TypeScript
+## Features & Capabilities
+
+Ship SDK provides comprehensive deployment functionality:
+
+- **Deployment Resource**: Complete operations (create, list, get, remove)
+- **Alias Resource**: Complete operations (set, get, list, remove)  
+- **Account Resource**: Account information retrieval
+- **Event System**: Comprehensive observability with request, response, error events
+- **Unified Error System**: Single `ShipError` class with factory methods
+- **Dynamic Platform Config**: Automatic limit fetching from API
+- **Simple CLI**: Deploy shortcut + explicit commands
+- **Streamlined Multipart**: `files[]` array + JSON checksums format
+- **Direct Validation**: Functions throw errors for immediate feedback
+- **Shared DTOs**: All types from `@shipstatic/types` package
+- **Tree-shakeable**: `"sideEffects": false` for optimal bundling
+- **Production Ready**: Clean, reliable implementation with comprehensive test coverage
+- **Native APIs**: Built on `fetch`, `crypto`, and `fs` for optimal performance
+- **Modern TypeScript**: Full type safety with ESM modules
 
 ## Testing
 
@@ -543,7 +704,7 @@ pnpm build && pnpm test --run
 - **Node.js tests**: Filesystem and path manipulation
 - **Error tests**: Unified error handling patterns
 
-**Current Status:** 566 tests passing (596 total) ✅
+**Current Status:** 614 tests passing (614 total) ✅
 
 ## Contributing
 

package/dist/browser.d.ts

@@ -91,118 +91,132 @@ 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
      */
+    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): Promise<Alias>;
+    getAlias(name: string): Promise<Alias>;
+    listAliases(): Promise<AliasListResponse>;
+    removeAlias(name: string): Promise<void>;
     checkAlias(name: string): Promise<{
         message: string;
     }>;
-    /**
-     * Gets account details for the authenticated user
-     * @returns Promise resolving to account details
-     */
     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 +268,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;
 }
 
 /**
@@ -438,4 +470,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, getENV, loadConfig, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForBrowser, 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, getENV, loadConfig, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForBrowser, resolveConfig, setConfig };