@clinia/context-engine-js

TypeScript client for the Clinia Context Engine API. A thin, typed wrapper over openapi-fetch — request/response shapes are generated from the OpenAPI contract, so paths, params, and bodies are fully type-checked. Works in Node 20+ and modern browsers on the standard fetch.

Install

npm install @clinia/context-engine-js

Published on npm. No registry configuration or authentication is needed.

While the engine is in release-candidate phase, the newest build is under the rc dist-tag:

npm install @clinia/context-engine-js@rc

This package is ESM-only ("type": "module"). require() of it throws ERR_REQUIRE_ESM; use import, or a dynamic await import() from CommonJS.

Exports

| Export | Description | | ------------------------------------------ | --------------------------------------------------------------------------- | | ContextEngineClient | Entry point. Holds a low-level http client. | | HttpClient | Typed openapi-fetch wrapper (GET/POST/PUT/PATCH/DELETE, use). | | ContextEngineClientOptions | Constructor options (alias of HttpClientOptions). | | createClientCredentialsTokenProvider | Builds a caching OAuth2 client-credentials token provider. | | TokenProvider, ClientCredentialsConfig | Auth types. | | paths, generated request/response types | Emitted from the OpenAPI spec. |

Usage

Every Clinia workspace requires authentication. Create OAuth credentials in the Console — scoped to your workspace, with Read & Write if you intend to ingest data or create patients — then point baseUrl at your workspace:

import { ContextEngineClient } from "@clinia/context-engine-js";

const client = new ContextEngineClient({
  baseUrl: "https://<workspace-id>.w.clinia.cloud",
  auth: {
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
  },
});

const { data, error } = await client.http.GET("/v1/patients");

That is the whole configuration. The client resolves Clinia's authorization server, acquires a bearer token, caches it, refreshes it before expiry, and attaches Authorization: Bearer <token> to every request. Tokens last an hour; you do not manage them.

The http client exposes the typed verbs directly, and the path, path params, query, and body are all checked against the OpenAPI contract:

await client.http.GET("/v1/patients/{patientId}/read", {
  params: { path: { patientId: "abc" } },
});

Responses are { data, error } — nothing throws on a non-2xx.

Without authentication

Omit auth entirely and the client sends no Authorization header. Useful against a server that does not require one — a stub or recorded fixture in your own tests:

const client = new ContextEngineClient({ baseUrl: "http://localhost:8000" });

An http:// base URL is fine here. Note this is about the client sending no credentials: a Clinia workspace always requires them, so pointing an unauthenticated client at one yields 401s on every request rather than a clear startup failure.

Bring your own token

For a token you obtained elsewhere, a different grant, or a custom refresh strategy, pass auth a function instead of a config object. It is called per request and returns the token to attach:

const client = new ContextEngineClient({
  baseUrl: "https://<workspace-id>.w.clinia.cloud",
  auth: async () => myTokenStore.getValidAccessToken(),
});

createClientCredentialsTokenProvider returns exactly such a function, so you can share one cached provider across several clients (or transports):

import {
  ContextEngineClient,
  createClientCredentialsTokenProvider,
} from "@clinia/context-engine-js";

const getAccessToken = createClientCredentialsTokenProvider({
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
});

const client = new ContextEngineClient({ baseUrl, auth: getAccessToken });
// The same provider can also feed a non-REST channel, e.g. an MCP transport.

Middleware

http.use(...) / http.eject(...) accept openapi-fetch middleware for cross-cutting concerns (logging, tracing, custom headers). The auth option is implemented as such a middleware internally.

Options

| Option | Type | Description | | --------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | baseUrl | string | Context Engine workspace base URL. Required. | | fetch | typeof fetch | Custom fetch (also used for the token exchange). Defaults to global. | | auth | ClientCredentialsConfig \| (() => string \| Promise<string>) | OAuth2 client-credentials config (common case) or a per-request token function (escape hatch). |

Development

pnpm generate   # regenerate types from ../../openapi/context-engine.yaml
pnpm build      # bundle (tsup) + emit declarations (tsc)
pnpm typecheck

Tests run from the repo root (Vitest discovers this package's vitest.config.ts):

pnpm test                                   # whole workspace
pnpm vitest run --project context-engine-js # this package only

License

Apache-2.0 © Clinia Health Inc.