@shipstatic/ship 0.3.2 → 0.3.4

package/README.md

@@ -5,9 +5,10 @@ A modern, lightweight SDK and CLI for deploying static files, designed for both
 ## Features
 
 - **🚀 Modern Resource API**: Clean `ship.deployments.create()` interface - no legacy wrappers
-- **🌍 Universal**: Automatic environment detection (Node.js/Browser) with optimized implementations  
+- **🌍 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
+- **✅ Client-Side Validation**: Validate files before upload (size, count, MIME types)
 - **📁 Flexible Input**: File paths (Node.js) or File objects (Browser/drag-drop)
 - **🔐 Secure**: MD5 checksums and data integrity validation
 - **📊 Progress Tracking**: Real-time deployment progress and statistics
@@ -133,6 +134,56 @@ const ship = new Ship({ apiKey: 'ship-your-key' });
 - **Always current** - SDK always uses current platform limits
 - **Fail fast** - SDK fails if unable to fetch valid configuration
 
+## Client-Side File Validation
+
+Ship SDK provides utilities for validating files before upload. Validation is **atomic** - if any file is invalid, the entire upload is rejected.
+
+```typescript
+import { validateFiles, formatFileSize } from '@shipstatic/ship';
+
+// Get platform configuration
+const config = await ship.getConfig();
+
+// Validate files before upload
+const result = validateFiles(files, config);
+
+if (result.error) {
+  // Global summary
+  console.error(result.error.details); // "2 files failed validation"
+
+  // All specific errors
+  result.error.errors.forEach(err => console.error(err));
+  // "file1.wasm: File type 'application/wasm' is not allowed"
+  // "file2.txt: File size (10 MB) exceeds limit of 5 MB"
+
+  // Per-file status (all files marked failed in atomic validation)
+  result.files.forEach(f => {
+    console.log(`${f.name}: ${f.statusMessage}`);
+  });
+} else {
+  console.log(`${result.validFiles.length} files ready to upload`);
+  await ship.deployments.create(result.validFiles);
+}
+```
+
+**Validation checks:**
+- File count limit
+- Individual file size limit
+- Total deployment size limit
+- MIME type validation (against allowed categories)
+- Empty file detection
+
+**Error handling:**
+- `error.details` - Human-readable summary ("2 files failed validation")
+- `error.errors` - Array of all validation errors for detailed display
+- `file.statusMessage` - Individual file status for UI highlighting
+
+**Utilities:**
+- `validateFiles(files, config)` - Validate files against config limits
+- `formatFileSize(bytes, decimals?)` - Format bytes to human-readable string
+- `getValidFiles(files)` - Filter files with `READY` status
+- `FILE_VALIDATION_STATUS` - Status constants for file processing
+
 ## API Reference
 
 ### Ship Class
@@ -180,14 +231,21 @@ await ship.deployments.get(id)
 
 #### Deploy Input Types
 
-**Node.js Environment:**
 ```typescript
-type NodeDeployInput = string[];  // File paths
+type DeployInput = File[] | string | string[];
 ```
 
+**Node.js Environment:**
+- `string` - Single file or directory path
+- `string[]` - Multiple file/directory paths
+
 **Browser Environment:**
+- `File[]` - Array of File objects
+
+**Note:** For `<input type="file">` elements, convert FileList to File[]:
 ```typescript
-type BrowserDeployInput = FileList | File[] | HTMLInputElement;
+const files = Array.from(fileInput.files);
+await ship.deploy(files);
 ```
 
 #### Deploy Options
@@ -284,17 +342,14 @@ const ship = new Ship({
   apiKey: 'ship-your-64-char-hex-string'  // 69 chars total
 });
 
-// From file input
+// From file input - convert FileList to File[]
 const fileInput = document.getElementById('fileInput') as HTMLInputElement;
