> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.basement.chat/pt-br/sdks/typescript/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.basement.chat/_mcp/server.

# SDK para TypeScript

O pacote é [`@basementai/gateway`](https://www.npmjs.com/package/@basementai/gateway). O código está no [GitHub](https://github.com/Get-Basement/gateway-typescript).

## Instalar

```bash
npm install @basementai/gateway
```

## Criar o cliente

```typescript
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.

```typescript
// 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.

```typescript
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](/pt-br/sdks/errors-and-limits) 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:

```typescript
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`:

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

> Use o Gateway em Node.js, Bun, Deno ou no navegador.