mitra-interactions-sdk 1.0.56 → 1.0.58-beta.0

package/README.md

@@ -1,540 +1,558 @@
-# Mitra Interactions SDK
-
-SDK para interações com a plataforma Mitra via endpoints `/interactions/`.
-
-## 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
-
-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
-
-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, 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