@circlesac/credentials

Circles credentials for Node and Bun

Official Node and Bun implementation of the Circles credential-provider contract. The language-neutral schemas live in the same repository so this SDK verifies the same behavior as the Go implementation.

The package is ESM-only and runs on Node.js 18 or later and Bun.

import { createCredentialProvider } from "@circlesac/credentials"

const provider = createCredentialProvider()
const credential = await provider.resolve()

await fetch("https://api.circles.ac/users/me", {
  headers: { Authorization: `Bearer ${credential.value}` },
})

Resolution supports explicit credentials/providers, canonical and compatibility environment variables, shared named profiles, legacy crcl migration, direct OAuth refresh, atomic persistence, and cross-process refresh locking. Errors use stable CirclesCredentialError.code values and never contain secrets.

Interactive clients can store one profile per Circles OAuth environment and verified email, such as prod:[e-mail], and call setCurrentProfile(profile). Resolution uses that shared current profile before the legacy default, while an explicit or environment-selected profile still wins.

Development

Requires Node.js 18 or later and Bun 1.2.2.

bun install --frozen-lockfile
bun run typecheck
bun run test
bun run build
bun run test:node

Publishing is performed by the manual GitHub Actions release workflow after the package version has been updated and the checks above pass.