Mitra Interactions SDK

SDK para interações com a plataforma Mitra via endpoints /agentAiShortcut/.

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 com seu token da plataforma Mitra.

Importante: 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';

configureSdkMitra({
  baseURL: process.env.MITRA_BASE_URL || 'https://api.mitra.com',
  token: process.env.MITRA_TOKEN!
});

Exemplo de .env:

MITRA_BASE_URL=https://api.mitra.com
MITRA_TOKEN=seu-jwt-token-da-plataforma-mitra

Autenticação (Login)

Login via popup seguro hospedado no domínio Mitra. Credenciais nunca passam pelo código do desenvolvedor. O SDK é auto-configurado após o login.

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

// Login com email e senha
const result = await loginMitra('email', {
  authUrl: 'https://coder.mitralab.io/sdk-auth/',
  projectId: 123
});

// Login com Google
const result = await loginMitra('google', {
  authUrl: 'https://coder.mitralab.io/sdk-auth/',
  projectId: 123
});

// Login com Microsoft
const result = await loginMitra('microsoft', {
  authUrl: 'https://coder.mitralab.io/sdk-auth/',
  projectId: 123
});

// authUrl e projectId são opcionais se já configurados via configureSdkMitra()
// result: { token, baseURL, integrationURL? }

Métodos Disponíveis

executeDbActionMitra

Executa uma DBAction (DML) cadastrada.

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

const result = await executeDbActionMitra({
  projectId: 123,
  dbActionId: 456,
  params: {           // Opcional
    campo1: 'valor1',
    campo2: 'valor2'
  }
});
// result: { status, result: { rowsAffected: number } }

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" } }

Integrações

Requisito: A integrationURL deve ser configurada via configureSdkMitra({ ..., integrationURL: 'https://api0.mitraecp.com:1003' }).

listIntegrationsMitra

Lista as integrações configuradas no projeto.

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

const integrations = await listIntegrationsMitra({ projectId: 123 });
// result: IntegrationResponse[] — [{ id (UUID), projectId, name, slug, blueprintId, blueprintType, authType, credentials, status, lastCheckedAt, createdAt, updatedAt }]

setFileStatusMitra

Move arquivo do chat para PUBLIC ou LOADABLE.

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

const result = await setFileStatusMitra({
  projectId: 123,
  fileName: 'arquivo.jpg',
  targetPath: 'PUBLIC'  // 'PUBLIC' ou 'LOADABLE'
});
// result: { status, result: { fileName, currentPath, publicUrl, message } }

setVariableMitra

Cria ou atualiza uma variável customizada.

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

const result = await setVariableMitra({
  projectId: 123,
  key: 'minhaVariavel',
  value: 'meuValor'  // Opcional
});
// result: { status, result: { key, value } }

listVariablesMitra

Lista variáveis de um projeto.

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

const result = await listVariablesMitra({ projectId: 123 });
// result: { status, projectId, result: [{ key, value }] }

getVariableMitra

Busca o valor de uma variável específica.

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

const result = await getVariableMitra({ projectId: 123, key: 'minhaVariavel' });
// result: { status, result: { key, value } }

runActionMitra

Executa uma Action (fluxo de ação Low-Code) cadastrada.

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

const result = await runActionMitra({
  projectId: 123,
  actionId: 456,
  params: {           // Opcional
    campo1: 'valor1'
  }
});
// result: { status, executionTime, result: { stepsExecuted, 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)

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
});

Tipos TypeScript

Todos os tipos estão incluídos:

import type {
  MitraConfig,
  // Login
  LoginOptions,
  LoginResponse,
  // Options
  ExecuteDbActionOptions,
  ExecuteServerFunctionOptions,
  ExecuteServerFunctionAsyncOptions,
  ListIntegrationsOptions,
  StopServerFunctionExecutionOptions,
  SetFileStatusOptions,
  SetVariableOptions,
  ListVariablesOptions,
  GetVariableOptions,
  RunActionOptions,
  ListRecordsOptions,
  GetRecordOptions,
  CreateRecordOptions,
  UpdateRecordOptions,
  PatchRecordOptions,
  DeleteRecordOptions,
  CreateRecordsBatchOptions,
  // Responses
  ExecuteDbActionResponse,
  SetFileStatusResponse,
  SetVariableResponse,
  ListVariablesResponse,
  GetVariableResponse,
  RunActionResponse,
  ExecuteServerFunctionResponse,
  ExecuteServerFunctionAsyncResponse,
  IntegrationResponse,
  StopServerFunctionExecutionResponse,
  ListRecordsResponse
} 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