🚀 Aether SDK

SDK oficial JavaScript/TypeScript para a plataforma Aether BaaS.

Instalação

npm install @allanfsouza/aether-sdk

Inicialização

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

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: '[email protected]' });

// Atualizar
await users.update('user-id', { name: 'Novo Nome' });

// Deletar
await users.delete('user-id');

Query Builder

const adults = await aether.db.collection('users')
  .query()
  .eq('status', 'active')
  .gt('age', 18)
  .order('name', 'ASC')
  .limit(50)
  .get();

🔐 Autenticação

// Login
const { accessToken, user } = await aether.auth.login('[email protected]', 'senha');

// Registro
await aether.auth.register({ name: 'João', email: '[email protected]', password: 'senha' });

// Logout
await aether.auth.logout();

// Sessão
const user = aether.auth.getCurrentUser();

📁 Storage

// 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

// Invocar função
const result = await aether.functions.invoke('send-email', {
  to: '[email protected]',
  subject: 'Olá!',
  body: 'Bem-vindo!'
});

📱 Push Notifications

// 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. Limites de uso são aplicados por plano - veja a seção de Monetização.

Chat Simples

// 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

// 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

// 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

// 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

// 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

// 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

// 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);

Memória de Usuário (Pro+)

// Salvar preferências do usuário
await aether.ai.memory.set("user-123", "preferences", { 
  theme: "dark", 
  language: "pt-BR" 
});

// Buscar memória
const prefs = await aether.ai.memory.get("user-123", "preferences");

// Listar chaves
const keys = await aether.ai.memory.listKeys("user-123");

// Deletar memória
await aether.ai.memory.delete("user-123", "preferences");

Feedback

// Enviar feedback sobre resposta
await aether.ai.feedback(messageId, 'thumbs_up');
await aether.ai.feedback(messageId, 'thumbs_down', 'Resposta incorreta');

Verificar Uso

// Retorna informações de quota
const usage = await aether.ai.getUsage();
console.log(`${usage.percentUsed}% do limite usado`);
console.log(`Requests: ${usage.requestsUsed}/${usage.requestsLimit}`);
console.log(`Tokens: ${usage.tokensUsed}/${usage.tokensLimit}`);
console.log(`Reset: ${usage.resetsAt}`);

Funções Administrativas

// Configurar persona da IA
await aether.ai.admin.setPersona({
  name: "Luna",
  role: "Assistente de Vendas",
  personality: "Amigável e usa emojis 🎉",
  rules: ["Sempre sugira produtos relacionados", "Responda em português"],
  temperature: 0.8
});

// Buscar persona
const persona = await aether.ai.admin.getPersona();

// Reindexa 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();

💰 Monetização e Quotas

O uso de IA é limitado por plano para controlar custos:

| Plano | Requests/mês | Tokens/mês | Features | |-------|--------------|------------|----------| | FREE | 100 | 50k | Chat, Search | | PRO | 10.000 | 2M | + Generate, Analyze, Memory, Persona | | BUSINESS | 100.000 | 20M | + Vision, Tudo liberado |

Quando o limite é atingido

try {
  await aether.ai.ask("Pergunta...");
} catch (error) {
  if (error.code === 'QUOTA_EXCEEDED') {
    console.log(error.usage.percentUsed); // 100
    console.log(error.upgradeUrl); // '/billing/upgrade'
  }
}

Features por plano

| Feature | Free | Pro | Business | |---------|:----:|:---:|:--------:| | Chat/Ask | ✅ | ✅ | ✅ | | Search | ✅ | ✅ | ✅ | | Streaming | ✅ | ✅ | ✅ | | Generate | ❌ | ✅ | ✅ | | Analyze | ❌ | ✅ | ✅ | | ParseQuery | ❌ | ✅ | ✅ | | Memory | ❌ | ✅ | ✅ | | Persona | ❌ | ✅ | ✅ | | Suggestions | ❌ | ✅ | ✅ | | Vision | ❌ | ❌ | ✅ |

👥 Tenant Auth

Para apps que precisam de sistema de login para usuários finais:

// Registro de usuário no projeto
const { user } = await aether.tenantAuth.signUp('project-id', {
  email: '[email protected]',
  password: 'senha123',
  name: 'Nome'
});

// Login
const { accessToken, user } = await aether.tenantAuth.signIn('project-id', {
  email: '[email protected]',
  password: 'senha123'
});

// Perfil
const profile = await aether.tenantAuth.getProfile();

// Logout
aether.tenantAuth.signOut();

📖 Tipos Exportados

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,
  UsageInfo, PersonaConfig
} from '@allanfsouza/aether-sdk';

📝 Licença

MIT © Allan Felipe de Souza