@aether-baas/core 3.6.1 → 3.6.4

package/dist/modules/storage.js

@@ -1,26 +1,87 @@
 // =============================================================================
-// @aether/core - Storage Module
+// @aether-baas/core - Storage Module (CORRIGIDO)
 // =============================================================================
-// Módulo de storage para upload/download de arquivos.
+// Módulo para operações de storage (upload, download, delete).
+// 
+// CORREÇÕES APLICADAS:
+// 1. Padronizado retorno para Result<T> em todos os métodos
+// 2. Assinatura unificada com options object
+// 3. Validações robustas de entrada
+// 4. Tratamento de erros consistente
+// 5. Documentação JSDoc completa
 // =============================================================================
 import axios from 'axios';
+import { ok, err } from '../types/result.js';
+// =============================================================================
+// CONSTANTES
+// =============================================================================
+/** Timeout padrão para uploads (5 minutos) */
+const UPLOAD_TIMEOUT = 300000;
+/** Mapeamento de extensões para MIME types */
+const MIME_TYPES = {
+    // Imagens
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    png: 'image/png',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    ico: 'image/x-icon',
+    // Documentos
+    pdf: 'application/pdf',
+    doc: 'application/msword',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xls: 'application/vnd.ms-excel',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    ppt: 'application/vnd.ms-powerpoint',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    // Texto
+    txt: 'text/plain',
+    csv: 'text/csv',
+    json: 'application/json',
+    xml: 'application/xml',
+    html: 'text/html',
+    css: 'text/css',
+    js: 'application/javascript',
+    // Áudio
+    mp3: 'audio/mpeg',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+    // Vídeo
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    avi: 'video/x-msvideo',
+    // Arquivos
+    zip: 'application/zip',
+    rar: 'application/vnd.rar',
+    tar: 'application/x-tar',
+    gz: 'application/gzip',
+};
 // =============================================================================
 // STORAGE MODULE
 // =============================================================================
 /**
- * Módulo de storage do Aether.
+ * Módulo para operações de storage.
  *
  * @example
  * ```typescript
- * // Upload
- * const { data } = await aether.storage.upload(file, 'avatar.png', 'image/png');
- * console.log(data.downloadUrl);
+ * // Upload de arquivo
+ * const result = await aether.storage.upload(file, {
+ *   folder: 'avatars',
+ *   onProgress: (p) => console.log(`${p.percent}%`)
+ * });
  *
- * // Listar
- * const files = await aether.storage.list('folder');
+ * if (result.success) {
+ *   console.log('URL:', result.data.downloadUrl);
+ * } else {
+ *   console.error('Erro:', result.error);
+ * }
  *
- * // Deletar
- * await aether.storage.delete('file-id');
+ * // Listar arquivos
+ * const files = await aether.storage.list('avatars');
+ *
+ * // Deletar arquivo
+ * await aether.storage.delete(fileId);
  * ```
  */
 export class StorageModule {
@@ -30,202 +91,448 @@ export class StorageModule {
         this.client = client;
         this.http = http;
     }
+    // ===========================================================================
+    // UPLOAD
+    // ===========================================================================
     /**
-     * Faz upload de um arquivo.
+     * Faz upload de um arquivo para o storage.
      *
-     * @param file Arquivo a ser enviado (File, Blob ou Buffer)
-     * @param fileName Nome do arquivo (com extensão)
-     * @param contentType MIME type do arquivo (ex: 'image/png')
-     * @param folder Pasta de destino (opcional)
-     * @param onProgress Callback de progresso (opcional)
+     * @param file - Arquivo a ser enviado (File, Blob ou Buffer)
+     * @param options - Opções de upload (fileName, contentType, folder, onProgress)
+     * @returns Result com FileObject em caso de sucesso, ou erro em caso de falha
      *
      * @example
      * ```typescript
-     * const { data, error } = await aether.storage.upload(file, 'foto.png', 'image/png');
-     * if (error) console.error('Falha no upload:', error);
+     * // Upload básico
+     * const result = await storage.upload(file);
+     *
+     * // Upload com opções
+     * const result = await storage.upload(file, {
+     *   fileName: 'avatar.jpg',
+     *   folder: 'users/123',
+     *   contentType: 'image/jpeg',
+     *   onProgress: (p) => setProgress(p.percent)
+     * });
+     *
+     * // Tratamento do resultado
+     * if (result.success) {
+     *   const url = result.data.downloadUrl;
+     *   console.log('Arquivo disponível em:', url);
+     * } else {
+     *   console.error('Falha no upload:', result.error);
+     * }
      * ```
      */
-    async upload(file, fileName, contentType, folder, onProgress) {
+    async upload(file, options = {}) {
         const projectId = this.client.projectId;
-        const mimeType = contentType || 'application/octet-stream';
-        // [SEGURANÇA] Validação básica do arquivo
+        // =========================================================================
+        // VALIDAÇÃO DE ENTRADA
+        // =========================================================================
+        // [SEGURANÇA] Validação do arquivo
         if (!file) {
-            throw new Error('Arquivo não fornecido');
+            return err('Arquivo não fornecido');
+        }
+        // Obtém tamanho do arquivo
+        const fileSize = this.getFileSize(file);
+        if (fileSize === 0) {
+            return err('Arquivo está vazio (0 bytes)');
         }
+        // Gera nome do arquivo se não fornecido
+        const fileName = options.fileName || this.generateFileName(file);
         if (!fileName || typeof fileName !== 'string') {
-            throw new Error('Nome do arquivo inválido');
+            return err('Nome do arquivo inválido');
         }
+        // [SEGURANÇA] Sanitiza nome do arquivo
+        const sanitizedFileName = this.sanitizeFileName(fileName);
+        // Infere MIME type se não fornecido
+        const contentType = options.contentType || this.inferContentType(file, sanitizedFileName);
         try {
-            // ================================================================
+            // =====================================================================
             // ETAPA 1: Obter URL presigned do backend
-            // ================================================================
-            const { data: uploadData } = await this.http.post(`/v1/projects/${projectId}/storage/upload-url`, {
-                fileName,
-                contentType: mimeType,
-                folder,
-                size: file instanceof Blob ? file.size : file.length,
+            // =====================================================================
+            const presignedResult = await this.getPresignedUrl({
+                fileName: sanitizedFileName,
+                contentType,
+                folder: options.folder,
+                size: fileSize,
             });
-            const presignedUrl = uploadData.data.uploadUrl || uploadData.data.url;
-            const fileId = uploadData.data.fileId;
-            if (!presignedUrl) {
-                throw new Error('Servidor não retornou URL de upload válida');
-            }
-            if (!fileId) {
-                throw new Error('Servidor não retornou ID do arquivo');
+            if (!presignedResult.success) {
+                return presignedResult;
             }
-            // ================================================================
+            const { uploadUrl, fileId } = presignedResult.data;
+            // =====================================================================
             // ETAPA 2: Preparar blob para upload
-            // ================================================================
-            let blob;
-            let fileSize;
-            if (typeof Buffer !== 'undefined' && Buffer.isBuffer(file)) {
-                // Node.js Buffer
-                blob = new Blob([new Uint8Array(file)], { type: mimeType });
-                fileSize = file.length;
-            }
-            else if (file instanceof Blob) {
-                // Browser File/Blob
-                blob = file;
-                fileSize = file.size;
-            }
-            else {
-                throw new Error('Tipo de arquivo não suportado (apenas Blob, Buffer ou File)');
-            }
-            // [SEGURANÇA] Validação de tamanho zero (arquivo vazio/corrompido)
-            if (fileSize === 0) {
-                throw new Error('Arquivo está vazio (0 bytes)');
+            // =====================================================================
+            const blob = this.prepareBlob(file, contentType);
+            // =====================================================================
+            // ETAPA 3: Upload para S3
+            // =====================================================================
+            const s3Result = await this.uploadToS3(uploadUrl, blob, contentType, options.onProgress);
+            if (!s3Result.success) {
+                return s3Result;
             }
-            // ================================================================
-            // ETAPA 3: Upload para S3 com validação rigorosa
-            // ================================================================
-            try {
-                const s3Response = await axios.put(presignedUrl, blob, {
-                    headers: {
-                        'Content-Type': mimeType,
-                    },
-                    validateStatus: (status) => status >= 200 && status < 300,
-                    onUploadProgress: (event) => {
-                        if (onProgress && event.total) {
-                            onProgress({
-                                loaded: event.loaded,
-                                total: event.total,
-                                percent: Math.round((event.loaded / event.total) * 100),
-                            });
-                        }
-                    },
-                    timeout: 300000,
-                    transformRequest: [(data) => data],
-                });
+            // =====================================================================
+            // ETAPA 4: Confirmar upload no backend
+            // =====================================================================
+            const confirmResult = await this.confirmUpload(fileId);
+            if (!confirmResult.success) {
+                return confirmResult;
             }
-            catch (s3Error) {
-                // [SEGURANÇA] Captura específica de erros do S3
-                const axiosError = s3Error;
-                console.error('[Aether SDK] Falha no PUT S3:', {
-                    status: axiosError.response?.status,
-                    statusText: axiosError.response?.statusText,
-                    code: axiosError.code,
-                    message: axiosError.message,
-                });
-                if (axiosError.code === 'ERR_NETWORK') {
-                    throw new Error('Falha de rede ao enviar arquivo. Verifique sua conexão.');
-                }
-                if (axiosError.response?.status === 403) {
-                    throw new Error('Permissão negada (403): O upload foi rejeitado pelo storage.');
-                }
-                if (axiosError.response?.status === 400) {
-                    throw new Error('Arquivo rejeitado (400): Verifique o tipo e tamanho.');
+            // =====================================================================
+            // ETAPA 5: Validar e retornar resultado
+            // =====================================================================
+            const fileObject = confirmResult.data;
+            // [ROBUSTEZ] Garante que temos uma URL válida
+            if (!fileObject.downloadUrl && !fileObject.publicUrl && !fileObject.url) {
+                // Tenta recuperar URL via GET
+                const refreshResult = await this.get(fileObject.id);
+                if (refreshResult.success && refreshResult.data.downloadUrl) {
+                    return refreshResult;
                 }
-                throw new Error(axiosError.message || 'Falha ao enviar arquivo para storage');
+                return err('Upload confirmado mas URL do arquivo não foi obtida');
             }
-            // ================================================================
-            // ETAPA 4: Confirmar upload no backend
-            // ================================================================
-            const { data: fileData } = await this.http.post(`/v1/projects/${projectId}/storage/confirm`, { fileId });
-            if (!fileData?.data?.id) {
-                throw new Error('Confirmação de upload falhou: ID não retornado');
+            return ok(fileObject);
+        }
+        catch (error) {
+            // [TRATAMENTO DE ERRO] Captura erros não tratados
+            const message = this.parseError(error);
+            console.error('[Aether Storage] Erro não tratado no upload:', message);
+            return err(message);
+        }
+    }
+    // ===========================================================================
+    // MÉTODOS AUXILIARES DE UPLOAD
+    // ===========================================================================
+    /**
+     * Obtém URL presigned para upload.
+     */
+    async getPresignedUrl(params) {
+        const projectId = this.client.projectId;
+        try {
+            const { data } = await this.http.post(`/v1/projects/${projectId}/storage/upload-url`, params);
+            const uploadUrl = data.data.uploadUrl || data.data.url;
+            const fileId = data.data.fileId;
+            if (!uploadUrl) {
+                return err('Servidor não retornou URL de upload válida');
             }
-            return fileData.data;
-        }
-        catch (err) {
-            // Propaga o erro para que o frontend possa tratar (ex: mostrar toast vermelho)
-            const error = err;
-            console.error('[Aether SDK] Erro no upload:', error.message);
-            if (error.response?.status === 429) {
-                throw new Error('Limite de uploads atingido. Tente novamente em alguns minutos.');
+            if (!fileId) {
+                return err('Servidor não retornou ID do arquivo');
             }
-            if (error.response?.status === 413) {
-                throw new Error('Arquivo muito grande para upload.');
+            return ok({ uploadUrl, fileId });
+        }
+        catch (error) {
+            return err(this.parseHttpError(error, 'Falha ao obter URL de upload'));
+        }
+    }
+    /**
+     * Faz upload do blob para S3.
+     */
+    async uploadToS3(presignedUrl, blob, contentType, onProgress) {
+        try {
+            await axios.put(presignedUrl, blob, {
+                headers: {
+                    'Content-Type': contentType,
+                },
+                validateStatus: (status) => status >= 200 && status < 300,
+                onUploadProgress: (event) => {
+                    if (onProgress && event.total) {
+                        onProgress({
+                            loaded: event.loaded,
+                            total: event.total,
+                            percent: Math.round((event.loaded / event.total) * 100),
+                        });
+                    }
+                },
+                timeout: UPLOAD_TIMEOUT,
+                // [IMPORTANTE] Não transformar o blob
+                transformRequest: [(data) => data],
+            });
+            return ok(undefined);
+        }
+        catch (error) {
+            return err(this.parseS3Error(error));
+        }
+    }
+    /**
+     * Confirma upload no backend.
+     */
+    async confirmUpload(fileId) {
+        const projectId = this.client.projectId;
+        try {
+            const { data } = await this.http.post(`/v1/projects/${projectId}/storage/confirm`, { fileId });
+            if (!data?.data?.id) {
+                return err('Confirmação de upload falhou: ID não retornado');
             }
-            // Se já for um erro tratado acima, relança. 
-            // Se for axios error genérico do http.post (upload-url), extrai mensagem.
-            const msg = error.response?.data?.error ||
-                error.response?.data?.message ||
-                error.message ||
-                'Erro desconhecido no upload';
-            throw new Error(msg);
+            return ok(data.data);
+        }
+        catch (error) {
+            return err(this.parseHttpError(error, 'Falha ao confirmar upload'));
         }
     }
+    // ===========================================================================
+    // LIST
+    // ===========================================================================
     /**
      * Lista arquivos de uma pasta.
+     *
+     * @param folder - Pasta para listar (opcional)
+     * @param options - Opções de paginação
+     * @returns Result com lista de FileObject
      */
-    async list(folder, options) {
+    async list(folder, options = {}) {
         const projectId = this.client.projectId;
         const params = {};
         if (folder)
             params.folder = folder;
-        if (options?.limit)
+        if (options.limit)
             params.limit = options.limit;
-        if (options?.offset)
+        if (options.offset)
             params.offset = options.offset;
-        const { data } = await this.http.get(`/v1/projects/${projectId}/storage`, { params });
-        return data.data;
+        if (options.order)
+            params.order = options.order;
+        if (options.orderBy)
+            params.orderBy = options.orderBy;
+        try {
+            const { data } = await this.http.get(`/v1/projects/${projectId}/storage`, { params });
+            return ok(data.data || []);
+        }
+        catch (error) {
+            return err(this.parseHttpError(error, 'Falha ao listar arquivos'));
+        }
     }
+    // ===========================================================================
+    // GET
+    // ===========================================================================
     /**
      * Busca um arquivo por ID.
+     *
+     * @param fileId - ID do arquivo
+     * @returns Result com FileObject ou erro
      */
     async get(fileId) {
+        if (!fileId) {
+            return err('ID do arquivo não fornecido');
+        }
         const projectId = this.client.projectId;
-        const { data } = await this.http.get(`/v1/projects/${projectId}/storage/${fileId}`);
-        return data.data;
+        try {
+            const { data } = await this.http.get(`/v1/projects/${projectId}/storage/${fileId}`);
+            if (!data?.data) {
+                return err('Arquivo não encontrado');
+            }
+            return ok(data.data);
+        }
+        catch (error) {
+            return err(this.parseHttpError(error, 'Falha ao buscar arquivo'));
+        }
     }
+    // ===========================================================================
+    // DELETE
+    // ===========================================================================
     /**
      * Deleta um arquivo.
+     *
+     * @param fileId - ID do arquivo a deletar
+     * @returns Result com boolean indicando sucesso
      */
     async delete(fileId) {
+        if (!fileId) {
+            return err('ID do arquivo não fornecido');
+        }
         const projectId = this.client.projectId;
-        await this.http.delete(`/v1/projects/${projectId}/storage/${fileId}`);
-        return true;
+        try {
+            await this.http.delete(`/v1/projects/${projectId}/storage/${fileId}`);
+            return ok(true);
+        }
+        catch (error) {
+            return err(this.parseHttpError(error, 'Falha ao deletar arquivo'));
+        }
     }
+    // ===========================================================================
+    // URL HELPERS
+    // ===========================================================================
     /**
-     * Gera URL assinada temporária para download.
+     * Gera URL assinada temporária para um arquivo.
+     *
+     * @param fileId - ID do arquivo
+     * @param expiresIn - Tempo de expiração em segundos (padrão: 3600)
+     * @returns Result com URL assinada
      */
     async getSignedUrl(fileId, expiresIn = 3600) {
+        if (!fileId) {
+            return err('ID do arquivo não fornecido');
+        }
         const projectId = this.client.projectId;
-        const { data } = await this.http.post(`/v1/projects/${projectId}/storage/${fileId}/signed-url`, { expiresIn });
-        return data.url;
+        try {
+            const { data } = await this.http.get(`/v1/projects/${projectId}/storage/${fileId}/signed-url`, { params: { expiresIn } });
+            if (!data?.data?.signedUrl) {
+                return err('Servidor não retornou URL assinada');
+            }
+            return ok(data.data.signedUrl);
+        }
+        catch (error) {
+            return err(this.parseHttpError(error, 'Falha ao gerar URL assinada'));
+        }
     }
     /**
-     * Retorna URL pública do arquivo (se bucket for público).
+     * Retorna URL pública de um arquivo.
+     *
+     * @param fileId - ID do arquivo
+     * @returns URL pública (síncrono)
      */
     getPublicUrl(fileId) {
         const projectId = this.client.projectId;
-        return `${this.client.apiUrl}/v1/projects/${projectId}/storage/public/${fileId}`;
+        const baseUrl = this.http.defaults.baseURL || '';
+        return `${baseUrl}/v1/projects/${projectId}/storage/${fileId}/public-download`;
     }
+    // ===========================================================================
+    // UTILITÁRIOS PRIVADOS
+    // ===========================================================================
     /**
-     * Move arquivo para outra pasta.
+     * Obtém tamanho do arquivo em bytes.
      */
-    async move(fileId, newFolder) {
-        const projectId = this.client.projectId;
-        const { data } = await this.http.put(`/v1/projects/${projectId}/storage/${fileId}/move`, { folder: newFolder });
-        return data.data;
+    getFileSize(file) {
+        if (typeof Buffer !== 'undefined' && Buffer.isBuffer(file)) {
+            return file.length;
+        }
+        return file.size;
     }
     /**
-     * Renomeia arquivo.
+     * Gera nome único para o arquivo.
      */
-    async rename(fileId, newName) {
-        const projectId = this.client.projectId;
-        const { data } = await this.http.put(`/v1/projects/${projectId}/storage/${fileId}`, { name: newName });
-        return data.data;
+    generateFileName(file) {
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substring(2, 8);
+        // Tenta obter extensão do arquivo original
+        let ext = 'bin';
+        if (typeof Buffer !== 'undefined' && Buffer.isBuffer(file)) {
+            // Buffer: tenta inferir do magic bytes se possível, mas aqui vamos de bin default
+            // Poderíamos passar contentType como dica se tivéssemos acesso aqui
+            ext = 'bin';
+        }
+        else if (file instanceof File && file.name) {
+            const parts = file.name.split('.');
+            if (parts.length > 1) {
+                ext = parts.pop().toLowerCase();
+            }
+        }
+        else if (file instanceof Blob && file.type) {
+            // Infere extensão do MIME type
+            const mimeExt = Object.entries(MIME_TYPES).find(([_, mime]) => mime === file.type);
+            if (mimeExt) {
+                ext = mimeExt[0];
+            }
+        }
+        return `file_${timestamp}_${random}.${ext}`;
+    }
+    /**
+     * Sanitiza nome do arquivo removendo caracteres perigosos.
+     */
+    sanitizeFileName(fileName) {
+        return fileName
+            // Remove path traversal
+            .replace(/\.\./g, '')
+            // Remove caracteres especiais perigosos
+            .replace(/[<>:"/\\|?*\x00-\x1f]/g, '_')
+            // Limita tamanho
+            .substring(0, 255)
+            // Remove espaços do início e fim
+            .trim();
+    }
+    /**
+     * Infere MIME type do arquivo.
+     */
+    inferContentType(file, fileName) {
+        // 1. Tenta do arquivo (se for File/Blob)
+        if (typeof Buffer === 'undefined' || !Buffer.isBuffer(file)) {
+            if (file instanceof File && file.type) {
+                return file.type;
+            }
+            if (file instanceof Blob && file.type) {
+                return file.type;
+            }
+        }
+        // 2. Infere da extensão
+        const ext = fileName.split('.').pop()?.toLowerCase();
+        if (ext && MIME_TYPES[ext]) {
+            return MIME_TYPES[ext];
+        }
+        // 3. Fallback
+        return 'application/octet-stream';
+    }
+    /**
+     * Prepara blob para upload.
+     */
+    prepareBlob(file, contentType) {
+        if (typeof Buffer !== 'undefined' && Buffer.isBuffer(file)) {
+            return new Blob([new Uint8Array(file)], { type: contentType });
+        }
+        return file;
+    }
+    /**
+     * Parseia erro genérico.
+     */
+    parseError(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        if (typeof error === 'string') {
+            return error;
+        }
+        return 'Erro desconhecido';
+    }
+    /**
+     * Parseia erro de requisição HTTP.
+     */
+    parseHttpError(error, fallback) {
+        const axiosError = error;
+        // Erro de rede
+        if (axiosError.code === 'ERR_NETWORK') {
+            return 'Falha de conexão. Verifique sua internet.';
+        }
+        // Erros HTTP específicos
+        if (axiosError.response?.status === 401) {
+            return 'Sessão expirada. Faça login novamente.';
+        }
+        if (axiosError.response?.status === 403) {
+            return 'Permissão negada para esta operação.';
+        }
+        if (axiosError.response?.status === 404) {
+            return 'Recurso não encontrado.';
+        }
+        if (axiosError.response?.status === 413) {
+            return 'Arquivo muito grande.';
+        }
+        if (axiosError.response?.status === 429) {
+            return 'Muitas requisições. Tente novamente em alguns minutos.';
+        }
+        // Mensagem do servidor
+        if (axiosError.response?.data?.message) {
+            return axiosError.response.data.message;
+        }
+        if (axiosError.response?.data?.error) {
+            return axiosError.response.data.error;
+        }
+        // Mensagem do axios
+        if (axiosError.message) {
+            return axiosError.message;
+        }
+        return fallback;
+    }
+    /**
+     * Parseia erro específico do S3.
+     */
+    parseS3Error(error) {
+        const axiosError = error;
+        if (axiosError.code === 'ERR_NETWORK') {
+            return 'Falha de rede ao enviar arquivo. Verifique sua conexão.';
+        }
+        if (axiosError.response?.status === 403) {
+            return 'Upload rejeitado pelo storage (403). URL pode ter expirado.';
+        }
+        if (axiosError.response?.status === 400) {
+            return 'Arquivo rejeitado (400). Verifique tipo e tamanho.';
+        }
+        return axiosError.message || 'Falha ao enviar arquivo para storage';
     }
 }
 //# sourceMappingURL=storage.js.map