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

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.

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:

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)

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.

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.

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

// 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:

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.

import { emailSignupMitra } from 'mitra-interactions-sdk';

await emailSignupMitra({
  name: 'João Silva',
  email: '[email protected]',
  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.

import { emailVerifyCodeMitra } from 'mitra-interactions-sdk';

const session = await emailVerifyCodeMitra({
  email: '[email protected]',
  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.

import { emailResendCodeMitra } from 'mitra-interactions-sdk';

await emailResendCodeMitra({ email: '[email protected]' });

emailLoginMitra

Login direto com email e senha. Retorna LoginResponse e auto-configura o SDK.

import { emailLoginMitra } from 'mitra-interactions-sdk';

const session = await emailLoginMitra({
  email: '[email protected]',
  password: 'minhasenha123'
});
// session: { token, baseURL, integrationURL? }

Fluxo completo de signup com email

// 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":

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.

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.

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.

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.

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.

import { executeDataLoaderMitra } from 'mitra-interactions-sdk';

const result = await executeDataLoaderMitra({
  projectId: 123,
  dataLoaderId: 5,
  input: { mes: 1, ano: 2025 }   // Opcional — parâmetros {{var}} da query
});
// result: { status, result: { dataLoaderId, executionLog: { timestamp, rowCount, query, status, fileSize?, duration? }, message } }

uploadFilePrivateMitra / uploadFilePublicMitra / uploadFileLoadableMitra

Faz upload de um arquivo diretamente para a pasta PRIVATE, PUBLIC ou LOADABLE do projeto. Usa multipart/form-data.

🔒 Privado é o padrão. uploadFilePrivateMitra guarda o arquivo em bucket sem leitura pública, com chave aleatória; o acesso é sempre autenticado e autorizado pela aplicação. uploadFilePublicMitra cria uma URL permanente e irreversível — só para conteúdo que precisa abrir sem sessão (logo, imagem em e-mail, tela pública), nunca para dado de cliente.

import { uploadFilePrivateMitra, uploadFilePublicMitra, uploadFileLoadableMitra } from 'mitra-interactions-sdk';

// Upload PRIVADO (recomendado): o arquivo não fica público; publicUrl vem null.
const priv = await uploadFilePrivateMitra({
  projectId: 123,
  file: fileInput.files[0]   // File ou Blob
});
// priv: { status, result: { fileName, currentPath, key, publicUrl: null, message } }
// key = ai-files/private/{24 chars aleatórios}/nome — guarde na linha do registro dono.
// Quem lê é a Server Function, depois de validar o registro (ver "Anexos privados — o padrão").

// Upload para PUBLIC (arquivo fica acessível publicamente via URL)
const result = await uploadFilePublicMitra({
  projectId: 123,
  file: fileInput.files[0]   // File ou Blob
});
// result: { status, result: { fileName, currentPath, key, publicUrl, message } }
// No PUBLIC, `currentPath` é a URL completa; `key` é a chave relativa (ai-files/public/...).

// Upload para LOADABLE (arquivo disponível para carga via Spark/ETL)
const result2 = await uploadFileLoadableMitra({
  projectId: 123,
  file: myBlob
});
// result2: { status, result: { fileName, currentPath, publicUrl: null, message } }

Anexos privados — o padrão (contrato TKT-000a0394)

A plataforma só sabe "esta pessoa pertence a este projeto". Quem sabe "o anexo X é da solicitação Y, que é do usuário Z" é a aplicação. Por isso o acesso a um arquivo privado pela chave é restrito a usuário DEV do projeto ou a uma Server Function em execução; a tela de usuário final nunca manda a chave — ela pede o anexo pelo registro a uma SF, que confere a regra e devolve um link temporário.

import { uploadFilePrivateMitra, executeServerFunctionMitra } from 'mitra-interactions-sdk';

// 1) Tela de formulário: sobe privado e guarda a CHAVE na linha do registro
const up = await uploadFilePrivateMitra({ projectId: 123, file: fileInput.files[0] });
const key = up.result.key;   // ai-files/private/{24 chars aleatórios}/comprovante.pdf
await executeServerFunctionMitra({ projectId: 123, serverFunctionId: SF_SALVAR_SOLICITACAO,
  input: { descricao, anexoKey: key } });

// 2) Tela que exibe: pede pelo REGISTRO, nunca pela chave
const res = await executeServerFunctionMitra({ projectId: 123, serverFunctionId: SF_ANEXO_DA_SOLICITACAO,
  input: { solicitacaoId: 482 } });
// a SF conferiu que o usuário pode ver a solicitação 482 e devolveu { url, expiresAt } (link de ~5 min)
window.open(res.result.output.url);

Do lado da SF (backend), depois da regra de negócio, a chave vira link temporário via GET {MITRA_BASE_URL}/agentAiShortcut/fileLink?projectId&key&ttlSeconds — exemplos completos em mitraapi/docs/SERVER_FUNCTIONS_API.md, seção "Arquivos privados a partir de uma Server Function".

Regras

• key só é aceita dentro das pastas do projeto (ai-files/private/, ai-files/public/, ai-files/loadable/). Chave iniciada em tenant_ ou /, com .. ou terminada em / é recusada (HTTP 400 INVALID_KEY). É isso que isola um projeto do outro.
• A chave privada tem um segmento aleatório de 24 caracteres: não é adivinhável e dois uploads com o mesmo nome não se sobrescrevem. Guarde-a como qualquer outra coluna do registro.
• Privado fica em bucket próprio, sem URL pública. Público é permanente e irreversível; nunca é o lugar de dado de cliente.
• Todo acesso é registrado (INT_FILEACCESSLOG do tenant): quem baixou, gerou link ou excluiu, e quando.

downloadFilePrivateMitra / getFileLinkMitra / deleteFileMitra (DEV e Server Function)

Acesso pela chave. Permissão: usuário DEV do projeto (sem API key BUSINESS) ou Server Function em execução. Usuário final recebe HTTP 403 ACCESS_DENIED — para ele, use o padrão acima.

import { downloadFilePrivateMitra, getFileLinkMitra, deleteFileMitra } from 'mitra-interactions-sdk';

// Download autenticado — retorna Blob
const blob = await downloadFilePrivateMitra({ projectId: 123, key });

// Link temporário (assinado); padrão 300 s, máximo definido no backend
const link = await getFileLinkMitra({ projectId: 123, key, ttlSeconds: 300 });
// link.result: { key, url, expiresAt, expiresInSeconds }

// Exclusão — apaga exatamente esse objeto
const del = await deleteFileMitra({ projectId: 123, key });
// erros: 400 INVALID_KEY | 403 ACCESS_DENIED | 404 FILE_NOT_FOUND

• O delete nunca apaga por prefixo/pasta, e chave inexistente devolve FILE_NOT_FOUND.
• Quando o registro é apagado, apague o anexo dele na mesma SF — senão sobra documento de cliente sem nada apontando para ele.

Dynamic Schema CRUD

🔒 userType=dev only. Falha 403 para business. Em telas com business, envelopar em SF tipo SQL.

CRUD completo em tabelas do projeto via Dynamic Schema (usa header X-TenantID).

Todos os endpoints suportam o parâmetro opcional jdbcConnectionConfigId para operar em datasources adicionais (PostgreSQL, Oracle, SQL Server, etc.) ao invés do banco principal do tenant.

• listRecordsMitra(...) → ListRecordsResponse { content, page, size, totalElements, totalPages } - Lista registros com paginação
• getRecordMitra(...) → Record<string, any> - Busca registro por ID
• createRecordMitra(...) → Record<string, any> - Cria registro (201)
• updateRecordMitra(...) → Record<string, any> - Atualiza registro (PUT)
• patchRecordMitra(...) → Record<string, any> - Atualiza parcialmente (PATCH)
• deleteRecordMitra(...) → void - Remove registro (204 No Content)
• createRecordsBatchMitra(...) → Record<string, any>[] - Cria múltiplos registros (201)

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

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

import { setProfileUsersMitra, setProfileSelectTablesMitra, setProfileServerFunctionsMitra } from 'mitra-interactions-sdk';

// Definir usuários do perfil
await setProfileUsersMitra({ projectId: 123, profileId: 1, userIds: [10, 20, 30] });

// Definir tabelas SELECT
await setProfileSelectTablesMitra({
  projectId: 123,
  profileId: 1,
  jdbcConnectionConfigId: 1,   // Opcional — ID da conexão JDBC (default: banco principal)
  tables: [
    { tableName: 'clientes' },
    { tableName: 'pedidos' }
  ]
});

// Definir server functions
await setProfileServerFunctionsMitra({ projectId: 123, profileId: 1, serverFunctionIds: [5, 8, 12] });

Agent Chat (embedded)

Chat com o agente de IA embarcado, sobre um WebSocket compartilhado (/sdk-ws). Uma única conexão atende todas as sessions — o roteamento de eventos é feito por taskId.

⚙️ Requisitos: roda apenas em apps publicadas pela plataforma Mitra (o build-proxy injeta window.__mitraEnv.agentWsUrl) e precisa de token configurado (faça login antes ou passe em configureSdkMitra).

Gerenciar os chats — manageAgentChatMitra

Operações stateless sobre a coleção de chats do usuário: listar, renomear, deletar.

import { manageAgentChatMitra } from 'mitra-interactions-sdk';

const chats  = await manageAgentChatMitra({ action: 'list' });                       // AgentChat[]
const renamed = await manageAgentChatMitra({ action: 'rename', taskId, name: 'Novo nome' });
const deleted = await manageAgentChatMitra({ action: 'delete', taskId });

• action: 'list' → AgentChat[] — { id, name, agentType?, provider?, createdAt, updatedAt }. Aceita projectId? pra sobrescrever o global.
• action: 'rename' → { taskId, name }
• action: 'delete' → { taskId, deleted }

Abrir uma session — getAgentTaskMitra

Retorna uma AgentTaskSession que encapsula todo o ciclo de vida de um chat (histórico, streaming, fila, cancel, eventos). Abrir a mesma taskId duas vezes devolve a mesma instância (cache).

import { getAgentTaskMitra } from 'mitra-interactions-sdk';

// Chat novo — taskId é preenchido depois do primeiro send()
const session = getAgentTaskMitra({ create: true, agentType: 'claudecode', modelId: 'openai/gpt-5.5:medium' });

// Chat existente — detecta automaticamente se já há stream ativo
const existing = getAgentTaskMitra({ taskId: 'abc123' });
await existing.loadHistory({ limit: 50 });

getAgentTaskMitra({ create: true, projectId?, agentType?, modelId?, name? }) ou getAgentTaskMitra({ taskId }).

Propriedades (somente leitura)

| Propriedade | Tipo | Descrição | |-------------|------|-----------| | taskId | string \| null | null até o primeiro send() num chat novo | | task | AgentChat \| null | Metadados do chat após criado | | isNew | boolean | Se foi aberto via { create: true } | | status | AgentTaskStatus | opening · idle · uploading · streaming · cancelled · error · closed | | history | AgentMessage[] | Histórico carregado | | content | string | Conteúdo acumulado do turno atual | | queue | QueuedItem[] | Mensagens enfileiradas (enviadas enquanto streamava) |

Métodos

• send(prompt, options?) → void — dispara um turno. Se já está streamando, enfileira (FIFO, máx 10). options: { agentType?, modelId?, files? }.
• cancel() → Promise<void> — cancela o turno atual; resolve quando o backend confirma (ou safety net de 30s).
• loadHistory({ limit? }) → Promise<AgentMessage[]> — carrega o histórico do chat.
• editQueueItem(id, text) / removeQueueItem(id) / clearQueue() — manipulam a fila.
• on(event, handler) → função de unsubscribe — assina eventos da session.
• close() — encerra a session e libera os listeners.

Eventos (session.on)

statusChange · historyLoaded · taskCreated · turnStart · delta · tool · turnEnd · cancelled · queueChange · error.

const session = getAgentTaskMitra({ create: true });

session.on('delta', ({ delta, kind }) => process.stdout.write(delta)); // kind: 'text' | 'tool'
session.on('tool',  ({ tool, input }) => console.log('🔧', tool));
session.on('turnEnd', ({ content }) => console.log('\n✓ fim do turno'));
session.on('taskCreated', ({ task }) => console.log('chat criado:', task.id));
session.on('error', ({ error }) => console.error(error));

session.send('Analise estas vendas e gere um resumo');

Anexos e seleção de modelo

// Anexos: passe os File crus (drop/input). A SDK sobe cada um (URL pública),
// detecta o tipo e monta os anexos. Status vai pra 'uploading'; falha sai no evento 'error'.
session.send('O que tem nesta planilha?', { files: [xlsxFile, pngFile] });

// Modelo por turno (sobrescreve o default da session)
session.send('Refaça com mais detalhes', { modelId: 'subscription:anthropic:claude-opus-4-7' });

Credenciais do agente — manageAgentCredentialMitra

Função única (sobre /sdk-ws) para API keys (8 providers: anthropic, openai, gemini, kimi, minimax, glm, qwen, openrouter) e subscriptions OAuth (Claude paste-código / OpenAI device flow via Codex).

🔒 Segurança: o token de subscription nunca volta cru pro cliente — fica server-side e é injetado no sandbox direto de lá.

import { manageAgentCredentialMitra } from 'mitra-interactions-sdk';

// Listar providers + status (pra montar a UI de conexão)
const { providers } = await manageAgentCredentialMitra({ action: 'list_providers' });

// Listar modelos disponíveis (só dos providers com credencial) → use o modelId em send()/getAgentTaskMitra
const { providers: groups } = await manageAgentCredentialMitra({ action: 'list_models' });

// API key
await manageAgentCredentialMitra({ action: 'validate', target: 'openai', key: 'sk-...' });
await manageAgentCredentialMitra({ action: 'save', target: 'glm', key: '...' });
await manageAgentCredentialMitra({ action: 'remove', target: 'anthropic' });

Subscriptions (alto nível, sem redirect/callback page) — auth inicia e retorna o que mostrar; connect finaliza:

// Claude — abra a authUrl, colete o código que a Anthropic mostra
const { authUrl, state } = await manageAgentCredentialMitra({ action: 'auth', target: 'claude' });
await manageAgentCredentialMitra({ action: 'connect', target: 'claude', code, state });

// Codex (OpenAI device flow) — mostre verificationUrl + userCode; a SDK faz o polling
const { verificationUrl, userCode, pollId } = await manageAgentCredentialMitra({ action: 'auth', target: 'codex' });
await manageAgentCredentialMitra({ action: 'connect', target: 'codex', pollId });

Tipos TypeScript

Todos os tipos estão incluídos:

import type {
  MitraConfig,
  // Login
  LoginOptions,
  LoginResponse,
  // Email Auth
  EmailSignupOptions,
  EmailLoginOptions,
  EmailVerifyCodeOptions,
  EmailResendCodeOptions,
  // Options
  ExecuteServerFunctionOptions,
  ExecuteServerFunctionAsyncOptions,
  UploadFileOptions,
  StopServerFunctionExecutionOptions,
  ListRecordsOptions,
  GetRecordOptions,
  CreateRecordOptions,
  UpdateRecordOptions,
  PatchRecordOptions,
  DeleteRecordOptions,
  CreateRecordsBatchOptions,
  // Responses
  ExecuteServerFunctionResponse,
  ExecuteServerFunctionAsyncResponse,
  UploadFileResponse,
  StopServerFunctionExecutionResponse,
  ListRecordsResponse,
  // Profile Management
  ListProfilesOptions,
  ListProfilesResponse,
  GetProfileDetailsOptions,
  GetProfileDetailsResponse,
  CreateProfileOptions,
  CreateProfileResponse,
  UpdateProfileOptions,
  UpdateProfileResponse,
  DeleteProfileOptions,
  DeleteProfileResponse,
  SetProfileUsersOptions,
  SetProfileSelectTablesOptions,
  SetProfileDmlTablesOptions,
  SetProfileActionsOptions,
  SetProfileScreensOptions,
  SetProfileServerFunctionsOptions,
  ProfileTableRef,
  SetProfilePermissionResponse,
  // Agent Chat
  AgentChat,
  AgentMessage,
  AgentType,
  AgentTaskSession,
  AgentTaskStatus,
  AgentTaskEventMap,
  AgentAttachment,
  QueuedItem,
  SendOptions,
  GetAgentTaskOptions,
  ManageAgentChatOptions,
  // Agent Credentials
  CredentialTarget,
  CredentialAction,
  ManageAgentCredentialOptions,
  AuthAgentCredentialOptions,
  ConnectAgentCredentialOptions,
  ListAgentModelsResult,
  ListAgentProvidersResult
} from 'mitra-interactions-sdk';

Tratamento de Erros

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

Dentro de uma Server Function (prova de execução)

Quando o código roda dentro de uma Server Function, o sandbox recebe a variável de ambiente MITRA_SF_EXECUTION_TOKEN. A partir da 1.0.67 a SDK a lê sozinha e envia o header X-SF-Execution-Token em toda chamada ao backend principal. É esse header que libera getFileLinkMitra, downloadFilePrivateMitra, deleteFileMitra e uploadFilePrivateMitra para a SF, mesmo quando quem disparou a SF é um usuário final (business). No navegador nada muda.