SDK para TypeScript | Basement Gateway

O pacote é @basementai/gateway. O código está no GitHub.

Instalar

npm install @basementai/gateway

Criar o cliente

import { BasementGatewayClient } from "@basementai/gateway";
const basement = new BasementGatewayClient({
  apiKey: process.env.BASEMENT_API_KEY,
});

Quando você não informa apiKey, o cliente lê a variável de ambiente BASEMENT_API_KEY.

Chamar o Gateway

Cada ferramenta é um método. Os argumentos e as respostas têm tipos.

// Documentos
const { docs } = await basement.docs.list();
const doc = await basement.docs.read({ docId: docs[0].id });
await basement.docs.edit({
  docId: doc.id,
  oldText: "Preços em USD",
  newText: "Preços em BRL",
  changeSummary: "Moeda",
});
// Buscar, e ler uma parte de um texto
const { results } = await basement.search({ query: "preço" });
const found = await basement.text.find({ docId: doc.id, query: "desconto" });
// Tarefas
const { taskId } = await basement.tasks.create({ title: "Revisar os preços do 4º trimestre" });
await basement.tasks.update({ taskId, status: "done" });
// Serviços conectados
const { connected } = await basement.services.list();
const issue = await basement.services.execute({
  toolSlug: "jira__getJiraIssue",
  arguments: { issueIdOrKey: "OPS-12" },
});

Tratar erros

Uma chamada que o Gateway recusa lança um BasementGatewayError, com o status HTTP e o corpo do erro.

import { BasementGatewayError } from "@basementai/gateway";
try {
  await basement.tasks.create({ title: "Revisar os preços do 4º trimestre" });
} catch (error) {
  if (error instanceof BasementGatewayError) {
    console.log(error.statusCode); // 403
    console.log(error.body);       // { error: { code: "forbidden", message: "Role lacks write access" } }
  }
}

Veja Erros e limites para cada status.

Tempo limite e novas tentativas

Uma chamada expira depois de 60 segundos. O cliente tenta de novo, até mais 2 vezes, quando recebe 408, 429 ou um status 5xx. Mude os dois no cliente ou em uma chamada:

const basement = new BasementGatewayClient({
  apiKey: process.env.BASEMENT_API_KEY,
  timeoutInSeconds: 30,
  maxRetries: 0,
});
await basement.docs.list({ timeoutInSeconds: 10, maxRetries: 3 });

Outro endereço

O cliente fala com https://mcp.basement.chat. Para usar outra instalação, informe baseUrl:

const basement = new BasementGatewayClient({
  apiKey: process.env.BASEMENT_API_KEY,
  baseUrl: "http://127.0.0.1:3214",
});