oblien 1.2.4 → 1.2.6

package/src/cdn/index.js

@@ -0,0 +1,744 @@
+/**
+ * Oblien CDN Module
+ * Upload and manage files on Oblien CDN with automatic token management
+ */
+
+export class OblienCDN {
+    constructor(client, config = {}) {
+        if (!client) throw new Error('Oblien client is required');
+        this.client = client;
+        this.cdnURL = config.cdnURL || 'https://cdn.oblien.com/api';
+        
+        // Token cache for reuse within expiration window
+        this._tokenCache = {
+            user: null,
+            admin: null
+        };
+    }
+
+    /**
+     * Generate a user CDN token (upload/process permissions)
+     * Tokens expire in 1 minute for security
+     * 
+     * @returns {Promise<Object>} Token response with token, scope, and permissions
+     * 
+     * @example
+     * const tokenData = await cdn.generateUserToken();
+     * // Returns:
+     * // {
+     * //   success: true,
+     * //   token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+     * //   scope: 'user',
+     * //   permissions: ['upload', 'process'],
+     * //   expiresIn: '1m'
+     * // }
+     */
+    async generateUserToken() {
+        const response = await this.client.post('cdn/token');
+        
+        // Cache token for reuse
+        if (response.success && response.token) {
+            this._tokenCache.user = {
+                token: response.token,
+                expiresAt: Date.now() + 50000 // 50 seconds (buffer before 1m expiry)
+            };
+        }
+        
+        return response;
+    }
+
+    /**
+     * Generate an admin CDN token (full access permissions)
+     * Requires admin privileges on the API account
+     * Tokens expire in 1 minute for security
+     * 
+     * @returns {Promise<Object>} Token response with token, scope, and permissions
+     * @throws {Error} If user doesn't have admin privileges
+     * 
+     * @example
+     * const tokenData = await cdn.generateAdminToken();
+     * // Returns:
+     * // {
+     * //   success: true,
+     * //   token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
+     * //   scope: 'admin',
+     * //   permissions: ['upload', 'process', 'read', 'list', 'info', 'delete'],
+     * //   expiresIn: '1m'
+     * // }
+     */
+    async generateAdminToken() {
+        const response = await this.client.post('cdn/token/admin');
+        
+        // Cache token for reuse
+        if (response.success && response.token) {
+            this._tokenCache.admin = {
+                token: response.token,
+                expiresAt: Date.now() + 50000 // 50 seconds (buffer before 1m expiry)
+            };
+        }
+        
+        return response;
+    }
+
+    /**
+     * Get a valid token (user or admin)
+     * Automatically generates new token if cache is empty or expired
+     * @private
+     */
+    async _getToken(scope = 'user') {
+        const cached = this._tokenCache[scope];
+        
+        // Use cached token if still valid
+        if (cached && cached.expiresAt > Date.now()) {
+            return cached.token;
+        }
+        
+        // Generate new token
+        const tokenData = scope === 'admin' 
+            ? await this.generateAdminToken() 
+            : await this.generateUserToken();
+        
+        return tokenData.token;
+    }
+
+    /**
+     * Normalize file input to buffer and filename
+     * Supports: Buffer, Base64, Multer files, Stream
+     * @private
+     */
+    _normalizeFile(file, providedFilename) {
+        let buffer;
+        let filename = providedFilename;
+        let mimetype;
+
+        // Handle Multer file object (from Express.js file uploads)
+        if (file && file.buffer && file.originalname) {
+            buffer = file.buffer;
+            filename = filename || file.originalname;
+            mimetype = file.mimetype;
+        }
+        // Handle Base64 string
+        else if (typeof file === 'string') {
+            // Check if it's a data URL (data:image/jpeg;base64,...)
+            const base64Match = file.match(/^data:([^;]+);base64,(.+)$/);
+            if (base64Match) {
+                mimetype = base64Match[1];
+                buffer = Buffer.from(base64Match[2], 'base64');
+                // Extract extension from mimetype if no filename
+                if (!filename) {
+                    const ext = mimetype.split('/')[1] || 'bin';
+                    filename = `file.${ext}`;
+                }
+            } else {
+                // Plain base64 string
+                buffer = Buffer.from(file, 'base64');
+                filename = filename || 'file.bin';
+            }
+        }
+        // Handle Buffer or Uint8Array
+        else if (file instanceof Buffer || file instanceof Uint8Array) {
+            buffer = file;
+            filename = filename || 'file.bin';
+        }
+        // Handle Node.js ReadableStream
+        else if (file && typeof file.pipe === 'function') {
+            throw new Error('Streams are not directly supported. Please convert to Buffer first using stream.toArray() or similar.');
+        }
+        // Handle other types (File, Blob, etc.) - pass through
+        else {
+            return { file, filename: filename || 'file' };
+        }
+
+        return { buffer, filename, mimetype };
+    }
+
+    /**
+     * Upload a single file to CDN
+     * Automatically handles token generation if not provided
+     * Supports: Buffer, Base64 strings, Multer file objects
+     * 
+     * @param {Buffer|string|Object} file - File to upload
+     *   - Buffer: Raw file buffer
+     *   - string: Base64 encoded file or data URL (data:image/jpeg;base64,...)
+     *   - Object: Multer file object ({ buffer, originalname, mimetype })
+     * @param {Object} options - Upload options
+     * @param {string} options.token - CDN token (optional, will auto-generate if not provided)
+     * @param {string} options.filename - Custom filename (optional)
+     * @param {string} options.mimetype - File mimetype (optional)
+     * @param {string} options.scope - Token scope to use: 'user' or 'admin' (default: 'user')
+     * @returns {Promise<Object>} Upload result with file URL and metadata
+     * 
+     * @example
+     * // Upload from Buffer
+     * const fs = require('fs');
+     * const fileBuffer = fs.readFileSync('image.jpg');
+     * const result = await cdn.upload(fileBuffer, { filename: 'image.jpg' });
+     * 
+     * @example
+     * // Upload from Base64
+     * const base64 = 'data:image/jpeg;base64,/9j/4AAQSkZJRg...';
+     * const result = await cdn.upload(base64, { filename: 'image.jpg' });
+     * 
+     * @example
+     * // Upload from Base64 (plain)
+     * const base64 = '/9j/4AAQSkZJRg...';
+     * const result = await cdn.upload(base64, { filename: 'image.jpg' });
+     * 
+     * @example
+     * // Upload from Multer (Express.js)
+     * app.post('/upload', upload.single('file'), async (req, res) => {
+     *   const result = await cdn.upload(req.file);
+     *   res.json(result);
+     * });
+     * 
+     * // Returns:
+     * // {
+     * //   success: true,
+     * //   file: {
+     * //     url: 'https://cdn.oblien.com/abc123/image.jpg',
+     * //     filename: 'image.jpg',
+     * //     size: 102400,
+     * //     mimetype: 'image/jpeg'
+     * //   }
+     * // }
+     */
+    async upload(file, options = {}) {
+        const { token, filename, mimetype, scope = 'user' } = options;
+        
+        // Get token (use provided or generate new one)
+        const cdnToken = token || await this._getToken(scope);
+        
+        // Normalize file input
+        const normalized = this._normalizeFile(file, filename);
+        
+        // Create FormData
+        const FormData = globalThis.FormData || (await import('form-data')).default;
+        const formData = new FormData();
+        
+        // Add file to form data
+        if (normalized.buffer) {
+            const Blob = globalThis.Blob || (await import('buffer')).Blob;
+            const fileBlob = new Blob([normalized.buffer], { 
+                type: mimetype || normalized.mimetype || 'application/octet-stream' 
+            });
+            formData.append('file', fileBlob, normalized.filename);
+        } else {
+            formData.append('file', normalized.file, normalized.filename);
+        }
+        
+        // Upload to CDN
+        const response = await fetch(`${this.cdnURL}/`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${cdnToken}`
+            },
+            body: formData
+        });
+        
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({}));
+            throw new Error(error.message || `Upload failed: ${response.status}`);
+        }
+        
+        return response.json();
+    }
+
+    /**
+     * Upload multiple files to CDN
+     * Automatically handles token generation if not provided
+     * Supports: Buffers, Base64 strings, Multer file objects
+     * 
+     * @param {Array<Buffer|string|Object>} files - Array of files to upload
+     *   - Buffer: Raw file buffers
+     *   - string: Base64 encoded files
+     *   - Object: Multer file objects
+     * @param {Object} options - Upload options
+     * @param {string} options.token - CDN token (optional, will auto-generate if not provided)
+     * @param {Array<string>} options.filenames - Array of custom filenames (optional)
+     * @param {string} options.scope - Token scope to use: 'user' or 'admin' (default: 'user')
+     * @returns {Promise<Object>} Upload result with array of file URLs and metadata
+     * 
+     * @example
+     * // Upload multiple buffers
+     * const files = [
+     *   fs.readFileSync('image1.jpg'),
+     *   fs.readFileSync('image2.jpg')
+     * ];
+     * const result = await cdn.uploadMultiple(files, {
+     *   filenames: ['image1.jpg', 'image2.jpg']
+     * });
+     * 
+     * @example
+     * // Upload multiple base64 strings
+     * const files = [
+     *   'data:image/jpeg;base64,/9j/4AAQ...',
+     *   'data:image/png;base64,iVBORw0KGgo...'
+     * ];
+     * const result = await cdn.uploadMultiple(files);
+     * 
+     * @example
+     * // Upload from Multer (Express.js)
+     * app.post('/upload', upload.array('files'), async (req, res) => {
+     *   const result = await cdn.uploadMultiple(req.files);
+     *   res.json(result);
+     * });
+     * 
+     * // Returns:
+     * // {
+     * //   success: true,
+     * //   files: [
+     * //     { url: 'https://cdn.oblien.com/abc123/image1.jpg', ... },
+     * //     { url: 'https://cdn.oblien.com/def456/image2.jpg', ... }
+     * //   ]
+     * // }
+     */
+    async uploadMultiple(files, options = {}) {
+        if (!Array.isArray(files) || files.length === 0) {
+            throw new Error('Files must be a non-empty array');
+        }
+        
+        const { token, filenames = [], scope = 'user' } = options;
+        
+        // Get token (use provided or generate new one)
+        const cdnToken = token || await this._getToken(scope);
+        
+        // Create FormData
+        const FormData = globalThis.FormData || (await import('form-data')).default;
+        const formData = new FormData();
+        
+        // Add all files
+        for (let i = 0; i < files.length; i++) {
+            const file = files[i];
+            const filename = filenames[i];
+            
+            // Normalize file input
+            const normalized = this._normalizeFile(file, filename);
+            
+            if (normalized.buffer) {
+                const Blob = globalThis.Blob || (await import('buffer')).Blob;
+                const fileBlob = new Blob([normalized.buffer], {
+                    type: normalized.mimetype || 'application/octet-stream'
+                });
+                formData.append('files', fileBlob, normalized.filename);
+            } else {
+                formData.append('files', normalized.file, normalized.filename);
+            }
+        }
+        
+        // Upload to CDN
+        const response = await fetch(`${this.cdnURL}/multiple`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${cdnToken}`
+            },
+            body: formData
+        });
+        
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({}));
+            throw new Error(error.message || `Upload failed: ${response.status}`);
+        }
+        
+        return response.json();
+    }
+
+    /**
+     * Upload files from URLs (download and upload to CDN)
+     * CDN will download the images from URLs and process them
+     * Automatically handles token generation if not provided
+     * 
+     * @param {Array<string>} urls - Array of image URLs to download and upload
+     * @param {Object} options - Upload options
+     * @param {string} options.token - CDN token (optional, will auto-generate if not provided)
+     * @param {string} options.scope - Token scope to use: 'user' or 'admin' (default: 'user')
+     * @returns {Promise<Object>} Upload result with processed file URLs
+     * 
+     * @example
+     * const result = await cdn.uploadFromUrls([
+     *   'https://example.com/image1.jpg',
+     *   'https://example.com/image2.png'
+     * ]);
+     * 
+     * // Returns:
+     * // {
+     * //   success: true,
+     * //   files: [
+     * //     { 
+     * //       url: 'https://cdn.oblien.com/abc123/image1.jpg',
+     * //       originalUrl: 'https://example.com/image1.jpg',
+     * //       filename: 'image1.jpg',
+     * //       size: 102400,
+     * //       mimetype: 'image/jpeg',
+     * //       variants: { ... }
+     * //     },
+     * //     { 
+     * //       url: 'https://cdn.oblien.com/def456/image2.png',
+     * //       originalUrl: 'https://example.com/image2.png',
+     * //       filename: 'image2.png',
+     * //       size: 204800,
+     * //       mimetype: 'image/png',
+     * //       variants: { ... }
+     * //     }
+     * //   ]
+     * // }
+     */
+    async uploadFromUrls(urls, options = {}) {
+        if (!Array.isArray(urls) || urls.length === 0) {
+            throw new Error('URLs must be a non-empty array');
+        }
+        
+        const { token, scope = 'user' } = options;
+        
+        // Get token (use provided or generate new one)
+        const cdnToken = token || await this._getToken(scope);
+        
+        // Upload from URLs
+        const response = await fetch(`${this.cdnURL}/process-urls`, {
+            method: 'POST',
+            headers: {
+                'Authorization': `Bearer ${cdnToken}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({ urls })
+        });
+        
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({}));
+            throw new Error(error.message || `Upload from URLs failed: ${response.status}`);
+        }
+        
+        return response.json();
+    }
+
+    /**
+     * @deprecated Use uploadFromUrls() instead
+     * Process URLs (download and process images from URLs)
+     */
+    async processUrls(urls, options = {}) {
+        console.warn('cdn.processUrls() is deprecated. Use cdn.uploadFromUrls() instead.');
+        return this.uploadFromUrls(urls, options);
+    }
+
+    /**
+     * Get file information (ADMIN ONLY)
+     * Requires admin token
+     * 
+     * @param {string} filePath - File path on CDN
+     * @param {Object} options - Options
+     * @param {string} options.token - Admin CDN token (optional, will auto-generate if not provided)
+     * @returns {Promise<Object>} File information
+     * 
+     * @example
+     * const info = await cdn.getFileInfo('abc123/image.jpg');
+     * 
+     * // Returns:
+     * // {
+     * //   success: true,
+     * //   file: {
+     * //     path: 'abc123/image.jpg',
+     * //     size: 102400,
+     * //     mimetype: 'image/jpeg',
+     * //     created: '2024-01-01T00:00:00.000Z'
+     * //   }
+     * // }
+     */
+    async getFileInfo(filePath, options = {}) {
+        if (!filePath) {
+            throw new Error('File path is required');
+        }
+        
+        const { token } = options;
+        
+        // Get admin token (use provided or generate new one)
+        const cdnToken = token || await this._getToken('admin');
+        
+        // Get file info
+        const response = await fetch(`${this.cdnURL}/info/${filePath}`, {
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${cdnToken}`
+            }
+        });
+        
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({}));
+            throw new Error(error.message || `Failed to get file info: ${response.status}`);
+        }
+        
+        return response.json();
+    }
+
+    /**
+     * Get available image variant options
+     * 
+     * @param {Object} options - Options
+     * @param {string} options.token - CDN token (optional, will auto-generate if not provided)
+     * @returns {Promise<Object>} Available variants
+     * 
+     * @example
+     * const variants = await cdn.getVariants();
+     * 
+     * // Returns:
+     * // {
+     * //   variants: {
+     * //     thumb: { width: 150, height: 150, fit: 'inside' },
+     * //     medium: { width: 800, height: 600, fit: 'inside' },
+     * //     blur: { width: 75, height: 75, fit: 'cover', blur: 5 }
+     * //   }
+     * // }
+     */
+    async getVariants(options = {}) {
+        const { token } = options;
+        
+        // Get token (use provided or generate new one)
+        const cdnToken = token || await this._getToken('user');
+        
+        const response = await fetch(`${this.cdnURL}/variants`, {
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${cdnToken}`
+            }
+        });
+        
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({}));
+            throw new Error(error.message || `Failed to get variants: ${response.status}`);
+        }
+        
+        return response.json();
+    }
+
+    /**
+     * Get file size limits
+     * 
+     * @param {Object} options - Options
+     * @param {string} options.token - CDN token (optional, will auto-generate if not provided)
+     * @returns {Promise<Object>} File size limits
+     * 
+     * @example
+     * const limits = await cdn.getLimits();
+     * 
+     * // Returns:
+     * // {
+     * //   limits: {
+     * //     'image/jpeg': 5242880,
+     * //     'image/png': 8388608,
+     * //     'default': 10485760
+     * //   }
+     * // }
+     */
+    async getLimits(options = {}) {
+        const { token } = options;
+        
+        // Get token (use provided or generate new one)
+        const cdnToken = token || await this._getToken('user');
+        
+        const response = await fetch(`${this.cdnURL}/limits`, {
+            method: 'GET',
+            headers: {
+                'Authorization': `Bearer ${cdnToken}`
+            }
+        });
+        
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({}));
+            throw new Error(error.message || `Failed to get limits: ${response.status}`);
+        }
+        
+        return response.json();
+    }
+
+    /**
+     * Clear token cache
+     * Useful when you want to force fresh token generation
+     * 
+     * @param {string} scope - Scope to clear: 'user', 'admin', or 'all' (default: 'all')
+     * 
+     * @example
+     * cdn.clearTokenCache(); // Clear all
+     * cdn.clearTokenCache('user'); // Clear user token only
+     */
+    clearTokenCache(scope = 'all') {
+        if (scope === 'all') {
+            this._tokenCache.user = null;
+            this._tokenCache.admin = null;
+        } else if (scope === 'user' || scope === 'admin') {
+            this._tokenCache[scope] = null;
+        }
+    }
+
+    // ===== FILE MANAGEMENT ENDPOINTS =====
+    // These endpoints use session authentication (not CDN tokens)
+
+    /**
+     * List user's uploaded files
+     * Uses session authentication (requires logged in user)
+     * 
+     * @param {Object} options - Query options
+     * @param {number} options.page - Page number (default: 1)
+     * @param {number} options.limit - Items per page (default: 50, max: 100)
+     * @param {boolean} options.includeDeleted - Include soft-deleted files (default: false)
+     * @param {string} options.uploadType - Filter by upload type: 'upload' or 'url'
+     * @param {string} options.sortBy - Sort column: 'created_at', 'size', 'filename' (default: 'created_at')
+     * @param {string} options.sortOrder - Sort order: 'ASC' or 'DESC' (default: 'DESC')
+     * @returns {Promise<Object>} Paginated list of files
+     * 
+     * @example
+     * const result = await cdn.listFiles({ page: 1, limit: 50 });
+     * 
+     * // Returns:
+     * // {
+     * //   success: true,
+     * //   data: {
+     * //     files: [
+     * //       {
+     * //         id: 123,
+     * //         filename: 'image.jpg',
+     * //         cdn_url: 'https://cdn.oblien.com/...',
+     * //         size: 102400,
+     * //         mime_type: 'image/jpeg',
+     * //         variants: [...],
+     * //         upload_type: 'upload',
+     * //         created_at: '2024-01-01T00:00:00.000Z'
+     * //       }
+     * //     ],
+     * //     pagination: {
+     * //       page: 1,
+     * //       limit: 50,
+     * //       total: 150,
+     * //       totalPages: 3,
+     * //       hasMore: true
+     * //     }
+     * //   }
+     * // }
+     */
+    async listFiles(options = {}) {
+        const {
+            page = 1,
+            limit = 50,
+            includeDeleted = false,
+            uploadType = null,
+            sortBy = 'created_at',
+            sortOrder = 'DESC'
+        } = options;
+
+        const queryParams = new URLSearchParams({
+            page: page.toString(),
+            limit: limit.toString(),
+            include_deleted: includeDeleted.toString(),
+            sort_by: sortBy,
+            sort_order: sortOrder
+        });
+
+        if (uploadType) {
+            queryParams.append('upload_type', uploadType);
+        }
+
+        return this.client.get(`cdn/files?${queryParams.toString()}`);
+    }
+
+    /**
+     * Get user storage statistics
+     * Uses session authentication (requires logged in user)
+     * 
+     * @returns {Promise<Object>} Storage statistics
+     * 
+     * @example
+     * const stats = await cdn.getStats();
+     * 
+     * // Returns:
+     * // {
+     * //   success: true,
+     * //   data: {
+     * //     totalFiles: 150,
+     * //     totalSize: 157286400,
+     * //     activeFiles: 145,
+     * //     activeSize: 152166400,
+     * //     uploadedFiles: 100,
+     * //     urlFiles: 50
+     * //   }
+     * // }
+     */
+    async getStats() {
+        return this.client.get('cdn/stats');
+    }
+
+    /**
+     * Get file by ID
+     * Uses session authentication (requires logged in user)
+     * 
+     * @param {number|string} fileId - File ID
+     * @returns {Promise<Object>} File details
+     * 
+     * @example
+     * const file = await cdn.getFile(123);
+     * 
+     * // Returns:
+     * // {
+     * //   success: true,
+     * //   data: {
+     * //     id: 123,
+     * //     filename: 'image.jpg',
+     * //     cdn_url: 'https://cdn.oblien.com/...',
+     * //     size: 102400,
+     * //     mime_type: 'image/jpeg',
+     * //     variants: [...],
+     * //     is_deleted: false,
+     * //     created_at: '2024-01-01T00:00:00.000Z'
+     * //   }
+     * // }
+     */
+    async getFile(fileId) {
+        if (!fileId) {
+            throw new Error('File ID is required');
+        }
+        return this.client.get(`cdn/files/${fileId}`);
+    }
+
+    /**
+     * Delete file (soft delete)
+     * Uses session authentication (requires logged in user)
+     * 
+     * @param {number|string} fileId - File ID to delete
+     * @returns {Promise<Object>} Delete result
+     * 
+     * @example
+     * const result = await cdn.deleteFile(123);
+     * 
+     * // Returns:
+     * // {
+     * //   success: true,
+     * //   message: 'File marked as deleted'
+     * // }
+     */
+    async deleteFile(fileId) {
+        if (!fileId) {
+            throw new Error('File ID is required');
+        }
+        return this.client.delete(`cdn/files/${fileId}`);
+    }
+
+    /**
+     * Restore a soft-deleted file
+     * Uses session authentication (requires logged in user)
+     * 
+     * @param {number|string} fileId - File ID to restore
+     * @returns {Promise<Object>} Restore result
+     * 
+     * @example
+     * const result = await cdn.restoreFile(123);
+     * 
+     * // Returns:
+     * // {
+     * //   success: true,
+     * //   message: 'File restored successfully'
+     * // }
+     */
+    async restoreFile(fileId) {
+        if (!fileId) {
+            throw new Error('File ID is required');
+        }
+        return this.client.post(`cdn/files/${fileId}/restore`);
+    }
+}
+