@allanfsouza/aether-sdk 2.5.0 → 2.5.1

package/README.md

@@ -129,6 +129,7 @@ await aether.push.sendToUser({
 ## 🤖 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](#-monetização-e-quotas).
 
 ### Chat Simples
 
@@ -218,6 +219,25 @@ await aether.ai.conversations.rename(conversationId, "Suporte Técnico");
 await aether.ai.conversations.delete(conversationId);
 ```
 
+### Memória de Usuário (Pro+)
+
+```typescript
+// 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
 
 ```typescript
@@ -226,10 +246,33 @@ await aether.ai.feedback(messageId, 'thumbs_up');
 await aether.ai.feedback(messageId, 'thumbs_down', 'Resposta incorreta');
 ```
 
+### Verificar Uso
+
+```typescript
+// 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
 
 ```typescript
-// Reindexar dados para RAG
+// 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
@@ -245,6 +288,46 @@ 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
+
+```typescript
+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:
@@ -288,7 +371,8 @@ import type {
   ChatOptions, ChatMetadata, AskResponse,
   Conversation, Message, FeedbackType,
   SemanticSearchOptions, SemanticSearchResult,
-  GenerateOptions, RetrievedSource
+  GenerateOptions, RetrievedSource,
+  UsageInfo, PersonaConfig
 } from '@allanfsouza/aether-sdk';
 ```
 

package/dist/ai.d.ts

@@ -102,11 +102,37 @@ export interface GenerateOptions {
     /** Contexto adicional para a geração */
     context?: string;
 }
+/**
+ * Informações de uso/quota
+ */
+export interface UsageInfo {
+    requestsUsed: number;
+    requestsLimit: number;
+    tokensUsed: number;
+    tokensLimit: number;
+    percentUsed: number;
+    plan: string;
+    resetsAt: string;
+}
+/**
+ * Configuração de persona
+ */
+export interface PersonaConfig {
+    name: string;
+    role: string;
+    personality?: string;
+    language?: string;
+    rules?: string[];
+    knowledge?: string[];
+    temperature?: number;
+}
 export declare class AIModule {
     private client;
     private http;
     /** Sub-módulo para gerenciar conversas */
     conversations: ConversationsAPI;
+    /** Sub-módulo para gerenciar memória de usuários */
+    memory: MemoryAPI;
     /** Sub-módulo para funções administrativas */
     admin: AIAdminAPI;
     constructor(client: PlataformaClient, http: AxiosInstance);
@@ -205,6 +231,14 @@ export declare class AIModule {
         filter?: Record<string, any>;
         sort?: Record<string, any>;
     }>;
+    /**
+     * Retorna informações de uso e quota.
+     *
+     * @example
+     * const usage = await aether.ai.getUsage();
+     * console.log(`${usage.percentUsed}% do limite usado`);
+     */
+    getUsage(): Promise<UsageInfo>;
 }
 declare class ConversationsAPI {
     private client;
@@ -241,6 +275,33 @@ declare class ConversationsAPI {
      */
     rename(conversationId: string, title: string): Promise<Conversation>;
 }
+declare class MemoryAPI {
+    private client;
+    private http;
+    constructor(client: PlataformaClient, http: AxiosInstance);
+    /**
+     * Busca memória de um usuário.
+     *
+     * @example
+     * const prefs = await aether.ai.memory.get("user-123", "preferences");
+     */
+    get(userId: string, key: string): Promise<any>;
+    /**
+     * Salva memória de um usuário.
+     *
+     * @example
+     * await aether.ai.memory.set("user-123", "preferences", { theme: "dark" });
+     */
+    set(userId: string, key: string, value: any): Promise<void>;
+    /**
+     * Deleta memória de um usuário.
+     */
+    delete(userId: string, key?: string): Promise<void>;
+    /**
+     * Lista todas as chaves de memória de um usuário.
+     */
+    listKeys(userId: string): Promise<string[]>;
+}
 declare class AIAdminAPI {
     private client;
     private http;
@@ -296,5 +357,21 @@ declare class AIAdminAPI {
         autoIndex: boolean;
         embeddingModel: string;
     }>;
+    /**
+     * Configura a persona da IA para o projeto.
+     *
+     * @example
+     * await aether.ai.admin.setPersona({
+     *   name: "Luna",
+     *   role: "Assistente de Vendas",
+     *   personality: "Amigável e usa emojis",
+     *   rules: ["Sempre sugira produtos relacionados"]
+     * });
+     */
+    setPersona(config: PersonaConfig): Promise<void>;
+    /**
+     * Busca a persona configurada.
+     */
+    getPersona(): Promise<PersonaConfig | null>;
 }
 export {};

package/dist/ai.js

@@ -10,6 +10,7 @@ export class AIModule {
         this.client = client;
         this.http = http;
         this.conversations = new ConversationsAPI(client, http);
+        this.memory = new MemoryAPI(client, http);
         this.admin = new AIAdminAPI(client, http);
     }
     // ===========================================================================
@@ -243,6 +244,22 @@ export class AIModule {
         });
         return data;
     }
+    // ===========================================================================
+    // INFORMAÇÕES DE USO
+    // ===========================================================================
+    /**
+     * Retorna informações de uso e quota.
+     *
+     * @example
+     * const usage = await aether.ai.getUsage();
+     * console.log(`${usage.percentUsed}% do limite usado`);
+     */
+    async getUsage() {
+        const { data } = await this.http.get('/ai/usage', {
+            params: { projectId: this.client.projectId }
+        });
+        return data;
+    }
 }
 // =============================================================================
 // SUB-MÓDULO: CONVERSAS
