@shipstatic/drop 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,200 @@
+import { ConfigResponse, StaticFile } from '@shipstatic/types';
+
+/**
+ * Core types for @shipstatic/dropzone
+ * Imports types from @shipstatic/types (single source of truth)
+ * and defines dropzone-specific types
+ */
+
+declare const FILE_STATUSES: {
+    readonly PENDING: "pending";
+    readonly PROCESSING: "processing";
+    readonly VALIDATION_FAILED: "validation_failed";
+    readonly PROCESSING_ERROR: "processing_error";
+    readonly EMPTY_FILE: "empty_file";
+    readonly READY: "ready";
+    readonly UPLOADING: "uploading";
+    readonly COMPLETE: "complete";
+    readonly ERROR: "error";
+};
+type FileStatus = (typeof FILE_STATUSES)[keyof typeof FILE_STATUSES];
+/**
+ * Client-side error structure
+ */
+interface ClientError {
+    error: string;
+    details: string;
+    isClientError: true;
+}
+/**
+ * Processed file entry ready for upload
+ * Extends StaticFile from SDK, adding UI-specific properties
+ * This means ProcessedFile IS a StaticFile - can be passed directly to ship.deployments.create()
+ */
+interface ProcessedFile extends StaticFile {
+    /** Unique identifier for React keys and tracking */
+    id: string;
+    /** Original File object (alias for 'content' from StaticFile for better DX) */
+    file: File;
+    /** Filename without path */
+    name: string;
+    /** MIME type for UI icons/previews */
+    type: string;
+    /** Last modified timestamp */
+    lastModified: number;
+    /** Current processing/upload status */
+    status: FileStatus;
+    /** Human-readable status message for UI */
+    statusMessage?: string;
+    /** Upload progress (0-100) - only set during upload */
+    progress?: number;
+}
+/**
+ * Validation configuration - direct alias to SDK's ConfigResponse
+ * This allows passing the config directly from ship.getConfig() to the dropzone
+ *
+ * Single source of truth: @shipstatic/types
+ */
+type ValidationConfig = ConfigResponse;
+/**
+ * Default validation limits
+ */
+declare const DEFAULT_VALIDATION: ConfigResponse;
+
+interface DropzoneManagerOptions {
+    /** Validation configuration (from ship.getConfig()) */
+    config?: Partial<ValidationConfig>;
+    /** Callback when validation fails */
+    onValidationError?: (error: ClientError) => void;
+    /** Callback when files are ready for upload */
+    onFilesReady?: (files: ProcessedFile[]) => void;
+    /** Whether to strip common directory prefix from paths (default: true) */
+    stripPrefix?: boolean;
+}
+interface DropzoneManagerReturn {
+    /** All processed files with their status */
+    files: ProcessedFile[];
+    /** Current status text */
+    statusText: string;
+    /** Whether currently processing files (ZIP extraction, etc.) */
+    isProcessing: boolean;
+    /** Last validation error if any */
+    validationError: ClientError | null;
+    /** Whether all valid files have MD5 checksums calculated */
+    hasChecksums: boolean;
+    /** Process files from dropzone (resets and replaces existing files) */
+    processFiles: (files: File[]) => Promise<void>;
+    /** Remove a specific file */
+    removeFile: (fileId: string) => void;
+    /** Clear all files and reset state */
+    clearAll: () => void;
+    /** Get only valid files ready for upload */
+    getValidFiles: () => ProcessedFile[];
+    /** Update upload state for a specific file (status, progress, message) */
+    updateFileStatus: (fileId: string, state: {
+        status: FileStatus;
+        statusMessage?: string;
+        progress?: number;
+    }) => void;
+}
+/**
+ * Headless dropzone manager hook
+ * Handles file processing, ZIP extraction, and validation
+ * Does NOT handle uploading - that's the consumer's responsibility
+ */
+declare function useDropzoneManager(options?: DropzoneManagerOptions): DropzoneManagerReturn;
+
+/**
+ * Calculate MD5 hash from ArrayBuffer
+ */
+declare function calculateMD5(buffer: ArrayBuffer): Promise<string>;
+/**
+ * Format file size to human-readable string
+ */
+declare function formatFileSize(bytes: number, decimals?: number): string;
+/**
+ * Create a ProcessedFile from a File object
+ * This is the single conversion point from File to ProcessedFile
+ *
+ * Path resolution priority:
+ * 1. options.path (if provided)
+ * 2. file.webkitRelativePath (if non-empty, preserves folder structure)
+ * 3. file.name (fallback)
+ */
+declare function createProcessedFile(file: File, options?: {
+    /** Custom path (defaults to webkitRelativePath or file.name) */
+    path?: string;
+    /** Whether to calculate MD5 hash (defaults to true) */
+    calculateMD5?: boolean;
+}): Promise<ProcessedFile>;
+/**
+ * Validate and update status of ProcessedFiles
+ * Returns files with updated status and validation error if any
+ */
+interface ValidationResult {
+    /** All files with updated status */
+    files: ProcessedFile[];
+    /** Files that passed validation (status: READY) */
+    validFiles: ProcessedFile[];
+    /** Validation error if any files failed */
+    error: ClientError | null;
+}
+declare function validateFiles(files: ProcessedFile[], config: ValidationConfig): ValidationResult;
+/**
+ * Get only the valid files (status: READY) from a list
+ */
+declare function getValidFiles(files: ProcessedFile[]): ProcessedFile[];
+/**
+ * Check if all valid files have MD5 checksums calculated
+ */
+declare function allValidFilesHaveChecksums(files: ProcessedFile[]): boolean;
+/**
+ * Strip common directory prefix from file paths
+ * Only strips if ALL files share the same prefix
+ */
+declare function stripCommonPrefix(files: ProcessedFile[]): ProcessedFile[];
+
+interface ZipExtractionResult {
+    /** Extracted files as regular File objects */
+    files: File[];
+    /** Any errors encountered during extraction */
+    errors: string[];
+}
+/**
+ * Extracts all files from a ZIP archive
+ * Returns regular File objects that can be processed like any other file
+ */
+declare function extractZipToFiles(zipFile: File): Promise<ZipExtractionResult>;
+/**
+ * Sanitize and normalize a file path to prevent directory traversal attacks
+ * Removes: .., ., leading/trailing slashes, absolute paths, and empty segments
+ *
+ * @example
+ * normalizePath('../../etc/passwd') → 'etc/passwd'
+ * normalizePath('foo/./bar/../baz.txt') → 'foo/baz.txt'
+ * normalizePath('/absolute/path.txt') → 'absolute/path.txt'
+ */
+declare function normalizePath(path: string): string;
+/**
+ * Check if a file path is a junk file that should be filtered out
+ * Filters common system files like .DS_Store, Thumbs.db, desktop.ini,
+ * and macOS resource fork metadata in __MACOSX directories
+ *
+ * Case-insensitive matching to handle files from different operating systems
+ * (Windows file systems are case-insensitive, so Thumbs.db === THUMBS.DB)
+ *
+ * @example
+ * isJunkFile('.DS_Store') → true
+ * isJunkFile('.ds_store') → true (case-insensitive)
+ * isJunkFile('THUMBS.DB') → true (case-insensitive)
+ * isJunkFile('folder/.DS_Store') → true
+ * isJunkFile('__MACOSX/file.txt') → true
+ * isJunkFile('mydsstore.txt') → false
+ */
+declare function isJunkFile(path: string): boolean;
+/**
+ * Check if a file is a ZIP file based on MIME type or extension
+ */
+declare function isZipFile(file: File): boolean;
+
+export { type ClientError, DEFAULT_VALIDATION, type DropzoneManagerOptions, type DropzoneManagerReturn, FILE_STATUSES, type FileStatus, type ProcessedFile, type ValidationConfig, type ValidationResult, type ZipExtractionResult, allValidFilesHaveChecksums, calculateMD5, createProcessedFile, extractZipToFiles, formatFileSize, getValidFiles, isJunkFile, isZipFile, normalizePath, stripCommonPrefix, useDropzoneManager, validateFiles };

