Configure the client

Configure transport defaults once. Pass practice context and attribution in request options.

import { Affinity } from "@affinity-health/sdk";

const affinity = new Affinity(process.env.AFFINITY_API_KEY!, {
  timeout: 60_000,
  maxNetworkRetries: 0,
});

Select a practice

Practice API keys identify their practice automatically. Platforms can scope a client once:

const practice = affinity.forPractice(practiceId);
const patient = await practice.patients.get(patientId);

forPractice() returns a new client without changing the original. A conflicting practice ID is rejected. For one request, pass practiceId in the last argument:

await affinity.patients.update(patientId, { email: "alex@example.com" }, { practiceId });

Attribute an action

Pass actorId and actorType when recording a person or worker in your platform. Attribution does not grant signing authority or identify the prescription’s prescriber.

await practice.patients.update(
  patientId,
  { email: "alex@example.com" },
  { actorId: session.user.id, actorType: "user" },
);

Signing still requires the clinician’s approval, attestation, and exact reviewed order revision.

Retries and cancellation

Retries default to zero. When enabled, reads and keyed writes retry connection failures, timeouts, and HTTP 429, 500, 502, 503, and 504 responses. Generated keys remain unchanged within one call. Persist explicit keys for consequential actions so a retry from another process uses the same key. Retry delays honor Retry-After and are capped at 30 seconds.

const patient = await practice.patients.get(patientId, {
  signal: AbortSignal.timeout(10_000),
});

An aborted signal also cancels retry waits.