@@ -298,6 +315,69 @@ class ConversationsAPI {
     }
 }
 // =============================================================================
+// SUB-MÓDULO: MEMÓRIA DE USUÁRIO
+// =============================================================================
+class MemoryAPI {
+    constructor(client, http) {
+        this.client = client;
+        this.http = http;
+    }
+    /**
+     * Busca memória de um usuário.
+     *
+     * @example
+     * const prefs = await aether.ai.memory.get("user-123", "preferences");
+     */
+    async get(userId, key) {
+        const { data } = await this.http.get('/ai/memory', {
+            params: {
+                projectId: this.client.projectId,
+                userId,
+                key
+            }
+        });
+        return data.value;
+    }
+    /**
+     * Salva memória de um usuário.
+     *
+     * @example
+     * await aether.ai.memory.set("user-123", "preferences", { theme: "dark" });
+     */
+    async set(userId, key, value) {
+        await this.http.post('/ai/memory', {
+            projectId: this.client.projectId,
+            userId,
+            key,
+            value
+        });
+    }
+    /**
+     * Deleta memória de um usuário.
+     */
+    async delete(userId, key) {
+        await this.http.delete('/ai/memory', {
+            params: {
+                projectId: this.client.projectId,
+                userId,
+                key
+            }
+        });
+    }
+    /**
+     * Lista todas as chaves de memória de um usuário.
+     */
+    async listKeys(userId) {
+        const { data } = await this.http.get('/ai/memory/keys', {
+            params: {
+                projectId: this.client.projectId,
+                userId
+            }
+        });
+        return data.keys || [];
+    }
+}
+// =============================================================================
 // SUB-MÓDULO: ADMIN
 // =============================================================================
 class AIAdminAPI {
@@ -367,4 +447,30 @@ class AIAdminAPI {
         });
         return data;
     }
+    /**
+     * Configura a persona da IA para o projeto.
+     *
+     * @example
+     * await aether.ai.admin.setPersona({
+     *   name: "Luna",
+     *   role: "Assistente de Vendas",
+     *   personality: "Amigável e usa emojis",
+     *   rules: ["Sempre sugira produtos relacionados"]
+     * });
+     */
+    async setPersona(config) {
+        await this.http.post('/ai/persona', {
+            projectId: this.client.projectId,
+            ...config
+        });
+    }
+    /**
+     * Busca a persona configurada.
+     */
+    async getPersona() {
+        const { data } = await this.http.get('/ai/persona', {
+            params: { projectId: this.client.projectId }
+        });
+        return data.persona || null;
+    }
 }

package/dist/index.d.ts

@@ -87,4 +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";
+export type { ChatOptions, ChatMetadata, AskResponse, Conversation, Message, FeedbackType, SemanticSearchOptions, SemanticSearchResult, GenerateOptions, RetrievedSource, UsageInfo, PersonaConfig, } from "./ai.js";

package/package.json

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

package/src/ai.ts

@@ -132,6 +132,32 @@ export interface GenerateOptions {
     context?: string;
 }
 
+/**
+ * Informações de uso/quota
+ */
+export interface UsageInfo {
+    requestsUsed: number;
+    requestsLimit: number;
+    tokensUsed: number;
+    tokensLimit: number;
+    percentUsed: number;
+    plan: string;
+    resetsAt: string;
+}
+
+/**
+ * Configuração de persona
+ */
+export interface PersonaConfig {
+    name: string;
+    role: string;
+    personality?: string;
+    language?: string;
+    rules?: string[];
+    knowledge?: string[];
+    temperature?: number;
+}
+
 // =============================================================================
 // MÓDULO PRINCIPAL
 // =============================================================================
