---
title: "SDK de TypeScript"
description: "Instala @arbol-ai/sdk, crea un cliente y llama a la API de Arbol desde TypeScript o JavaScript."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.getarbol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK de TypeScript

[`@arbol-ai/sdk`](https://www.npmjs.com/package/@arbol-ai/sdk) es la API de Arbol para TypeScript y JavaScript. Se genera a partir del documento OpenAPI público de la API y se publica bajo la licencia Apache 2.0.

## Instalar

```sh
npm i @arbol-ai/sdk
yarn add @arbol-ai/sdk
pnpm add @arbol-ai/sdk
bun add @arbol-ai/sdk
```

El paquete es un módulo ES: cárgalo con `import`.

## Requisitos

- **`fetch` y `Temporal`** en el runtime: Node.js 26, Bun 1.4 o un navegador actual. Los campos `date-time` son `Temporal.Instant` y los campos `date` son `Temporal.PlainDate`.
- **TypeScript** con `"lib": ["ESNext"]` en `tsconfig.json`.

## Crear un cliente

```ts
import { createClient } from '@arbol-ai/sdk';

const arbol = createClient({
  baseUrl: 'https://api.getarbol.com',
  token: process.env.ARBOL_API_KEY!,
});
```

`token` se envía como `Authorization: Bearer <token>`. Es una de estas dos cosas:

- una API key de Arbol, creada en Cuenta. Guárdala en un gestor de secretos y nunca la expongas en un navegador;
- un token de acceso para la audiencia `https://api.getarbol.com`, como la sesión de una persona en tu app.

El SDK no contiene lógica de inicio de sesión: haz que las personas inicien sesión como lo haga tu aplicación y luego crea un cliente con el token que tengas. Consulta [Autenticación](/developers/authentication/).

| Opción | Significado |
|---|---|
| `baseUrl` | Obligatoria: `https://api.getarbol.com`. |
| `token` | Obligatoria: la credencial. |
| `fetch` | Una función con la que enviar las solicitudes, en lugar del `fetch` global. |
| `headers`, `query` | Encabezados y parámetros de query que se agregan a cada solicitud. |

## Llamar a una operación

Cada operación es `arbol.<service>.<resource>.<verb>(request, options?)`, con el nombre de su operation id: `raiz.agents.create` es `arbol.raiz.agents.create()`, y `nueva-eps` es `arbol.nuevaEps`. Las solicitudes y las respuestas están tipadas a partir del documento OpenAPI.

```ts
const { data: agent } = await arbol.raiz.agents.create({
  modality: 'text',
  name: 'Recordatorios de citas',
  instructions: 'Recuerdas a los pacientes de Example Clinic sus próximas citas.',
  language: 'es-CO',
  timeZone: 'America/Bogota',
});

const { data: appointment } = await arbol.agenda.appointments.get({
  appointmentId: 'eng_0f6b2c1e-7d4a-4c3b-9e8f-1a2b3c4d5e6f',
});
appointment.startsAt; // Temporal.Instant
```

Un método resuelve con el envoltorio de respuesta completo, `{ success: true, data, error: null, metadata }`, así que desestructura `data`. El segundo argumento recibe `signal` para abortar la llamada, y `headers` o `query` solo para esta solicitud.

Una lista responde con una página: los elementos están en `data.data`, y `data.pageInfo.nextCursor` pide la siguiente.

```ts
let cursor: string | undefined;
do {
  const { data: page } = await arbol.raiz.agents.list({ status: 'active', cursor });
  for (const item of page.data) console.log(item.id, item.name);
  cursor = page.pageInfo.nextCursor ?? undefined;
} while (cursor);
```

### Importar solo lo que usas

Cada servicio y cada recurso es también una entrada propia del paquete, con su propio `createClient`, para que tu aplicación incluya solo lo que llama:

```ts
import { createClient } from '@arbol-ai/sdk/agenda/appointments';

const appointments = createClient({
  baseUrl: 'https://api.getarbol.com',
  token: process.env.ARBOL_API_KEY!,
});

const { data } = await appointments.get({
  appointmentId: 'eng_0f6b2c1e-7d4a-4c3b-9e8f-1a2b3c4d5e6f',
});
```

`@arbol-ai/sdk/<service>` es un servicio (`client.<resource>.<verb>`) y `@arbol-ai/sdk/<service>/<resource>`, un recurso (`client.<verb>`), con los nombres que usa el SDK, como `agenda/appointments` o `nuevaEps/affiliations`. Cada entrada exporta sus tipos y `ApiError`.

## Errores

Una respuesta con cualquier estado fuera de 2xx lanza `ApiError`, con el `status`, la `response` y, en `details`, el cuerpo de error que declara la API: `{ success: false, error: { code, message, retryable, data }, metadata }`. Un fallo al llegar a la API rechaza con el error que lanza `fetch`.

```ts
import { ApiError, type Failure } from '@arbol-ai/sdk';

try {
  await arbol.raiz.agents.get({ agentId: 'agt_01jd8x5k2m7q9r3t6v8w0y4z1b' });
} catch (error) {
  if (!(error instanceof ApiError)) throw error;
  const failure = (error.details as { error?: Failure } | undefined)?.error;
  console.error(error.status, failure?.code, error.response.headers.get('x-request-id'));
}
```

Cada llamada envía una solicitud y nunca se reintenta. Antes de repetir una escritura que falló sin una respuesta clara, como `502 OUTCOME_UNKNOWN`, lee el estado actual. Consulta [Respuestas y errores](/developers/concepts/responses-and-errors/) y [Reintentos](/developers/concepts/retries/).

La API autoriza cada llamada: un método en el cliente no es un permiso.

## Versiones

Las versiones siguen semver. Una versión mayor trae cambios incompatibles: la 5.0.0, por ejemplo, adoptó los nombres definitivos de los recursos y de los ids en las rutas. Las publicaciones automáticas suben la versión minor, así que fija la versión exacta y revisa cada release antes de actualizar.

Cada versión registra el release de la API a partir del que se generó:

```bash
npm view @arbol-ai/sdk arbol.openapi          # la última versión
npm view @arbol-ai/sdk@5.0.0 arbol.openapi   # una versión en particular
```

Imprime el release (el `info.version` del documento OpenAPI) y un hash SHA-256 del contenido del documento. Fija la versión exacta y verifica tu integración al actualizar (ver [Versiones y actualizaciones](/developers/concepts/versions/)).

Source: https://docs.getarbol.com/developers/sdks/typescript/index.mdx