Configuration

Every option on the OpenAPI singleton, plus runtime config patterns for Node, Edge, and browser environments.

The SDK reads configuration from a single mutable singleton at call time. Set it once at boot, or read from a function for environments where the value changes (cookies, refresh tokens).

The `OpenAPI` singleton

import { OpenAPI } from "@citefoundry/api-client";

OpenAPI.BASE = "https://api.citefoundry.com";
OpenAPI.TOKEN = async () => process.env.CITEFOUNDRY_TOKEN!;
OpenAPI.HEADERS = { "X-Client": "my-app/1.0.0" };
OpenAPI.WITH_CREDENTIALS = false;

Option	Type	Default	Purpose
`BASE`	`string`	`""`	API root. Required.
`VERSION`	`string`	`""`	Optional version tag, sent as a header.
`TOKEN`	`string \| (() => Promise<string>)`	`undefined`	Bearer token or async resolver.
`USERNAME` / `PASSWORD`	`string`	`undefined`	Basic auth — rarely used.
`HEADERS`	`Record<string, string> \| (() => Promise<Record<string, string>>)`	`{}`	Extra headers per request.
`WITH_CREDENTIALS`	`boolean`	`false`	Send cookies (browser only).
`CREDENTIALS`	`"include" \| "omit" \| "same-origin"`	`"include"`	Fetch credentials mode.

Patterns by environment

Node server

Static config at boot. The token comes from a secret manager and is stable for the process lifetime.

import { OpenAPI } from "@citefoundry/api-client";

OpenAPI.BASE = process.env.CITEFOUNDRY_API_URL!;
OpenAPI.TOKEN = process.env.CITEFOUNDRY_TOKEN!;

Next.js server components

The token is the request’s session JWT, which changes per request. Use async-local-storage (unstable_cache or a per-request store) or the function form:

import { OpenAPI } from "@citefoundry/api-client";
import { getCurrentSession } from "./auth";

OpenAPI.BASE = process.env.CITEFOUNDRY_API_URL!;
OpenAPI.TOKEN = async () => {
  const session = await getCurrentSession();
  return session.accessToken;
};

Browser

Don’t ship a long-lived token to the browser. Either:

Use a same-origin session cookie and call the API via a server route that adds the Bearer header on the way out.
Use short-lived JWTs minted server-side and refreshed before expiry.

Setting WITH_CREDENTIALS = true + a same-origin cookie is the simplest pattern for an internal tool.

Edge runtimes

Cloudflare Workers, Vercel Edge, Deno Deploy — they all run the SDK fine. Set OpenAPI.BASE and OpenAPI.TOKEN per request from the worker’s environment binding:

export default {
  async fetch(req, env) {
    OpenAPI.BASE = env.CITEFOUNDRY_API_URL;
    OpenAPI.TOKEN = env.CITEFOUNDRY_TOKEN;
    // ... use DefaultService
  },
};

The same singleton-races caveat applies. For high-concurrency workers, prefer the function form so each request fetches its own token.

Custom fetch

The SDK uses the global fetch. To intercept (logging, tracing, retries), wrap globalThis.fetch before the SDK is loaded, or use a fetch-monkeypatching library that hooks at the runtime level — the SDK doesn’t expose a per-request fetch override yet.

Examples — worked snippets using the patterns above.
Error handling — the 401-refresh-retry pattern.