TypeScript SDK

Why an SDK?

The REST API is the source of truth, but if you're building in TypeScript or JavaScript you shouldn't need to hand-roll fetches, hand-write types, or hand-parse error responses. @zilfu/sdk is the official client. It is:

• Generated from the OpenAPI spec, so request and response types stay in lockstep with the live API.
• Promise-based, with a single createZilfuClient(...) factory and one namespace per resource.
• Strict on errors — non-2xx responses throw a typed ZilfuApiError, so you can try/catch instead of branching on result.error.
• Multi-instance safe — every call to the factory returns an independent client, so you can talk to multiple workspaces or environments from the same process without them stepping on each other.

It works in Node 18.17+ and any runtime with global fetch (Bun, Deno, Vercel Edge, Cloudflare Workers).

Install

pnpm add @zilfu/sdk
# or
npm install @zilfu/sdk
# or
yarn add @zilfu/sdk

Authenticate

You need a personal access token. If you don't have one, follow the Quickstart — it walks through creating one from Settings → API Tokens.

Configure

import { createZilfuClient } from "@zilfu/sdk";

const api = createZilfuClient({
  baseUrl: "https://zilfu.app/api",
  token: process.env.ZILFU_TOKEN!,
});

createZilfuClient accepts:

Multiple clients can coexist:

const prod    = createZilfuClient({ baseUrl: "https://zilfu.app/api",   token: PROD_TOKEN });
const staging = createZilfuClient({ baseUrl: "https://staging.zilfu.app/api", token: STAGING_TOKEN });

await prod.spaces.list();
await staging.spaces.list();

First Request

const { data } = await api.spaces.list();
console.log(data); // { data: [{ id: 1, name: "..." }, ...] }

Most endpoints are scoped to a space:

const space = data!.data[0]!;
const posts = await api.posts.list({ path: { space: space.id } });

Errors

Any non-2xx response throws a typed ZilfuApiError:

import { ZilfuApiError } from "@zilfu/sdk";

try {
  await api.posts.create({
    path: { space: "1" },
    body: { /* invalid */ },
  });
} catch (e) {
  if (e instanceof ZilfuApiError) {
    console.log(e.status);   // e.g. 422
    console.log(e.message);  // human-readable summary
    console.log(e.errors);   // Laravel-style { field: ["msg", ...] } map, when present
    console.log(e.body);     // raw response body
  }
}

Network failures (DNS, TLS, abort, timeout) surface as ZilfuApiError with status: 0 and the underlying error in body.

See the Rate Limits page for handling 429 responses specifically — the SDK respects Retry-After if you read it from e.body, but it does not retry automatically.

Custom fetch

For retries, logging, or edge runtimes:

import { fetch as undiciFetch } from "undici";

const api = createZilfuClient({
  token: process.env.ZILFU_TOKEN!,
  fetch: undiciFetch,
});

Types

Every request and response type is exported from the package:

import type {
  PostResource,
  SpaceResource,
  AccountResource,
  WebhookResource,
  StorePostRequest,
} from "@zilfu/sdk";

Methods

The SDK exposes one namespace per resource. Every method takes a single options object (path, query, body as needed) and returns Promise<{ data, response }>. On non-2xx, it throws.

health

spaces

slots

queue

accounts

posts

clusters

A cluster is a multi-account post group. Update one cluster atomically with:

media

// FormData upload
const fd = new FormData();
fd.append("file", file);
const { data } = await api.media.create({ body: { file } });

apiTokens

webhooks

subscription

bio and bio.blocks

The link-in-bio page lives under bio; its blocks live under bio.blocks.

API Reference

The SDK is regenerated from the live OpenAPI spec on every change. See the API Reference for the full request/response schemas and try-it-now playgrounds.