@allanfsouza/aether-sdk 2.4.11 → 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/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.11",
+  "version": "2.5.0",
   "description": "SDK do Cliente para a Plataforma Aether",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -7,6 +7,7 @@ import { StorageModule } from "./storage.js";
 import { FunctionsModule } from "./functions.js";
 import { PushModule } from "./push.js";
 import { TenantAuthModule, TenantUser, TenantLoginResponse, TenantRegisterCredentials, TenantLoginCredentials } from "./tenant-auth.js";
+import { AIModule } from "./ai.js";
 
 // =============================================================================
 // CONSTANTES DE STORAGE
@@ -59,6 +60,7 @@ export class PlataformaClient {
   public functions: FunctionsModule;
   public push: PushModule;
   public tenantAuth: TenantAuthModule;
+  public ai: AIModule;
 
   // Alias para 'db' que o showcase tenta usar como 'database'
   public database: DatabaseModule;
@@ -101,6 +103,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;
@@ -258,4 +261,16 @@ export type {
   TenantLoginResponse,
   TenantRegisterCredentials,
   TenantLoginCredentials,
-} from "./tenant-auth.js";
+} from "./tenant-auth.js";
+export type {
+  ChatOptions,
+  ChatMetadata,
+  AskResponse,
+  Conversation,
+  Message,
+  FeedbackType,
+  SemanticSearchOptions,
+  SemanticSearchResult,
+  GenerateOptions,
+  RetrievedSource,
+} from "./ai.js";