@allanfsouza/aether-sdk 2.4.10 → 2.5.0

package/README.md

@@ -1,9 +1,299 @@
-# Plataforma SDK (Cliente JS/TS)
+# 🚀 Aether SDK
 
-Este é o SDK oficial para interagir com a sua "Plataforma BaaS" (clone do Firebase). Ele gerencia autenticação, banco de dados genérico (com tempo real) e storage.
+SDK oficial JavaScript/TypeScript para a plataforma **Aether BaaS**.
+
+[![npm version](https://badge.fury.io/js/%40allanfsouza%2Faether-sdk.svg)](https://www.npmjs.com/package/@allanfsouza/aether-sdk)
 
 ## Instalação
 
 ```bash
-npm install @seu-username/plataforma-sdk
+npm install @allanfsouza/aether-sdk
+```
+
+## Inicialização
+
+```typescript
+import { PlataformaClient } from '@allanfsouza/aether-sdk';
+
+const aether = new PlataformaClient({
+  baseUrl: 'https://sua-api.aether.com',
+  apiKey: 'seu-project-id',
+  persistSession: true // Salva sessão no localStorage (padrão: true)
+});
+```
+
+---
+
+## 📦 Database
+
+```typescript
+const users = aether.db.collection('users');
+
+// Listar
+const list = await users.list({ limit: 10 });
+
+// Buscar por ID
+const user = await users.get('user-id');
+
+// Criar
+const newUser = await users.create({ name: 'João', email: 'joao@email.com' });
+
+// Atualizar
+await users.update('user-id', { name: 'Novo Nome' });
+
+// Deletar
+await users.delete('user-id');
+```
+
+### Query Builder
+
+```typescript
+const adults = await aether.db.collection('users')
+  .query()
+  .eq('status', 'active')
+  .gt('age', 18)
+  .order('name', 'ASC')
+  .limit(50)
+  .get();
+```
+
+---
+
+## 🔐 Autenticação
+
+```typescript
+// Login
+const { accessToken, user } = await aether.auth.login('email@test.com', 'senha');
+
+// Registro
+await aether.auth.register({ name: 'João', email: 'joao@email.com', password: 'senha' });
+
+// Logout
+await aether.auth.logout();
+
+// Sessão
+const user = aether.auth.getCurrentUser();
+```
+
+---
+
+## 📁 Storage
+
+```typescript
+// Upload
+const { data } = await aether.storage.upload(file, 'avatar.png', 'image/png');
+console.log(data.downloadUrl);
+
+// Listar
+const files = await aether.storage.list('folder');
+
+// Deletar
+await aether.storage.delete('file-id');
+```
+
+---
+
+## ⚡ Functions
+
+```typescript
+// Invocar função
+const result = await aether.functions.invoke('send-email', {
+  to: 'user@email.com',
+  subject: 'Olá!',
+  body: 'Bem-vindo!'
+});
 ```
+
+---
+
+## 📱 Push Notifications
+
+```typescript
+// Registrar dispositivo
+await aether.push.registerDevice({
+  token: 'fcm-token',
+  platform: 'android',
+  environment: 'prod'
+});
+
+// Enviar para usuário
+await aether.push.sendToUser({
+  userId: 'user-id',
+  title: 'Olá!',
+  body: 'Nova mensagem'
+});
+```
+
+---
+
+## 🤖 AI (Inteligência Artificial)
+
+O módulo de IA permite adicionar capacidades de linguagem natural aos seus apps.
+
+### Chat Simples
+
+```typescript
+// Pergunta simples (aguarda resposta completa)
+const { text, conversationId } = await aether.ai.ask("Quais produtos estão em promoção?");
+console.log(text);
+```
+
+### Chat com Streaming
+
+```typescript
+// Resposta em tempo real (chunk por chunk)
+await aether.ai.chat("Explique como funciona o sistema de pagamentos", {
+  conversationId: 'conv-id-opcional', // Mantém contexto
+  onChunk: (chunk) => {
+    // Atualiza UI em tempo real
+    setResponse(prev => prev + chunk);
+  },
+  onComplete: (fullResponse, meta) => {
+    console.log("Conversa:", meta.conversationId);
+  },
+  onError: (error) => {
+    console.error(error);
+  }
+});
+```
+
+### Busca Semântica
+
+```typescript
+// Encontra documentos similares usando embeddings
+const results = await aether.ai.search("tênis confortável para corrida", {
+  collection: "products", // Opcional: filtrar por collection
+  limit: 10,
+  minScore: 0.7
+});
+
+results.forEach(r => console.log(r.content, r.similarity));
+```
+
+### Geração de Conteúdo
+
+```typescript
+// Gera texto baseado em dados e prompt
+const descricao = await aether.ai.generate(
+  "Escreva uma descrição para o produto",
+  { name: "iPhone 15", price: 5999, features: ["5G", "48MP"] },
+  { tone: 'friendly', length: 'medium', language: 'pt-BR' }
+);
+```
+
+### Análise de Dados
+
+```typescript
+// Analisa dados e retorna insights em linguagem natural
+const { insights, data } = await aether.ai.analyze("orders", {
+  question: "Como foram as vendas essa semana?",
+  period: "7d"
+});
+console.log(insights);
+```
+
+### Conversão de Linguagem Natural para Query
+
+```typescript
+// Converte texto em filtros estruturados
+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' } }
+```
+
+### Gerenciar Conversas
+
+```typescript
+// Listar conversas
+const conversas = await aether.ai.conversations.list();
+
+// Histórico de mensagens
+const mensagens = await aether.ai.conversations.getMessages(conversationId);
+
+// Renomear conversa
+await aether.ai.conversations.rename(conversationId, "Suporte Técnico");
+
+// Deletar conversa
+await aether.ai.conversations.delete(conversationId);
+```
+
+### Feedback
+
+```typescript
+// Enviar feedback sobre resposta
+await aether.ai.feedback(messageId, 'thumbs_up');
+await aether.ai.feedback(messageId, 'thumbs_down', 'Resposta incorreta');
+```
+
+### Funções Administrativas
+
+```typescript
+// Reindexar dados para RAG
+await aether.ai.admin.reindex();
+
+// Estatísticas de uso
+const stats = await aether.ai.admin.stats();
+console.log(stats.totalConversations, stats.totalMessages);
+
+// Configurar collections indexadas
+await aether.ai.admin.setIndexedCollections(['products', 'articles', 'faq']);
+
+// Limpar embeddings (CUIDADO!)
+await aether.ai.admin.clear();
+```
+
+---
+
+## 👥 Tenant Auth
+
+Para apps que precisam de sistema de login para usuários finais:
+
+```typescript
+// Registro de usuário no projeto
+const { user } = await aether.tenantAuth.signUp('project-id', {
+  email: 'usuario@app.com',
+  password: 'senha123',
+  name: 'Nome'
+});
+
+// Login
+const { accessToken, user } = await aether.tenantAuth.signIn('project-id', {
+  email: 'usuario@app.com',
+  password: 'senha123'
+});
+
+// Perfil
+const profile = await aether.tenantAuth.getProfile();
+
+// Logout
+aether.tenantAuth.signOut();
+```
+
+---
+
+## 📖 Tipos Exportados
+
+```typescript
+import type {
+  // Auth
+  LoginResponse, Session, User,
+  // Database
+  ListOptions,
+  // Push
+  PushDevice, PushStatus, PushStats,
+  // Tenant
+  TenantUser, TenantLoginResponse,
+  // AI
+  ChatOptions, ChatMetadata, AskResponse,
+  Conversation, Message, FeedbackType,
+  SemanticSearchOptions, SemanticSearchResult,
+  GenerateOptions, RetrievedSource
+} from '@allanfsouza/aether-sdk';
+```
+
+---
+
+## 📝 Licença
+
+MIT © Allan Felipe de Souza

package/dist/ai.d.ts

@@ -0,0 +1,300 @@
+import type { AxiosInstance } from "axios";
+import type { PlataformaClient } from "./index.js";
+/**
+ * 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;
+}
+export declare class AIModule {
+    private client;
+    private http;
+    /** Sub-módulo para gerenciar conversas */
+    conversations: ConversationsAPI;
+    /** Sub-módulo para funções administrativas */
+    admin: AIAdminAPI;
+    constructor(client: PlataformaClient, http: AxiosInstance);
+    /**
+     * 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);
+     */
+    ask(message: string, conversationId?: string): Promise<AskResponse>;
+    /**
+     * 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);
+     *   }
+     * });
+     */
+    chat(message: string, options?: ChatOptions): Promise<void>;
+    /**
+     * 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');
+     */
+    feedback(messageId: string, type: FeedbackType, comment?: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * 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
+     * });
+     */
+    search(query: string, options?: SemanticSearchOptions): Promise<SemanticSearchResult[]>;
+    /**
+     * 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' }
+     * );
+     */
+    generate(prompt: string, data: Record<string, any>, options?: GenerateOptions): Promise<string>;
+    /**
+     * 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"
+     * });
+     */
+    analyze(collection: string, options: {
+        question: string;
+        period?: string;
+    }): Promise<{
+        insights: string;
+        data?: any;
+    }>;
+    /**
+     * 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' } }
+     */
+    parseQuery(naturalLanguage: string, collection?: string): Promise<{
+        filter?: Record<string, any>;
+        sort?: Record<string, any>;
+    }>;
+}
+declare class ConversationsAPI {
+    private client;
+    private http;
+    constructor(client: PlataformaClient, http: AxiosInstance);
+    /**
+     * Lista todas as conversas do usuário no projeto.
+     *
+     * @example
+     * const conversas = await aether.ai.conversations.list();
+     */
+    list(): Promise<Conversation[]>;
+    /**
+     * Busca o histórico de mensagens de uma conversa.
+     *
+     * @example
+     * const mensagens = await aether.ai.conversations.getMessages(conversationId);
+     */
+    getMessages(conversationId: string): Promise<Message[]>;
+    /**
+     * Deleta uma conversa e todo seu histórico.
+     *
+     * @example
+     * await aether.ai.conversations.delete(conversationId);
+     */
+    delete(conversationId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Renomeia uma conversa.
+     *
+     * @example
+     * await aether.ai.conversations.rename(conversationId, "Suporte Técnico");
+     */
+    rename(conversationId: string, title: string): Promise<Conversation>;
+}
+declare class AIAdminAPI {
+    private client;
+    private http;
+    constructor(client: PlataformaClient, http: AxiosInstance);
+    /**
+     * 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();
+     */
+    reindex(): Promise<{
+        message: string;
+    }>;
+    /**
+     * Limpa todos os embeddings do projeto.
+     * CUIDADO: A IA "esquece" todo o contexto aprendido.
+     *
+     * @example
+     * const { deletedCount } = await aether.ai.admin.clear();
+     */
+    clear(): Promise<{
+        deletedCount: number;
+    }>;
+    /**
+     * Retorna estatísticas de uso da IA.
+     *
+     * @example
+     * const stats = await aether.ai.admin.stats();
+     * console.log(stats.totalConversations, stats.totalMessages);
+     */
+    stats(): Promise<{
+        totalConversations: number;
+        totalMessages: number;
+        totalEmbeddings: number;
+        storageUsedMB: number;
+    }>;
+    /**
+     * Configura quais collections são indexadas automaticamente.
+     *
+     * @example
+     * await aether.ai.admin.setIndexedCollections(['products', 'articles', 'faq']);
+     */
+    setIndexedCollections(collections: string[]): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Busca configurações atuais de IA do projeto.
+     */
+    getConfig(): Promise<{
+        indexedCollections: string[];
+        autoIndex: boolean;
+        embeddingModel: string;
+    }>;
+}
+export {};