@allanfsouza/aether-sdk 1.0.0 → 2.1.0

package/dist/storage.js

@@ -1,40 +1,65 @@
-import axios from "axios"; // [A CORREÇÃO ESTÁ AQUI]
-/**
- * Módulo de Storage
- * Lida com upload e download de arquivos.
- */
+import axios from "axios";
 export class StorageModule {
     constructor(client, http) {
         this.client = client;
         this.http = http;
     }
     /**
-     * Faz o upload de um arquivo para o Storage do projeto.
-     * Isso lida com o fluxo de "presign" (URL assinada) automaticamente.
-     * @param file O objeto 'File' (do navegador) ou um Buffer (do Node.js)
-     * @param fileName O nome do arquivo (ex: "imagem.png")
-     * @param contentType O tipo (ex: "image/png")
-     * @returns O objeto do arquivo criado no banco
+     * Faz o upload de um arquivo.
+     * @param file Arquivo (Browser: File, Node: Buffer)
+     * @param fileName Nome do arquivo (ex: 'foto.jpg')
+     * @param contentType MIME Type (ex: 'image/jpeg')
+     * @param folder (Opcional) Pasta de destino (ex: 'usuarios/123/')
      */
-    async upload(file, fileName, contentType) {
-        const size = file.size || file.length;
-        // 1. Pedir a URL de upload para nossa API
+    async upload(file, fileName, contentType, folder // [NOVO]
+    ) {
+        // Calcula tamanho de forma segura para Browser e Node
+        let size = 0;
+        if (typeof File !== "undefined" && file instanceof File) {
+            size = file.size;
+        }
+        else if (typeof Blob !== "undefined" && file instanceof Blob) {
+            size = file.size;
+        }
+        else if (file instanceof Buffer) {
+            // Node.js
+            size = file.length;
+        }
+        // 1. Pedir URL assinada
         const { data: presignData } = await this.http.post("/storage/presign", {
-            fileName: fileName,
-            contentType: contentType,
-            size: size,
+            fileName,
+            contentType,
+            size,
+            prefix: folder || "", // [NOVO] Envia o prefixo para o backend
         });
-        // O 'presign' vem dentro de 'data'
         const presign = presignData.data;
-        if (!presign?.url) {
-            throw new Error("API não retornou uma URL de upload assinada.");
-        }
-        // 2. Enviar o arquivo diretamente para o Minio/S3 (sem auth)
-        //    Usamos o 'axios' global aqui, não o 'this.http' (que adicionaria auth)
+        if (!presign?.url)
+            throw new Error("Falha ao obter URL de upload.");
+        // 2. Upload direto para S3
         await axios.put(presign.url, file, {
             headers: { "Content-Type": contentType },
         });
-        // 3. Retorna os detalhes do objeto (downloadUrl, objectId, etc.)
-        return presign;
+        return {
+            id: presign.objectId,
+            key: presign.key,
+            downloadUrl: presign.downloadUrl,
+            url: presign.downloadUrl, // Alias amigável
+        };
+    }
+    /**
+     * Lista arquivos de uma pasta.
+     */
+    async list(folder = "") {
+        const { data } = await this.http.get("/storage/list", {
+            params: { projectId: this.client.projectId, prefix: folder },
+        });
+        return data.data; // Retorna { files: [], folders: [] }
+    }
+    /**
+     * Deleta um arquivo pelo ID.
+     */
+    async delete(fileId) {
+        await this.http.delete("/storage/delete", { data: { objectId: fileId } });
+        return true;
     }
 }

package/errors.ts

@@ -0,0 +1,46 @@
+// src/errors.ts
+export class AetherError extends Error {
+  constructor(
+    public code: string,
+    public message: string,
+    public status?: number,
+    public details?: any
+  ) {
+    super(message);
+    this.name = "AetherError";
+    // Garante que instanceof AetherError funcione bem em qualquer bundler (ES5/ES6)
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export function handleAxiosError(error: any): never {
+  if (error?.response) {
+    // Erro vindo da API (4xx, 5xx)
+    const data = error.response.data;
+    const message =
+      data?.error || data?.message || "Erro desconhecido na API";
+    const status: number = error.response.status;
+
+    let code = "api_error";
+    if (status === 401) code = "unauthorized";
+    if (status === 403) code = "permission_denied";
+    if (status === 404) code = "not_found";
+    if (status === 409) code = "conflict";
+    if (status === 429) code = "rate_limit_exceeded";
+
+    throw new AetherError(code, message, status, data);
+  }
+
+  if (error?.request && !error.response) {
+    // Erro de rede (sem resposta, offline, timeout)
+    throw new AetherError(
+      "network_error",
+      "Não foi possível conectar ao servidor Aether. Verifique sua conexão.",
+      0
+    );
+  }
+
+  // Erro na configuração / código cliente
+  const fallbackMessage = error?.message || "Erro interno no cliente SDK.";
+  throw new AetherError("client_error", fallbackMessage);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@allanfsouza/aether-sdk",
-  "version": "1.0.0",
-  "description": "SDK do Cliente para a Plataforma API",
+  "version": "2.1.0",
+  "description": "SDK do Cliente para a Plataforma Aether",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -15,15 +15,17 @@
     "build": "npx tsc",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "keywords": [],
+  "keywords": [
+    "baas",
+    "sdk",
+    "aether"
+  ],
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "axios": "^1.13.2",
-    "ws": "^8.18.0"
+    "axios": "^1.6.0"
   },
   "devDependencies": {
-    "@types/ws": "^8.5.11",
-    "typescript": "^5.9.3"
+    "typescript": "^5.3.0"
   }
-}
+}

package/src/auth.ts

@@ -2,10 +2,6 @@
 import type { AxiosInstance } from "axios";
 import type { PlataformaClient } from "./index.js";
 
-/**
- * Módulo de Autenticação
- * Lida com login, registro e gerenciamento de token.
- */
 export class AuthModule {
   private client: PlataformaClient;
   private http: AxiosInstance;
@@ -15,48 +11,43 @@ export class AuthModule {
     this.http = http;
   }
 
-  /**
-   * Autentica um usuário e armazena o token no SDK.
-   * @param email O e-mail do usuário
-   * @param password A senha do usuário
-   * @returns O objeto do usuário e o token
-   */
   async login(email: string, password: string) {
     try {
       const { data } = await this.http.post("/auth/login", { email, password });
-      // Salva o token DENTRO da instância do SDK
-      this.client.setToken(data.token);
-      return data; // Retorna { user, token }
-    } catch (e: unknown) {
-      this.client.setToken(null); // Limpa o token em caso de falha
+      if (data.token) {
+        this.client.setToken(data.token);
+      }
+      return data;
+    } catch (e) {
+      this.client.setToken(null);
       throw e;
     }
   }
 
-  /**
-   * Registra um novo usuário e já o loga.
-   * @param credentials Nome, email e senha
-   * @returns O objeto do usuário e o token
-   */
-  async register(credentials: {
-    name: string;
-    email: string;
-    password: string;
-  }) {
+  async register(credentials: { name: string; email: string; password: string }) {
     try {
       const { data } = await this.http.post("/auth/register", credentials);
-      this.client.setToken(data.token);
+      if (data.token) {
+        this.client.setToken(data.token);
+      }
       return data;
-    } catch (e: unknown) {
+    } catch (e) {
       this.client.setToken(null);
       throw e;
     }
   }
 
-  /**
-   * Desconecta o usuário limpando o token do SDK.
-   */
+  async forgotPassword(email: string) {
+    const { data } = await this.http.post("/auth/forgot-password", { email });
+    return data;
+  }
+
+  async resetPassword(token: string, newPassword: string) {
+    const { data } = await this.http.post("/auth/reset-password", { token, newPassword });
+    return data;
+  }
+
   logout() {
     this.client.setToken(null);
   }
-}
+}

package/src/database.ts

@@ -4,15 +4,25 @@ import type { PlataformaClient } from "./index.js";
 import WebSocket from "ws";
 
 // Tipo para a mensagem que recebemos do WebSocket
-type WebSocketMessage = {
+type WebSocketMessage<T = any> = {
   action: "create" | "update" | "delete";
   collection: string;
-  data: any;
+  data: T;
+};
+
+// [NOVO] Opções de Listagem Avançada
+export type ListOptions<T> = {
+  // Filtro parcial (ex: { status: 'active' })
+  filter?: Partial<T>;
+  // Ordenação
+  sort?: {
+    field: keyof T & string; // Garante que o campo existe no tipo T
+    order: "ASC" | "DESC";
+  };
 };
 
 /**
- * Módulo de Banco de Dados (Firestore-like)
- * Ponto de entrada para acessar as coleções.
+ * Módulo de Banco de Dados
  */
 export class DatabaseModule {
   private client: PlataformaClient;
@@ -24,20 +34,20 @@ export class DatabaseModule {
   }
 
   /**
-   * Seleciona uma coleção de dados (ex: 'tasks' ou 'posts').
-   * @param collectionName O nome da coleção (ex: "tasks")
-   * @returns Uma instância de CollectionReference para operar nela
+   * Seleciona uma coleção de dados.
+   * [PREMIUM] Suporta Generics <T> para tipagem forte.
+   * * @example client.db.collection<Product>('products')
    */
-  collection(collectionName: string) {
-    return new CollectionReference(this.client, this.http, collectionName);
+  collection<T = any>(collectionName: string) {
+    return new CollectionReference<T>(this.client, this.http, collectionName);
   }
 }
 
 /**
- * Representa uma referência a uma coleção específica no banco.
- * Contém os métodos CRUD (create, list, update, delete) e subscribe.
+ * Referência a uma coleção específica.
+ * O <T> define o formato dos dados (ex: interface User).
  */
-class CollectionReference {
+class CollectionReference<T> {
   private client: PlataformaClient;
   private http: AxiosInstance;
   private collectionName: string;
@@ -47,103 +57,123 @@ class CollectionReference {
     this.client = client;
     this.http = http;
     this.collectionName = name;
-    // Constrói a URL do WebSocket (substituindo http por ws)
-    this.wsUrl = client.apiUrl.replace(/^http/, "ws");
+    // Ajusta protocolo para WS/WSS
+    const protocol = client.apiUrl.startsWith("https") ? "wss" : "ws";
+    this.wsUrl = client.apiUrl.replace(/^https?/, protocol);
+  }
+
+  /**
+   * Lista documentos da coleção com filtros opcionais.
+   * @param options Filtros e Ordenação
+   */
+  async list(options?: ListOptions<T>): Promise<T[]> {
+    const params: any = {};
+
+    // Converte os objetos do SDK para strings que o Backend entende
+    if (options?.filter) {
+      params.filter = JSON.stringify(options.filter);
+    }
+
+    if (options?.sort) {
+      // Backend espera formato array: ["campo", "DESC"]
+      params.sort = JSON.stringify([options.sort.field, options.sort.order]);
+    }
+
+    const { data } = await this.http.get(`/db/${this.collectionName}`, {
+      params,
+    });
+    return data.data;
   }
 
   /**
-   * Lista todos os documentos da coleção.
-   * (GET /v1/db/tasks)
+   * Busca um documento pelo ID.
    */
-  async list() {
-    const { data } = await this.http.get(`/db/${this.collectionName}`);
-    return data.data; // Retorna o array de documentos
+  async get(id: string): Promise<T> {
+    const { data } = await this.http.get(`/db/${this.collectionName}/${id}`);
+    return data.data;
   }
 
   /**
-   * Cria um novo documento na coleção.
-   * (POST /v1/db/tasks)
-   * @param newData O objeto de dados a ser criado
+   * Cria um novo documento.
+   * O Partial<T> permite criar sem passar campos gerados (como id, createdAt).
    */
-  async create(newData: Record<string, any>) {
+  async create(newData: Partial<T>): Promise<T> {
     const { data } = await this.http.post(
       `/db/${this.collectionName}`,
       newData
     );
-    return data.data; // Retorna o documento criado
+    return data.data;
   }
 
   /**
    * Atualiza um documento existente.
-   * (PUT /v1/db/tasks/:id)
-   * @param id O ID do documento
-   * @param updates Os campos a serem atualizados
    */
-  async update(id: string, updates: Record<string, any>) {
+  async update(id: string, updates: Partial<T>): Promise<T> {
     const { data } = await this.http.put(
       `/db/${this.collectionName}/${id}`,
       updates
     );
-    return data.data; // Retorna o documento atualizado
+    return data.data;
   }
 
   /**
    * Deleta um documento.
-   * (DELETE /v1/db/tasks/:id)
-   * @param id O ID do documento
    */
-  async delete(id: string) {
-    const { data } = await this.http.delete(`/db/${this.collectionName}/${id}`);
-    return data; // Retorna { ok: true, ... }
+  async delete(id: string): Promise<boolean> {
+    await this.http.delete(`/db/${this.collectionName}/${id}`);
+    return true;
   }
 
   /**
-   * Inscreve-se para mudanças em tempo real na coleção.
-   * @param callback A função que será chamada com (action, data)
-   * @returns Uma função 'unsubscribe' para fechar a conexão
+   * Inscreve-se para mudanças em tempo real.
+   * O callback recebe os dados já tipados como T.
    */
   subscribe(
-    callback: (action: "create" | "update" | "delete", data: any) => void
+    callback: (action: "create" | "update" | "delete", data: T) => void
   ) {
     const token = this.client.getToken();
     const projectId = this.client.projectId;
 
     if (!token || !projectId) {
-      throw new Error("Não é possível se inscrever sem um token e projectId.");
+      console.warn("[SDK] Realtime falhou: Token ou ProjectId ausentes.");
+      return () => {};
     }
 
-    // Constrói a URL: ws://localhost:3000/v1/db/subscribe/tasks?token=...&projectId=...
     const url = `${this.wsUrl}/v1/db/subscribe/${this.collectionName}?token=${token}&projectId=${projectId}`;
 
-    const ws = new WebSocket(url);
-
-    ws.on("open", () => {
-      console.log(
-        `[SDK] Inscrito em tempo real na coleção '${this.collectionName}'`
-      );
-    });
-
-    ws.on("message", (message: string) => {
-      try {
-        const payload = JSON.parse(message) as WebSocketMessage;
-        // Chama o callback do usuário
-        callback(payload.action, payload.data);
-      } catch (e) {
-        console.error("[SDK] Erro ao processar mensagem WS:", e);
-      }
-    });
-
-    ws.on("close", () => {
-      console.log(`[SDK] Desconectado da coleção '${this.collectionName}'`);
-    });
-
-    ws.on("error", (err) => {
-      console.error("[SDK] Erro no WebSocket:", err.message);
-    });
-
-    // Retorna uma função que o usuário pode chamar para parar de "ouvir"
-    return () => {
-      ws.close();
-    };
+    let ws: WebSocket | null = null;
+
+    try {
+      ws = new WebSocket(url);
+
+      ws.onopen = () => {
+        // Conectado
+      };
+
+      ws.onmessage = (event: any) => {
+        try {
+          const raw = event.data?.toString() || event.toString();
+          if (raw === "pong") return;
+
+          const payload = JSON.parse(raw) as WebSocketMessage<T>;
+          callback(payload.action, payload.data);
+        } catch (e) {
+          // Erro silencioso de parse
+        }
+      };
+
+      // Mantém a conexão viva (Heartbeat)
+      const pingInterval = setInterval(() => {
+        if (ws?.readyState === WebSocket.OPEN) ws.send("ping");
+      }, 30000);
+
+      return () => {
+        clearInterval(pingInterval);
+        if (ws) ws.close();
+      };
+    } catch (err) {
+      console.error("[SDK] Erro WS:", err);
+      return () => {};
+    }
   }
 }

package/src/errors.ts

@@ -0,0 +1,50 @@
+// src/errors.ts
+export class AetherError extends Error {
+  constructor(
+    public code: string,
+    public message: string,
+    public status?: number,
+    public details?: any
+  ) {
+    super(message);
+    this.name = "AetherError";
+    // Garante que instanceof AetherError funcione mesmo em cenários com transpile/bundler
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Converte qualquer erro vindo do Axios em um AetherError padronizado.
+ * Essa função é pensada para ser usada no interceptor de responses.
+ */
+export function handleAxiosError(error: any): never {
+  // Erro com resposta do servidor (4xx, 5xx)
+  if (error && error.response) {
+    const data = error.response.data;
+    const message =
+      data?.error || data?.message || "Erro desconhecido na API";
+    const status: number = error.response.status;
+
+    let code = "api_error";
+    if (status === 401) code = "unauthorized";
+    if (status === 403) code = "permission_denied";
+    if (status === 404) code = "not_found";
+    if (status === 429) code = "rate_limit_exceeded";
+
+    throw new AetherError(code, message, status, data);
+  }
+
+  // Erro de rede (sem resposta do servidor)
+  if (error && error.request && !error.response) {
+    throw new AetherError(
+      "network_error",
+      "Não foi possível conectar ao servidor Aether.",
+      0
+    );
+  }
+
+  // Erro de configuração / código do cliente
+  const fallbackMessage =
+    (error && error.message) || "Erro interno no cliente SDK.";
+  throw new AetherError("client_error", fallbackMessage);
+}

package/src/functions.ts

@@ -0,0 +1,31 @@
+// src/functions.ts
+import type { AxiosInstance } from "axios";
+import type { PlataformaClient } from "./index.js";
+
+export class FunctionsModule {
+  private client: PlataformaClient;
+  private http: AxiosInstance;
+
+  constructor(client: PlataformaClient, http: AxiosInstance) {
+    this.client = client;
+    this.http = http;
+  }
+
+  async invoke<T = any>(
+    functionName: string,
+    body?: any,
+    method?: "GET" | "POST" | "PUT" | "DELETE"
+  ) {
+    const projectId = this.client.projectId;
+    const cleanName = functionName.replace(/^\//, "");
+    const finalMethod = method || (body ? "POST" : "GET");
+
+    const response = await this.http.request<T>({
+      url: `/functions/http/${projectId}/${cleanName}`,
+      method: finalMethod,
+      data: body,
+    });
+
+    return response.data;
+  }
+}

package/src/http-client.ts

@@ -1,27 +1,29 @@
 // src/http-client.ts
 import axios, { type AxiosInstance } from "axios";
-import { PlataformaClient } from "./index.js"; // Importa o tipo da classe principal
+import type { PlataformaClient } from "./index.js";
+import { handleAxiosError } from "./errors.js";
 
 /**
  * Cria uma instância do Axios pré-configurada.
- * Ela usa um interceptor para adicionar dinamicamente os
- * headers 'Authorization' e 'X-Project-ID' em cada requisição.
- * * @param client A instância principal do PlataformaClient
- * @returns Uma instância configurada do Axios
+ * - Injeta automaticamente headers de Auth e Projeto.
+ * - Converte erros em AetherError.
  */
 export function createHttpClient(client: PlataformaClient): AxiosInstance {
   const http = axios.create({
-    baseURL: `${client.apiUrl}/v1`, // Adiciona o /v1 automaticamente
+    // Adiciona o /v1 automaticamente em todas as chamadas do SDK
+    baseURL: `${client.apiUrl}/v1`,
+    headers: {
+      "Content-Type": "application/json",
+    },
   });
 
+  // Interceptor de REQUEST
   http.interceptors.request.use((config) => {
-    // 1. Pega o token atual do cliente
     const token = client.getToken();
     if (token) {
       config.headers.Authorization = `Bearer ${token}`;
     }
 
-    // 2. Pega o ID do projeto
     if (client.projectId) {
       config.headers["X-Project-ID"] = client.projectId;
     }
@@ -29,5 +31,11 @@ export function createHttpClient(client: PlataformaClient): AxiosInstance {
     return config;
   });
 
+  // Interceptor de RESPONSE
+  http.interceptors.response.use(
+    (response) => response,
+    (error) => handleAxiosError(error)
+  );
+
   return http;
-}
+}