mitra-interactions-sdk 1.0.64 → 1.0.66

package/README.md

@@ -1,698 +1,769 @@
-# Mitra Interactions SDK
-
-SDK para interações com a plataforma Mitra via endpoints `/interactions/`.
-
-## Permissões: `dev` vs `business`
-
-`userType` no token de login:
-- `dev` — chama tudo
-- `business` — chama apenas execução (SF, Data Loader, upload), auth e chat. Outras chamadas retornam **403**.
-
-> Não confundir com o pacote `mitra-business-sdk` (SDK separado, usado pelo agente IA).
-
-**Bloqueado para `business`:** CRUD REST (`*RecordMitra`), Profile Management (`*ProfileMitra`, `setProfile*Mitra`), `listProjectUsersMitra`, `manageUserAccessMitra`.
-
-> SF tipo JAVASCRIPT herda o `userType` do caller — se chamar funções bloqueadas, retorna 403 para business.
-
----
-
-## Instalação
-
-```bash
-npm install mitra-interactions-sdk
-# ou
-yarn add mitra-interactions-sdk
-# ou
-pnpm add mitra-interactions-sdk
-```
-
-## Configuração
-
-Antes de usar qualquer função, configure o SDK. O `token` é **opcional** — Server Functions públicas podem ser chamadas sem autenticação.
-
-> **Importante:** Quando usado, o token é um JWT de autenticação da plataforma Mitra. **Nunca deixe o token estático no código.** Utilize variáveis de ambiente para armazená-lo de forma segura.
-
-```typescript
-import { configureSdkMitra } from 'mitra-interactions-sdk';
-
-// Configuração completa (com autenticação)
-const instance = configureSdkMitra({
-  baseURL: process.env.MITRA_BASE_URL || 'https://api.mitra.com',
-  token: process.env.MITRA_TOKEN!,                       // Opcional — necessário apenas para endpoints autenticados
-  authUrl: 'https://coder.mitralab.io/sdk-auth/',       // Opcional — necessário para login e token refresh
-  projectId: 123,                                        // Opcional — se informado, torna projectId opcional em TODOS os métodos
-  integrationURL: 'https://api0.mitraecp.com:1003',     // Opcional — necessário para integrações
-  onTokenRefresh: (session) => {                         // Opcional — chamado quando o token é renovado automaticamente
-    localStorage.setItem('mitra_session', JSON.stringify(session));
-  }
-});
-
-// Configuração mínima (sem token — apenas para Server Functions públicas)
-const instance = configureSdkMitra({
-  baseURL: 'https://api.mitra.com',
-  projectId: 123
-});
-await instance.executeServerFunction({ serverFunctionId: 42 }); // OK — sem token
-```
-
-> **`projectId` global:** Se você passar `projectId` no `configureSdkMitra`, ele será usado como fallback em **todos** os métodos do SDK. Assim, não é necessário passar `projectId` em cada chamada individual — basta configurar uma vez.
-
-`configureSdkMitra` retorna uma `MitraInstance` que também pode ser usada diretamente:
-
-```typescript
-await instance.executeServerFunction({ serverFunctionId: 42 });  // projectId já vem do configureSdkMitra
-```
-
-## Autenticação (Login)
-
-Login via popup ou redirect seguro hospedado no domínio Mitra. Credenciais nunca passam pelo código do desenvolvedor. O SDK é **auto-configurado** após o login.
-
-> **Nota:** `authUrl` e `projectId` são **obrigatórios** para login. Porém, se já foram passados no `configureSdkMitra()`, não é necessário repeti-los — o SDK usa os valores configurados como fallback.
-
-### Login via Popup (padrão)
-
-```typescript
-import { loginMitra } from 'mitra-interactions-sdk';
-
-// Métodos disponíveis: 'email', 'google', 'microsoft', 'mitra'
-// Primeira vez — sem configureSdkMitra: authUrl e projectId são obrigatórios
-const result = await loginMitra('email', {
-  authUrl: 'https://coder.mitralab.io/sdk-auth/',
-  projectId: 123
-});
-
-// Se já chamou configureSdkMitra({ authUrl, projectId }), basta:
-const result = await loginMitra('google');
-const result = await loginMitra('microsoft');
-
-// result: { token, baseURL, integrationURL? }
-```
-
-### Login Completo (method 'mitra')
-
-Abre uma tela com todas as opções (Google, Microsoft, Email) e toggle entre Login/Cadastro.
-
-```typescript
-await loginMitra('mitra', {
-  authUrl: 'https://coder.mitralab.io/sdk-auth/',
-  projectId: 123,
-  title: 'Meu App'   // Opcional — título exibido na tela de login (default: "Mitra")
-});
-```
-
-### Login via Redirect
-
-Navega o usuário para a página de auth. Após o login, redireciona de volta com token nos query params.
-
-```typescript
-import { loginMitra } from 'mitra-interactions-sdk';
-
-// Iniciar login — o navegador navega para fora da página
-await loginMitra('google', {
-  mode: 'redirect',
-  returnTo: '/dashboard'   // Opcional — URL de retorno após login (default: página atual). Só funciona com mode 'redirect'.
-});
-```
-
-### Fluxo de Criar Conta
-
-```typescript
-// create funciona tanto em popup quanto redirect
-await loginMitra('email', { create: true });
-
-await loginMitra('mitra', {
-  mode: 'redirect',
-  create: true,        // Abre direto no modo cadastro
-  returnTo: '/onboarding',
-  title: 'Meu App'
-});
-```
-
-### Token Refresh Automático
-
-Quando qualquer requisição retorna **403**, o SDK tenta renovar o token automaticamente via iframe invisível (usa o cookie de sessão do provider). Se o refresh funcionar, a requisição é retentada com o novo token — transparente para o desenvolvedor.
-
-O callback `onTokenRefresh` é chamado após renovação bem-sucedida:
-
-```typescript
-configureSdkMitra({
-  baseURL: '...',
-  token: '...',
-  authUrl: 'https://coder.mitralab.io/sdk-auth/',
-  projectId: 123,
-  onTokenRefresh: (session) => {
-    // Atualiza o token salvo (ex: localStorage, store, etc.)
-    localStorage.setItem('mitra_token', session.token);
-  }
-});
-```
-
-### Login por Email (iframe silencioso)
-
-Para quem precisa montar sua **própria tela de login** (sem popup/redirect), o SDK oferece funções que fazem a autenticação via iframe invisível. As credenciais são enviadas ao HTML de auth via `postMessage` — sem CORS, sem expor a API.
-
-#### emailSignupMitra
-
-Cria conta. Após sucesso, o usuário recebe um código de verificação por email.
-
-```typescript
-import { emailSignupMitra } from 'mitra-interactions-sdk';
-
-await emailSignupMitra({
-  name: 'João Silva',
-  email: 'joao@email.com',
-  password: 'minhasenha123'
-});
-// Não retorna token — o próximo passo é verificar o código
-```
-
-#### emailVerifyCodeMitra
-
-Verifica o código de 6 dígitos e faz login automático. Retorna `LoginResponse` e auto-configura o SDK.
-
-```typescript
-import { emailVerifyCodeMitra } from 'mitra-interactions-sdk';
-
-const session = await emailVerifyCodeMitra({
-  email: 'joao@email.com',
-  code: '123456',
-  password: 'minhasenha123'   // Necessário para login automático após verificação
-});
-// session: { token, baseURL, integrationURL? }
-```
-
-#### emailResendCodeMitra
-
-Reenvia o código de verificação para o email.
-
-```typescript
-import { emailResendCodeMitra } from 'mitra-interactions-sdk';
-
-await emailResendCodeMitra({ email: 'joao@email.com' });
-```
-
-#### emailLoginMitra
-
-Login direto com email e senha. Retorna `LoginResponse` e auto-configura o SDK.
-
-```typescript
-import { emailLoginMitra } from 'mitra-interactions-sdk';
-
-const session = await emailLoginMitra({
-  email: 'joao@email.com',
-  password: 'minhasenha123'
-});
-// session: { token, baseURL, integrationURL? }
-```
-
-#### Fluxo completo de signup com email
-
-```typescript
-// 1. Criar conta
-await emailSignupMitra({ name: 'João', email, password });
-
-// 2. Usuário recebe código por email e digita na tela
-const session = await emailVerifyCodeMitra({ email, code: '123456', password });
-
-// 3. SDK já está configurado — pode chamar qualquer método
-await executeDbActionMitra({ dbActionId: 1 });
-```
-
-> **Nota:** `authUrl` e `projectId` são opcionais em todas as funções de email se já foram configurados via `configureSdkMitra()`.
-
-### Reset de Senha (esqueci minha senha)
-
-Endpoints públicos (sem token) para o fluxo de "esqueci minha senha":
-
-```typescript
-import {
-  sendPasswordResetCodeMitra,
-  validatePasswordResetCodeMitra,
-  resetPasswordMitra,
-  emailLoginMitra
-} from 'mitra-interactions-sdk';
-
-// 1. Envia código de 6 dígitos por email
-await sendPasswordResetCodeMitra({ email });
-
-// 2. (opcional) Valida o código antes de pedir a senha nova
-await validatePasswordResetCodeMitra({ email, code: '123456' });
-
-// 3. Troca a senha
-await resetPasswordMitra({ email, code: '123456', newPassword: 'novaSenha' });
-
-// 4. Login com a nova senha
-await emailLoginMitra({ email, password: 'novaSenha' });
-```
-
-> **Nota:** `projectId` é opcional se já configurado via `configureSdkMitra()`.
-
-## Métodos Disponíveis
-
-### executeServerFunctionMitra
-
-Executa uma Server Function de forma **síncrona** (timeout de 60s no backend). Retorna o resultado diretamente.
-
-```typescript
-import { executeServerFunctionMitra } from 'mitra-interactions-sdk';
-
-const result = await executeServerFunctionMitra({
-  projectId: 123,
-  serverFunctionId: 101,
-  input: {           // Opcional - objeto de entrada para a função
-    arg1: 'valor1'
-  }
-});
-// result: { status, result: { executionId, executionStatus, output, logs, error, durationMs } }
-```
-
-### executeServerFunctionAsyncMitra
-
-Executa uma Server Function de forma **assíncrona**. Retorna um `executionId` imediatamente. Use `stopServerFunctionExecutionMitra` para parar ou `getServerFunctionExecutionMitra` (mitra-sdk) para consultar o resultado.
-
-```typescript
-import { executeServerFunctionAsyncMitra } from 'mitra-interactions-sdk';
-
-const result = await executeServerFunctionAsyncMitra({
-  projectId: 123,
-  serverFunctionId: 101,
-  input: {           // Opcional - objeto de entrada para a função
-    arg1: 'valor1'
-  }
-});
-// result: { status, result: { executionId, executionStatus } }
-```
-
-### stopServerFunctionExecutionMitra
-
-Para a execução de uma Server Function em andamento.
-
-```typescript
-import { stopServerFunctionExecutionMitra } from 'mitra-interactions-sdk';
-
-const result = await stopServerFunctionExecutionMitra({
-  projectId: 123,
-  executionId: 'exec-uuid-aqui'
-});
-// result: { status, result: { executionId, executionStatus: "CANCELLED" | "ALREADY_FINISHED" } }
-```
-
-### Public Server Functions (sem autenticação)
-
-Para Server Functions com `publicExecution = true`. Não requerem token.
-
-```typescript
-import {
-  executePublicServerFunctionMitra,
-  executePublicServerFunctionAsyncMitra,
-  getPublicServerFunctionExecutionMitra
-} from 'mitra-interactions-sdk';
-
-// Sync — retorna resultado inline (timeout 5min)
-const result = await executePublicServerFunctionMitra({
-  projectId: 123,
-  serverFunctionId: 49,
-  input: { param1: 'value' }
-});
-// result: { executionId, status, output, logs, error, durationMs }
-
-// Async — retorna executionId imediatamente
-const { executionId } = await executePublicServerFunctionAsyncMitra({
-  projectId: 123,
-  serverFunctionId: 50,
-  input: { heavyParam: true }
-});
-
-// Polling — consulta status/resultado
-const execution = await getPublicServerFunctionExecutionMitra({
-  projectId: 123,
-  executionId
-});
-// execution: { executionId, status, output, logs, error, durationMs }
-```
-
-### executeDataLoaderMitra
-
-Executa um Data Loader cadastrado no projeto.
-
-```typescript
-import { executeDataLoaderMitra } from 'mitra-interactions-sdk';
-
-const result = await executeDataLoaderMitra({
-  projectId: 123,
-  dataLoaderId: 5,
-  input: { mes: 1, ano: 2025 }   // Opcional — parâmetros {{var}} da query
-});
-// result: { status, result: { dataLoaderId, executionLog: { timestamp, rowCount, query, status, fileSize?, duration? }, message } }
-```
-
-### uploadFilePublicMitra / uploadFileLoadableMitra
-
-Faz upload de um arquivo diretamente para a pasta PUBLIC ou LOADABLE do projeto. Usa `multipart/form-data`.
-
-```typescript
-import { uploadFilePublicMitra, uploadFileLoadableMitra } from 'mitra-interactions-sdk';
-
-// Upload para PUBLIC (arquivo fica acessível publicamente via URL)
-const result = await uploadFilePublicMitra({
-  projectId: 123,
-  file: fileInput.files[0]   // File ou Blob
-});
-// result: { status, result: { fileName, currentPath, publicUrl, message } }
-
-// Upload para LOADABLE (arquivo disponível para carga via Spark/ETL)
-const result2 = await uploadFileLoadableMitra({
-  projectId: 123,
-  file: myBlob
-});
-// result2: { status, result: { fileName, currentPath, publicUrl: null, message } }
-```
-
-### Dynamic Schema CRUD
-
-> 🔒 `userType=dev` only. Falha 403 para business. Em telas com business, envelopar em SF tipo SQL.
-
-CRUD completo em tabelas do projeto via Dynamic Schema (usa header `X-TenantID`).
-
-Todos os endpoints suportam o parâmetro opcional `jdbcConnectionConfigId` para operar em datasources adicionais (PostgreSQL, Oracle, SQL Server, etc.) ao invés do banco principal do tenant.
-
-- `listRecordsMitra(...)` → `ListRecordsResponse` `{ content, page, size, totalElements, totalPages }` - Lista registros com paginação
-- `getRecordMitra(...)` → `Record<string, any>` - Busca registro por ID
-- `createRecordMitra(...)` → `Record<string, any>` - Cria registro (201)
-- `updateRecordMitra(...)` → `Record<string, any>` - Atualiza registro (PUT)
-- `patchRecordMitra(...)` → `Record<string, any>` - Atualiza parcialmente (PATCH)
-- `deleteRecordMitra(...)` → `void` - Remove registro (204 No Content)
-- `createRecordsBatchMitra(...)` → `Record<string, any>[]` - Cria múltiplos registros (201)
-
-```typescript
-import { listRecordsMitra, createRecordMitra, updateRecordMitra, deleteRecordMitra } from 'mitra-interactions-sdk';
-
-// Listar registros
-const result = await listRecordsMitra({
-  projectId: 123,
-  tableName: 'produtos',
-  page: 0,
-  size: 20
-});
-
-// Criar registro
-await createRecordMitra({
-  projectId: 123,
-  tableName: 'produtos',
-  data: { nome: 'Produto A', preco: 99.90 }
-});
-
-// Atualizar registro
-await updateRecordMitra({
-  projectId: 123,
-  tableName: 'produtos',
-  id: 1,
-  data: { nome: 'Produto A Atualizado', preco: 89.90, version: 0 }
-});
-
-// Deletar registro
-await deleteRecordMitra({ projectId: 123, tableName: 'produtos', id: 1 });
-
-// Usando datasource adicional (jdbcConnectionConfigId)
-const result2 = await listRecordsMitra({
-  projectId: 123,
-  tableName: 'clientes',
-  jdbcConnectionConfigId: 5
-});
-```
-
-### Profile Management
-
-> 🔒 `userType=dev` only. Falha 403 para business. Telas de perfis exigem guard de `userType`.
-
-Gerenciamento de perfis de acesso. Permite gestão de quem pode acessar quais recursos no projeto.
-
-#### CRUD de Perfis
-
-- `listProfilesMitra({ projectId? })` → `ListProfilesResponse` - Lista todos os perfis do projeto
-- `getProfileDetailsMitra({ projectId?, profileId })` → `GetProfileDetailsResponse` - Detalhes de um perfil (usuários, tabelas, actions, screens, server functions)
-- `createProfileMitra({ projectId?, name, color?, homeScreenId? })` → `CreateProfileResponse` - Cria um novo perfil
-- `updateProfileMitra({ projectId?, profileId, name?, color?, homeScreenId? })` → `UpdateProfileResponse` - Atualiza um perfil existente
-- `deleteProfileMitra({ projectId?, profileId })` → `DeleteProfileResponse` - Deleta um perfil
-
-```typescript
-import { listProfilesMitra, createProfileMitra, getProfileDetailsMitra } from 'mitra-interactions-sdk';
-
-// Listar perfis
-const profiles = await listProfilesMitra({ projectId: 123 });
-// { status, projectId, result: [{ id, name, color, homeScreenId }] }
-
-// Criar perfil
-const created = await createProfileMitra({ projectId: 123, name: 'Vendedores', color: '#FF5733' });
-// { status, result: { id, name, message } }
-
-// Detalhes do perfil
-const details = await getProfileDetailsMitra({ projectId: 123, profileId: 1 });
-// { status, projectId, result: { id, name, users, selectTables, dmlTables, actions, screens, serverFunctions } }
-```
-
-#### Permissões de Perfil
-
-Define quais recursos cada perfil pode acessar. Todas substituem a lista atual (não fazem append).
-
-- `setProfileUsersMitra({ projectId?, profileId, userIds })` - Define os usuários do perfil
-- `setProfileSelectTablesMitra({ projectId?, profileId, jdbcConnectionConfigId?, tables })` - Define tabelas SELECT permitidas
-- `setProfileDmlTablesMitra({ projectId?, profileId, jdbcConnectionConfigId?, tables })` - Define tabelas DML permitidas
-- `setProfileActionsMitra({ projectId?, profileId, actionIds })` - Define actions permitidas
-- `setProfileScreensMitra({ projectId?, profileId, screenIds })` - Define screens permitidas
-- `setProfileServerFunctionsMitra({ projectId?, profileId, serverFunctionIds })` - Define server functions permitidas
-
-```typescript
-import { setProfileUsersMitra, setProfileSelectTablesMitra, setProfileServerFunctionsMitra } from 'mitra-interactions-sdk';
-
-// Definir usuários do perfil
-await setProfileUsersMitra({ projectId: 123, profileId: 1, userIds: [10, 20, 30] });
-
-// Definir tabelas SELECT
-await setProfileSelectTablesMitra({
-  projectId: 123,
-  profileId: 1,
-  jdbcConnectionConfigId: 1,   // Opcional — ID da conexão JDBC (default: banco principal)
-  tables: [
-    { tableName: 'clientes' },
-    { tableName: 'pedidos' }
-  ]
-});
-
-// Definir server functions
-await setProfileServerFunctionsMitra({ projectId: 123, profileId: 1, serverFunctionIds: [5, 8, 12] });
-```
-
-## Agent Chat (embedded)
-
-Chat com o agente de IA embarcado, sobre um WebSocket compartilhado (`/sdk-ws`). Uma única conexão atende todas as sessions — o roteamento de eventos é feito por `taskId`.
-
-> ⚙️ Requisitos: roda **apenas em apps publicadas pela plataforma Mitra** (o build-proxy injeta `window.__mitraEnv.agentWsUrl`) e precisa de `token` configurado (faça login antes ou passe em `configureSdkMitra`).
-
-### Gerenciar os chats — `manageAgentChatMitra`
-
-Operações stateless sobre a coleção de chats do usuário: listar, renomear, deletar.
-
-```typescript
-import { manageAgentChatMitra } from 'mitra-interactions-sdk';
-
-const chats  = await manageAgentChatMitra({ action: 'list' });                       // AgentChat[]
-const renamed = await manageAgentChatMitra({ action: 'rename', taskId, name: 'Novo nome' });
-const deleted = await manageAgentChatMitra({ action: 'delete', taskId });
-```
-
-- `action: 'list'` → `AgentChat[]` — `{ id, name, agentType?, provider?, createdAt, updatedAt }`. Aceita `projectId?` pra sobrescrever o global.
-- `action: 'rename'` → `{ taskId, name }`
-- `action: 'delete'` → `{ taskId, deleted }`
-
-### Abrir uma session — `getAgentTaskMitra`
-
-Retorna uma `AgentTaskSession` que encapsula todo o ciclo de vida de um chat (histórico, streaming, fila, cancel, eventos). Abrir a mesma `taskId` duas vezes devolve a **mesma** instância (cache).
-
-```typescript
-import { getAgentTaskMitra } from 'mitra-interactions-sdk';
-
-// Chat novo — taskId é preenchido depois do primeiro send()
-const session = getAgentTaskMitra({ create: true, agentType: 'claudecode', modelId: 'openai/gpt-5.5:medium' });
-
-// Chat existente — detecta automaticamente se já há stream ativo
-const existing = getAgentTaskMitra({ taskId: 'abc123' });
-await existing.loadHistory({ limit: 50 });
-```
-
-`getAgentTaskMitra({ create: true, projectId?, agentType?, modelId?, name? })` ou `getAgentTaskMitra({ taskId })`.
-
-#### Propriedades (somente leitura)
-
-| Propriedade | Tipo | Descrição |
-|-------------|------|-----------|
-| `taskId` | `string \| null` | `null` até o primeiro `send()` num chat novo |
-| `task` | `AgentChat \| null` | Metadados do chat após criado |
-| `isNew` | `boolean` | Se foi aberto via `{ create: true }` |
-| `status` | `AgentTaskStatus` | `opening` · `idle` · `uploading` · `streaming` · `cancelled` · `error` · `closed` |
-| `history` | `AgentMessage[]` | Histórico carregado |
-| `content` | `string` | Conteúdo acumulado do turno atual |
-| `queue` | `QueuedItem[]` | Mensagens enfileiradas (enviadas enquanto streamava) |
-
-#### Métodos
-
-- `send(prompt, options?)` → `void` — dispara um turno. Se já está streamando, **enfileira** (FIFO, máx 10). `options`: `{ agentType?, modelId?, files? }`.
-- `cancel()` → `Promise<void>` — cancela o turno atual; resolve quando o backend confirma (ou safety net de 30s).
-- `loadHistory({ limit? })` → `Promise<AgentMessage[]>` — carrega o histórico do chat.
-- `editQueueItem(id, text)` / `removeQueueItem(id)` / `clearQueue()` — manipulam a fila.
-- `on(event, handler)` → função de unsubscribe — assina eventos da session.
-- `close()` — encerra a session e libera os listeners.
-
-#### Eventos (`session.on`)
-
-`statusChange` · `historyLoaded` · `taskCreated` · `turnStart` · `delta` · `tool` · `turnEnd` · `cancelled` · `queueChange` · `error`.
-
-```typescript
-const session = getAgentTaskMitra({ create: true });
-
-session.on('delta', ({ delta, kind }) => process.stdout.write(delta)); // kind: 'text' | 'tool'
-session.on('tool',  ({ tool, input }) => console.log('🔧', tool));
-session.on('turnEnd', ({ content }) => console.log('\n✓ fim do turno'));
-session.on('taskCreated', ({ task }) => console.log('chat criado:', task.id));
-session.on('error', ({ error }) => console.error(error));
-
-session.send('Analise estas vendas e gere um resumo');
-```
-
-#### Anexos e seleção de modelo
-
-```typescript
-// Anexos: passe os File crus (drop/input). A SDK sobe cada um (URL pública),
-// detecta o tipo e monta os anexos. Status vai pra 'uploading'; falha sai no evento 'error'.
-session.send('O que tem nesta planilha?', { files: [xlsxFile, pngFile] });
-
-// Modelo por turno (sobrescreve o default da session)
-session.send('Refaça com mais detalhes', { modelId: 'subscription:anthropic:claude-opus-4-7' });
-```
-
-### Credenciais do agente — `manageAgentCredentialMitra`
-
-Função única (sobre `/sdk-ws`) para API keys (8 providers: `anthropic`, `openai`, `gemini`, `kimi`, `minimax`, `glm`, `qwen`, `openrouter`) e subscriptions OAuth (Claude paste-código / OpenAI device flow via Codex).
-
-> 🔒 Segurança: o token de subscription **nunca volta cru** pro cliente — fica server-side e é injetado no sandbox direto de lá.
-
-```typescript
-import { manageAgentCredentialMitra } from 'mitra-interactions-sdk';
-
-// Listar providers + status (pra montar a UI de conexão)
-const { providers } = await manageAgentCredentialMitra({ action: 'list_providers' });
-
-// Listar modelos disponíveis (só dos providers com credencial) → use o modelId em send()/getAgentTaskMitra
-const { providers: groups } = await manageAgentCredentialMitra({ action: 'list_models' });
-
-// API key
-await manageAgentCredentialMitra({ action: 'validate', target: 'openai', key: 'sk-...' });
-await manageAgentCredentialMitra({ action: 'save', target: 'glm', key: '...' });
-await manageAgentCredentialMitra({ action: 'remove', target: 'anthropic' });
-```
-
-Subscriptions (alto nível, sem redirect/callback page) — `auth` inicia e retorna o que mostrar; `connect` finaliza:
-
-```typescript
-// Claude — abra a authUrl, colete o código que a Anthropic mostra
-const { authUrl, state } = await manageAgentCredentialMitra({ action: 'auth', target: 'claude' });
-await manageAgentCredentialMitra({ action: 'connect', target: 'claude', code, state });
-
-// Codex (OpenAI device flow) — mostre verificationUrl + userCode; a SDK faz o polling
-const { verificationUrl, userCode, pollId } = await manageAgentCredentialMitra({ action: 'auth', target: 'codex' });
-await manageAgentCredentialMitra({ action: 'connect', target: 'codex', pollId });
-```
-
-## Tipos TypeScript
-
-Todos os tipos estão incluídos:
-
-```typescript
-import type {
-  MitraConfig,
-  // Login
-  LoginOptions,
-  LoginResponse,
-  // Email Auth
-  EmailSignupOptions,
-  EmailLoginOptions,
-  EmailVerifyCodeOptions,
-  EmailResendCodeOptions,
-  // Options
-  ExecuteServerFunctionOptions,
-  ExecuteServerFunctionAsyncOptions,
-  UploadFileOptions,
-  StopServerFunctionExecutionOptions,
-  ListRecordsOptions,
-  GetRecordOptions,
-  CreateRecordOptions,
-  UpdateRecordOptions,
-  PatchRecordOptions,
-  DeleteRecordOptions,
-  CreateRecordsBatchOptions,
-  // Responses
-  ExecuteServerFunctionResponse,
-  ExecuteServerFunctionAsyncResponse,
-  UploadFileResponse,
-  StopServerFunctionExecutionResponse,
-  ListRecordsResponse,
-  // Profile Management
-  ListProfilesOptions,
-  ListProfilesResponse,
-  GetProfileDetailsOptions,
-  GetProfileDetailsResponse,
-  CreateProfileOptions,
-  CreateProfileResponse,
-  UpdateProfileOptions,
-  UpdateProfileResponse,
-  DeleteProfileOptions,
-  DeleteProfileResponse,
-  SetProfileUsersOptions,
-  SetProfileSelectTablesOptions,
-  SetProfileDmlTablesOptions,
-  SetProfileActionsOptions,
-  SetProfileScreensOptions,
-  SetProfileServerFunctionsOptions,
-  ProfileTableRef,
-  SetProfilePermissionResponse,
-  // Agent Chat
-  AgentChat,
-  AgentMessage,
-  AgentType,
-  AgentTaskSession,
-  AgentTaskStatus,
-  AgentTaskEventMap,
-  AgentAttachment,
-  QueuedItem,
-  SendOptions,
-  GetAgentTaskOptions,
-  ManageAgentChatOptions,
-  // Agent Credentials
-  CredentialTarget,
-  CredentialAction,
-  ManageAgentCredentialOptions,
-  AuthAgentCredentialOptions,
-  ConnectAgentCredentialOptions,
-  ListAgentModelsResult,
-  ListAgentProvidersResult
-} from 'mitra-interactions-sdk';
-```
-
-## Tratamento de Erros
-
-```typescript
-try {
-  const result = await executeDbActionMitra({
-    projectId: 123,
-    dbActionId: 456
-  });
-} catch (error) {
-  console.log('Erro:', error.message);
-  console.log('Status:', error.status);
-  console.log('Detalhes:', error.details);
-}
-```
-
-## Licença
-
-MIT
+# Mitra Interactions SDK
+
+SDK para interações com a plataforma Mitra via endpoints `/interactions/`.
+
+## Permissões: `dev` vs `business`
+
+`userType` no token de login:
+- `dev` — chama tudo
+- `business` — chama apenas execução (SF, Data Loader, upload), auth e chat. Outras chamadas retornam **403**.
+
+> Não confundir com o pacote `mitra-business-sdk` (SDK separado, usado pelo agente IA).
+
+**Bloqueado para `business`:** CRUD REST (`*RecordMitra`), Profile Management (`*ProfileMitra`, `setProfile*Mitra`), `listProjectUsersMitra`, `manageUserAccessMitra`.
+
+> SF tipo JAVASCRIPT herda o `userType` do caller — se chamar funções bloqueadas, retorna 403 para business.
+
+---
+
+## Instalação
+
+```bash
+npm install mitra-interactions-sdk
+# ou
+yarn add mitra-interactions-sdk
+# ou
+pnpm add mitra-interactions-sdk
+```
+
+## Configuração
+
+Antes de usar qualquer função, configure o SDK. O `token` é **opcional** — Server Functions públicas podem ser chamadas sem autenticação.
+
+> **Importante:** Quando usado, o token é um JWT de autenticação da plataforma Mitra. **Nunca deixe o token estático no código.** Utilize variáveis de ambiente para armazená-lo de forma segura.
+
+```typescript
+import { configureSdkMitra } from 'mitra-interactions-sdk';
+
+// Configuração completa (com autenticação)
+const instance = configureSdkMitra({
+  baseURL: process.env.MITRA_BASE_URL || 'https://api.mitra.com',
+  token: process.env.MITRA_TOKEN!,                       // Opcional — necessário apenas para endpoints autenticados
+  authUrl: 'https://coder.mitralab.io/sdk-auth/',       // Opcional — necessário para login e token refresh
+  projectId: 123,                                        // Opcional — se informado, torna projectId opcional em TODOS os métodos
+  integrationURL: 'https://api0.mitraecp.com:1003',     // Opcional — necessário para integrações
+  onTokenRefresh: (session) => {                         // Opcional — chamado quando o token é renovado automaticamente
+    localStorage.setItem('mitra_session', JSON.stringify(session));
+  }
+});
+
+// Configuração mínima (sem token — apenas para Server Functions públicas)
+const instance = configureSdkMitra({
+  baseURL: 'https://api.mitra.com',
+  projectId: 123
+});
+await instance.executeServerFunction({ serverFunctionId: 42 }); // OK — sem token
+```
+
+> **`projectId` global:** Se você passar `projectId` no `configureSdkMitra`, ele será usado como fallback em **todos** os métodos do SDK. Assim, não é necessário passar `projectId` em cada chamada individual — basta configurar uma vez.
+
+`configureSdkMitra` retorna uma `MitraInstance` que também pode ser usada diretamente:
+
+```typescript
+await instance.executeServerFunction({ serverFunctionId: 42 });  // projectId já vem do configureSdkMitra
+```
+
+## Autenticação (Login)
+
+Login via popup ou redirect seguro hospedado no domínio Mitra. Credenciais nunca passam pelo código do desenvolvedor. O SDK é **auto-configurado** após o login.
+
+> **Nota:** `authUrl` e `projectId` são **obrigatórios** para login. Porém, se já foram passados no `configureSdkMitra()`, não é necessário repeti-los — o SDK usa os valores configurados como fallback.
+
+### Login via Popup (padrão)
+
+```typescript
+import { loginMitra } from 'mitra-interactions-sdk';
+
+// Métodos disponíveis: 'email', 'google', 'microsoft', 'mitra'
+// Primeira vez — sem configureSdkMitra: authUrl e projectId são obrigatórios
+const result = await loginMitra('email', {
+  authUrl: 'https://coder.mitralab.io/sdk-auth/',
+  projectId: 123
+});
+
+// Se já chamou configureSdkMitra({ authUrl, projectId }), basta:
+const result = await loginMitra('google');
+const result = await loginMitra('microsoft');
+
+// result: { token, baseURL, integrationURL? }
+```
+
+### Login Completo (method 'mitra')
+
+Abre uma tela com todas as opções (Google, Microsoft, Email) e toggle entre Login/Cadastro.
+
+```typescript
+await loginMitra('mitra', {
+  authUrl: 'https://coder.mitralab.io/sdk-auth/',
+  projectId: 123,
+  title: 'Meu App'   // Opcional — título exibido na tela de login (default: "Mitra")
+});
+```
+
+### Login via Redirect
+
+Navega o usuário para a página de auth. Após o login, redireciona de volta com token nos query params.
+
+```typescript
+import { loginMitra } from 'mitra-interactions-sdk';
+
+// Iniciar login — o navegador navega para fora da página
+await loginMitra('google', {
+  mode: 'redirect',
+  returnTo: '/dashboard'   // Opcional — URL de retorno após login (default: página atual). Só funciona com mode 'redirect'.
+});
+```
+
+### Fluxo de Criar Conta
+
+```typescript
+// create funciona tanto em popup quanto redirect
+await loginMitra('email', { create: true });
+
+await loginMitra('mitra', {
+  mode: 'redirect',
+  create: true,        // Abre direto no modo cadastro
+  returnTo: '/onboarding',
+  title: 'Meu App'
+});
+```
+
+### Token Refresh Automático
+
+Quando qualquer requisição retorna **403**, o SDK tenta renovar o token automaticamente via iframe invisível (usa o cookie de sessão do provider). Se o refresh funcionar, a requisição é retentada com o novo token — transparente para o desenvolvedor.
+
+O callback `onTokenRefresh` é chamado após renovação bem-sucedida:
+
+```typescript
+configureSdkMitra({
+  baseURL: '...',
+  token: '...',
+  authUrl: 'https://coder.mitralab.io/sdk-auth/',
+  projectId: 123,
+  onTokenRefresh: (session) => {
+    // Atualiza o token salvo (ex: localStorage, store, etc.)
+    localStorage.setItem('mitra_token', session.token);
+  }
+});
+```
+
+### Login por Email (iframe silencioso)
+
+Para quem precisa montar sua **própria tela de login** (sem popup/redirect), o SDK oferece funções que fazem a autenticação via iframe invisível. As credenciais são enviadas ao HTML de auth via `postMessage` — sem CORS, sem expor a API.
+
+#### emailSignupMitra
+
+Cria conta. Após sucesso, o usuário recebe um código de verificação por email.
+
+```typescript
+import { emailSignupMitra } from 'mitra-interactions-sdk';
+
+await emailSignupMitra({
+  name: 'João Silva',
+  email: 'joao@email.com',
+  password: 'minhasenha123'
+});
+// Não retorna token — o próximo passo é verificar o código
+```
+
+#### emailVerifyCodeMitra
+
+Verifica o código de 6 dígitos e faz login automático. Retorna `LoginResponse` e auto-configura o SDK.
+
+```typescript
+import { emailVerifyCodeMitra } from 'mitra-interactions-sdk';
+
+const session = await emailVerifyCodeMitra({
+  email: 'joao@email.com',
+  code: '123456',
+  password: 'minhasenha123'   // Necessário para login automático após verificação
+});
+// session: { token, baseURL, integrationURL? }
+```
+
+#### emailResendCodeMitra
+
+Reenvia o código de verificação para o email.
+
+```typescript
+import { emailResendCodeMitra } from 'mitra-interactions-sdk';
+
+await emailResendCodeMitra({ email: 'joao@email.com' });
+```
+
+#### emailLoginMitra
+
+Login direto com email e senha. Retorna `LoginResponse` e auto-configura o SDK.
+
+```typescript
+import { emailLoginMitra } from 'mitra-interactions-sdk';
+
+const session = await emailLoginMitra({
+  email: 'joao@email.com',
+  password: 'minhasenha123'
+});
+// session: { token, baseURL, integrationURL? }
+```
+
+#### Fluxo completo de signup com email
+
+```typescript
+// 1. Criar conta
+await emailSignupMitra({ name: 'João', email, password });
+
+// 2. Usuário recebe código por email e digita na tela
+const session = await emailVerifyCodeMitra({ email, code: '123456', password });
+
+// 3. SDK já está configurado — pode chamar qualquer método
+await executeDbActionMitra({ dbActionId: 1 });
+```
+
+> **Nota:** `authUrl` e `projectId` são opcionais em todas as funções de email se já foram configurados via `configureSdkMitra()`.
+
+### Reset de Senha (esqueci minha senha)
+
+Endpoints públicos (sem token) para o fluxo de "esqueci minha senha":
+
+```typescript
+import {
+  sendPasswordResetCodeMitra,
+  validatePasswordResetCodeMitra,
+  resetPasswordMitra,
+  emailLoginMitra
+} from 'mitra-interactions-sdk';
+
+// 1. Envia código de 6 dígitos por email
+await sendPasswordResetCodeMitra({ email });
+
+// 2. (opcional) Valida o código antes de pedir a senha nova
+await validatePasswordResetCodeMitra({ email, code: '123456' });
+
+// 3. Troca a senha
+await resetPasswordMitra({ email, code: '123456', newPassword: 'novaSenha' });
+
+// 4. Login com a nova senha
+await emailLoginMitra({ email, password: 'novaSenha' });
+```
+
+> **Nota:** `projectId` é opcional se já configurado via `configureSdkMitra()`.
+
+## Métodos Disponíveis
+
+### executeServerFunctionMitra
+
+Executa uma Server Function de forma **síncrona** (timeout de 60s no backend). Retorna o resultado diretamente.
+
+```typescript
+import { executeServerFunctionMitra } from 'mitra-interactions-sdk';
+
+const result = await executeServerFunctionMitra({
+  projectId: 123,
+  serverFunctionId: 101,
+  input: {           // Opcional - objeto de entrada para a função
+    arg1: 'valor1'
+  }
+});
+// result: { status, result: { executionId, executionStatus, output, logs, error, durationMs } }
+```
+
+### executeServerFunctionAsyncMitra
+
+Executa uma Server Function de forma **assíncrona**. Retorna um `executionId` imediatamente. Use `stopServerFunctionExecutionMitra` para parar ou `getServerFunctionExecutionMitra` (mitra-sdk) para consultar o resultado.
+
+```typescript
+import { executeServerFunctionAsyncMitra } from 'mitra-interactions-sdk';
+
+const result = await executeServerFunctionAsyncMitra({
+  projectId: 123,
+  serverFunctionId: 101,
+  input: {           // Opcional - objeto de entrada para a função
+    arg1: 'valor1'
+  }
+});
+// result: { status, result: { executionId, executionStatus } }
+```
+
+### stopServerFunctionExecutionMitra
+
+Para a execução de uma Server Function em andamento.
+
+```typescript
+import { stopServerFunctionExecutionMitra } from 'mitra-interactions-sdk';
+
+const result = await stopServerFunctionExecutionMitra({
+  projectId: 123,
+  executionId: 'exec-uuid-aqui'
+});
+// result: { status, result: { executionId, executionStatus: "CANCELLED" | "ALREADY_FINISHED" } }
+```
+
+### Public Server Functions (sem autenticação)
+
+Para Server Functions com `publicExecution = true`. Não requerem token.
+
+```typescript
+import {
+  executePublicServerFunctionMitra,
+  executePublicServerFunctionAsyncMitra,
+  getPublicServerFunctionExecutionMitra
+} from 'mitra-interactions-sdk';
+
+// Sync — retorna resultado inline (timeout 5min)
+const result = await executePublicServerFunctionMitra({
+  projectId: 123,
+  serverFunctionId: 49,
+  input: { param1: 'value' }
+});
+// result: { executionId, status, output, logs, error, durationMs }
+
+// Async — retorna executionId imediatamente
+const { executionId } = await executePublicServerFunctionAsyncMitra({
+  projectId: 123,
+  serverFunctionId: 50,
+  input: { heavyParam: true }
+});
+
+// Polling — consulta status/resultado
+const execution = await getPublicServerFunctionExecutionMitra({
+  projectId: 123,
+  executionId
+});
+// execution: { executionId, status, output, logs, error, durationMs }
+```
+
+### executeDataLoaderMitra
+
+Executa um Data Loader cadastrado no projeto.
+
+```typescript
+import { executeDataLoaderMitra } from 'mitra-interactions-sdk';
+
+const result = await executeDataLoaderMitra({
+  projectId: 123,
+  dataLoaderId: 5,
+  input: { mes: 1, ano: 2025 }   // Opcional — parâmetros {{var}} da query
+});
+// result: { status, result: { dataLoaderId, executionLog: { timestamp, rowCount, query, status, fileSize?, duration? }, message } }
+```
+
+### uploadFilePrivateMitra / uploadFilePublicMitra / uploadFileLoadableMitra
+
+Faz upload de um arquivo diretamente para a pasta PRIVATE, PUBLIC ou LOADABLE do projeto. Usa `multipart/form-data`.
+
+> 🔒 **Privado é o padrão.** `uploadFilePrivateMitra` guarda o arquivo em bucket sem leitura pública, com chave aleatória; o acesso é sempre autenticado e autorizado pela aplicação. `uploadFilePublicMitra` cria uma URL permanente e irreversível — só para conteúdo que precisa abrir sem sessão (logo, imagem em e-mail, tela pública), nunca para dado de cliente.
+
+```typescript
+import { uploadFilePrivateMitra, uploadFilePublicMitra, uploadFileLoadableMitra } from 'mitra-interactions-sdk';
+
+// Upload PRIVADO (recomendado): o arquivo não fica público; publicUrl vem null.
+const priv = await uploadFilePrivateMitra({
+  projectId: 123,
+  file: fileInput.files[0]   // File ou Blob
+});
+// priv: { status, result: { fileName, currentPath, key, publicUrl: null, message } }
+// key = ai-files/private/{24 chars aleatórios}/nome — guarde na linha do registro dono.
+// Quem lê é a Server Function, depois de validar o registro (ver "Anexos privados — o padrão").
+
+// Upload para PUBLIC (arquivo fica acessível publicamente via URL)
+const result = await uploadFilePublicMitra({
+  projectId: 123,
+  file: fileInput.files[0]   // File ou Blob
+});
+// result: { status, result: { fileName, currentPath, key, publicUrl, message } }
+// No PUBLIC, `currentPath` é a URL completa; `key` é a chave relativa (ai-files/public/...).
+
+// Upload para LOADABLE (arquivo disponível para carga via Spark/ETL)
+const result2 = await uploadFileLoadableMitra({
+  projectId: 123,
+  file: myBlob
+});
+// result2: { status, result: { fileName, currentPath, publicUrl: null, message } }
+```
+
+### Anexos privados — o padrão (contrato TKT-000a0394)
+
+A plataforma só sabe "esta pessoa pertence a este projeto". Quem sabe "o anexo X é da solicitação Y,
+que é do usuário Z" é a aplicação. Por isso o acesso a um arquivo privado **pela chave** é restrito
+a usuário DEV do projeto ou a uma Server Function em execução; **a tela de usuário final nunca manda
+a chave** — ela pede o anexo **pelo registro** a uma SF, que confere a regra e devolve um link
+temporário.
+
+```typescript
+import { uploadFilePrivateMitra, executeServerFunctionMitra } from 'mitra-interactions-sdk';
+
+// 1) Tela de formulário: sobe privado e guarda a CHAVE na linha do registro
+const up = await uploadFilePrivateMitra({ projectId: 123, file: fileInput.files[0] });
+const key = up.result.key;   // ai-files/private/{24 chars aleatórios}/comprovante.pdf
+await executeServerFunctionMitra({ projectId: 123, serverFunctionId: SF_SALVAR_SOLICITACAO,
+  input: { descricao, anexoKey: key } });
+
+// 2) Tela que exibe: pede pelo REGISTRO, nunca pela chave
+const res = await executeServerFunctionMitra({ projectId: 123, serverFunctionId: SF_ANEXO_DA_SOLICITACAO,
+  input: { solicitacaoId: 482 } });
+// a SF conferiu que o usuário pode ver a solicitação 482 e devolveu { url, expiresAt } (link de ~5 min)
+window.open(res.result.output.url);
+```
+
+Do lado da SF (backend), depois da regra de negócio, a chave vira link temporário via
+`GET {MITRA_BASE_URL}/agentAiShortcut/fileLink?projectId&key&ttlSeconds` — exemplos completos em
+`mitraapi/docs/SERVER_FUNCTIONS_API.md`, seção "Arquivos privados a partir de uma Server Function".
+
+**Regras**
+
+- **`key` só é aceita dentro das pastas do projeto** (`ai-files/private/`, `ai-files/public/`, `ai-files/loadable/`). Chave iniciada em `tenant_` ou `/`, com `..` ou terminada em `/` é recusada (HTTP 400 `INVALID_KEY`). É isso que isola um projeto do outro.
+- **A chave privada tem um segmento aleatório** de 24 caracteres: não é adivinhável e dois uploads com o mesmo nome não se sobrescrevem. Guarde-a como qualquer outra coluna do registro.
+- **Privado fica em bucket próprio, sem URL pública.** Público é permanente e irreversível; nunca é o lugar de dado de cliente.
+- **Todo acesso é registrado** (`INT_FILEACCESSLOG` do tenant): quem baixou, gerou link ou excluiu, e quando.
+
+### downloadFilePrivateMitra / getFileLinkMitra / deleteFileMitra (DEV e Server Function)
+
+Acesso **pela chave**. Permissão: usuário **DEV** do projeto (sem API key BUSINESS) ou **Server
+Function em execução**. Usuário final recebe HTTP 403 `ACCESS_DENIED` — para ele, use o padrão acima.
+
+```typescript
+import { downloadFilePrivateMitra, getFileLinkMitra, deleteFileMitra } from 'mitra-interactions-sdk';
+
+// Download autenticado — retorna Blob
+const blob = await downloadFilePrivateMitra({ projectId: 123, key });
+
+// Link temporário (assinado); padrão 300 s, máximo definido no backend
+const link = await getFileLinkMitra({ projectId: 123, key, ttlSeconds: 300 });
+// link.result: { key, url, expiresAt, expiresInSeconds }
+
+// Exclusão — apaga exatamente esse objeto
+const del = await deleteFileMitra({ projectId: 123, key });
+// erros: 400 INVALID_KEY | 403 ACCESS_DENIED | 404 FILE_NOT_FOUND
+```
+
+- O delete nunca apaga por prefixo/pasta, e chave inexistente devolve `FILE_NOT_FOUND`.
+- Quando o registro é apagado, apague o anexo dele na mesma SF — senão sobra documento de cliente
+  sem nada apontando para ele.
+
+### Dynamic Schema CRUD
+
+> 🔒 `userType=dev` only. Falha 403 para business. Em telas com business, envelopar em SF tipo SQL.
+
+CRUD completo em tabelas do projeto via Dynamic Schema (usa header `X-TenantID`).
+
+Todos os endpoints suportam o parâmetro opcional `jdbcConnectionConfigId` para operar em datasources adicionais (PostgreSQL, Oracle, SQL Server, etc.) ao invés do banco principal do tenant.
+
+- `listRecordsMitra(...)` → `ListRecordsResponse` `{ content, page, size, totalElements, totalPages }` - Lista registros com paginação
+- `getRecordMitra(...)` → `Record<string, any>` - Busca registro por ID
+- `createRecordMitra(...)` → `Record<string, any>` - Cria registro (201)
+- `updateRecordMitra(...)` → `Record<string, any>` - Atualiza registro (PUT)
+- `patchRecordMitra(...)` → `Record<string, any>` - Atualiza parcialmente (PATCH)
+- `deleteRecordMitra(...)` → `void` - Remove registro (204 No Content)
+- `createRecordsBatchMitra(...)` → `Record<string, any>[]` - Cria múltiplos registros (201)
+
+```typescript
+import { listRecordsMitra, createRecordMitra, updateRecordMitra, deleteRecordMitra } from 'mitra-interactions-sdk';
+
+// Listar registros
+const result = await listRecordsMitra({
+  projectId: 123,
+  tableName: 'produtos',
+  page: 0,
+  size: 20
+});
+
+// Criar registro
+await createRecordMitra({
+  projectId: 123,
+  tableName: 'produtos',
+  data: { nome: 'Produto A', preco: 99.90 }
+});
+
+// Atualizar registro
+await updateRecordMitra({
+  projectId: 123,
+  tableName: 'produtos',
+  id: 1,
+  data: { nome: 'Produto A Atualizado', preco: 89.90, version: 0 }
+});
+
+// Deletar registro
+await deleteRecordMitra({ projectId: 123, tableName: 'produtos', id: 1 });
+
+// Usando datasource adicional (jdbcConnectionConfigId)
+const result2 = await listRecordsMitra({
+  projectId: 123,
+  tableName: 'clientes',
+  jdbcConnectionConfigId: 5
+});
+```
+
+### Profile Management
+
+> 🔒 `userType=dev` only. Falha 403 para business. Telas de perfis exigem guard de `userType`.
+
+Gerenciamento de perfis de acesso. Permite gestão de quem pode acessar quais recursos no projeto.
+
+#### CRUD de Perfis
+
+- `listProfilesMitra({ projectId? })` → `ListProfilesResponse` - Lista todos os perfis do projeto
+- `getProfileDetailsMitra({ projectId?, profileId })` → `GetProfileDetailsResponse` - Detalhes de um perfil (usuários, tabelas, actions, screens, server functions)
+- `createProfileMitra({ projectId?, name, color?, homeScreenId? })` → `CreateProfileResponse` - Cria um novo perfil
+- `updateProfileMitra({ projectId?, profileId, name?, color?, homeScreenId? })` → `UpdateProfileResponse` - Atualiza um perfil existente
+- `deleteProfileMitra({ projectId?, profileId })` → `DeleteProfileResponse` - Deleta um perfil
+
+```typescript
+import { listProfilesMitra, createProfileMitra, getProfileDetailsMitra } from 'mitra-interactions-sdk';
+
+// Listar perfis
+const profiles = await listProfilesMitra({ projectId: 123 });
+// { status, projectId, result: [{ id, name, color, homeScreenId }] }
+
+// Criar perfil
+const created = await createProfileMitra({ projectId: 123, name: 'Vendedores', color: '#FF5733' });
+// { status, result: { id, name, message } }
+
+// Detalhes do perfil
+const details = await getProfileDetailsMitra({ projectId: 123, profileId: 1 });
+// { status, projectId, result: { id, name, users, selectTables, dmlTables, actions, screens, serverFunctions } }
+```
+
+#### Permissões de Perfil
+
+Define quais recursos cada perfil pode acessar. Todas substituem a lista atual (não fazem append).
+
+- `setProfileUsersMitra({ projectId?, profileId, userIds })` - Define os usuários do perfil
+- `setProfileSelectTablesMitra({ projectId?, profileId, jdbcConnectionConfigId?, tables })` - Define tabelas SELECT permitidas
+- `setProfileDmlTablesMitra({ projectId?, profileId, jdbcConnectionConfigId?, tables })` - Define tabelas DML permitidas
+- `setProfileActionsMitra({ projectId?, profileId, actionIds })` - Define actions permitidas
+- `setProfileScreensMitra({ projectId?, profileId, screenIds })` - Define screens permitidas
+- `setProfileServerFunctionsMitra({ projectId?, profileId, serverFunctionIds })` - Define server functions permitidas
+
+```typescript
+import { setProfileUsersMitra, setProfileSelectTablesMitra, setProfileServerFunctionsMitra } from 'mitra-interactions-sdk';
+
+// Definir usuários do perfil
+await setProfileUsersMitra({ projectId: 123, profileId: 1, userIds: [10, 20, 30] });
+
+// Definir tabelas SELECT
+await setProfileSelectTablesMitra({
+  projectId: 123,
+  profileId: 1,
+  jdbcConnectionConfigId: 1,   // Opcional — ID da conexão JDBC (default: banco principal)
+  tables: [
+    { tableName: 'clientes' },
+    { tableName: 'pedidos' }
+  ]
+});
+
+// Definir server functions
+await setProfileServerFunctionsMitra({ projectId: 123, profileId: 1, serverFunctionIds: [5, 8, 12] });
+```
+
+## Agent Chat (embedded)
+
+Chat com o agente de IA embarcado, sobre um WebSocket compartilhado (`/sdk-ws`). Uma única conexão atende todas as sessions — o roteamento de eventos é feito por `taskId`.
+
+> ⚙️ Requisitos: roda **apenas em apps publicadas pela plataforma Mitra** (o build-proxy injeta `window.__mitraEnv.agentWsUrl`) e precisa de `token` configurado (faça login antes ou passe em `configureSdkMitra`).
+
+### Gerenciar os chats — `manageAgentChatMitra`
+
+Operações stateless sobre a coleção de chats do usuário: listar, renomear, deletar.
+
+```typescript
+import { manageAgentChatMitra } from 'mitra-interactions-sdk';
+
+const chats  = await manageAgentChatMitra({ action: 'list' });                       // AgentChat[]
+const renamed = await manageAgentChatMitra({ action: 'rename', taskId, name: 'Novo nome' });
+const deleted = await manageAgentChatMitra({ action: 'delete', taskId });
+```
+
+- `action: 'list'` → `AgentChat[]` — `{ id, name, agentType?, provider?, createdAt, updatedAt }`. Aceita `projectId?` pra sobrescrever o global.
+- `action: 'rename'` → `{ taskId, name }`
+- `action: 'delete'` → `{ taskId, deleted }`
+
+### Abrir uma session — `getAgentTaskMitra`
+
+Retorna uma `AgentTaskSession` que encapsula todo o ciclo de vida de um chat (histórico, streaming, fila, cancel, eventos). Abrir a mesma `taskId` duas vezes devolve a **mesma** instância (cache).
+
+```typescript
+import { getAgentTaskMitra } from 'mitra-interactions-sdk';
+
+// Chat novo — taskId é preenchido depois do primeiro send()
+const session = getAgentTaskMitra({ create: true, agentType: 'claudecode', modelId: 'openai/gpt-5.5:medium' });
+
+// Chat existente — detecta automaticamente se já há stream ativo
+const existing = getAgentTaskMitra({ taskId: 'abc123' });
+await existing.loadHistory({ limit: 50 });
+```
+
+`getAgentTaskMitra({ create: true, projectId?, agentType?, modelId?, name? })` ou `getAgentTaskMitra({ taskId })`.
+
+#### Propriedades (somente leitura)
+
+| Propriedade | Tipo | Descrição |
+|-------------|------|-----------|
+| `taskId` | `string \| null` | `null` até o primeiro `send()` num chat novo |
+| `task` | `AgentChat \| null` | Metadados do chat após criado |
+| `isNew` | `boolean` | Se foi aberto via `{ create: true }` |
+| `status` | `AgentTaskStatus` | `opening` · `idle` · `uploading` · `streaming` · `cancelled` · `error` · `closed` |
+| `history` | `AgentMessage[]` | Histórico carregado |
+| `content` | `string` | Conteúdo acumulado do turno atual |
+| `queue` | `QueuedItem[]` | Mensagens enfileiradas (enviadas enquanto streamava) |
+
+#### Métodos
+
+- `send(prompt, options?)` → `void` — dispara um turno. Se já está streamando, **enfileira** (FIFO, máx 10). `options`: `{ agentType?, modelId?, files? }`.
+- `cancel()` → `Promise<void>` — cancela o turno atual; resolve quando o backend confirma (ou safety net de 30s).
+- `loadHistory({ limit? })` → `Promise<AgentMessage[]>` — carrega o histórico do chat.
+- `editQueueItem(id, text)` / `removeQueueItem(id)` / `clearQueue()` — manipulam a fila.
+- `on(event, handler)` → função de unsubscribe — assina eventos da session.
+- `close()` — encerra a session e libera os listeners.
+
+#### Eventos (`session.on`)
+
+`statusChange` · `historyLoaded` · `taskCreated` · `turnStart` · `delta` · `tool` · `turnEnd` · `cancelled` · `queueChange` · `error`.
+
+```typescript
+const session = getAgentTaskMitra({ create: true });
+
+session.on('delta', ({ delta, kind }) => process.stdout.write(delta)); // kind: 'text' | 'tool'
+session.on('tool',  ({ tool, input }) => console.log('🔧', tool));
+session.on('turnEnd', ({ content }) => console.log('\n✓ fim do turno'));
+session.on('taskCreated', ({ task }) => console.log('chat criado:', task.id));
+session.on('error', ({ error }) => console.error(error));
+
+session.send('Analise estas vendas e gere um resumo');
+```
+
+#### Anexos e seleção de modelo
+
+```typescript
+// Anexos: passe os File crus (drop/input). A SDK sobe cada um (URL pública),
+// detecta o tipo e monta os anexos. Status vai pra 'uploading'; falha sai no evento 'error'.
+session.send('O que tem nesta planilha?', { files: [xlsxFile, pngFile] });
+
+// Modelo por turno (sobrescreve o default da session)
+session.send('Refaça com mais detalhes', { modelId: 'subscription:anthropic:claude-opus-4-7' });
+```
+
+### Credenciais do agente — `manageAgentCredentialMitra`
+
+Função única (sobre `/sdk-ws`) para API keys (8 providers: `anthropic`, `openai`, `gemini`, `kimi`, `minimax`, `glm`, `qwen`, `openrouter`) e subscriptions OAuth (Claude paste-código / OpenAI device flow via Codex).
+
+> 🔒 Segurança: o token de subscription **nunca volta cru** pro cliente — fica server-side e é injetado no sandbox direto de lá.
+
+```typescript
+import { manageAgentCredentialMitra } from 'mitra-interactions-sdk';
+
+// Listar providers + status (pra montar a UI de conexão)
+const { providers } = await manageAgentCredentialMitra({ action: 'list_providers' });
+
+// Listar modelos disponíveis (só dos providers com credencial) → use o modelId em send()/getAgentTaskMitra
+const { providers: groups } = await manageAgentCredentialMitra({ action: 'list_models' });
+
+// API key
+await manageAgentCredentialMitra({ action: 'validate', target: 'openai', key: 'sk-...' });
+await manageAgentCredentialMitra({ action: 'save', target: 'glm', key: '...' });
+await manageAgentCredentialMitra({ action: 'remove', target: 'anthropic' });
+```
+
+Subscriptions (alto nível, sem redirect/callback page) — `auth` inicia e retorna o que mostrar; `connect` finaliza:
+
+```typescript
+// Claude — abra a authUrl, colete o código que a Anthropic mostra
+const { authUrl, state } = await manageAgentCredentialMitra({ action: 'auth', target: 'claude' });
+await manageAgentCredentialMitra({ action: 'connect', target: 'claude', code, state });
+
+// Codex (OpenAI device flow) — mostre verificationUrl + userCode; a SDK faz o polling
+const { verificationUrl, userCode, pollId } = await manageAgentCredentialMitra({ action: 'auth', target: 'codex' });
+await manageAgentCredentialMitra({ action: 'connect', target: 'codex', pollId });
+```
+
+## Tipos TypeScript
+
+Todos os tipos estão incluídos:
+
+```typescript
+import type {
+  MitraConfig,
+  // Login
+  LoginOptions,
+  LoginResponse,
+  // Email Auth
+  EmailSignupOptions,
+  EmailLoginOptions,
+  EmailVerifyCodeOptions,
+  EmailResendCodeOptions,
+  // Options
+  ExecuteServerFunctionOptions,
+  ExecuteServerFunctionAsyncOptions,
+  UploadFileOptions,
+  StopServerFunctionExecutionOptions,
+  ListRecordsOptions,
+  GetRecordOptions,
+  CreateRecordOptions,
+  UpdateRecordOptions,
+  PatchRecordOptions,
+  DeleteRecordOptions,
+  CreateRecordsBatchOptions,
+  // Responses
+  ExecuteServerFunctionResponse,
+  ExecuteServerFunctionAsyncResponse,
+  UploadFileResponse,
+  StopServerFunctionExecutionResponse,
+  ListRecordsResponse,
+  // Profile Management
+  ListProfilesOptions,
+  ListProfilesResponse,
+  GetProfileDetailsOptions,
+  GetProfileDetailsResponse,
+  CreateProfileOptions,
+  CreateProfileResponse,
+  UpdateProfileOptions,
+  UpdateProfileResponse,
+  DeleteProfileOptions,
+  DeleteProfileResponse,
+  SetProfileUsersOptions,
+  SetProfileSelectTablesOptions,
+  SetProfileDmlTablesOptions,
+  SetProfileActionsOptions,
+  SetProfileScreensOptions,
+  SetProfileServerFunctionsOptions,
+  ProfileTableRef,
+  SetProfilePermissionResponse,
+  // Agent Chat
+  AgentChat,
+  AgentMessage,
+  AgentType,
+  AgentTaskSession,
+  AgentTaskStatus,
+  AgentTaskEventMap,
+  AgentAttachment,
+  QueuedItem,
+  SendOptions,
+  GetAgentTaskOptions,
+  ManageAgentChatOptions,
+  // Agent Credentials
+  CredentialTarget,
+  CredentialAction,
+  ManageAgentCredentialOptions,
+  AuthAgentCredentialOptions,
+  ConnectAgentCredentialOptions,
+  ListAgentModelsResult,
+  ListAgentProvidersResult
+} from 'mitra-interactions-sdk';
+```
+
+## Tratamento de Erros
+
+```typescript
+try {
+  const result = await executeDbActionMitra({
+    projectId: 123,
+    dbActionId: 456
+  });
+} catch (error) {
+  console.log('Erro:', error.message);
+  console.log('Status:', error.status);
+  console.log('Detalhes:', error.details);
+}
+```
+
+## Licença
+
+MIT