SDK de TypeScript

@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

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

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.

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.

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.

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:

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.

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 y Reintentos.

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ó:

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).