@arbol-ai/sdk

The Arbol API for TypeScript and JavaScript, generated by Cloudflare Forge from the platform's public OpenAPI, https://api.getarbol.com/openapi.json. Everything in src/ is Forge's TypeScript output, unedited. Versions are semver, and each one records the OpenAPI it was generated from: npm view @arbol-ai/sdk@<version> arbol.openapi prints its release (info.version) and content hash (sha256).

npm install @arbol-ai/sdk

import { ApiError, createClient } from '@arbol-ai/sdk';

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

const { data } = await arbol.agenda.appointments.get({ appointmentId: 'eng_…' });
data.startsAt; // Temporal.Instant

Every operation is client.<service>.<resource>.<verb>(request, options?), with its request and response types beside it (agenda/appointments: GetRequest, GetResponse, …).

Only the clients you use

Each service and each of its resources is also an entry of its own, with its own createClient, so an application bundles only what it calls instead of every service's:

import { createClient } from '@arbol-ai/sdk/account/organization';
import type { AccountCurrentOrganization } from '@arbol-ai/sdk/account/organization';

const organization = createClient({ baseUrl: 'https://api.getarbol.com', token });

const { data } = await organization.get();

@arbol-ai/sdk/<service> is one service (client.<resource>.<verb>) and @arbol-ai/sdk/<service>/<resource> one resource (client.<verb>), named as in src/ (account/members, agenda/appointments, nuevaEps/…); each exports its types and ApiError.

Credentials

token is sent as Authorization: Bearer <token>. It is one of:

• an Arbol API key, created in Arbol Account. Keep it in a secret manager and never ship it to a browser;
• an access token for the audience https://api.getarbol.com, from any OAuth client, such as a person's session in your app.

The SDK holds no OAuth logic: sign people in however your application does, and create a client with the token you have.

Responses and errors

A method resolves with the response the API declares: { success: true, data, error: null, metadata }. Any other status throws ApiError, with status, the response, and its declared body in details ({ success: false, error: { code, message, retryable, data }, metadata }).

Each call sends one request and is never retried. Pass fetch to send requests through your own function, headers or query to add to every request, and signal to abort a call.

The server authorizes every call: a method in the client is not a grant.

Requirements

date-time fields are Temporal.Instant and date fields Temporal.PlainDate, so the runtime needs fetch and Temporal (Node.js 26, Bun 1.4, current browsers), and TypeScript needs "lib": ["ESNext"].

Development

bun install
bun run forge       # build the pinned Cloudflare Forge with cargo into .forge/ (once; needs Rust)
bun run openapi     # download https://api.getarbol.com/openapi.json
bun run generate    # src/ from openapi.json with `forge --target ts`; its release and hash in arbol.openapi
bun run hash        # the OpenAPI's content hash (see Releases)
bun run verify      # typecheck and build dist/

openapi.json is downloaded at generation time and not committed. package.json's arbol.openapi records the OpenAPI src/ was generated from, its info.version as release and its content hash as sha256; version and arbol are release metadata the workflows set. Forge is pinned to its commit 7f86447210b7bea3779bfdab3cd5655eade0eadb (0.1.0) in the forge script.

Releases

Versions are semver, independent of the OpenAPI's release number. The 1.x versions (1.YYYYMMDD.n) were the OpenAPI's date releases; 2.x starts at 2.1.0.

Releases of a new OpenAPI are automatic, from the API down to the CLI:

1. Gateway. When the Arbol API ships an OpenAPI release, the gateway sends this repository a repository_dispatch openapi-release with { "version": "<release>" }.
2. SDK (this repository). Generate runs on that dispatch, every six hours, and by hand. It downloads the OpenAPI (waiting until the API serves the announced release) and hashes its content. When the hash differs from arbol.openapi.sha256 in package.json, it regenerates src/ with Forge, records the OpenAPI in arbol.openapi, and takes the highest version on npm with the minor raised and the patch at 0 (2.1.0, 2.2.0, 2.3.0, …). It verifies the result, commits Release <version> to main as Arbol, and publishes @arbol-ai/sdk to npm with Publish. Package access stays public while the source repository is private. Provenance is disabled because npm does not support it for private source repositories.
3. CLI. After publishing, Publish sends project-arbol-cli a repository_dispatch sdk-release with { "version": "<published version>", "openapi": { "release": "…", "sha256": "…" } }, the published version and arbol.openapi, and the CLI releases itself on it.

The hash (scripts/release.ts) is the SHA-256 hex of the OpenAPI's canonical JSON (object keys sorted recursively, arrays in order, no whitespace) with info.version removed. A new release number with an identical API hashes the same, so Generate commits, publishes, and announces nothing. A version on main that is not on npm yet, such as one a failed run left behind, is published by the next run.

Changes to the SDK itself, such as a new Forge pin, are released by hand: commit them to main (regenerated with bun run generate when they change src/), then run Publish on main with bump patch (the default), minor or major:

gh workflow run publish.yml --repo getarbol/project-arbol-sdk-js --ref main -f bump=patch

It raises that part of the highest version on npm (while no 2.x version is published, the result is 2.1.0 whatever the bump), commits Release <version> to main, publishes it, and announces it to the CLI like Generate. It refuses when main's version is not on npm yet (run Generate, which publishes it), and when nothing that goes into the package (src/, package.json, tsconfig.json, bun.lock, README.md, LICENSE) changed since the commit that released main's version, so the same SDK is never published twice. A manual release and Generate wait for each other.

Generate and Publish push and dispatch as the Arbol Bot GitHub App, so their commits to main run Verify. They need the organization variable ARBOL_BOT_APP_ID, the organization secret ARBOL_BOT_PRIVATE_KEY, and the App installed with contents write access to this repository and project-arbol-cli. npm publishing uses the organization secret NPM_TOKEN.

Migrating to SDK 5

SDK 5 follows the current public owner contracts across the platform. Update Account calls inherited from SDK 3:

Agenda booking discovery now uses bookingLocations.list, bookingOfferings.list, bookingRequirements.get, bookingSlots.list and nearestBookingSlots.list. bookings.lookup replaces bookings.list; firstAvailability.get replaces availability.first; resourceSchedules.update replaces scheduleRules.replace. Schedule rules use separate create and update methods instead of upsert.

SURA uses appointments.lookup, bookingOptions.lookup, availability.lookup and copays.lookup in place of appointments.list, appointments.prepare, availability.list and copays.list. Lookups containing personal data use the owner's current JSON request body. gMedic also exposes patients.lookup.

Account resource identifiers now use apiKeyId, billingProfileId, invitationId, invoiceId and memberId in place of id, as the generated request types declare. Connection create, update and delete are staff-user operations outside the public SDK. Authorized staff use the private operator CLI; credential-bearing operations remain outside MCP. Account still owns and enforces those permissions.

Shared generated model exports also follow the current schema names. Update explicit model imports using the compiler's diagnostics. The client constructor, response envelope, ApiError and Temporal values keep their existing behavior.

License

Apache License 2.0

Publishing a prepared source commit

The Publish workflow accepts an existing main-branch ref to publish without creating a release commit. Set announce to false when coordinating the CLI release separately. Generation applies scripts/forge-path-segments.patch to the pinned Forge transport so a path identifier of . or .. fails before a request can reach a different route. The generation step fails if a future Forge version changes the patched code.

Publication runs the same type checks, SDK unit tests and build as pull requests. Run bun test ./tests to exercise the generated public client independently.