@bloomneo/appkit 1.2.9

package/dist/storage/storage.js

@@ -0,0 +1,439 @@
+/**
+ * Core storage class with automatic strategy selection and ultra-simple API
+ * @module @bloomneo/appkit/storage
+ * @file src/storage/storage.ts
+ *
+ * @llm-rule WHEN: Building apps that need file storage with automatic Local/S3/R2 selection
+ * @llm-rule AVOID: Using directly - always get instance via storageClass.get()
+ * @llm-rule NOTE: Auto-detects Local vs S3 vs R2 based on environment variables
+ */
+import { LocalStrategy } from './strategies/local.js';
+import { S3Strategy } from './strategies/s3.js';
+import { R2Strategy } from './strategies/r2.js';
+/**
+ * Storage class with automatic strategy selection and ultra-simple API
+ */
+export class StorageClass {
+    config;
+    strategy;
+    connected = false;
+    constructor(config) {
+        this.config = config;
+        this.strategy = this.createStrategy();
+    }
+    /**
+     * Creates appropriate strategy based on configuration
+     * @llm-rule WHEN: Storage initialization - selects Local, S3, or R2 based on environment
+     * @llm-rule AVOID: Manual strategy creation - configuration handles strategy selection
+     */
+    createStrategy() {
+        switch (this.config.strategy) {
+            case 'local':
+                return new LocalStrategy(this.config);
+            case 's3':
+                return new S3Strategy(this.config);
+            case 'r2':
+                return new R2Strategy(this.config);
+            default:
+                throw new Error(`Unknown storage strategy: ${this.config.strategy}`);
+        }
+    }
+    /**
+     * Connects to storage backend with automatic setup
+     * @llm-rule WHEN: Storage initialization or reconnection after failure
+     * @llm-rule AVOID: Manual connection management - this handles connection state
+     */
+    async connect() {
+        if (this.connected)
+            return;
+        try {
+            // Strategy-specific connection (S3/R2 connect, Local creates dirs)
+            if ('connect' in this.strategy) {
+                await this.strategy.connect();
+            }
+            this.connected = true;
+            if (this.config.environment.isDevelopment) {
+                console.log(`✅ [AppKit] Storage system connected using ${this.config.strategy} strategy`);
+            }
+        }
+        catch (error) {
+            console.error(`❌ [AppKit] Storage connection failed:`, error.message);
+            throw error;
+        }
+    }
+    /**
+     * Disconnects from storage backend gracefully
+     * @llm-rule WHEN: App shutdown or storage cleanup
+     * @llm-rule AVOID: Abrupt disconnection - graceful shutdown prevents data loss
+     */
+    async disconnect() {
+        if (!this.connected)
+            return;
+        try {
+            await this.strategy.disconnect();
+            this.connected = false;
+            if (this.config.environment.isDevelopment) {
+                console.log(`👋 [AppKit] Storage system disconnected`);
+            }
+        }
+        catch (error) {
+            console.error(`⚠️ [AppKit] Storage disconnect error:`, error.message);
+        }
+    }
+    /**
+     * Stores file with automatic validation and type detection
+     * @llm-rule WHEN: Uploading files to storage backend
+     * @llm-rule AVOID: Manual file validation - this handles size, type, and path validation
+     * @llm-rule NOTE: Returns the key/path where file was stored
+     */
+    async put(key, data, options) {
+        this.validateKey(key);
+        await this.ensureConnected();
+        try {
+            // Convert data to Buffer for consistency
+            const buffer = this.normalizeData(data);
+            // Validate file size
+            this.validateFileSize(buffer);
+            // Auto-detect content type if not provided
+            const contentType = options?.contentType || this.detectContentType(key, buffer);
+            // Validate file type
+            this.validateFileType(contentType);
+            // Store via strategy with enhanced options
+            const enhancedOptions = {
+                ...options,
+                contentType,
+            };
+            const result = await this.strategy.put(key, buffer, enhancedOptions);
+            // Log in development
+            if (this.config.environment.isDevelopment) {
+                console.log(`📤 [AppKit] File stored: ${key} (${buffer.length} bytes, ${contentType})`);
+            }
+            return result;
+        }
+        catch (error) {
+            console.error(`[AppKit] Storage put error for "${key}":`, error.message);
+            throw error;
+        }
+    }
+    /**
+     * Retrieves file with automatic error handling
+     * @llm-rule WHEN: Downloading files from storage backend
+     * @llm-rule AVOID: Manual error handling - this provides consistent error messages
+     */
+    async get(key) {
+        this.validateKey(key);
+        await this.ensureConnected();
+        try {
+            const result = await this.strategy.get(key);
+            // Log in development
+            if (this.config.environment.isDevelopment) {
+                console.log(`📥 [AppKit] File retrieved: ${key} (${result.length} bytes)`);
+            }
+            return result;
+        }
+        catch (error) {
+            console.error(`[AppKit] Storage get error for "${key}":`, error.message);
+            throw new Error(`File not found: ${key}`);
+        }
+    }
+    /**
+     * Deletes file with confirmation
+     * @llm-rule WHEN: Removing files from storage backend
+     * @llm-rule AVOID: Silent failures - this confirms deletion success
+     */
+    async delete(key) {
+        this.validateKey(key);
+        await this.ensureConnected();
+        try {
+            const result = await this.strategy.delete(key);
+            // Log in development
+            if (this.config.environment.isDevelopment) {
+                console.log(`🗑️ [AppKit] File deleted: ${key} (success: ${result})`);
+            }
+            return result;
+        }
+        catch (error) {
+            console.error(`[AppKit] Storage delete error for "${key}":`, error.message);
+            return false;
+        }
+    }
+    /**
+     * Lists files with prefix filtering and metadata
+     * @llm-rule WHEN: Browsing files or implementing file managers
+     * @llm-rule AVOID: Loading all files - use prefix filtering for performance
+     */
+    async list(prefix = '', limit) {
+        await this.ensureConnected();
+        try {
+            const files = await this.strategy.list(prefix);
+            // Apply limit if specified
+            const result = limit ? files.slice(0, limit) : files;
+            // Log in development
+            if (this.config.environment.isDevelopment) {
+                console.log(`📋 [AppKit] Files listed: ${prefix}* (${result.length} files)`);
+            }
+            return result;
+        }
+        catch (error) {
+            console.error(`[AppKit] Storage list error for prefix "${prefix}":`, error.message);
+            return [];
+        }
+    }
+    /**
+     * Gets public URL for file access
+     * @llm-rule WHEN: Generating URLs for file access in web applications
+     * @llm-rule AVOID: Hardcoding URLs - this handles CDN and strategy-specific URLs
+     */
+    url(key) {
+        this.validateKey(key);
+        try {
+            const url = this.strategy.url(key);
+            // Log in development
+            if (this.config.environment.isDevelopment) {
+                console.log(`🔗 [AppKit] URL generated: ${key} → ${url}`);
+            }
+            return url;
+        }
+        catch (error) {
+            console.error(`[AppKit] URL generation error for "${key}":`, error.message);
+            throw error;
+        }
+    }
+    /**
+     * Generates signed URL for temporary access
+     * @llm-rule WHEN: Creating temporary download links or private file access
+     * @llm-rule AVOID: Permanent URLs for private files - use signed URLs with expiration
+     */
+    async signedUrl(key, expiresIn = 3600) {
+        this.validateKey(key);
+        await this.ensureConnected();
+        try {
+            if (!this.strategy.signedUrl) {
+                throw new Error(`Signed URLs not supported with ${this.config.strategy} strategy`);
+            }
+            const url = await this.strategy.signedUrl(key, expiresIn);
+            // Log in development
+            if (this.config.environment.isDevelopment) {
+                console.log(`🔐 [AppKit] Signed URL generated: ${key} (expires in ${expiresIn}s)`);
+            }
+            return url;
+        }
+        catch (error) {
+            console.error(`[AppKit] Signed URL error for "${key}":`, error.message);
+            throw error;
+        }
+    }
+    /**
+     * Checks if file exists without downloading
+     * @llm-rule WHEN: Validating file existence before operations
+     * @llm-rule AVOID: Downloading files just to check existence - this is more efficient
+     */
+    async exists(key) {
+        this.validateKey(key);
+        await this.ensureConnected();
+        try {
+            const result = await this.strategy.exists(key);
+            // Log in development
+            if (this.config.environment.isDevelopment) {
+                console.log(`🔍 [AppKit] File exists check: ${key} → ${result}`);
+            }
+            return result;
+        }
+        catch (error) {
+            console.error(`[AppKit] Exists check error for "${key}":`, error.message);
+            return false;
+        }
+    }
+    /**
+     * Copies file from one location to another
+     * @llm-rule WHEN: Duplicating files or moving between folders
+     * @llm-rule AVOID: Download and upload - this uses efficient copy operations when possible
+     */
+    async copy(sourceKey, destKey) {
+        this.validateKey(sourceKey);
+        this.validateKey(destKey);
+        await this.ensureConnected();
+        try {
+            // Strategy-specific copy if available, otherwise download/upload
+            if ('copy' in this.strategy) {
+                return await this.strategy.copy(sourceKey, destKey);
+            }
+            // Fallback: download and upload
+            const data = await this.get(sourceKey);
+            return await this.put(destKey, data);
+        }
+        catch (error) {
+            console.error(`[AppKit] Copy error "${sourceKey}" → "${destKey}":`, error.message);
+            throw error;
+        }
+    }
+    /**
+     * Gets current storage strategy name for debugging
+     * @llm-rule WHEN: Debugging or health checks to see which strategy is active
+     * @llm-rule AVOID: Using for application logic - storage should be transparent
+     */
+    getStrategy() {
+        return this.config.strategy;
+    }
+    /**
+     * Gets storage configuration summary for debugging
+     * @llm-rule WHEN: Health checks or debugging storage configuration
+     * @llm-rule AVOID: Exposing sensitive details - this only shows safe info
+     */
+    getConfig() {
+        // Get config values based on strategy
+        let maxFileSize = 52428800; // 50MB default
+        let allowedTypes = [];
+        if (this.config.strategy === 'local' && this.config.local) {
+            maxFileSize = this.config.local.maxFileSize;
+            allowedTypes = this.config.local.allowedTypes;
+        }
+        else {
+            // S3 and R2 use global config or defaults
+            maxFileSize = 52428800; // 50MB default for cloud
+            allowedTypes = ['*']; // Allow all for cloud storage
+        }
+        return {
+            strategy: this.config.strategy,
+            connected: this.connected,
+            maxFileSize,
+            allowedTypes,
+        };
+    }
+    // Private helper methods
+    /**
+     * Ensures storage system is connected before operations
+     */
+    async ensureConnected() {
+        if (!this.connected) {
+            await this.connect();
+        }
+    }
+    /**
+     * Validates storage key format and security
+     */
+    validateKey(key) {
+        if (!key || typeof key !== 'string') {
+            throw new Error('Storage key must be a non-empty string');
+        }
+        if (key.length > 1024) {
+            throw new Error('Storage key too long (max 1024 characters)');
+        }
+        // Security: prevent path traversal
+        if (key.includes('..') || key.includes('//')) {
+            throw new Error('Storage key contains invalid path components');
+        }
+        // Normalize separators
+        if (key.includes('\\')) {
+            throw new Error('Storage key must use forward slashes (/) as separators');
+        }
+        // Remove leading slash for consistency
+        if (key.startsWith('/')) {
+            throw new Error('Storage key should not start with forward slash');
+        }
+    }
+    /**
+     * Normalizes input data to Buffer
+     */
+    normalizeData(data) {
+        if (Buffer.isBuffer(data)) {
+            return data;
+        }
+        if (data instanceof Uint8Array) {
+            return Buffer.from(data);
+        }
+        if (typeof data === 'string') {
+            return Buffer.from(data, 'utf8');
+        }
+        throw new Error('Data must be Buffer, Uint8Array, or string');
+    }
+    /**
+     * Validates file size against configured limits
+     */
+    validateFileSize(buffer) {
+        let maxSize = 52428800; // 50MB default
+        if (this.config.strategy === 'local' && this.config.local) {
+            maxSize = this.config.local.maxFileSize;
+        }
+        // S3 and R2 use default limit for now
+        if (buffer.length > maxSize) {
+            const maxMB = Math.round(maxSize / 1048576);
+            const fileMB = Math.round(buffer.length / 1048576);
+            throw new Error(`File too large: ${fileMB}MB (max: ${maxMB}MB)`);
+        }
+    }
+    /**
+     * Detects content type from file extension and buffer
+     */
+    detectContentType(key, buffer) {
+        // Get extension from key
+        const ext = key.split('.').pop()?.toLowerCase();
+        // Common MIME types
+        const mimeTypes = {
+            'jpg': 'image/jpeg',
+            'jpeg': 'image/jpeg',
+            'png': 'image/png',
+            'gif': 'image/gif',
+            'webp': 'image/webp',
+            'svg': 'image/svg+xml',
+            'pdf': 'application/pdf',
+            'txt': 'text/plain',
+            'json': 'application/json',
+            'csv': 'text/csv',
+            'zip': 'application/zip',
+            'mp4': 'video/mp4',
+            'webm': 'video/webm',
+            'mp3': 'audio/mpeg',
+            'wav': 'audio/wav',
+        };
+        if (ext && mimeTypes[ext]) {
+            return mimeTypes[ext];
+        }
+        // Simple buffer-based detection
+        const magic = buffer.subarray(0, 4);
+        if (magic[0] === 0xFF && magic[1] === 0xD8 && magic[2] === 0xFF) {
+            return 'image/jpeg';
+        }
+        if (magic[0] === 0x89 && magic[1] === 0x50 && magic[2] === 0x4E && magic[3] === 0x47) {
+            return 'image/png';
+        }
+        if (magic[0] === 0x47 && magic[1] === 0x49 && magic[2] === 0x46) {
+            return 'image/gif';
+        }
+        return 'application/octet-stream'; // Default binary
+    }
+    /**
+     * Validates file type against allowed types
+     */
+    validateFileType(contentType) {
+        let allowedTypes = [];
+        if (this.config.strategy === 'local' && this.config.local) {
+            allowedTypes = this.config.local.allowedTypes;
+        }
+        else {
+            // S3 and R2 allow all types by default (filtering done at app level)
+            allowedTypes = ['*'];
+        }
+        // Allow all types if wildcard is present
+        if (allowedTypes.includes('*')) {
+            return;
+        }
+        // Check exact match or wildcard patterns
+        const isAllowed = allowedTypes.some(allowedType => {
+            if (allowedType === contentType) {
+                return true;
+            }
+            // Support wildcard patterns like "image/*"
+            if (allowedType.endsWith('/*')) {
+                const prefix = allowedType.slice(0, -2);
+                return contentType.startsWith(prefix + '/');
+            }
+            return false;
+        });
+        if (!isAllowed) {
+            throw new Error(`File type not allowed: ${contentType}. ` +
+                `Allowed types: ${allowedTypes.join(', ')}`);
+        }
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/storage/storage.ts"],"names":[],"mappings":"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"}

package/dist/storage/strategies/local.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Local filesystem storage strategy with automatic directory management
+ * @module @bloomneo/appkit/storage
+ * @file src/storage/strategies/local.ts
+ *
+ * @llm-rule WHEN: No cloud storage env vars - perfect for development and single-server apps
+ * @llm-rule AVOID: Production use across multiple servers - files don't sync across instances
+ * @llm-rule NOTE: Fast local storage, automatic directory creation, file serving support
+ */
+import type { StorageStrategy, StorageFile, PutOptions } from '../storage.js';
+import type { StorageConfig } from '../defaults.js';
+/**
+ * Local filesystem storage strategy with intelligent file management
+ */
+export declare class LocalStrategy implements StorageStrategy {
+    private config;
+    private baseDir;
+    private baseUrl;
+    private maxFileSize;
+    private allowedTypes;
+    /**
+     * Creates local strategy with direct environment access (like auth pattern)
+     * @llm-rule WHEN: Storage initialization without cloud env vars - automatic fallback
+     * @llm-rule AVOID: Manual local configuration - environment detection handles this
+     */
+    constructor(config: StorageConfig);
+    /**
+     * Stores file to local filesystem with automatic directory creation
+     * @llm-rule WHEN: Saving files to local storage for development or single-server apps
+     * @llm-rule AVOID: Manual directory management - this handles nested paths automatically
+     */
+    put(key: string, data: Buffer, options?: PutOptions): Promise<string>;
+    /**
+     * Retrieves file from local filesystem with error handling
+     * @llm-rule WHEN: Loading files from local storage
+     * @llm-rule AVOID: Direct fs operations - this handles errors and validation
+     */
+    get(key: string): Promise<Buffer>;
+    /**
+     * Deletes file from local filesystem with confirmation
+     * @llm-rule WHEN: Removing files from local storage
+     * @llm-rule AVOID: Silent failures - this confirms deletion or reports issues
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Lists files with prefix filtering and metadata
+     * @llm-rule WHEN: Browsing local files or implementing file managers
+     * @llm-rule AVOID: Loading all files - this efficiently scans directories
+     */
+    list(prefix?: string): Promise<StorageFile[]>;
+    /**
+     * Gets public URL for local file access
+     * @llm-rule WHEN: Generating URLs for local file serving
+     * @llm-rule AVOID: Hardcoded paths - this handles base URL configuration
+     */
+    url(key: string): string;
+    /**
+     * Checks if file exists without reading content
+     * @llm-rule WHEN: Validating file existence efficiently
+     * @llm-rule AVOID: Reading entire file just to check existence
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Generates signed URL for temporary local file access (not applicable for local storage)
+     * @llm-rule WHEN: API compatibility - local storage doesn't support signed URLs
+     * @llm-rule AVOID: Using signed URLs with local storage - use regular URLs instead
+     */
+    signedUrl(key: string, expiresIn?: number): Promise<string>;
+    /**
+     * Copies file within local filesystem efficiently
+     * @llm-rule WHEN: Duplicating files within local storage
+     * @llm-rule AVOID: Read/write operations - this uses efficient copy operations
+     */
+    copy(sourceKey: string, destKey: string): Promise<string>;
+    /**
+     * Disconnects local strategy gracefully
+     * @llm-rule WHEN: App shutdown or storage cleanup
+     * @llm-rule AVOID: Leaving temp files - this cleans up if configured
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Gets absolute file path from storage key
+     */
+    private getFilePath;
+    /**
+     * Ensures directory exists, creating it if necessary
+     */
+    private ensureDirectoryExists;
+    /**
+     * Recursively scans directory for files matching pattern
+     */
+    private scanDirectory;
+    /**
+     * Cleans up empty directories after file deletion
+     */
+    private cleanupEmptyDirectories;
+    /**
+     * Sets file metadata using extended attributes (where supported)
+     */
+    private setFileMetadata;
+    /**
+     * Gets content type from file extension
+     */
+    private getContentTypeFromExtension;
+    /**
+     * Gets detailed local storage statistics
+     */
+    getDetailedStats(): {
+        strategy: string;
+        baseDir: string;
+        totalFiles: number;
+        totalSize: number;
+        maxFileSize: number;
+        allowedTypes: string[];
+    };
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/storage/strategies/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/storage/strategies/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD;;GAEG;AACH,qBAAa,aAAc,YAAW,eAAe;IACnD,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,YAAY,CAAW;IAE/B;;;;OAIG;gBACS,MAAM,EAAE,aAAa;IAoBjC;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAiC3E;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAsBvC;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA0B3C;;;;OAIG;IACG,IAAI,CAAC,MAAM,GAAE,MAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA0BvD;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAWxB;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS3C;;;;OAIG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAMvE;;;;OAIG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA2B/D;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAWjC;;OAEG;IACH,OAAO,CAAC,WAAW;IAMnB;;OAEG;YACW,qBAAqB;IAUnC;;OAEG;YACW,aAAa;IAyC3B;;OAEG;YACW,uBAAuB;IA2BrC;;OAEG;YACW,eAAe;IAiB7B;;OAEG;IACH,OAAO,CAAC,2BAA2B;IAwBnC;;OAEG;IACH,gBAAgB,IAAI;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,EAAE,CAAC;KACxB;CAUF"}