@ligantic/sdk

The official TypeScript SDK for the Ligantic API.

The SDK is a thin, result-based, versioned mirror of the Ligantic OpenAPI v1 surface. Every operation returns Promise<Result<T, LiganticError>> and the SDK never throws — failures are returned as the Err side of the result.

Install

npm install @ligantic/sdk

Requires Node.js 22+.

Quick start

import { Ligantic } from "@ligantic/sdk";

const client = new Ligantic({
  apiKey: process.env.LIGANTIC_API_KEY!,
  // Optional: baseUrl for staging/self-hosted, retry policy, custom fetch.
});

// List Spaces
const spaces = await client.spaces.list();
if (!spaces.ok) {
  console.error(spaces.error.code, spaces.error.message);
  process.exit(1);
}
const spaceId = spaces.value[0]?.id;
if (!spaceId) {
  console.error("No spaces found");
  process.exit(1);
}

// List Records in a Schema
const records = await client.records.list(spaceId, "sc_customer", {
  limit: 10,
  offset: 0,
});

Authentication

API-key only in v1. The key is sent as Authorization: Bearer <key>.

The result model

const result = await client.schemas.get(spaceId, schemaId);

if (result.ok) {
  const schema = result.value; // typed
} else {
  const err = result.error; // LiganticError
  // err.status  — HTTP status, or null for network failures
  // err.code    — e.g. "NOT_FOUND", "UNAUTHORIZED"
  // err.message — human-readable message
  // err.issues  — validation issues (422)
  // err.requestId — x-request-id, when present
}

Capabilities (v1)

| Group | Methods | | --- | --- | | identity | me | | spaces | list, get, create, rename, delete | | schemas | list, get, create, update, delete, getConfig | | records | list, get, create, update, delete, patch (JSON-Patch) | | flows | list, get, create, delete, getBySchema, run, listRuns, getRun, getRunOutputs, cancelRun |

Retries

Idempotent requests (GET, DELETE, PUT) are retried with exponential backoff on transport failures and 408/429/5xx. Mutating requests (POST, PATCH) are never auto-retried.

Compatibility

The SDK is a versioned mirror of the OpenAPI contract. It documents the API version it targets, majors when its own surface breaks, and minors for additive API surface.