@allanfsouza/aether-sdk 2.4.10 → 2.5.0

package/dist/ai.js

@@ -0,0 +1,370 @@
+// 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
+// =============================================================================
+// MÓDULO PRINCIPAL
+// =============================================================================
+export class AIModule {
+    constructor(client, http) {
+        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, conversationId) {
+        return new Promise((resolve, reject) => {
+            let fullText = '';
+            let metadata = { 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, options = {}) {
+        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) {
+            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, type, comment) {
+        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, options = {}) {
+        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, data, options = {}) {
+        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, options) {
+        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, collection) {
+        const { data } = await this.http.post('/ai/parse-query', {
+            query: naturalLanguage,
+            collection,
+            projectId: this.client.projectId
+        });
+        return data;
+    }
+}
+// =============================================================================
+// SUB-MÓDULO: CONVERSAS
+// =============================================================================
+class ConversationsAPI {
+    constructor(client, http) {
+        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() {
+        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) {
+        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) {
+        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, title) {
+        const { data } = await this.http.patch(`/ai/conversations/${conversationId}`, {
+            title
+        });
+        return data;
+    }
+}
+// =============================================================================
+// SUB-MÓDULO: ADMIN
+// =============================================================================
+class AIAdminAPI {
+    constructor(client, http) {
+        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() {
+        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() {
+        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() {
+        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) {
+        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() {
+        const { data } = await this.http.get('/ai/config', {
+            params: { projectId: this.client.projectId }
+        });
+        return data;
+    }
+}

package/dist/index.d.ts

@@ -5,6 +5,7 @@ import { StorageModule } from "./storage.js";
 import { FunctionsModule } from "./functions.js";
 import { PushModule } from "./push.js";
 import { TenantAuthModule } from "./tenant-auth.js";
+import { AIModule } from "./ai.js";
 /**
  * Configuração usada para criar o cliente principal da plataforma.
  */
@@ -31,6 +32,7 @@ export declare class PlataformaClient {
     functions: FunctionsModule;
     push: PushModule;
     tenantAuth: TenantAuthModule;
+    ai: AIModule;
     database: DatabaseModule;
     apiUrl: string;
     projectId: string;
@@ -85,3 +87,4 @@ export type { LoginResponse, Session, User } from "./auth.js";
 export type { ListOptions } from "./database.js";
 export type { PushPlatform, PushEnvironment, PushDevice, RegisterDeviceParams, SendPushResponse, PushStatus, PushLogEntry, ListPushLogsOptions, PushStats, } from "./push.js";
 export type { TenantUser, TenantLoginResponse, TenantRegisterCredentials, TenantLoginCredentials, } from "./tenant-auth.js";
+export type { ChatOptions, ChatMetadata, AskResponse, Conversation, Message, FeedbackType, SemanticSearchOptions, SemanticSearchResult, GenerateOptions, RetrievedSource, } from "./ai.js";

package/dist/index.js

@@ -5,6 +5,7 @@ import { StorageModule } from "./storage.js";
 import { FunctionsModule } from "./functions.js";
 import { PushModule } from "./push.js";
 import { TenantAuthModule } from "./tenant-auth.js";
+import { AIModule } from "./ai.js";
 // =============================================================================
 // CONSTANTES DE STORAGE
 // Chaves padronizadas para localStorage - evita conflito com outros SDKs
@@ -48,6 +49,7 @@ export class PlataformaClient {
         this.functions = new FunctionsModule(this, this.http);
         this.push = new PushModule(this, this.http);
         this.tenantAuth = new TenantAuthModule(this, this.http);
+        this.ai = new AIModule(this, this.http);
         // Cria o alias que o Showcase App espera
         this.database = this.db;
     }

package/package.json

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