package/dist/index.d.ts

@@ -0,0 +1,200 @@
+import { ConfigResponse, StaticFile } from '@shipstatic/types';
+
+/**
+ * Core types for @shipstatic/dropzone
+ * Imports types from @shipstatic/types (single source of truth)
+ * and defines dropzone-specific types
+ */
+
+declare const FILE_STATUSES: {
+    readonly PENDING: "pending";
+    readonly PROCESSING: "processing";
+    readonly VALIDATION_FAILED: "validation_failed";
+    readonly PROCESSING_ERROR: "processing_error";
+    readonly EMPTY_FILE: "empty_file";
+    readonly READY: "ready";
+    readonly UPLOADING: "uploading";
+    readonly COMPLETE: "complete";
+    readonly ERROR: "error";
+};
+type FileStatus = (typeof FILE_STATUSES)[keyof typeof FILE_STATUSES];
+/**
+ * Client-side error structure
+ */
+interface ClientError {
+    error: string;
+    details: string;
+    isClientError: true;
+}
+/**
+ * Processed file entry ready for upload
+ * Extends StaticFile from SDK, adding UI-specific properties
+ * This means ProcessedFile IS a StaticFile - can be passed directly to ship.deployments.create()
+ */
+interface ProcessedFile extends StaticFile {
+    /** Unique identifier for React keys and tracking */
+    id: string;
+    /** Original File object (alias for 'content' from StaticFile for better DX) */
+    file: File;
+    /** Filename without path */
+    name: string;
+    /** MIME type for UI icons/previews */
+    type: string;
+    /** Last modified timestamp */
+    lastModified: number;
+    /** Current processing/upload status */
+    status: FileStatus;
+    /** Human-readable status message for UI */
+    statusMessage?: string;
+    /** Upload progress (0-100) - only set during upload */
+    progress?: number;
+}
+/**
+ * Validation configuration - direct alias to SDK's ConfigResponse
+ * This allows passing the config directly from ship.getConfig() to the dropzone
+ *
+ * Single source of truth: @shipstatic/types
+ */
+type ValidationConfig = ConfigResponse;
+/**
+ * Default validation limits
+ */
+declare const DEFAULT_VALIDATION: ConfigResponse;
+
+interface DropzoneManagerOptions {
+    /** Validation configuration (from ship.getConfig()) */
+    config?: Partial<ValidationConfig>;
+    /** Callback when validation fails */
+    onValidationError?: (error: ClientError) => void;
+    /** Callback when files are ready for upload */
+    onFilesReady?: (files: ProcessedFile[]) => void;
+    /** Whether to strip common directory prefix from paths (default: true) */
+    stripPrefix?: boolean;
+}
+interface DropzoneManagerReturn {
+    /** All processed files with their status */
+    files: ProcessedFile[];
+    /** Current status text */
+    statusText: string;
+    /** Whether currently processing files (ZIP extraction, etc.) */
+    isProcessing: boolean;
+    /** Last validation error if any */
+    validationError: ClientError | null;
+    /** Whether all valid files have MD5 checksums calculated */
+    hasChecksums: boolean;
+    /** Process files from dropzone (resets and replaces existing files) */
+    processFiles: (files: File[]) => Promise<void>;
+    /** Remove a specific file */
+    removeFile: (fileId: string) => void;
+    /** Clear all files and reset state */
+    clearAll: () => void;
+    /** Get only valid files ready for upload */
+    getValidFiles: () => ProcessedFile[];
+    /** Update upload state for a specific file (status, progress, message) */
+    updateFileStatus: (fileId: string, state: {
+        status: FileStatus;
+        statusMessage?: string;
+        progress?: number;
+    }) => void;
+}
+/**
+ * Headless dropzone manager hook
+ * Handles file processing, ZIP extraction, and validation
+ * Does NOT handle uploading - that's the consumer's responsibility
+ */
+declare function useDropzoneManager(options?: DropzoneManagerOptions): DropzoneManagerReturn;
+
+/**
+ * Calculate MD5 hash from ArrayBuffer
+ */
+declare function calculateMD5(buffer: ArrayBuffer): Promise<string>;
+/**
+ * Format file size to human-readable string
+ */
+declare function formatFileSize(bytes: number, decimals?: number): string;
+/**
+ * Create a ProcessedFile from a File object
+ * This is the single conversion point from File to ProcessedFile
+ *
+ * Path resolution priority:
+ * 1. options.path (if provided)
+ * 2. file.webkitRelativePath (if non-empty, preserves folder structure)
+ * 3. file.name (fallback)
+ */
+declare function createProcessedFile(file: File, options?: {
+    /** Custom path (defaults to webkitRelativePath or file.name) */
+    path?: string;
+    /** Whether to calculate MD5 hash (defaults to true) */
+    calculateMD5?: boolean;
+}): Promise<ProcessedFile>;
+/**
+ * Validate and update status of ProcessedFiles
+ * Returns files with updated status and validation error if any
+ */
+interface ValidationResult {
+    /** All files with updated status */
+    files: ProcessedFile[];
+    /** Files that passed validation (status: READY) */
+    validFiles: ProcessedFile[];
+    /** Validation error if any files failed */
+    error: ClientError | null;
+}
+declare function validateFiles(files: ProcessedFile[], config: ValidationConfig): ValidationResult;
+/**
+ * Get only the valid files (status: READY) from a list
+ */
+declare function getValidFiles(files: ProcessedFile[]): ProcessedFile[];
+/**
+ * Check if all valid files have MD5 checksums calculated
+ */
+declare function allValidFilesHaveChecksums(files: ProcessedFile[]): boolean;
+/**
+ * Strip common directory prefix from file paths
+ * Only strips if ALL files share the same prefix
+ */
+declare function stripCommonPrefix(files: ProcessedFile[]): ProcessedFile[];
+
+interface ZipExtractionResult {
+    /** Extracted files as regular File objects */
+    files: File[];
+    /** Any errors encountered during extraction */
+    errors: string[];
+}
+/**
+ * Extracts all files from a ZIP archive
+ * Returns regular File objects that can be processed like any other file
+ */
+declare function extractZipToFiles(zipFile: File): Promise<ZipExtractionResult>;
+/**
+ * Sanitize and normalize a file path to prevent directory traversal attacks
+ * Removes: .., ., leading/trailing slashes, absolute paths, and empty segments
+ *
+ * @example
+ * normalizePath('../../etc/passwd') → 'etc/passwd'
+ * normalizePath('foo/./bar/../baz.txt') → 'foo/baz.txt'
+ * normalizePath('/absolute/path.txt') → 'absolute/path.txt'
+ */
+declare function normalizePath(path: string): string;
+/**
+ * Check if a file path is a junk file that should be filtered out
+ * Filters common system files like .DS_Store, Thumbs.db, desktop.ini,
+ * and macOS resource fork metadata in __MACOSX directories
+ *
+ * Case-insensitive matching to handle files from different operating systems
+ * (Windows file systems are case-insensitive, so Thumbs.db === THUMBS.DB)
+ *
+ * @example
+ * isJunkFile('.DS_Store') → true
+ * isJunkFile('.ds_store') → true (case-insensitive)
+ * isJunkFile('THUMBS.DB') → true (case-insensitive)
+ * isJunkFile('folder/.DS_Store') → true
+ * isJunkFile('__MACOSX/file.txt') → true
+ * isJunkFile('mydsstore.txt') → false
+ */
+declare function isJunkFile(path: string): boolean;
+/**
+ * Check if a file is a ZIP file based on MIME type or extension
+ */
+declare function isZipFile(file: File): boolean;
+
+export { type ClientError, DEFAULT_VALIDATION, type DropzoneManagerOptions, type DropzoneManagerReturn, FILE_STATUSES, type FileStatus, type ProcessedFile, type ValidationConfig, type ValidationResult, type ZipExtractionResult, allValidFilesHaveChecksums, calculateMD5, createProcessedFile, extractZipToFiles, formatFileSize, getValidFiles, isJunkFile, isZipFile, normalizePath, stripCommonPrefix, useDropzoneManager, validateFiles };