circleso

TypeScript SDK for Circle's Admin V2, Headless Member V1 and Headless Auth APIs. Typed requests and responses, ESM/CJS exports, retries, timeouts, pagination and token refresh.

Installation

Install the stable release:

npm install [email protected]

See v1 release notes for details and migration from 0.3.0 for breaking changes. latest selects 1.0.1; next currently selects 1.0.0-rc.1.

Requires Node.js 22 or 24. TypeScript users need 5.9.3 or newer and DOM/Fetch types. The Member client also supports browsers and browser workers with Fetch and CORS support. Admin, Auth and built-in token refresh run on your server.

Quick start

Admin API

Create an Admin V2 token in Circle and keep it on your server:

import { createAdmin } from "circleso/admin";

const token = process.env.CIRCLE_ADMIN_TOKEN;
if (!token) throw new Error("Missing CIRCLE_ADMIN_TOKEN.");

const admin = createAdmin({ token, timeoutMs: 10_000 });
const posts = await admin.posts.list({ page: 1, per_page: 20 });
console.log(posts?.records ?? []);

Member API

Use a member access token issued by your authenticated server. Keep Headless Auth application tokens and member refresh tokens on the server.

import { createHeadless } from "circleso/headless";

const accessToken = process.env.CIRCLE_HEADLESS_TOKEN;
if (!accessToken) throw new Error("Missing CIRCLE_HEADLESS_TOKEN.");

const member = createHeadless({ accessToken, timeoutMs: 10_000 });
const bookmarks = await member.bookmarks.list({ page: 1, per_page: 20 });
console.log(bookmarks?.records ?? []);

The example above runs on Node. In a browser, obtain the member token from your own server; see authentication and cookies for token issuance, refresh and browser integration.

Choose a client

| Import | Purpose | Credential | | --- | --- | --- | | circleso/admin → createAdmin | Community administration | Admin V2 token | | circleso/headless → createHeadless | Member actions | Member access token | | circleso/auth → createAuth | Issue, refresh and revoke tokens | Headless Auth application token | | circleso → CircleSo | All three clients together on a server | Credentials for each client |

All entry points support ESM import and CommonJS require. Each client exposes a typed raw OpenAPI client for lower-level requests.

Configuration

• baseUrl defaults to https://app.circle.so.
• Admin's communityHost sets its Host header, defaults to app.circle.so, and requires a custom server transport when it differs from the destination. Native Fetch removes Host overrides.
• timeoutMs covers each attempt through response-body completion. Set it explicitly; the default has no deadline. Pass a per-call signal to cancel across retries.
• Retries default to two for eligible methods and failures, including rate limits. POST/PATCH are not retried by default. For deliberate mutations, set retries: { retries: 0 }.
• Named methods take flat query/body options, for example { page: 1, per_page: 20 }.

See client configuration for all options, retry behavior, token refresh and redacted logging, and request options for serialization.

Error handling

Named methods throw SDK errors. Catch CircleHttpError for HTTP failures:

import { CircleHttpError, createAdmin } from "circleso/admin";

const token = process.env.CIRCLE_ADMIN_TOKEN;
if (!token) throw new Error("Missing CIRCLE_ADMIN_TOKEN.");
const admin = createAdmin({ token, timeoutMs: 10_000 });

try {
  await admin.posts.list({ page: 1, per_page: 20 });
} catch (error) {
  if (error instanceof CircleHttpError) {
    console.error("Circle request failed", error.status);
  } else {
    throw error;
  }
}

Other failures use CircleNetworkError, CircleTimeoutError or CircleConfigError. Raw clients return { data, error, response } for HTTP responses; check response.ok. Error bodies and causes may contain sensitive data; keep diagnostics redacted.

Documentation

• API reference — clients, resources, types and schema limitations
• Pagination — bounded async iterators
• File uploads and rich text
• Usage controls — optional concurrency, queues and request budgets
• Examples
• Support and compatibility, changelog and security reporting
• Contributing

License

MIT