@allanfsouza/aether-sdk 2.4.9 → 2.4.11

package/dist/database.js

@@ -199,7 +199,6 @@ export class CollectionReference {
             console.warn("[SDK] Realtime falhou: Token ou ProjectId ausentes.");
             return () => { };
         }
-        // URL correta de subscribe
         const url = `${this.wsUrl}/v1/db/subscribe/${this.collectionName}?token=${token}&projectId=${projectId}`;
         let ws = null;
         try {
@@ -207,7 +206,7 @@ export class CollectionReference {
             if (!ws)
                 return () => { };
             ws.onopen = () => {
-                // Conectado
+                console.log(`[SDK] Realtime conectado: ${this.collectionName}`);
             };
             ws.onmessage = (event) => {
                 try {
@@ -215,16 +214,27 @@ export class CollectionReference {
                     if (raw === "pong")
                         return;
                     const payload = JSON.parse(raw);
-                    callback(payload.action, payload.data);
+                    console.log(`[SDK] Evento recebido:`, payload.action, payload.data?.id);
+                    // [FIX] Mapeia 'insert' do Postgres para 'create' do SDK
+                    let action = payload.action;
+                    if (payload.action === 'insert') {
+                        action = 'create';
+                    }
+                    callback(action, payload.data);
                 }
                 catch (e) {
-                    // Erro silencioso de parse
+                    console.error('[SDK] Erro ao parsear evento:', e);
                 }
             };
+            ws.onerror = (err) => {
+                console.error('[SDK] WebSocket erro:', err);
+            };
+            ws.onclose = () => {
+                console.log(`[SDK] Realtime desconectado: ${this.collectionName}`);
+            };
             // Heartbeat
             const pingInterval = setInterval(() => {
-                // [CORREÇÃO] Adicionada verificação explicita 'ws &&' para evitar erro 'possibly null'
-                if (ws && ws.readyState === 1) { // 1 = OPEN
+                if (ws && ws.readyState === 1) {
                     ws.send("ping");
                 }
             }, 30000);

package/dist/http-client.js

@@ -115,7 +115,7 @@ export function createHttpClient(client, retryConfig = {}) {
     });
     // ===========================================================================
     // INTERCEPTOR DE REQUEST
-    // Injeta token e projectId em todas as requisições
+    // Injeta token, projectId e API Key em todas as requisições
     // ===========================================================================
     http.interceptors.request.use((reqConfig) => {
         const token = client.getToken();
@@ -125,6 +125,10 @@ export function createHttpClient(client, retryConfig = {}) {
         if (client.projectId) {
             reqConfig.headers["X-Project-ID"] = client.projectId;
         }
+        // [NOVO] Envia API Key para autenticação de operações de banco de dados
+        if (client.serviceApiKey) {
+            reqConfig.headers["X-API-Key"] = client.serviceApiKey;
+        }
         // Inicializa contador de retry
         if (reqConfig._retryCount === undefined) {
             reqConfig._retryCount = 0;

package/dist/index.d.ts

@@ -13,6 +13,11 @@ export type ClientConfig = {
     baseUrl?: string;
     projectId?: string;
     apiKey?: string;
+    /**
+     * [NOVO] API Key de serviço para autenticação em operações de banco de dados.
+     * Necessário para apps client-side que usam tenant auth.
+     */
+    serviceApiKey?: string;
     /**
      * Habilita persistência automática de sessão no localStorage.
      * Padrão: true em browsers, false em Node.js/SSR.
@@ -29,6 +34,7 @@ export declare class PlataformaClient {
     database: DatabaseModule;
     apiUrl: string;
     projectId: string;
+    serviceApiKey: string | null;
     http: AxiosInstance;
     private _token;
     private _persistSession;

package/dist/index.js

@@ -24,6 +24,7 @@ function isBrowser() {
 }
 export class PlataformaClient {
     constructor(config) {
+        this.serviceApiKey = null;
         this._token = null;
         // Resolve URL (prioridade para baseUrl se existir, senão apiUrl)
         const url = config.baseUrl || config.apiUrl;
@@ -33,6 +34,7 @@ export class PlataformaClient {
         }
         this.apiUrl = url.replace(/\/+$/, "");
         this.projectId = project;
+        this.serviceApiKey = config.serviceApiKey || null;
         // Persistência habilitada por padrão apenas em browsers
         this._persistSession = config.persistSession ?? isBrowser();
         // Restaura sessão salva ANTES de criar o httpClient

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allanfsouza/aether-sdk",
-  "version": "2.4.9",
+  "version": "2.4.11",
   "description": "SDK do Cliente para a Plataforma Aether",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/ai.ts

@@ -0,0 +1,580 @@
+// src/ai.ts
+// [NOVO] Módulo de IA do Aether SDK
+// Permite que clientes adicionem IA aos seus apps com poucas linhas de código
+// Data: Dezembro 2025
+
+import type { AxiosInstance } from "axios";
+import type { PlataformaClient } from "./index.js";
+
+// =============================================================================
+// TIPOS
+// =============================================================================
+
+/**
+ * Opções para o método chat()
+ */
+export interface ChatOptions {
+    /** ID da conversa para manter contexto entre mensagens */
+    conversationId?: string;
+
+    /** Contexto adicional (ex: "vendas", "suporte", "produtos") */
+    context?: string;
+
+    /** Callback chamado a cada chunk de texto recebido (streaming) */
+    onChunk?: (chunk: string) => void;
+
+    /** Callback chamado quando a resposta completa é recebida */
+    onComplete?: (fullResponse: string, metadata: ChatMetadata) => void;
+
+    /** Callback chamado em caso de erro */
+    onError?: (error: Error) => void;
+
+    /** Timeout em ms (padrão: 30000) */
+    timeout?: number;
+}
+
+/**
+ * Metadados retornados após uma resposta completa
+ */
+export interface ChatMetadata {
+    conversationId: string;
+    messageId?: string;
+    tokensUsed?: number;
+    sources?: RetrievedSource[];
+}
+
+/**
+ * Fonte de dados usada pelo RAG
+ */
+export interface RetrievedSource {
+    type: string;
+    content: string;
+    similarity: number;
+}
+
+/**
+ * Resposta do método ask()
+ */
+export interface AskResponse {
+    text: string;
+    conversationId: string;
+    sources?: RetrievedSource[];
+}
+
+/**
+ * Conversa persistida
+ */
+export interface Conversation {
+    id: string;
+    title: string;
+    context: string;
+    createdAt: string;
+    updatedAt: string;
+    messageCount?: number;
+}
+
+/**
+ * Mensagem de uma conversa
+ */
+export interface Message {
+    id: string;
+    conversationId: string;
+    role: 'user' | 'assistant';
+    content: string;
+    metadata?: Record<string, any>;
+    createdAt: string;
+}
+
+/**
+ * Tipo de feedback
+ */
+export type FeedbackType = 'thumbs_up' | 'thumbs_down';
+
+/**
+ * Opções para busca semântica
+ */
+export interface SemanticSearchOptions {
+    /** Número máximo de resultados (padrão: 10) */
+    limit?: number;
+
+    /** Score mínimo de similaridade 0-1 (padrão: 0.5) */
+    minScore?: number;
+
+    /** Filtrar por collection específica */
+    collection?: string;
+}
+
+/**
+ * Resultado de busca semântica
+ */
+export interface SemanticSearchResult {
+    id: string;
+    content: string;
+    collection: string;
+    similarity: number;
+    metadata?: Record<string, any>;
+}
+
+/**
+ * Opções para geração de conteúdo
+ */
+export interface GenerateOptions {
+    /** Tom do texto (formal, casual, técnico, etc) */
+    tone?: 'formal' | 'casual' | 'technical' | 'friendly';
+
+    /** Tamanho aproximado (short, medium, long) */
+    length?: 'short' | 'medium' | 'long';
+
+    /** Idioma (padrão: pt-BR) */
+    language?: string;
+
+    /** Contexto adicional para a geração */
+    context?: string;
+}
+
+// =============================================================================
+// MÓDULO PRINCIPAL
+// =============================================================================
+
+export class AIModule {
+    private client: PlataformaClient;
+    private http: AxiosInstance;
+
+    /** Sub-módulo para gerenciar conversas */
+    public conversations: ConversationsAPI;
+
+    /** Sub-módulo para funções administrativas */
+    public admin: AIAdminAPI;
+
+    constructor(client: PlataformaClient, http: AxiosInstance) {
+        this.client = client;
+        this.http = http;
+        this.conversations = new ConversationsAPI(client, http);
+        this.admin = new AIAdminAPI(client, http);
+    }
+
+    // ===========================================================================
+    // MÉTODOS PRINCIPAIS
+    // ===========================================================================
+
+    /**
+     * Faz uma pergunta simples e aguarda a resposta completa.
+     * Ideal para quando não precisa de streaming.
+     * 
+     * @example
+     * const { text } = await aether.ai.ask("Quais produtos estão em promoção?");
+     * console.log(text);
+     */
+    async ask(message: string, conversationId?: string): Promise<AskResponse> {
+        return new Promise((resolve, reject) => {
+            let fullText = '';
+            let metadata: ChatMetadata = { conversationId: conversationId || '' };
+
+            this.chat(message, {
+                conversationId,
+                onChunk: (chunk) => {
+                    fullText += chunk;
+                },
+                onComplete: (response, meta) => {
+                    metadata = meta;
+                    resolve({
+                        text: fullText,
+                        conversationId: meta.conversationId,
+                        sources: meta.sources
+                    });
+                },
+                onError: reject
+            }).catch(reject);
+        });
+    }
+
+    /**
+     * Inicia um chat com streaming de resposta.
+     * A resposta chega em chunks conforme a IA gera.
+     * 
+     * @example
+     * await aether.ai.chat("Explique como funciona o sistema de pagamentos", {
+     *   onChunk: (chunk) => {
+     *     // Atualiza UI em tempo real
+     *     setResponse(prev => prev + chunk);
+     *   },
+     *   onComplete: (full, meta) => {
+     *     console.log("Conversa ID:", meta.conversationId);
+     *   }
+     * });
+     */
+    async chat(message: string, options: ChatOptions = {}): Promise<void> {
+        const projectId = this.client.projectId;
+        const token = this.client.getToken();
+
+        if (!token) {
+            const error = new Error('Usuário não autenticado. Faça login primeiro.');
+            if (options.onError) {
+                options.onError(error);
+                return;
+            }
+            throw error;
+        }
+
+        const timeout = options.timeout || 30000;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+        try {
+            const response = await fetch(`${this.client.apiUrl}/v1/ai/chat`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${token}`,
+                    'X-Project-ID': projectId
+                },
+                body: JSON.stringify({
+                    message,
+                    projectId,
+                    conversationId: options.conversationId,
+                    context: options.context || 'general'
+                }),
+                signal: controller.signal
+            });
+
+            clearTimeout(timeoutId);
+
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`Erro na API: ${response.status} - ${errorText}`);
+            }
+
+            // Captura conversation ID do header (se disponível)
+            const convIdFromHeader = response.headers.get('X-Conversation-ID');
+
+            // Processa o stream
+            const reader = response.body?.getReader();
+            const decoder = new TextDecoder();
+            let fullResponse = '';
+
+            if (!reader) {
+                throw new Error('Stream não disponível');
+            }
+
+            while (true) {
+                const { done, value } = await reader.read();
+
+                if (done) break;
+
+                const chunk = decoder.decode(value, { stream: true });
+                fullResponse += chunk;
+
+                if (options.onChunk) {
+                    options.onChunk(chunk);
+                }
+            }
+
+            // Callback de conclusão
+            if (options.onComplete) {
+                options.onComplete(fullResponse, {
+                    conversationId: convIdFromHeader || options.conversationId || '',
+                });
+            }
+
+        } catch (error: any) {
+            clearTimeout(timeoutId);
+
+            if (error.name === 'AbortError') {
+                error = new Error(`Timeout: A requisição excedeu ${timeout}ms`);
+            }
+
+            if (options.onError) {
+                options.onError(error);
+            } else {
+                throw error;
+            }
+        }
+    }
+
+    /**
+     * Envia feedback sobre uma resposta da IA.
+     * Ajuda a melhorar as respostas futuras.
+     * 
+     * @example
+     * await aether.ai.feedback(messageId, 'thumbs_up');
+     * await aether.ai.feedback(messageId, 'thumbs_down', 'Resposta incorreta');
+     */
+    async feedback(
+        messageId: string,
+        type: FeedbackType,
+        comment?: string
+    ): Promise<{ success: boolean }> {
+        const { data } = await this.http.post('/ai/feedback', {
+            messageId,
+            feedbackType: type,
+            comment
+        });
+        return data;
+    }
+
+    // ===========================================================================
+    // BUSCA SEMÂNTICA
+    // ===========================================================================
+
+    /**
+     * Busca semântica nos dados do projeto.
+     * Encontra documentos similares usando embeddings.
+     * 
+     * @example
+     * // Busca produtos similares a uma descrição
+     * const results = await aether.ai.search("tênis confortável para corrida");
+     * 
+     * // Com filtros
+     * const results = await aether.ai.search("problema no login", {
+     *   collection: "support_tickets",
+     *   limit: 5,
+     *   minScore: 0.7
+     * });
+     */
+    async search(
+        query: string,
+        options: SemanticSearchOptions = {}
+    ): Promise<SemanticSearchResult[]> {
+        const { data } = await this.http.post('/ai/search', {
+            query,
+            projectId: this.client.projectId,
+            limit: options.limit || 10,
+            minScore: options.minScore || 0.5,
+            collection: options.collection
+        });
+        return data.results;
+    }
+
+    // ===========================================================================
+    // GERAÇÃO DE CONTEÚDO
+    // ===========================================================================
+
+    /**
+     * Gera texto baseado em um prompt e contexto.
+     * Útil para descrições de produtos, resumos, etc.
+     * 
+     * @example
+     * // Gerar descrição de produto
+     * const descricao = await aether.ai.generate(
+     *   "Escreva uma descrição para o produto",
+     *   { productName: "iPhone 15", price: 5999, features: ["5G", "48MP"] },
+     *   { tone: 'friendly', length: 'medium' }
+     * );
+     */
+    async generate(
+        prompt: string,
+        data: Record<string, any>,
+        options: GenerateOptions = {}
+    ): Promise<string> {
+        const { data: response } = await this.http.post('/ai/generate', {
+            prompt,
+            data,
+            projectId: this.client.projectId,
+            tone: options.tone || 'friendly',
+            length: options.length || 'medium',
+            language: options.language || 'pt-BR',
+            context: options.context
+        });
+        return response.text;
+    }
+
+    // ===========================================================================
+    // ANÁLISE DE DADOS
+    // ===========================================================================
+
+    /**
+     * Analisa dados e retorna insights em linguagem natural.
+     * 
+     * @example
+     * const insights = await aether.ai.analyze("orders", {
+     *   question: "Como foram as vendas essa semana?",
+     *   period: "7d"
+     * });
+     */
+    async analyze(
+        collection: string,
+        options: { question: string; period?: string }
+    ): Promise<{ insights: string; data?: any }> {
+        const { data } = await this.http.post('/ai/analyze', {
+            collection,
+            projectId: this.client.projectId,
+            question: options.question,
+            period: options.period || '7d'
+        });
+        return data;
+    }
+
+    /**
+     * Processa linguagem natural e converte em query estruturada.
+     * Útil para criar filtros de busca baseados em texto do usuário.
+     * 
+     * @example
+     * const query = await aether.ai.parseQuery(
+     *   "produtos vermelhos acima de 100 reais ordenados por preço"
+     * );
+     * // Retorna: { filter: { color: 'vermelho', price: { $gt: 100 } }, sort: { price: 'ASC' } }
+     */
+    async parseQuery(
+        naturalLanguage: string,
+        collection?: string
+    ): Promise<{ filter?: Record<string, any>; sort?: Record<string, any> }> {
+        const { data } = await this.http.post('/ai/parse-query', {
+            query: naturalLanguage,
+            collection,
+            projectId: this.client.projectId
+        });
+        return data;
+    }
+}
+
+// =============================================================================
+// SUB-MÓDULO: CONVERSAS
+// =============================================================================
+
+class ConversationsAPI {
+    private client: PlataformaClient;
+    private http: AxiosInstance;
+
+    constructor(client: PlataformaClient, http: AxiosInstance) {
+        this.client = client;
+        this.http = http;
+    }
+
+    /**
+     * Lista todas as conversas do usuário no projeto.
+     * 
+     * @example
+     * const conversas = await aether.ai.conversations.list();
+     */
+    async list(): Promise<Conversation[]> {
+        const { data } = await this.http.get('/ai/conversations', {
+            params: { projectId: this.client.projectId }
+        });
+        return data;
+    }
+
+    /**
+     * Busca o histórico de mensagens de uma conversa.
+     * 
+     * @example
+     * const mensagens = await aether.ai.conversations.getMessages(conversationId);
+     */
+    async getMessages(conversationId: string): Promise<Message[]> {
+        const { data } = await this.http.get(`/ai/messages/${conversationId}`);
+        return data;
+    }
+
+    /**
+     * Deleta uma conversa e todo seu histórico.
+     * 
+     * @example
+     * await aether.ai.conversations.delete(conversationId);
+     */
+    async delete(conversationId: string): Promise<{ success: boolean }> {
+        const { data } = await this.http.delete(`/ai/conversations/${conversationId}`);
+        return data;
+    }
+
+    /**
+     * Renomeia uma conversa.
+     * 
+     * @example
+     * await aether.ai.conversations.rename(conversationId, "Suporte Técnico");
+     */
+    async rename(conversationId: string, title: string): Promise<Conversation> {
+        const { data } = await this.http.patch(`/ai/conversations/${conversationId}`, {
+            title
+        });
+        return data;
+    }
+}
+
+// =============================================================================
+// SUB-MÓDULO: ADMIN
+// =============================================================================
+
+class AIAdminAPI {
+    private client: PlataformaClient;
+    private http: AxiosInstance;
+
+    constructor(client: PlataformaClient, http: AxiosInstance) {
+        this.client = client;
+        this.http = http;
+    }
+
+    /**
+     * Reindexa todos os dados do projeto para RAG.
+     * Use após adicionar/modificar grandes volumes de dados.
+     * Executa em background.
+     * 
+     * @example
+     * await aether.ai.admin.reindex();
+     */
+    async reindex(): Promise<{ message: string }> {
+        const { data } = await this.http.post('/ai/reindex', {
+            projectId: this.client.projectId
+        });
+        return data;
+    }
+
+    /**
+     * Limpa todos os embeddings do projeto.
+     * CUIDADO: A IA "esquece" todo o contexto aprendido.
+     * 
+     * @example
+     * const { deletedCount } = await aether.ai.admin.clear();
+     */
+    async clear(): Promise<{ deletedCount: number }> {
+        const { data } = await this.http.post('/ai/clear', {
+            projectId: this.client.projectId
+        });
+        return data;
+    }
+
+    /**
+     * Retorna estatísticas de uso da IA.
+     * 
+     * @example
+     * const stats = await aether.ai.admin.stats();
+     * console.log(stats.totalConversations, stats.totalMessages);
+     */
+    async stats(): Promise<{
+        totalConversations: number;
+        totalMessages: number;
+        totalEmbeddings: number;
+        storageUsedMB: number;
+    }> {
+        const { data } = await this.http.get('/ai/stats', {
+            params: { projectId: this.client.projectId }
+        });
+        return data;
+    }
+
+    /**
+     * Configura quais collections são indexadas automaticamente.
+     * 
+     * @example
+     * await aether.ai.admin.setIndexedCollections(['products', 'articles', 'faq']);
+     */
+    async setIndexedCollections(collections: string[]): Promise<{ success: boolean }> {
+        const { data } = await this.http.post('/ai/config/collections', {
+            projectId: this.client.projectId,
+            collections
+        });
+        return data;
+    }
+
+    /**
+     * Busca configurações atuais de IA do projeto.
+     */
+    async getConfig(): Promise<{
+        indexedCollections: string[];
+        autoIndex: boolean;
+        embeddingModel: string;
+    }> {
+        const { data } = await this.http.get('/ai/config', {
+            params: { projectId: this.client.projectId }
+        });
+        return data;
+    }
+}