mitra-interactions-sdk 1.0.60-beta.4 → 1.0.60-beta.41

package/README.md

@@ -1,558 +1,433 @@
-# 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] });
-```
-
-## 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
-} 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), 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 }
+```
+
+### 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
+
+// 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