mitra-interactions-sdk 1.0.60-beta.42 → 1.0.60-beta.43

package/README.md

@@ -1,461 +1,472 @@
-# 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), auth SSO e integrações. 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`).
-
-> 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 { loginWithGoogleMitra, loginWithMicrosoftMitra } from 'mitra-interactions-sdk';
-
-// Primeira vez — sem configureSdkMitra: authUrl e projectId são obrigatórios
-const result = await loginWithGoogleMitra({
-  authUrl: 'https://stg.mitralab.io/legacy',
-  projectId: 'uuid-do-projeto'
-});
-
-// Se já chamou configureSdkMitra({ authUrl, projectId }), basta:
-const result = await loginWithGoogleMitra();
-const result = await loginWithMicrosoftMitra();
-
-// result: { token, baseURL, refreshToken }
-```
-
-`create` separa a intenção do SSO sem quebrar integrações existentes:
-
-| Valor | Comportamento |
-| --- | --- |
-| omitido | Fluxo combinado compatível: autentica e cria o vínculo quando o app permite |
-| `false` | Login estrito: exige acesso efetivo existente e nunca cria o vínculo |
-| `true` | Signup explícito: cria o vínculo quando o app permite |
-
-```typescript
-await loginWithGoogleMitra({ create: false }); // Entrar
-await loginWithGoogleMitra({ create: true });  // Criar conta
-```
-
-O login estrito pode retornar `APP_ACCESS_REQUIRED` quando não existe acesso ou
-`APP_ACCESS_REVOKED` quando o vínculo foi desligado. Signup bloqueado retorna
-`SIGNUP_NOT_ALLOWED`. O mesmo campo é preservado no modo redirect.
-
-### Login via Redirect (mobile)
-
-No celular o popup vira aba — use `mode: 'redirect'`: a página de auth navega de volta pro app com `#codeMitra`/`#stateMitra` no fragment, e o app conclui com `exchangeSsoCodeMitra`.
-
-```typescript
-import { loginWithGoogleMitra, exchangeSsoCodeMitra } from 'mitra-interactions-sdk';
-
-// 1. Iniciar login — o navegador navega para fora da página
-await loginWithGoogleMitra({ mode: 'redirect' });
-
-// 2. No boot do app, se houver #codeMitra/#stateMitra no fragment:
-const session = await exchangeSsoCodeMitra({ code, state });
-// A SDK valida o nonce (anti-CSRF), troca o code no BFF e configura o SDK.
-```
-
-### 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);
-  }
-});
-```
-
-## 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" } }
-```
-
-### Server Functions Públicas (sem autenticação)
-
-A SF deve ter `publicExecution = true` (via `togglePublicExecutionMitra` do mitra-sdk). Não exigem token.
-
-```typescript
-import {
-  executePublicServerFunctionMitra,
-  executePublicServerFunctionAsyncMitra,
-  getPublicServerFunctionExecutionMitra
-} from 'mitra-interactions-sdk';
-
-// Síncrona (timeout 5min)
-const res = await executePublicServerFunctionMitra({ projectId, serverFunctionId, input: { x: 1 } });
-// { executionId, status, output, logs, error, durationMs }
-
-// Assíncrona + polling
-const async1 = await executePublicServerFunctionAsyncMitra({ projectId, serverFunctionId });
-const status = await getPublicServerFunctionExecutionMitra({ projectId, executionId: async1.executionId });
-```
-
-### 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
-});
-```
-
-## Agent Chat (copilot)
-
-Chat com o agente de IA embarcado. **REST-first, tudo pela BFF no `baseURL` normal** (`/agentAiShortcut/*` — herda `fetchWithRefresh` e CORS): chats (`createChat`/`listChats`/`readChat`/`renameChat`/`deleteChat`), histórico (`listChatMessages`), credenciais e modelos. `projectId` obrigatório em todas (opcional na chamada se veio do `configureSdkMitra`). **Só o prompt é streaming** — um WebSocket por task em `wss://{origin}/copilot/ws/tasks/{taskId}?token=JWT`, aberto pela SDK quando a conversa começa (WS não passa por preflight de CORS).
-
-Precisa de `token` e `baseURL` configurados (o login já deixa pronto). O transporte do prompt aceita `transport: 'ws' | 'http'` — `'ws'` é o default; `'http'` é **funcional**: `POST /copilot/api/v1/tasks/{id}/inputs` + SSE em `/events` via fetch, com a MESMA paridade de eventos do WS (pra ambientes onde WebSocket não rola, ex.: serverless).
-
-### Gerenciar os chats — `manageAgentChatMitra`
-
-Tudo HTTP: listar (com filtros), renomear e deletar (= arquivar).
-
-```typescript
-import { manageAgentChatMitra } from 'mitra-interactions-sdk';
-
-const chats    = await manageAgentChatMitra({ action: 'list' });                          // AgentChat[]
-const doAgente = await manageAgentChatMitra({ action: 'list', agentId: 'uuid-do-agente' }); // só os chats de um agente business
-const busca    = await manageAgentChatMitra({ action: 'list', search: 'vendas', page: 0, size: 20 });
-const renamed  = await manageAgentChatMitra({ action: 'rename', taskId, name: 'Novo nome' });
-const deleted  = await manageAgentChatMitra({ action: 'delete', taskId }); // arquiva (some da lista default)
-```
-
-- `action: 'list'` → `AgentChat[]` — `{ id, name, agentType, agentId, archived, createdAt, updatedAt }`. Filtros: `agentId?`, `archived?`, `search?`, `page?`, `size?`.
-- `action: 'rename'` → `{ taskId, name }` (POST `/agentAiShortcut/renameChat`)
-- `action: 'delete'` → `{ taskId, deleted }` (POST `/agentAiShortcut/deleteChat` — arquiva, o histórico não é destruído)
-
-### Abrir uma session — `getAgentTaskMitra`
-
-Retorna uma `AgentTaskSession` que encapsula o ciclo de vida do chat. A task é criada via BFF (`POST /agentAiShortcut/createChat`) no primeiro `send()`; o WS da task conecta em seguida. Abrir a mesma `taskId` duas vezes devolve a **mesma** instância (cache).
-
-```typescript
-import { getAgentTaskMitra } from 'mitra-interactions-sdk';
-
-// Chat novo — SEMPRE com agentId (sessão sem agente não executa nada).
-// taskId é preenchido no primeiro send() (evento taskCreated)
-const session = getAgentTaskMitra({ create: true, agentId: 'uuid-do-agente', agentType: 'ANTHROPIC_CLAUDE_OPUS', name: 'Meu chat' });
-
-// Chat existente
-const existing = getAgentTaskMitra({ taskId: 'uuid-da-task' });
-await existing.loadHistory({ limit: 50 });
-```
-
-`getAgentTaskMitra({ create: true, agentType?, name?, agentId?, reasoningEffort?, transport? })` ou `getAgentTaskMitra({ taskId, transport? })`.
-
-**Agente autônomo**: a autonomia é **propriedade do AGENTE** (`autonomous` em `createAgentMitra`/`updateAgentMitra`, no `mitra-sdk`) — não existe flag na criação do chat. Ao criar um chat contra um agente autônomo (`getAgentTaskMitra({ create: true, agentId })`), o copilot deriva a autonomia do agente e o chat já nasce **sem dono** (`user_id NULL` — a dona é o agente), usando a connection anexada ao agente como credencial. Exige auth `AGENT_WRITE` (chave de SF ou token de app EDIT) — usuário business comum não abre chat autônomo. Depois de criado, dirigir/listar é igual ao chat normal (`getAgentTaskMitra({ taskId })`, `send`, `manageAgentChatMitra({ list, agentId })`).
-
-- `agentType` vem de `manageAgentCredentialMitra({ action: 'list_models' })` — ex.: `'ANTHROPIC_CLAUDE_OPUS'`, `'OPENAI_GPT5'`. Default: `'ANTHROPIC_CLAUDE_OPUS'`.
-- **`agentId`**: id de um agente business (CRUD via `mitra-sdk`: `listAgentsMitra` e família). A sessão sobe com o system prompt do agente e um token escopado — as tools enxergam só as Server Functions dele. **Sem `agentId`: sessão business sem agente** — sem system prompt e sem acesso às Server Functions (as tools recusam); não há adoção automática de agente único. Na prática, sempre passe `agentId`.
-
-#### Propriedades (somente leitura)
-
-| Propriedade | Tipo | Descrição |
-|-------------|------|-----------|
-| `taskId` | `string \| null` | `null` até o primeiro `send()` num chat novo |
-| `task` | `AgentChat \| null` | Metadados do chat |
-| `isNew` | `boolean` | Se foi aberto via `{ create: true }` |
-| `status` | `AgentTaskStatus` | `opening` · `idle` · `streaming` · `cancelled` · `error` · `closed` |
-| `history` | `AgentTimelineItem[]` | Linha do tempo canônica — `{ id, kind: 'user' \| 'agent', text, at }` ou `{ id, kind: 'tool', tool: AgentToolEvent, at }` (tool já desempacotada, mesmo shape do evento do streaming) |
-| `content` | `string` | Conteúdo acumulado do turno atual |
-| `queue` | `QueuedItem[]` | Mensagens enfileiradas (enviadas enquanto streamava) |
-
-#### Métodos
-
-- `send(prompt, { reasoningEffort?, agentType? })` → `void` — dispara um turno (`message` no WS ou POST `/inputs`). Se já está streamando, **enfileira** (FIFO, máx 10; as opções viajam com o item). `reasoningEffort`: intensidade desta mensagem — valores válidos vêm das `reasoningOptions` do modelo em `list_models` (**nunca invente**; fora do registro = `INVALID_REASONING_EFFORT`); herda o default de `getAgentTaskMitra({ create, reasoningEffort })` quando omitido. `agentType`: troca o modelo nesta mensagem — **só dentro do mesmo harness** (Claude↔Codex em conversa iniciada = `HARNESS_SWITCH`).
-- `cancel()` → `Promise<void>` — interrompe o turno atual (WS `interrupt`, safety net de 10s).
-- `respondApproval(approved)` → `void` — responde um pedido de aprovação do agente (WS `approval_response`).
-- `loadHistory({ limit? })` → `Promise<AgentTimelineItem[]>` — histórico persistido via REST, já no formato canônico da timeline (renderizou o streaming, renderizou o histórico).
-- `editQueueItem(id, text)` / `removeQueueItem(id)` / `clearQueue()` — manipulam a fila.
-- `on(event, handler)` → função de unsubscribe — assina eventos da session.
-- `close()` — encerra a session, fecha o WS e libera os listeners.
-
-#### Eventos (`session.on`)
-
-`statusChange` · `historyLoaded` · `taskCreated` · `turnStart` · `delta` (`{ delta, kind: 'text' | 'thinking' }`) · `tool` (`{ tool, toolId?, input?, content?, phase: 'call' | 'result' }`) · `turnEnd` (`{ content }`) · `cancelled` · `queueChange` · `error` (`{ code?, error }`) · `raw` (eventos não mapeados do stream, ex.: `workspace`).
-
-```typescript
-const session = getAgentTaskMitra({ create: true, agentId: 'uuid-do-agente' });
-
-session.on('delta', ({ delta, kind }) => { if (kind === 'text') process.stdout.write(delta); });
-session.on('tool',  ({ tool, phase }) => console.log('🔧', phase, 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');
-```
-
-### Credenciais do agente — `manageAgentCredentialMitra`
-
-Função única, toda HTTP **via BFF** (`/agentAiShortcut/listProviders`, `saveCredential`, `oauthStart`...). Providers: `'anthropic'` e `'openai'`. API key via `save`/`remove` (ambos); **OAuth (`auth`/`connect`) é exclusivo do anthropic; device flow (`device_auth`/`device_poll`) é exclusivo do openai** — fluxo trocado falha rápido com erro claro.
-
-**`projectId` é obrigatório** em todas as actions (opcional na chamada se já veio do `configureSdkMitra`) — é ele que define de qual app é a credencial; o BFF resolve `projectId → appId` e cunha o token de app.
-
-> 🔒 Tokens/keys nunca voltam crus — o backend devolve só status, e-mail da conta e a key mascarada.
-
-```typescript
-import { manageAgentCredentialMitra } from 'mitra-interactions-sdk';
-
-// Status por provider (pra montar a UI de conexão)
-const { providers } = await manageAgentCredentialMitra({ action: 'list_providers' });
-// AgentCredentialStatus[]: { provider, connected, credentialType, accountEmail, maskedApiKey }
-
-// Modelos selecionáveis → use o agentType em getAgentTaskMitra
-const { models } = await manageAgentCredentialMitra({ action: 'list_models' });
-// AgentModel[]: { model, name, provider, agentType, reasoningOptions }
-// reasoningOptions = registro das intensidades válidas por modelo (variam por
-// harness) — monte o seletor de reasoning a partir DAQUI, nunca hardcode.
-// Round-trip: os valores vêm em minúsculo e são aceitos na entrada COMO ESTÃO.
-
-// Com agentId: o que o PRÓXIMO TURNO daquele agente consegue rodar.
-// Agente com connection → catálogo da connection, SEMPRE (é ela que roda o
-// turno, mesmo que o caller tenha credencial própria). Sem connection →
-// fallback pro catálogo da credencial do usuário.
-const doAgente = await manageAgentCredentialMitra({ action: 'list_models', agentId: 'uuid-do-agente' });
-// Erros nomeados (err.code, HTTP 400 — reaja pelo código):
-//   NO_CREDENTIAL_AVAILABLE → nenhuma credencial utilizável (nunca vem lista
-//     vazia nesse caso) — mande conectar um provider
-//   CONNECTION_NOT_FOUND    → a connection do agente não existe mais
-
-// API key
-await manageAgentCredentialMitra({ action: 'save', target: 'openai', key: 'sk-...' });
-await manageAgentCredentialMitra({ action: 'remove', target: 'anthropic' });
-```
-
-OAuth (só Anthropic) — `auth` devolve o que mostrar, `connect` finaliza:
-
-```typescript
-const { authUrl, state } = await manageAgentCredentialMitra({ action: 'auth', target: 'anthropic' });
-// app abre authUrl; usuário autoriza e copia o código
-const { connected, email } = await manageAgentCredentialMitra({ action: 'connect', target: 'anthropic', code, state });
-```
-
-Device flow (só OpenAI) — mostre `userCode` + `verificationUri` e faça polling:
-
-```typescript
-const { deviceAuthId, userCode, verificationUri, intervalSeconds } =
-  await manageAgentCredentialMitra({ action: 'device_auth', target: 'openai' });
-// app mostra: "abra {verificationUri} e digite {userCode}"; depois, a cada intervalSeconds:
-const { connected } = await manageAgentCredentialMitra({ action: 'device_poll', target: 'openai', deviceAuthId });
-```
-
-## Tipos TypeScript
-
-Todos os tipos estão incluídos:
-
-```typescript
-import type {
-  MitraConfig,
-  // Login
-  LoginOptions,
-  LoginResponse,
-  // Options
-  ExecuteServerFunctionOptions,
-  ExecuteServerFunctionAsyncOptions,
-  StopServerFunctionExecutionOptions,
-  ListRecordsOptions,
-  GetRecordOptions,
-  CreateRecordOptions,
-  UpdateRecordOptions,
-  PatchRecordOptions,
-  DeleteRecordOptions,
-  CreateRecordsBatchOptions,
-  // Responses
-  ExecuteServerFunctionResponse,
-  ExecuteServerFunctionAsyncResponse,
-  StopServerFunctionExecutionResponse,
-  ListRecordsResponse,
-  // Agent Chat
-  AgentChat,
-  AgentMessage,
-  AgentTaskSession,
-  AgentTaskStatus,
-  SendOptions,
-  ManageAgentChatOptions,
-  GetAgentTaskOptions,
-  // Agent Credentials
-  ManageAgentCredentialOptions,
-  ListAgentModelsResult,
-  ListAgentProvidersResult
-} from 'mitra-interactions-sdk';
-```
-
-## Tratamento de Erros
-
-```typescript
-try {
-  const result = await executeServerFunctionMitra({
-    projectId: 123,
-    serverFunctionId: 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), auth SSO e integrações. 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`).
+
+> 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 { loginWithGoogleMitra, loginWithMicrosoftMitra } from 'mitra-interactions-sdk';
+
+// Primeira vez — sem configureSdkMitra: authUrl e projectId são obrigatórios
+const result = await loginWithGoogleMitra({
+  authUrl: 'https://stg.mitralab.io/legacy',
+  projectId: 'uuid-do-projeto'
+});
+
+// Se já chamou configureSdkMitra({ authUrl, projectId }), basta:
+const result = await loginWithGoogleMitra();
+const result = await loginWithMicrosoftMitra();
+
+// result: { token, baseURL, refreshToken }
+```
+
+`create` separa a intenção do SSO sem quebrar integrações existentes:
+
+| Valor | Comportamento |
+| --- | --- |
+| omitido | Fluxo combinado compatível: autentica e cria o vínculo quando o app permite |
+| `false` | Login estrito: exige acesso efetivo existente e nunca cria o vínculo |
+| `true` | Signup explícito: cria o vínculo quando o app permite |
+
+```typescript
+await loginWithGoogleMitra({ create: false }); // Entrar
+await loginWithGoogleMitra({ create: true });  // Criar conta
+```
+
+O login estrito pode retornar `APP_ACCESS_REQUIRED` quando não existe acesso ou
+`APP_ACCESS_REVOKED` quando o vínculo foi desligado. Signup bloqueado retorna
+`SIGNUP_NOT_ALLOWED`. O mesmo campo é preservado no modo redirect.
+
+### Login via Redirect (mobile)
+
+No celular o popup vira aba — use `mode: 'redirect'`: a página de auth navega de volta pro app com `#codeMitra`/`#stateMitra` no fragment, e o app conclui com `exchangeSsoCodeMitra`.
+
+```typescript
+import { loginWithGoogleMitra, exchangeSsoCodeMitra } from 'mitra-interactions-sdk';
+
+// 1. Iniciar login — o navegador navega para fora da página
+await loginWithGoogleMitra({ mode: 'redirect' });
+
+// 2. No boot do app, se houver #codeMitra/#stateMitra no fragment:
+const session = await exchangeSsoCodeMitra({ code, state });
+// A SDK valida o nonce (anti-CSRF), troca o code no BFF e configura o SDK.
+```
+
+### 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);
+  }
+});
+```
+
+## 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" } }
+```
+
+### Server Functions Públicas (sem autenticação)
+
+A SF deve ter `publicExecution = true` (via `togglePublicExecutionMitra` do mitra-sdk). Não exigem token.
+
+```typescript
+import {
+  executePublicServerFunctionMitra,
+  executePublicServerFunctionAsyncMitra,
+  getPublicServerFunctionExecutionMitra
+} from 'mitra-interactions-sdk';
+
+// Síncrona (timeout 5min)
+const res = await executePublicServerFunctionMitra({ projectId, serverFunctionId, input: { x: 1 } });
+// { executionId, status, output, logs, error, durationMs }
+
+// Assíncrona + polling
+const async1 = await executePublicServerFunctionAsyncMitra({ projectId, serverFunctionId });
+const status = await getPublicServerFunctionExecutionMitra({ projectId, executionId: async1.executionId });
+```
+
+### 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
+});
+```
+
+## Agent Chat (copilot)
+
+Chat com o agente de IA embarcado. **REST-first, tudo pela BFF no `baseURL` normal** (`/agentAiShortcut/*` — herda `fetchWithRefresh` e CORS): chats (`createChat`/`listChats`/`readChat`/`renameChat`/`deleteChat`), histórico (`listChatMessages`), credenciais e modelos. `projectId` obrigatório em todas (opcional na chamada se veio do `configureSdkMitra`). **Só o prompt é streaming** — um WebSocket por task em `wss://{origin}/copilot/ws/tasks/{taskId}?token=JWT`, aberto pela SDK quando a conversa começa (WS não passa por preflight de CORS).
+
+Precisa de `token` e `baseURL` configurados (o login já deixa pronto). O transporte do prompt aceita `transport: 'ws' | 'http'` — `'ws'` é o default; `'http'` é **funcional**: `POST /copilot/api/v1/tasks/{id}/inputs` + SSE em `/events` via fetch, com a MESMA paridade de eventos do WS (pra ambientes onde WebSocket não rola, ex.: serverless).
+
+### Gerenciar os chats — `manageAgentChatMitra`
+
+Tudo HTTP: listar (com filtros), renomear e deletar (= arquivar).
+
+```typescript
+import { manageAgentChatMitra } from 'mitra-interactions-sdk';
+
+const chats    = await manageAgentChatMitra({ action: 'list' });                          // AgentChat[]
+const doAgente = await manageAgentChatMitra({ action: 'list', agentId: 'uuid-do-agente' }); // só os chats de um agente business
+const busca    = await manageAgentChatMitra({ action: 'list', search: 'vendas', page: 0, size: 20 });
+const renamed  = await manageAgentChatMitra({ action: 'rename', taskId, name: 'Novo nome' });
+const deleted  = await manageAgentChatMitra({ action: 'delete', taskId }); // arquiva (some da lista default)
+```
+
+- `action: 'list'` → `AgentChat[]` — `{ id, name, agentType, agentId, archived, createdAt, updatedAt }`. Filtros: `agentId?`, `archived?`, `search?`, `page?`, `size?`.
+- `action: 'rename'` → `{ taskId, name }` (POST `/agentAiShortcut/renameChat`)
+- `action: 'delete'` → `{ taskId, deleted }` (POST `/agentAiShortcut/deleteChat` — arquiva, o histórico não é destruído)
+
+### Abrir uma session — `getAgentTaskMitra`
+
+Retorna uma `AgentTaskSession` que encapsula o ciclo de vida do chat. A task é criada via BFF (`POST /agentAiShortcut/createChat`) no primeiro `send()`; o WS da task conecta em seguida. Abrir a mesma `taskId` duas vezes devolve a **mesma** instância (cache).
+
+```typescript
+import { getAgentTaskMitra } from 'mitra-interactions-sdk';
+
+// Chat novo — SEMPRE com agentId (sessão sem agente não executa nada).
+// taskId é preenchido no primeiro send() (evento taskCreated)
+const session = getAgentTaskMitra({ create: true, agentId: 'uuid-do-agente', agentType: 'ANTHROPIC_CLAUDE_OPUS', name: 'Meu chat' });
+
+// Chat existente
+const existing = getAgentTaskMitra({ taskId: 'uuid-da-task' });
+await existing.loadHistory({ limit: 50 });
+```
+
+`getAgentTaskMitra({ create: true, agentType?, name?, agentId?, reasoningEffort?, transport?, userId? })` ou `getAgentTaskMitra({ taskId, transport?, userId? })`.
+
+**Agente autônomo**: a autonomia é **propriedade do AGENTE** (`autonomous` em `createAgentMitra`/`updateAgentMitra`, no `mitra-sdk`) — não existe flag na criação do chat. Ao criar um chat contra um agente autônomo (`getAgentTaskMitra({ create: true, agentId })`), o copilot deriva a autonomia do agente e o chat já nasce **sem dono** (`user_id NULL` — a dona é o agente), usando a connection anexada ao agente como credencial. Exige auth `AGENT_WRITE` (chave de SF ou token de app EDIT) — usuário business comum não abre chat autônomo. Depois de criado, dirigir/listar é igual ao chat normal (`getAgentTaskMitra({ taskId })`, `send`, `manageAgentChatMitra({ list, agentId })`).
+
+- `agentType` vem de `manageAgentCredentialMitra({ action: 'list_models' })` — ex.: `'ANTHROPIC_CLAUDE_OPUS'`, `'OPENAI_GPT5'`. Default: `'ANTHROPIC_CLAUDE_OPUS'`.
+- **`agentId`**: id de um agente business (CRUD via `mitra-sdk`: `listAgentsMitra` e família). A sessão sobe com o system prompt do agente e um token escopado — as tools enxergam só as Server Functions dele. **Sem `agentId`: sessão business sem agente** — sem system prompt e sem acesso às Server Functions (as tools recusam); não há adoção automática de agente único. Na prática, sempre passe `agentId`.
+
+**Agir em nome do dono (`userId`)**: uma Server Function disparada por webhook/cron pode abrir e dirigir o chat de um usuário específico, em nome dele — o chat é normal, com dono; o turno roda com a identidade e a credencial do dono (connection do agente primeiro, senão a conta dele). Exige `AGENT_WRITE` no app (senão 403); o backend decide a autorização, a SDK só repassa. Tudo opcional: ausente = comportamento de sempre, byte a byte.
+
+```typescript
+// SF reagindo a webhook: continua a thread da pessoa atendida
+const task = getAgentTaskMitra({ create: true, agentId, userId: 'uuid-do-usuario' }); // chat nasce DELE
+const dela = await manageAgentChatMitra({ action: 'list', userId: 'uuid-do-usuario' }); // chats DELA
+const mesma = getAgentTaskMitra({ taskId, userId: 'uuid-do-usuario' }); // defensivo: 404 se o chat não for dela
+```
+
+Erros nomeados: `403` sem `AGENT_WRITE`; `400 AUTONOMOUS_TASK_HAS_NO_OWNER` (userId + agente autônomo é contradição); `404` quando o `userId` defensivo não bate com o dono real. Nunca invente `userId` de texto do usuário — use o id do vínculo canal→usuário da sua aplicação.
+
+#### Propriedades (somente leitura)
+
+| Propriedade | Tipo | Descrição |
+|-------------|------|-----------|
+| `taskId` | `string \| null` | `null` até o primeiro `send()` num chat novo |
+| `task` | `AgentChat \| null` | Metadados do chat |
+| `isNew` | `boolean` | Se foi aberto via `{ create: true }` |
+| `status` | `AgentTaskStatus` | `opening` · `idle` · `streaming` · `cancelled` · `error` · `closed` |
+| `history` | `AgentTimelineItem[]` | Linha do tempo canônica — `{ id, kind: 'user' \| 'agent', text, at }` ou `{ id, kind: 'tool', tool: AgentToolEvent, at }` (tool já desempacotada, mesmo shape do evento do streaming) |
+| `content` | `string` | Conteúdo acumulado do turno atual |
+| `queue` | `QueuedItem[]` | Mensagens enfileiradas (enviadas enquanto streamava) |
+
+#### Métodos
+
+- `send(prompt, { reasoningEffort?, agentType? })` → `void` — dispara um turno (`message` no WS ou POST `/inputs`). Se já está streamando, **enfileira** (FIFO, máx 10; as opções viajam com o item). `reasoningEffort`: intensidade desta mensagem — valores válidos vêm das `reasoningOptions` do modelo em `list_models` (**nunca invente**; fora do registro = `INVALID_REASONING_EFFORT`); herda o default de `getAgentTaskMitra({ create, reasoningEffort })` quando omitido. `agentType`: troca o modelo nesta mensagem — **só dentro do mesmo harness** (Claude↔Codex em conversa iniciada = `HARNESS_SWITCH`).
+- `cancel()` → `Promise<void>` — interrompe o turno atual (WS `interrupt`, safety net de 10s).
+- `respondApproval(approved)` → `void` — responde um pedido de aprovação do agente (WS `approval_response`).
+- `loadHistory({ limit? })` → `Promise<AgentTimelineItem[]>` — histórico persistido via REST, já no formato canônico da timeline (renderizou o streaming, renderizou o histórico).
+- `editQueueItem(id, text)` / `removeQueueItem(id)` / `clearQueue()` — manipulam a fila.
+- `on(event, handler)` → função de unsubscribe — assina eventos da session.
+- `close()` — encerra a session, fecha o WS e libera os listeners.
+
+#### Eventos (`session.on`)
+
+`statusChange` · `historyLoaded` · `taskCreated` · `turnStart` · `delta` (`{ delta, kind: 'text' | 'thinking' }`) · `tool` (`{ tool, toolId?, input?, content?, phase: 'call' | 'result' }`) · `turnEnd` (`{ content }`) · `cancelled` · `queueChange` · `error` (`{ code?, error }`) · `raw` (eventos não mapeados do stream, ex.: `workspace`).
+
+```typescript
+const session = getAgentTaskMitra({ create: true, agentId: 'uuid-do-agente' });
+
+session.on('delta', ({ delta, kind }) => { if (kind === 'text') process.stdout.write(delta); });
+session.on('tool',  ({ tool, phase }) => console.log('🔧', phase, 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');
+```
+
+### Credenciais do agente — `manageAgentCredentialMitra`
+
+Função única, toda HTTP **via BFF** (`/agentAiShortcut/listProviders`, `saveCredential`, `oauthStart`...). Providers: `'anthropic'` e `'openai'`. API key via `save`/`remove` (ambos); **OAuth (`auth`/`connect`) é exclusivo do anthropic; device flow (`device_auth`/`device_poll`) é exclusivo do openai** — fluxo trocado falha rápido com erro claro.
+
+**`projectId` é obrigatório** em todas as actions (opcional na chamada se já veio do `configureSdkMitra`) — é ele que define de qual app é a credencial; o BFF resolve `projectId → appId` e cunha o token de app.
+
+> 🔒 Tokens/keys nunca voltam crus — o backend devolve só status, e-mail da conta e a key mascarada.
+
+```typescript
+import { manageAgentCredentialMitra } from 'mitra-interactions-sdk';
+
+// Status por provider (pra montar a UI de conexão)
+const { providers } = await manageAgentCredentialMitra({ action: 'list_providers' });
+// AgentCredentialStatus[]: { provider, connected, credentialType, accountEmail, maskedApiKey }
+
+// Modelos selecionáveis → use o agentType em getAgentTaskMitra
+const { models } = await manageAgentCredentialMitra({ action: 'list_models' });
+// AgentModel[]: { model, name, provider, agentType, reasoningOptions }
+// reasoningOptions = registro das intensidades válidas por modelo (variam por
+// harness) — monte o seletor de reasoning a partir DAQUI, nunca hardcode.
+// Round-trip: os valores vêm em minúsculo e são aceitos na entrada COMO ESTÃO.
+
+// Com agentId: o que o PRÓXIMO TURNO daquele agente consegue rodar.
+// Agente com connection → catálogo da connection, SEMPRE (é ela que roda o
+// turno, mesmo que o caller tenha credencial própria). Sem connection →
+// fallback pro catálogo da credencial do usuário.
+const doAgente = await manageAgentCredentialMitra({ action: 'list_models', agentId: 'uuid-do-agente' });
+// Erros nomeados (err.code, HTTP 400 — reaja pelo código):
+//   NO_CREDENTIAL_AVAILABLE → nenhuma credencial utilizável (nunca vem lista
+//     vazia nesse caso) — mande conectar um provider
+//   CONNECTION_NOT_FOUND    → a connection do agente não existe mais
+
+// API key
+await manageAgentCredentialMitra({ action: 'save', target: 'openai', key: 'sk-...' });
+await manageAgentCredentialMitra({ action: 'remove', target: 'anthropic' });
+```
+
+OAuth (só Anthropic) — `auth` devolve o que mostrar, `connect` finaliza:
+
+```typescript
+const { authUrl, state } = await manageAgentCredentialMitra({ action: 'auth', target: 'anthropic' });
+// app abre authUrl; usuário autoriza e copia o código
+const { connected, email } = await manageAgentCredentialMitra({ action: 'connect', target: 'anthropic', code, state });
+```
+
+Device flow (só OpenAI) — mostre `userCode` + `verificationUri` e faça polling:
+
+```typescript
+const { deviceAuthId, userCode, verificationUri, intervalSeconds } =
+  await manageAgentCredentialMitra({ action: 'device_auth', target: 'openai' });
+// app mostra: "abra {verificationUri} e digite {userCode}"; depois, a cada intervalSeconds:
+const { connected } = await manageAgentCredentialMitra({ action: 'device_poll', target: 'openai', deviceAuthId });
+```
+
+## Tipos TypeScript
+
+Todos os tipos estão incluídos:
+
+```typescript
+import type {
+  MitraConfig,
+  // Login
+  LoginOptions,
+  LoginResponse,
+  // Options
+  ExecuteServerFunctionOptions,
+  ExecuteServerFunctionAsyncOptions,
+  StopServerFunctionExecutionOptions,
+  ListRecordsOptions,
+  GetRecordOptions,
+  CreateRecordOptions,
+  UpdateRecordOptions,
+  PatchRecordOptions,
+  DeleteRecordOptions,
+  CreateRecordsBatchOptions,
+  // Responses
+  ExecuteServerFunctionResponse,
+  ExecuteServerFunctionAsyncResponse,
+  StopServerFunctionExecutionResponse,
+  ListRecordsResponse,
+  // Agent Chat
+  AgentChat,
+  AgentMessage,
+  AgentTaskSession,
+  AgentTaskStatus,
+  SendOptions,
+  ManageAgentChatOptions,
+  GetAgentTaskOptions,
+  // Agent Credentials
+  ManageAgentCredentialOptions,
+  ListAgentModelsResult,
+  ListAgentProvidersResult
+} from 'mitra-interactions-sdk';
+```
+
+## Tratamento de Erros
+
+```typescript
+try {
+  const result = await executeServerFunctionMitra({
+    projectId: 123,
+    serverFunctionId: 456
+  });
+} catch (error) {
+  console.log('Erro:', error.message);
+  console.log('Status:', error.status);
+  console.log('Detalhes:', error.details);
+}
+```
+
+## Licença
+
+MIT