@@ -143,6 +169,9 @@ export class AIModule {
     /** Sub-módulo para gerenciar conversas */
     public conversations: ConversationsAPI;
 
+    /** Sub-módulo para gerenciar memória de usuários */
+    public memory: MemoryAPI;
+
     /** Sub-módulo para funções administrativas */
     public admin: AIAdminAPI;
 
@@ -150,6 +179,7 @@ export class AIModule {
         this.client = client;
         this.http = http;
         this.conversations = new ConversationsAPI(client, http);
+        this.memory = new MemoryAPI(client, http);
         this.admin = new AIAdminAPI(client, http);
     }
 
@@ -425,6 +455,24 @@ export class AIModule {
         });
         return data;
     }
+
+    // ===========================================================================
+    // INFORMAÇÕES DE USO
+    // ===========================================================================
+
+    /**
+     * Retorna informações de uso e quota.
+     * 
+     * @example
+     * const usage = await aether.ai.getUsage();
+     * console.log(`${usage.percentUsed}% do limite usado`);
+     */
+    async getUsage(): Promise<UsageInfo> {
+        const { data } = await this.http.get('/ai/usage', {
+            params: { projectId: this.client.projectId }
+        });
+        return data;
+    }
 }
 
 // =============================================================================
@@ -489,6 +537,78 @@ class ConversationsAPI {
     }
 }
 
+// =============================================================================
+// SUB-MÓDULO: MEMÓRIA DE USUÁRIO
+// =============================================================================
+
+class MemoryAPI {
+    private client: PlataformaClient;
+    private http: AxiosInstance;
+
+    constructor(client: PlataformaClient, http: AxiosInstance) {
+        this.client = client;
+        this.http = http;
+    }
+
+    /**
+     * Busca memória de um usuário.
+     * 
+     * @example
+     * const prefs = await aether.ai.memory.get("user-123", "preferences");
+     */
+    async get(userId: string, key: string): Promise<any> {
+        const { data } = await this.http.get('/ai/memory', {
+            params: {
+                projectId: this.client.projectId,
+                userId,
+                key
+            }
+        });
+        return data.value;
+    }
+
+    /**
+     * Salva memória de um usuário.
+     * 
+     * @example
+     * await aether.ai.memory.set("user-123", "preferences", { theme: "dark" });
+     */
+    async set(userId: string, key: string, value: any): Promise<void> {
+        await this.http.post('/ai/memory', {
+            projectId: this.client.projectId,
+            userId,
+            key,
+            value
+        });
+    }
+
+    /**
+     * Deleta memória de um usuário.
+     */
+    async delete(userId: string, key?: string): Promise<void> {
+        await this.http.delete('/ai/memory', {
+            params: {
+                projectId: this.client.projectId,
+                userId,
+                key
+            }
+        });
+    }
+
+    /**
+     * Lista todas as chaves de memória de um usuário.
+     */
+    async listKeys(userId: string): Promise<string[]> {
+        const { data } = await this.http.get('/ai/memory/keys', {
+            params: {
+                projectId: this.client.projectId,
+                userId
+            }
+        });
+        return data.keys || [];
+    }
+}
+
 // =============================================================================
 // SUB-MÓDULO: ADMIN
 // =============================================================================
@@ -577,4 +697,32 @@ class AIAdminAPI {
         });
         return data;
     }
+
+    /**
+     * Configura a persona da IA para o projeto.
+     * 
+     * @example
+     * await aether.ai.admin.setPersona({
+     *   name: "Luna",
+     *   role: "Assistente de Vendas",
+     *   personality: "Amigável e usa emojis",
+     *   rules: ["Sempre sugira produtos relacionados"]
+     * });
+     */
+    async setPersona(config: PersonaConfig): Promise<void> {
+        await this.http.post('/ai/persona', {
+            projectId: this.client.projectId,
+            ...config
+        });
+    }
+
+    /**
+     * Busca a persona configurada.
+     */
+    async getPersona(): Promise<PersonaConfig | null> {
+        const { data } = await this.http.get('/ai/persona', {
+            params: { projectId: this.client.projectId }
+        });
+        return data.persona || null;
+    }
 }

package/src/index.ts

@@ -273,4 +273,6 @@ export type {
   SemanticSearchResult,
   GenerateOptions,
   RetrievedSource,
+  UsageInfo,
+  PersonaConfig,
 } from "./ai.js";