-const result = await ship.deployments.create(fileInput, {
+const files: File[] = Array.from(fileInput.files || []);
+const result = await ship.deployments.create(files, {
   onProgress: (progress) => {
     document.getElementById('progress').textContent = `${progress}%`;
   }
 });
-
-// From File objects
-const files: File[] = Array.from(fileInput.files || []);
-const result2 = await ship.deployments.create(files);
 ```
 
 ## Event System

package/dist/browser.d.ts

@@ -439,6 +439,96 @@ declare function __setTestEnvironment(env: ExecutionEnvironment | null): void;
  */
 declare function getENV(): ExecutionEnvironment;
 
+/**
+ * @file File validation utilities for Ship SDK
+ * Provides client-side validation for file uploads before deployment
+ */
+
+/**
+ * File status constants for validation state tracking
+ */
+declare const FILE_VALIDATION_STATUS: {
+    readonly PENDING: "pending";
+    readonly PROCESSING_ERROR: "processing_error";
+    readonly EMPTY_FILE: "empty_file";
+    readonly VALIDATION_FAILED: "validation_failed";
+    readonly READY: "ready";
+};
+type FileValidationStatus = (typeof FILE_VALIDATION_STATUS)[keyof typeof FILE_VALIDATION_STATUS];
+/**
+ * Client-side validation error structure
+ */
+interface ValidationError {
+    error: string;
+    details: string;
+    errors: string[];
+    isClientError: true;
+}
+/**
+ * Minimal file interface required for validation
+ */
+interface ValidatableFile {
+    name: string;
+    size: number;
+    type: string;
+    status?: string;
+    statusMessage?: string;
+}
+/**
+ * File validation result
+ *
+ * NOTE: Validation is ATOMIC - if any file fails validation, ALL files are rejected.
+ * This ensures deployments are all-or-nothing for data integrity.
+ */
+interface FileValidationResult<T extends ValidatableFile> {
+    /** All files with updated status */
+    files: T[];
+    /** Files that passed validation (empty if ANY file failed - atomic validation) */
+    validFiles: T[];
+    /** Validation error if any files failed */
+    error: ValidationError | null;
+}
+/**
+ * Format file size to human-readable string
+ */
+declare function formatFileSize(bytes: number, decimals?: number): string;
+/**
+ * Validate files against configuration limits
+ *
+ * ATOMIC VALIDATION: If ANY file fails validation, ALL files are rejected.
+ * This ensures deployments are all-or-nothing for data integrity.
+ *
+ * @param files - Array of files to validate
+ * @param config - Validation configuration from ship.getConfig()
+ * @returns Validation result with updated file status
+ *
+ * @example
+ * ```typescript
+ * const config = await ship.getConfig();
+ * const result = validateFiles(files, config);
+ *
+ * if (result.error) {
+ *   // Validation failed - result.validFiles will be empty
+ *   console.error(result.error.details);
+ *   // Show individual file errors:
+ *   result.files.forEach(f => console.log(`${f.name}: ${f.statusMessage}`));
+ * } else {
+ *   // All files valid - safe to upload
+ *   await ship.deploy(result.validFiles);
+ * }
+ * ```
+ */
+declare function validateFiles<T extends ValidatableFile>(files: T[], config: ConfigResponse): FileValidationResult<T>;
+/**
+ * Get only the valid files from validation results
+ */
+declare function getValidFiles<T extends ValidatableFile>(files: T[]): T[];
+/**
+ * Check if all valid files have required properties for upload
+ * (Can be extended to check for MD5, etc.)
+ */
+declare function allValidFilesReady<T extends ValidatableFile>(files: T[]): boolean;
+
 /**
  * @file Browser configuration implementation - no file system access.
  * Browser environment receives all config through constructor options.
@@ -471,15 +561,15 @@ declare function getCurrentConfig(): ConfigResponse;
  */
 
 /**
- * Processes browser files (FileList or File[]) into an array of StaticFile objects ready for deploy.
+ * Processes browser files 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 browserFiles - 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[]>;
+declare function processFilesForBrowser(browserFiles: File[], options?: DeploymentOptions): Promise<StaticFile[]>;
 
 /**
  * @file Ship SDK for browser environments with streamlined configuration.
@@ -500,7 +590,7 @@ declare function processFilesForBrowser(browserFiles: FileList | File[], options
  * });
  *
  * // Deploy files from input element
- * const files = fileInput.files;
+ * const files = Array.from(fileInput.files);
  * await ship.deploy(files);
  * ```
  */
@@ -512,4 +602,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, type ShipEvents, __setTestEnvironment, calculateMD5, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, filterJunk, getCurrentConfig, getENV, loadConfig, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForBrowser, resolveConfig, setConfig as setPlatformConfig };
+export { type ApiDeployOptions, ApiHttp, type Config, type DeployFile, type DeploymentOptions, type ExecutionEnvironment, FILE_VALIDATION_STATUS, type FileValidationResult, type FileValidationStatus, JUNK_DIRECTORIES, type MD5Result, type ProgressStats, Ship, type ShipClientOptions, type ShipEvents, type ValidatableFile, type ValidationError, __setTestEnvironment, allValidFilesReady, calculateMD5, createAccountResource, createDeploymentResource, createDomainResource, createTokenResource, Ship as default, filterJunk, formatFileSize, getCurrentConfig, getENV, getValidFiles, loadConfig, mergeDeployOptions, optimizeDeployPaths, pluralize, processFilesForBrowser, resolveConfig, setConfig as setPlatformConfig, validateFiles };