Efimis Client TypeScript

TypeScript Efimis API client generated from the Efimis OpenAPI (3.0.x) definition using Hey API.

This package generates a single combined client at src/client/ and re-exports it from src/index.ts.

Install

npm install @forsyteco/efimis-client-typescript

Usage (client credentials)

Efimis authenticates with OAuth2 via Azure AD B2C. Machine-to-machine integrations use the client-credentials grant; the token URL defaults to the value declared in the Efimis spec.

import {
  createRequestScopedClient,
  getApiV1Clients,
  requestClientCredentialsToken,
  requestWithResponse,
} from "@forsyteco/efimis-client-typescript";

const token = await requestClientCredentialsToken({
  clientId: process.env.EFIMIS_CLIENT_ID!,
  clientSecret: process.env.EFIMIS_CLIENT_SECRET!,
  scope: "write",
});

const scoped = createRequestScopedClient({
  baseUrl: process.env.EFIMIS_BASE_URL!,
  auth: token.access_token!,
});

const response = await getApiV1Clients({
  client: scoped.client,
  headers: scoped.headers,
  query: { pageSize: 20 },
  throwOnError: true,
});

const created = await requestWithResponse(scoped, {
  method: "POST",
  url: "/api/v1/clients",
  body: { name: "Example client" },
});

console.log(created.status, created.data);

EFIMIS_BASE_URL is the API host including the environment path segment (for example the sandbox environment path is /sandbox). Use createRequestScopedClient() per request to avoid request-path reliance on shared mutable singleton auth/baseUrl configuration.

Authorization-code / refresh

The spec also declares an authorization-code flow. exchangeAuthorizationCode() and refreshToken() are provided for interactive/user-delegated integrations.

Development

npm install
npm run generate
npm run lint
npm run build

Regenerate Client

npm run generate

The generation flow:

1. Prefers a remote OpenAPI URL (EFIMIS_SPEC_URL env, or openapi/manifest.ts), validates it, and writes it to openapi/openapi.json. If the URL is unset or the fetch/validation fails, falls back to the committed local openapi/openapi.json.
2. Runs Hey API once to produce the combined client at src/client/.

# optional: pin a stable https:// OpenAPI URL for this run
EFIMIS_SPEC_URL=https://example.com/efimis.openapi.json npm run generate

Browser blob: download links from developer.efimis.com are session-only and cannot be fetched from Node/CI. Until Efimis publishes a stable HTTPS OpenAPI URL, keep the latest export in openapi/openapi.json as the fallback.

Hey API owns the src/client/ directory and rewrites it wholesale on every run. The hand-written OAuth (src/auth.ts) and request-scoped transport (src/transport.ts) helpers live at the src/ root, outside the generated directory, so they survive regeneration and are re-exported from src/index.ts.

Generated clients are treated as build artifacts. Re-run generation whenever Efimis updates the published OpenAPI definition.

Publish Checklist

npm run generate
npm run pack:check
npm run publish:public

prepack runs automatically during pack/publish, so lint/build happen before publishing without committing dist.

Release Commands

# choose one semantic version bump
npm run release:patch
npm run release:minor
npm run release:major

CI Publish (npm token)

Set NPM_TOKEN in your CI secret store, then run:

npm ci
npm run generate
npm run lint
npm run build
npm run pack:check
npm run publish:public