@yourera/canvas-client

The one HTTP client every service uses to talk to Canvas FHIR. Shared package, not a service. Lives in packages/canvas-client/ in the platform monorepo.

Overview

Canvas-client is a single package, not a service. Every sidecar that needs to read or write Canvas FHIR imports it and speaks to Canvas through a typed client instance. This gives us one place to manage OAuth, one place to apply retry / rate-limit / timeout policy, one error taxonomy to match on, and one source of truth for the FHIR resource shapes we actually use.

What's in it

• OAuth2 client_credentials flow with token cache and single-flight refresh.
• HTTP transport with 401 refresh-retry, 429 rate-limit surfacing, 5xx exponential backoff with jitter, and AbortController-based timeouts.
• Error taxonomy of seven typed errors, each carrying the Canvas response body where relevant.
• FHIR primitives — typed helpers for the datatypes that show up everywhere (Reference, Identifier, CodeableConcept, etc.).
• Resource wrappers for the 16 Canvas resources we read or write.
• Webhook verifier — HMAC-SHA256 signature check with timing-safe compare, used by webhook-receiver.

What's NOT in it

• Caching of Canvas data. The client caches tokens, not responses. Sidecars that need hot reads build materialized views fed by Canvas webhooks (see webhook-receiver).
• Business logic. No MRN generation, no atomicity semantics, no saga state. Those live in the caller.
• Service discovery. The base URL is injected at construction; no ambient service locator.

Status

Install & Construct

It's a workspace package. Add it to the consumer's package.json:

{
  "dependencies": {
    "@yourera/canvas-client": "workspace:*"
  }
}

Construct once per service, inject via DI or factory:

import { createCanvasClient } from '@yourera/canvas-client';

const canvas = createCanvasClient({
  baseUrl: process.env.CANVAS_BASE_URL!,
  clientId: process.env.CANVAS_CLIENT_ID!,
  clientSecret: process.env.CANVAS_CLIENT_SECRET!,
  timeoutMs: 10_000,
  maxRetries: 3,
});

const patient = await canvas.patient.create({
  name: [{ given: ['Jane'], family: 'Doe' }],
  telecom: [{ system: 'email', value: 'jane@example.com' }],
  identifier: [{ system: 'https://yourera.com/mrn', value: 'YR-A1B2C3D4E5' }],
  managingOrganization: { reference: 'Organization/abc-123' },
});

OAuth & Token Cache

Canvas uses OAuth2 client_credentials. The client maintains an in-memory token cache keyed by client_id. Tokens are refreshed when they're within 60 seconds of expiry. Concurrent requests hitting an expired token trigger a single-flight refresh — all waiters receive the same refreshed token, and exactly one network call is made.

HTTP Transport

Every request goes through a shared transport layer that applies:

Error Taxonomy

Seven concrete error classes. All extend a shared CanvasError base so callers can instanceof-branch.

FHIR Primitives

Typed helpers for the FHIR datatypes we actually use. Reduces boilerplate and makes lint enforce shape consistency.

Resource Wrappers

Sixteen resource wrappers. Each exposes the subset of operations we use (usually create, get, update, and sometimes search).

Webhook Verifier

Canvas signs outbound webhook POSTs with HMAC-SHA256 over the raw body. The client exports a verifyCanvasWebhook(rawBody, signatureHeader, secret) helper that performs a timing-safe comparison and returns a boolean. Used exclusively by webhook-receiver.

import { verifyCanvasWebhook } from '@yourera/canvas-client';

const ok = verifyCanvasWebhook(rawBody, req.headers['x-canvas-signature'], secret);
if (!ok) {
  // log verbatim for forensics, respond 401, DO NOT dispatch
}

Testing

1065 unit tests under packages/canvas-client/src/**/*.test.ts. Coverage areas:

• Token cache behavior (cold start, near-expiry refresh, single-flight concurrency).
• Every retry path, including jitter bounds and max-retry exhaustion.
• Every error class from every status code + response-body shape we've seen in the wild.
• FHIR primitive builders (round-trip tests through JSON.parse).
• Every resource wrapper op (create, get, update, search where applicable).
• Webhook verifier: known-vector match, tamper rejection, timing-attack resistance via statistical equal-time test.

We deliberately avoid mocking Canvas at the HTTP layer in integration tests; consumers use MSW or Nock to simulate. The canvas-client's own tests use a small in-package transport stub.

TODOs & Future Waves

• Bulk export. $export and async FHIR bulk APIs are not wired. Compliance tooling currently paginates; a bulk wrapper is a Wave C item.
• Subscription resource. Not used yet — we rely on Canvas console-configured webhooks. When we move to programmatic subscription management we'll add a Subscription wrapper.
• SMART-on-FHIR user tokens. Only client_credentials today. Patient-token flows are out of scope until we need end-user scoping (not foreseeable in current roadmap).
• Structured log redaction. Responses are logged at debug level with no PHI redaction. Fine for staging, but we'll want field-level redaction before production log forwarding.
• OpenTelemetry tracing. Context propagation is manual; a proper OTel layer with Canvas as a span boundary is deferred.