@allanfsouza/aether-sdk 2.0.0 → 2.2.0

package/src/database.ts

@@ -12,15 +12,130 @@ type WebSocketMessage<T = any> = {
 
 // [NOVO] Opções de Listagem Avançada
 export type ListOptions<T> = {
-  // Filtro parcial (ex: { status: 'active' })
-  filter?: Partial<T>;
-  // Ordenação
+  filter?: Partial<T> | Record<string, any>; // Suporta operadores avançados
   sort?: {
-    field: keyof T & string; // Garante que o campo existe no tipo T
+    field: keyof T & string;
     order: "ASC" | "DESC";
   };
+  limit?: number;
+  offset?: number;
 };
 
+/**
+ * Builder para construção fluente de queries.
+ */
+export class QueryBuilder<T> {
+  private collectionRef: CollectionReference<T>;
+  private filter: Record<string, any> = {};
+  private sort?: { field: string; order: "ASC" | "DESC" };
+  private limitVal?: number;
+  private offsetVal?: number;
+
+  constructor(collectionRef: CollectionReference<T>) {
+    this.collectionRef = collectionRef;
+  }
+
+  /**
+   * Adiciona um filtro de igualdade.
+   */
+  eq(column: keyof T & string, value: any): this {
+    this.filter[column] = value;
+    return this;
+  }
+
+  /**
+   * Adiciona um filtro de desigualdade ($ne).
+   */
+  neq(column: keyof T & string, value: any): this {
+    this.filter[column] = { ...this.filter[column], $ne: value };
+    return this;
+  }
+
+  /**
+   * Adiciona um filtro maior que ($gt).
+   */
+  gt(column: keyof T & string, value: number | string): this {
+    this.filter[column] = { ...this.filter[column], $gt: value };
+    return this;
+  }
+
+  /**
+   * Adiciona um filtro maior ou igual ($gte).
+   */
+  gte(column: keyof T & string, value: number | string): this {
+    this.filter[column] = { ...this.filter[column], $gte: value };
+    return this;
+  }
+
+  /**
+   * Adiciona um filtro menor que ($lt).
+   */
+  lt(column: keyof T & string, value: number | string): this {
+    this.filter[column] = { ...this.filter[column], $lt: value };
+    return this;
+  }
+
+  /**
+   * Adiciona um filtro menor ou igual ($lte).
+   */
+  lte(column: keyof T & string, value: number | string): this {
+    this.filter[column] = { ...this.filter[column], $lte: value };
+    return this;
+  }
+
+  /**
+   * Adiciona um filtro LIKE ($like).
+   */
+  like(column: keyof T & string, value: string): this {
+    this.filter[column] = { ...this.filter[column], $like: value };
+    return this;
+  }
+
+  /**
+   * Define a ordenação.
+   */
+  order(column: keyof T & string, direction: "ASC" | "DESC" = "ASC"): this {
+    this.sort = { field: column, order: direction };
+    return this;
+  }
+
+  /**
+   * Define o limite de registros.
+   */
+  limit(count: number): this {
+    this.limitVal = count;
+    return this;
+  }
+
+  /**
+   * Define o deslocamento (paginação).
+   */
+  offset(count: number): this {
+    this.offsetVal = count;
+    return this;
+  }
+
+  /**
+   * Executa a query e retorna os resultados.
+   */
+  async get(): Promise<T[]> {
+    return this.collectionRef.list({
+      filter: this.filter,
+      sort: this.sort as any,
+      limit: this.limitVal,
+      offset: this.offsetVal,
+    });
+  }
+}
+
+/**
+ * Operação em lote.
+ */
+export type BatchOperation =
+  | { type: "create"; collection: string; data: any }
+  | { type: "update"; collection: string; id: string; data: any }
+  | { type: "delete"; collection: string; id: string };
+
 /**
  * Módulo de Banco de Dados
  */
@@ -41,13 +156,22 @@ export class DatabaseModule {
   collection<T = any>(collectionName: string) {
     return new CollectionReference<T>(this.client, this.http, collectionName);
   }
+
+  /**
+   * Executa múltiplas operações em uma única transação.
+   * Se uma falhar, todas são revertidas.
+   */
+  async batch(operations: BatchOperation[]): Promise<any[]> {
+    const { data } = await this.http.post("/db/batch", { operations });
+    return data.results;
+  }
 }
 
 /**
  * Referência a uma coleção específica.
  * O <T> define o formato dos dados (ex: interface User).
  */
-class CollectionReference<T> {
+export class CollectionReference<T> {
   private client: PlataformaClient;
   private http: AxiosInstance;
   private collectionName: string;
@@ -62,6 +186,31 @@ class CollectionReference<T> {
     this.wsUrl = client.apiUrl.replace(/^https?/, protocol);
   }
 
+  /**
+   * Inicia o QueryBuilder.
+   * Atalho para .eq()
+   */
+  eq(column: keyof T & string, value: any): QueryBuilder<T> {
+    return new QueryBuilder<T>(this).eq(column, value);
+  }
+
+  /**
+   * Inicia o QueryBuilder.
+   * Atalho para .gt()
+   */
+  gt(column: keyof T & string, value: number | string): QueryBuilder<T> {
+    return new QueryBuilder<T>(this).gt(column, value);
+  }
+
+  // ... Outros atalhos podem ser adicionados conforme necessidade ...
+
+  /**
+   * Retorna uma nova instância do QueryBuilder.
+   */
+  query(): QueryBuilder<T> {
+    return new QueryBuilder<T>(this);
+  }
+
   /**
    * Lista documentos da coleção com filtros opcionais.
    * @param options Filtros e Ordenação
@@ -79,6 +228,10 @@ class CollectionReference<T> {
       params.sort = JSON.stringify([options.sort.field, options.sort.order]);
     }
 
+    // TODO: Backend precisa implementar limit/offset na rota GET
+    // if (options?.limit) params.limit = options.limit;
+    // if (options?.offset) params.offset = options.offset;
+
     const { data } = await this.http.get(`/db/${this.collectionName}`, {
       params,
     });
@@ -136,7 +289,7 @@ class CollectionReference<T> {
 
     if (!token || !projectId) {
       console.warn("[SDK] Realtime falhou: Token ou ProjectId ausentes.");
-      return () => {};
+      return () => { };
     }
 
     const url = `${this.wsUrl}/v1/db/subscribe/${this.collectionName}?token=${token}&projectId=${projectId}`;
@@ -173,7 +326,7 @@ class CollectionReference<T> {
       };
     } catch (err) {
       console.error("[SDK] Erro WS:", err);
-      return () => {};
+      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

@@ -11,23 +11,13 @@ export class FunctionsModule {
     this.http = http;
   }
 
-  /**
-   * Chama uma função HTTP Serverless.
-   * @param functionName O nome da função (ou rota, ex: 'pedidos/123')
-   * @param body (Opcional) Dados para enviar no corpo (POST)
-   * @param method (Opcional) Método HTTP (padrão POST se tiver body, GET se não)
-   */
   async invoke<T = any>(
     functionName: string,
     body?: any,
     method?: "GET" | "POST" | "PUT" | "DELETE"
   ) {
     const projectId = this.client.projectId;
-
-    // Remove barras iniciais para evitar URL malformada
     const cleanName = functionName.replace(/^\//, "");
-
-    // Define método automaticamente se não informado
     const finalMethod = method || (body ? "POST" : "GET");
 
     const response = await this.http.request<T>({
@@ -38,4 +28,4 @@ export class FunctionsModule {
 
     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;
-}
+}

package/src/index.ts

@@ -4,55 +4,62 @@ import { createHttpClient } from "./http-client.js";
 import { AuthModule } from "./auth.js";
 import { DatabaseModule } from "./database.js";
 import { StorageModule } from "./storage.js";
-import { FunctionsModule } from "./functions.js"; // [NOVO] Import do módulo
+import { FunctionsModule } from "./functions.js";
+import { PushModule } from "./push.js";
 
-type ClientConfig = {
+/**
+ * Configuração usada para criar o cliente principal da plataforma.
+ */
+export type ClientConfig = {
   apiUrl: string;
   projectId: string;
 };
 
 /**
- * O cliente principal da Plataforma API.
- * Ponto de entrada para todos os módulos (Auth, DB, Storage, Functions).
+ * O cliente principal da Plataforma API (Aether).
+ * Ponto de entrada para todos os módulos (Auth, DB, Storage, Functions, Push).
  */
 export class PlataformaClient {
-  // Propriedades públicas (os "módulos")
+  // Módulos públicos disponíveis para o usuário do SDK
   public auth: AuthModule;
   public db: DatabaseModule;
   public storage: StorageModule;
-  public functions: FunctionsModule; // [NOVO] Propriedade pública
+  public functions: FunctionsModule;
+  public push: PushModule;
 
-  // Propriedades de configuração
+  // Configurações imutáveis da instância
   public apiUrl: string;
   public projectId: string;
 
-  // Propriedades internas
-  private http: AxiosInstance;
+  // Infra interna
+  public http: AxiosInstance;
   private _token: string | null = null;
 
   constructor(config: ClientConfig) {
     if (!config.apiUrl || !config.projectId) {
       throw new Error("apiUrl e projectId são obrigatórios.");
     }
-    this.apiUrl = config.apiUrl.replace(/\/$/, ""); // Remove barra final se houver
+
+    // Normaliza apiUrl removendo barras finais, se houver
+    this.apiUrl = config.apiUrl.replace(/\/+$/, "");
     this.projectId = config.projectId;
 
-    // Inicializa o cliente HTTP (passando 'this', a própria instância para injetar token/ID)
+    // Inicializa o cliente HTTP (passando a própria instância)
     this.http = createHttpClient(this);
 
-    // Inicializa os módulos passando a referência do cliente e do axios
+    // Inicializa os módulos de alto nível
     this.auth = new AuthModule(this, this.http);
     this.db = new DatabaseModule(this, this.http);
     this.storage = new StorageModule(this, this.http);
-    this.functions = new FunctionsModule(this, this.http); // [NOVO] Inicialização
+    this.functions = new FunctionsModule(this, this.http);
+    this.push = new PushModule(this, this.http);
   }
 
   // --- Gerenciamento de Token ---
 
   /**
    * Armazena o token de autenticação em memória.
-   * Chamado automaticamente pelo AuthModule após login.
-   * @param token O JWT (ou null para logout)
+   * Chamado automaticamente pelo AuthModule após login/registro.
    */
   setToken(token: string | null) {
     this._token = token;
@@ -61,9 +68,25 @@ export class PlataformaClient {
   /**
    * Recupera o token de autenticação atual.
    * Usado pelo http-client para injetar o header Authorization.
-   * @returns O JWT ou null
    */
   getToken(): string | null {
     return this._token;
   }
 }
+
+// Re-exports convenientes para quem consome o SDK
+export { AetherError } from "./errors.js";
+export type { ListOptions } from "./database.js";
+
+// Tipos relacionados a Push
+export type {
+  PushPlatform,
+  PushEnvironment,
+  PushDevice,
+  RegisterDeviceParams,
+  SendPushResponse,
+  PushStatus,
+  PushLogEntry,
+  ListPushLogsOptions,
+  PushStats,
+} from "./push.js";

package/src/push.ts

@@ -0,0 +1,157 @@
+// src/push.ts
+import type { AxiosInstance } from "axios";
+import type { PlataformaClient } from "./index.js";
+
+export type PushPlatform = "android" | "ios" | "web";
+export type PushEnvironment = "dev" | "staging" | "prod";
+
+export interface RegisterDeviceParams {
+    platform: PushPlatform;
+    token: string;
+    environment?: PushEnvironment;
+}
+
+export interface PushDevice {
+    id: string;
+    projectId: string;
+    userId?: string | null;
+    platform: PushPlatform;
+    token: string;
+    environment: PushEnvironment;
+    createdAt: string;
+    lastSeenAt: string;
+}
+
+export interface RegisterDeviceResponse {
+    device: PushDevice;
+}
+
+export interface SendPushResponse {
+    sent: number;
+    total: number;
+    message: string;
+}
+
+export type PushStatus = "sent" | "failed";
+
+export interface PushLogEntry {
+    id: string;
+    projectId: string;
+    userId?: string | null;
+    deviceId?: string | null;
+    title: string;
+    body: string;
+    data: Record<string, string>;
+    status: PushStatus;
+    errorMessage?: string | null;
+    createdAt: string;
+}
+
+export interface ListPushLogsOptions {
+    limit?: number;
+    offset?: number;
+    status?: PushStatus;
+}
+
+export interface PushStats {
+    totalDevices: number;
+    sent24h: number;
+    successRate: number;
+}
+
+export class PushModule {
+    constructor(
+        private client: PlataformaClient,
+        private http: AxiosInstance
+    ) { }
+
+    async registerDevice(params: RegisterDeviceParams): Promise<PushDevice> {
+        const projectId = this.client.projectId;
+
+        const { data } = await this.http.post<RegisterDeviceResponse>(
+            `/projects/${projectId}/push/devices`,
+            {
+                platform: params.platform,
+                token: params.token,
+                environment: params.environment ?? "prod",
+            }
+        );
+
+        return data.device;
+    }
+
+    async sendToToken(params: {
+        token: string;
+        title: string;
+        body: string;
+        data?: Record<string, string>;
+        environment?: PushEnvironment;
+    }): Promise<SendPushResponse> {
+        const projectId = this.client.projectId;
+
+        const { data } = await this.http.post<SendPushResponse>(
+            `/projects/${projectId}/push/send`,
+            {
+                token: params.token,
+                title: params.title,
+                body: params.body,
+                data: params.data ?? {},
+                environment: params.environment ?? "prod",
+            }
+        );
+
+        return data;
+    }
+
+    async sendToUser(params: {
+        userId: string;
+        title: string;
+        body: string;
+        data?: Record<string, string>;
+        environment?: PushEnvironment;
+    }): Promise<SendPushResponse> {
+        const projectId = this.client.projectId;
+
+        const { data } = await this.http.post<SendPushResponse>(
+            `/projects/${projectId}/push/send`,
+            {
+                userId: params.userId,
+                title: params.title,
+                body: params.body,
+                data: params.data ?? {},
+                environment: params.environment ?? "prod",
+            }
+        );
+
+        return data;
+    }
+
+    async listLogs(
+        options: ListPushLogsOptions = {}
+    ): Promise<PushLogEntry[]> {
+        const projectId = this.client.projectId;
+
+        const { data } = await this.http.get<{ data: PushLogEntry[] }>(
+            `/projects/${projectId}/push/logs`,
+            {
+                params: {
+                    limit: options.limit,
+                    offset: options.offset,
+                    status: options.status,
+                },
+            }
+        );
+
+        return data.data;
+    }
+
+    async getStats(): Promise<PushStats> {
+        const projectId = this.client.projectId;
+
+        const { data } = await this.http.get<PushStats>(
+            `/projects/${projectId}/push/stats`
+        );
+
+        return data;
+    }
+}

package/tsconfig.json

@@ -1,14 +1,21 @@
 {
   "compilerOptions": {
-    "target": "ES2020", // Moderno, mas compatível
-    "module": "NodeNext", // Suporta tanto 'require' (CJS) quanto 'import' (ESM)
-    "declaration": true, // [IMPORTANTE] Gera arquivos .d.ts (para autocompletar)
-    "outDir": "./dist", // Onde o JavaScript compilado irá
-    "rootDir": "./src", // Onde nosso código TypeScript está
-    "strict": true, // Força boas práticas
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
-    "moduleResolution": "NodeNext"
+    // Adicionado DOM para reconhecer 'File', 'Blob' e 'WebSocket' nativos
+    "lib": [
+      "ES2020",
+      "DOM"
+    ]
   },
-  "include": ["src"] // Só compila o que está na pasta 'src'
-}
+  "include": [
+    "src"
+  ]
+}