@bloomneo/appkit 1.2.9

package/dist/storage/strategies/local.js

@@ -0,0 +1,368 @@
+/**
+ * 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 fs from 'fs/promises';
+import path from 'path';
+import { existsSync } from 'fs';
+/**
+ * Local filesystem storage strategy with intelligent file management
+ */
+export class LocalStrategy {
+    config;
+    baseDir;
+    baseUrl;
+    maxFileSize;
+    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) {
+        this.config = config;
+        if (!config.local) {
+            throw new Error('Local storage configuration missing');
+        }
+        this.baseDir = path.resolve(config.local.dir);
+        this.baseUrl = config.local.baseUrl;
+        this.maxFileSize = config.local.maxFileSize;
+        this.allowedTypes = config.local.allowedTypes;
+        // Ensure base directory exists on initialization
+        this.ensureDirectoryExists(this.baseDir);
+        if (this.config.environment.isDevelopment) {
+            console.log(`✅ [AppKit] Local storage initialized (dir: ${this.baseDir}, maxSize: ${Math.round(this.maxFileSize / 1048576)}MB)`);
+        }
+    }
+    /**
+     * 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
+     */
+    async put(key, data, options) {
+        try {
+            const filePath = this.getFilePath(key);
+            // Ensure parent directory exists
+            const parentDir = path.dirname(filePath);
+            await this.ensureDirectoryExists(parentDir);
+            // Write file to disk
+            await fs.writeFile(filePath, data);
+            // Set file metadata if supported (extended attributes not available on all systems)
+            if (options?.metadata) {
+                try {
+                    await this.setFileMetadata(filePath, options.metadata);
+                }
+                catch (error) {
+                    // Metadata setting is optional, don't fail the operation
+                    if (this.config.environment.isDevelopment) {
+                        console.warn(`[AppKit] Could not set metadata for ${key}:`, error.message);
+                    }
+                }
+            }
+            if (this.config.environment.isDevelopment) {
+                console.log(`📁 [AppKit] Local file stored: ${key} (${data.length} bytes)`);
+            }
+            return key;
+        }
+        catch (error) {
+            throw new Error(`Failed to store file locally: ${error.message}`);
+        }
+    }
+    /**
+     * 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
+     */
+    async get(key) {
+        try {
+            const filePath = this.getFilePath(key);
+            // Check if file exists before reading
+            if (!existsSync(filePath)) {
+                throw new Error(`File not found: ${key}`);
+            }
+            // Read file from disk
+            const data = await fs.readFile(filePath);
+            if (this.config.environment.isDevelopment) {
+                console.log(`📁 [AppKit] Local file retrieved: ${key} (${data.length} bytes)`);
+            }
+            return data;
+        }
+        catch (error) {
+            throw new Error(`Failed to retrieve file locally: ${error.message}`);
+        }
+    }
+    /**
+     * 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
+     */
+    async delete(key) {
+        try {
+            const filePath = this.getFilePath(key);
+            // Check if file exists
+            if (!existsSync(filePath)) {
+                return false; // File doesn't exist, consider it "deleted"
+            }
+            // Delete file
+            await fs.unlink(filePath);
+            // Clean up empty directories
+            await this.cleanupEmptyDirectories(path.dirname(filePath));
+            if (this.config.environment.isDevelopment) {
+                console.log(`🗑️ [AppKit] Local file deleted: ${key}`);
+            }
+            return true;
+        }
+        catch (error) {
+            console.error(`[AppKit] Local delete error for "${key}":`, error.message);
+            return false;
+        }
+    }
+    /**
+     * 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
+     */
+    async list(prefix = '') {
+        try {
+            const searchDir = prefix ? path.join(this.baseDir, path.dirname(prefix)) : this.baseDir;
+            const searchPattern = prefix ? path.basename(prefix) : '';
+            if (!existsSync(searchDir)) {
+                return []; // Directory doesn't exist, return empty list
+            }
+            const files = [];
+            await this.scanDirectory(searchDir, files, searchPattern, prefix);
+            // Sort by key for consistent ordering
+            files.sort((a, b) => a.key.localeCompare(b.key));
+            if (this.config.environment.isDevelopment) {
+                console.log(`📋 [AppKit] Local files listed: ${prefix}* (${files.length} files)`);
+            }
+            return files;
+        }
+        catch (error) {
+            console.error(`[AppKit] Local list error for prefix "${prefix}":`, error.message);
+            return [];
+        }
+    }
+    /**
+     * 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) {
+        // Normalize key to use forward slashes for URLs
+        const normalizedKey = key.replace(/\\/g, '/');
+        // Ensure base URL ends with / and key doesn't start with /
+        const baseUrl = this.baseUrl.endsWith('/') ? this.baseUrl : this.baseUrl + '/';
+        const cleanKey = normalizedKey.startsWith('/') ? normalizedKey.slice(1) : normalizedKey;
+        return baseUrl + cleanKey;
+    }
+    /**
+     * Checks if file exists without reading content
+     * @llm-rule WHEN: Validating file existence efficiently
+     * @llm-rule AVOID: Reading entire file just to check existence
+     */
+    async exists(key) {
+        try {
+            const filePath = this.getFilePath(key);
+            return existsSync(filePath);
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * 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
+     */
+    async signedUrl(key, expiresIn = 3600) {
+        // Local storage doesn't support signed URLs, return regular URL
+        console.warn('[AppKit] Signed URLs not supported with local storage, returning public URL');
+        return this.url(key);
+    }
+    /**
+     * 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
+     */
+    async copy(sourceKey, destKey) {
+        try {
+            const sourcePath = this.getFilePath(sourceKey);
+            const destPath = this.getFilePath(destKey);
+            // Check source exists
+            if (!existsSync(sourcePath)) {
+                throw new Error(`Source file not found: ${sourceKey}`);
+            }
+            // Ensure destination directory exists
+            const destDir = path.dirname(destPath);
+            await this.ensureDirectoryExists(destDir);
+            // Copy file
+            await fs.copyFile(sourcePath, destPath);
+            if (this.config.environment.isDevelopment) {
+                console.log(`📁 [AppKit] Local file copied: ${sourceKey} → ${destKey}`);
+            }
+            return destKey;
+        }
+        catch (error) {
+            throw new Error(`Failed to copy file locally: ${error.message}`);
+        }
+    }
+    /**
+     * Disconnects local strategy gracefully
+     * @llm-rule WHEN: App shutdown or storage cleanup
+     * @llm-rule AVOID: Leaving temp files - this cleans up if configured
+     */
+    async disconnect() {
+        // Local storage doesn't need explicit disconnection
+        // Could implement cleanup of temp files here if needed
+        if (this.config.environment.isDevelopment) {
+            console.log(`👋 [AppKit] Local storage strategy disconnected`);
+        }
+    }
+    // Private helper methods
+    /**
+     * Gets absolute file path from storage key
+     */
+    getFilePath(key) {
+        // Normalize path separators and prevent directory traversal
+        const normalizedKey = key.replace(/\\/g, '/').replace(/\.\.+/g, '');
+        return path.join(this.baseDir, normalizedKey);
+    }
+    /**
+     * Ensures directory exists, creating it if necessary
+     */
+    async ensureDirectoryExists(dirPath) {
+        try {
+            if (!existsSync(dirPath)) {
+                await fs.mkdir(dirPath, { recursive: true });
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to create directory: ${error.message}`);
+        }
+    }
+    /**
+     * Recursively scans directory for files matching pattern
+     */
+    async scanDirectory(dirPath, files, pattern = '', prefix = '') {
+        try {
+            const entries = await fs.readdir(dirPath, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dirPath, entry.name);
+                if (entry.isDirectory()) {
+                    // Recursively scan subdirectories
+                    await this.scanDirectory(fullPath, files, pattern, prefix);
+                }
+                else if (entry.isFile()) {
+                    // Check if file matches pattern
+                    if (!pattern || entry.name.startsWith(pattern)) {
+                        const relativePath = path.relative(this.baseDir, fullPath);
+                        const key = relativePath.replace(/\\/g, '/'); // Normalize to forward slashes
+                        // Get file stats
+                        const stats = await fs.stat(fullPath);
+                        files.push({
+                            key,
+                            size: stats.size,
+                            lastModified: stats.mtime,
+                            contentType: this.getContentTypeFromExtension(key),
+                        });
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // Directory access error, skip silently
+            if (this.config.environment.isDevelopment) {
+                console.warn(`[AppKit] Error scanning directory ${dirPath}:`, error.message);
+            }
+        }
+    }
+    /**
+     * Cleans up empty directories after file deletion
+     */
+    async cleanupEmptyDirectories(dirPath) {
+        try {
+            // Don't clean up the base directory
+            if (dirPath === this.baseDir) {
+                return;
+            }
+            const entries = await fs.readdir(dirPath);
+            // If directory is empty, remove it and check parent
+            if (entries.length === 0) {
+                await fs.rmdir(dirPath);
+                // Recursively check parent directory
+                const parentDir = path.dirname(dirPath);
+                if (parentDir !== dirPath && parentDir !== this.baseDir) {
+                    await this.cleanupEmptyDirectories(parentDir);
+                }
+            }
+        }
+        catch (error) {
+            // Cleanup is optional, don't fail if it doesn't work
+            if (this.config.environment.isDevelopment) {
+                console.warn(`[AppKit] Could not cleanup directory ${dirPath}:`, error.message);
+            }
+        }
+    }
+    /**
+     * Sets file metadata using extended attributes (where supported)
+     */
+    async setFileMetadata(filePath, metadata) {
+        // Extended attributes are not universally supported
+        // This is a placeholder for future metadata support
+        // Could implement using file naming conventions or sidecar files
+        // For now, we'll store metadata in a separate .meta file
+        const metaPath = filePath + '.meta';
+        const metaContent = JSON.stringify(metadata, null, 2);
+        try {
+            await fs.writeFile(metaPath, metaContent);
+        }
+        catch (error) {
+            // Metadata is optional
+            throw new Error(`Failed to write metadata: ${error.message}`);
+        }
+    }
+    /**
+     * Gets content type from file extension
+     */
+    getContentTypeFromExtension(key) {
+        const ext = path.extname(key).toLowerCase();
+        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',
+        };
+        return mimeTypes[ext] || 'application/octet-stream';
+    }
+    /**
+     * Gets detailed local storage statistics
+     */
+    getDetailedStats() {
+        return {
+            strategy: 'local',
+            baseDir: this.baseDir,
+            totalFiles: 0, // Would need to scan to get accurate count
+            totalSize: 0, // Would need to scan to get accurate size
+            maxFileSize: this.maxFileSize,
+            allowedTypes: this.allowedTypes,
+        };
+    }
+}
+//# sourceMappingURL=local.js.map

package/dist/storage/strategies/local.js.map

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

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

@@ -0,0 +1,130 @@
+/**
+ * Cloudflare R2 storage strategy with zero egress fees and automatic CDN integration
+ * @module @bloomneo/appkit/storage
+ * @file src/storage/strategies/r2.ts
+ *
+ * @llm-rule WHEN: App has CLOUDFLARE_R2_BUCKET env var for cost-effective distributed storage
+ * @llm-rule AVOID: Manual R2 setup - this handles connection, CDN integration, and S3-compatible API
+ * @llm-rule NOTE: Production-ready with zero egress fees, automatic CDN, S3-compatible operations
+ */
+import type { StorageStrategy, StorageFile, PutOptions } from '../storage.js';
+import type { StorageConfig } from '../defaults.js';
+/**
+ * Cloudflare R2 storage strategy with cost optimization and CDN integration
+ */
+export declare class R2Strategy implements StorageStrategy {
+    private config;
+    private r2Client;
+    private connected;
+    private bucket;
+    private accountId;
+    private cdnUrl?;
+    private endpoint;
+    /**
+     * Creates R2 strategy with direct environment access (like auth pattern)
+     * @llm-rule WHEN: Storage initialization with Cloudflare R2 environment variables detected
+     * @llm-rule AVOID: Manual R2 configuration - environment detection handles Cloudflare specifics
+     */
+    constructor(config: StorageConfig);
+    /**
+     * Connects to Cloudflare R2 with automatic account validation
+     * @llm-rule WHEN: Storage initialization or reconnection after failure
+     * @llm-rule AVOID: Manual R2 client setup - this handles Cloudflare-specific configuration
+     */
+    connect(): Promise<void>;
+    /**
+     * Tests R2 connection by checking bucket access
+     */
+    private testConnection;
+    /**
+     * Stores file to R2 with automatic content type detection and zero egress cost
+     * @llm-rule WHEN: Uploading files to Cloudflare R2 for cost-effective storage
+     * @llm-rule AVOID: Manual R2 operations - this handles R2-specific optimizations
+     */
+    put(key: string, data: Buffer, options?: PutOptions): Promise<string>;
+    /**
+     * Retrieves file from R2 with streaming support and zero egress cost
+     * @llm-rule WHEN: Downloading files from Cloudflare R2
+     * @llm-rule AVOID: Manual R2 operations - this handles streaming and cost optimization
+     */
+    get(key: string): Promise<Buffer>;
+    /**
+     * Deletes file from R2 with confirmation
+     * @llm-rule WHEN: Removing files from Cloudflare R2 storage
+     * @llm-rule AVOID: Silent failures - this confirms deletion success
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Lists files with prefix filtering and R2-optimized pagination
+     * @llm-rule WHEN: Browsing R2 files or implementing file managers
+     * @llm-rule AVOID: Loading all objects - R2 has same limits as S3
+     */
+    list(prefix?: string): Promise<StorageFile[]>;
+    /**
+     * Gets CDN or public URL for R2 object with automatic CDN detection
+     * @llm-rule WHEN: Generating URLs for R2 file access with CDN optimization
+     * @llm-rule AVOID: Hardcoded URLs - this handles CDN and R2-specific URLs
+     */
+    url(key: string): string;
+    /**
+     * Generates R2 public URL hash (simplified for demo)
+     */
+    private generatePublicHash;
+    /**
+     * Generates signed URL for temporary R2 object access
+     * @llm-rule WHEN: Creating temporary download/upload links for R2 objects
+     * @llm-rule AVOID: Public URLs for private files - use signed URLs with expiration
+     */
+    signedUrl(key: string, expiresIn?: number): Promise<string>;
+    /**
+     * Checks if R2 object exists without downloading
+     * @llm-rule WHEN: Validating R2 object existence efficiently
+     * @llm-rule AVOID: Downloading objects just to check existence
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Copies R2 object efficiently using server-side copy (zero egress cost)
+     * @llm-rule WHEN: Duplicating R2 objects without bandwidth costs
+     * @llm-rule AVOID: Download and upload - R2 server-side copy has zero egress fees
+     */
+    copy(sourceKey: string, destKey: string): Promise<string>;
+    /**
+     * Disconnects R2 strategy gracefully
+     * @llm-rule WHEN: App shutdown or storage cleanup
+     * @llm-rule AVOID: Abrupt disconnection - graceful shutdown prevents connection issues
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Converts readable stream to buffer
+     */
+    private streamToBuffer;
+    /**
+     * Detects content type from file extension and buffer
+     */
+    private detectContentType;
+    /**
+     * Gets content type for existing R2 object
+     */
+    private getObjectContentType;
+    /**
+     * Gets R2 connection info for debugging
+     */
+    getConnectionInfo(): {
+        connected: boolean;
+        bucket: string;
+        accountId: string;
+        endpoint: string;
+        cdnEnabled: boolean;
+        zeroEgressFees: boolean;
+    };
+    /**
+     * Gets R2-specific cost optimization info
+     */
+    getCostInfo(): {
+        egressFees: string;
+        storageClass: string;
+        cdnIntegration: boolean;
+        recommendedFor: string[];
+    };
+}
+//# sourceMappingURL=r2.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../../../src/storage/strategies/r2.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,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,UAAW,YAAW,eAAe;IAChD,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;OAIG;gBACS,MAAM,EAAE,aAAa;IAejC;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA0C9B;;OAEG;YACW,cAAc;IAgB5B;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IA6C3E;;;;OAIG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmCvC;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA2B3C;;;;OAIG;IACG,IAAI,CAAC,MAAM,GAAE,MAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA8CvD;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAYxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAM1B;;;;OAIG;IACG,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IA4BvE;;;;OAIG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAwB3C;;;;OAIG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0B/D;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAkBjC;;OAEG;YACW,cAAc;IAU5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkDzB;;OAEG;YACW,oBAAoB;IAiBlC;;OAEG;IACH,iBAAiB,IAAI;QACnB,SAAS,EAAE,OAAO,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,OAAO,CAAC;QACpB,cAAc,EAAE,OAAO,CAAC;KACzB;IAWD;;OAEG;IACH,WAAW,IAAI;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,cAAc,EAAE,OAAO,CAAC;QACxB,cAAc,EAAE,MAAM,EAAE,CAAC;KAC1B;CAaF"}