TypeScript SDK | Basement Gateway

The package is @basementai/gateway. The source is on GitHub.

Install

npm install @basementai/gateway

Create the client

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

When you do not give apiKey, the client reads the BASEMENT_API_KEY environment variable.

Call the Gateway

Each tool is a method. Arguments and answers are typed.

// Documents
const { docs } = await basement.docs.list();
const doc = await basement.docs.read({ docId: docs[0].id });
await basement.docs.edit({
  docId: doc.id,
  oldText: "Prices are in USD",
  newText: "Prices are in BRL",
  changeSummary: "Currency",
});
// Search, and read a part of a text
const { results } = await basement.search({ query: "pricing" });
const found = await basement.text.find({ docId: doc.id, query: "discount" });
// Tasks
const { taskId } = await basement.tasks.create({ title: "Review the Q4 pricing" });
await basement.tasks.update({ taskId, status: "done" });
// Connected services
const { connected } = await basement.services.list();
const issue = await basement.services.execute({
  toolSlug: "jira__getJiraIssue",
  arguments: { issueIdOrKey: "OPS-12" },
});

Handle errors

A call that the Gateway refuses throws a BasementGatewayError with the HTTP status and the error body.

import { BasementGatewayError } from "@basementai/gateway";
try {
  await basement.tasks.create({ title: "Review the Q4 pricing" });
} catch (error) {
  if (error instanceof BasementGatewayError) {
    console.log(error.statusCode); // 403
    console.log(error.body);       // { error: { code: "forbidden", message: "Role lacks write access" } }
  }
}

See Errors and limits for each status.

Timeouts and retries

A call times out after 60 seconds. The client tries a call again, up to 2 more times, when it gets 408, 429 or a 5xx status. Change both for the client or for one call:

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

Another address

The client talks to https://mcp.basement.chat. To use another deployment, give baseUrl:

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