Skip to content

@opensteward/sdk — getting started

Official TypeScript SDK for OpenSteward. Two clients in one package:

  • Public client — for tenant developers consuming the unified /v1/* integration API. Auth: tenant Bearer API key (osk_…), or an OIDC bearer token from the operator’s identity provider.
  • Operator client — for operators and CI scripts driving the admin-api (/api/*). Auth: JWT issued by POST /api/auth/login, with built-in helpers to manage it.

Both clients are generated from the committed OpenAPI specs (docs/openapi/openapi.json and docs/openapi/admin-api.openapi.json), so every route in either spec is type-checked at compile time. Adding or renaming a route in the source spec → rerun pnpm sdk:generate → the new path appears in the SDK with no manual editing.

Terminal window
pnpm add @opensteward/sdk
# or: npm i @opensteward/sdk
# or: yarn add @opensteward/sdk

Needs a runtime with global fetch; the package declares no engines floor of its own, and the monorepo builds on Node 24+. No browser-only dependencies — the public client runs in browsers and on Node; the operator client’s fromCredentialsFile() helper is Node-only because it reads disk.

import { createPublicClient } from '@opensteward/sdk'
const client = createPublicClient({
baseUrl: 'http://localhost:3010',
apiKey: process.env.OPENSTEWARD_API_KEY!,
})
// Typed end-to-end: path, query params, response shape.
const { data, error } = await client.GET('/customers', {
params: { query: { limit: 10 } },
})
if (error) {
console.error('list failed', error)
process.exit(1)
}
for (const c of data!.data) {
console.log(c.id, c.displayName)
}

baseUrl is the bare host — no /v1. The client appends the version segment itself, per path (details below). A baseUrl ending in /v1 double-prefixes to /v1/v1/… and 404s on every call.

Pass mode: 'test' and every versioned call routes to the deployment’s /test/v1/* sandbox — synthetic data seeded from the documented schema examples, no upstream calls, and writes that persist until DELETE /test/v1/reset:

const sandbox = createPublicClient({
baseUrl: 'http://localhost:3010',
mode: 'test', // default: 'live'
apiKey: process.env.OPENSTEWARD_TEST_API_KEY!, // a key minted with --test
})
// Discover the sandbox's synthetic connection ids — no setup step needed.
const { data } = await sandbox.GET('/test/v1/connections')

The two modes never share a credential: a live key on /test/v1/* answers 403 KEY_MODE_MISMATCH, and so does the reverse. Going to production is therefore exactly two edits: drop mode: 'test' and swap in the live key. The sandbox accepts osk_test_ keys only — OIDC bearer tokens are refused there by design (the verifier would need egress the sandbox promises not to have).

Where the deployment’s operator has registered an identity provider, the same routes accept a short-lived token from it. Pass getAccessToken instead of apiKey — a function rather than a string, because tokens expire and the client has to be able to ask again:

import { createPublicClient, clientCredentialsTokenSource } from '@opensteward/sdk'
const client = createPublicClient({
baseUrl: 'http://localhost:3010',
getAccessToken: clientCredentialsTokenSource({
tokenUrl: 'https://idp.example.com/oauth/token',
clientId: process.env.IDP_CLIENT_ID!,
clientSecret: process.env.IDP_CLIENT_SECRET!,
// The API identifier the operator registered as the issuer's audience.
audience: 'https://opensteward.internal',
}),
})

clientCredentialsTokenSource caches the token until a minute before it expires and collapses concurrent callers into one request, so a busy client does not hammer the token endpoint. It is deliberately small — if you already have an OAuth library, hand getAccessToken whatever it gives you:

const client = createPublicClient({
baseUrl: 'http://localhost:3010',
getAccessToken: () => myOAuthLibrary.getValidAccessToken(),
})

Nothing else changes. The token resolves to the same scopes an API key does, so every route, error and scope rule below applies identically. Two responses are specific to this pairing: 403 OAUTH_DISABLED means the deployment does not accept OIDC tokens, and 403 API_KEYS_DISABLED means it no longer accepts osk_ keys — ask the operator which they have enabled. Verification failures all answer the same 401 UNAUTHENTICATED, deliberately, so the response cannot be used to enumerate the operator’s service accounts.

Every operation in docs/openapi/openapi.json is callable. Use client.GET, client.POST, client.PUT, client.PATCH, client.DELETE with a path that exists in the spec — your IDE autocompletes both the path and the request shape. Successful list responses are enveloped: { data: [...] }, usually with a meta alongside it.

The spec keeps two namespaces (see dev-api.md §11), and the client reconciles them so one instance serves both:

  • Versioned — /customers, /accounting/invoices, /{vertical}/sync and friends are written without a version prefix in the spec. The client prepends /v1 (or /test/v1 in test mode) to these on the wire.
  • Unversioned — /health, /auth/*, /admin/*, /webhooks/* and the sandbox control routes spell their real path in full and are sent as-is; a generated set (public-unversioned.ts) says which, so it cannot drift from the spec.

So: always pass the bare host. There is no need for a second client instance, and a baseUrl that already carries /v1 is the one configuration that breaks.

import { createOperatorClient } from '@opensteward/sdk'
const op = createOperatorClient({ baseUrl: 'http://localhost:3001' })
// 1. Login — stores the JWT inside the client instance.
await op.login('admin', process.env.OS_PASSWORD!)
// 2. Make typed calls. Authorization header is added automatically.
const { data } = await op.GET('/api/users', {})
console.table(data?.data)
// 3. Done.
await op.logout()

.login() is one of three ways to put a token on the client:

// (a) From an existing JWT (env var, another script, etc.)
op.setToken(process.env.OS_TOKEN!)
// (b) From a credentials file on disk (the path the `os` CLI writes:
// ~/.config/opensteward/credentials.json).
op.fromCredentialsFile('/Users/me/.config/opensteward/credentials.json')
// (c) `await op.login(user, pw)` — covered above.

@opensteward/cli writes that file from os setup, whose first step signs in and persists the JWT to ~/.config/opensteward/credentials.json (file mode 0600, directory 0700). os auth login mints a JWT too, but — like every mechanically generated command — it prints the response rather than saving it. fromCredentialsFile() is the supported way to pick the stored token up in scripts without re-prompting for credentials. Full command reference: operations/cli.md.

op.getToken() // returns the stored JWT, or `null`
op.setToken(null) // clear without calling the API
await op.logout() // POSTs /api/auth/logout, then clears

The package re-exports the underlying paths types so you can derive your own helper types per operation:

import type { PublicPaths, OperatorPaths } from '@opensteward/sdk'
type ListCustomersResponse =
PublicPaths['/customers']['get']['responses']['200']['content']['application/json']
type CreateUserBody =
OperatorPaths['/api/users']['post']['requestBody']['content']['application/json']

openapi-fetch returns { data, error, response } — a tagged union where success has data set and failure has error. The HTTP Response is always available for callers that need raw access (headers, status, body stream).

const { data, error, response } = await client.GET('/customers', {})
if (error) {
console.error(`HTTP ${response.status}`, error)
}

The SDK ships in lock-step with the OpenSteward release that produced its specs. A spec change → pnpm sdk:generate runs as part of pnpm docs:all. CI fails (pnpm check:docs) if the committed generated files drift from the live specs, so the published SDK surface always matches the specs.