@haau3/sdk
The TypeScript SDK for the haau3 platform API, as typed calls:
- Scheduling: open appointment slots from many SMART Scheduling Links publishers, in one search.
- Medical Benefits: Medicare Advantage and ACA Marketplace plans as FHIR
InsurancePlan, searchable by state or county, and which providers are in a plan's network. - MedList: one reconciled medication list from one patient's FHIR medication records.
On the same key and FHIR base: RxNorm, LOINC and ICD-10-CM lookups, value sets and code validation (Terminology), practitioners and organizations from CMS's National Provider Directory (Provider directory), and standard FHIR Questionnaires such as the PHQ-9.
The haau3 platform API is in preview: it may change as we build, usually to add features or improve performance.
Also for Python: haau3 on PyPI, and for Go:
github.com/haau3/haau3-go.
Install
npm install @haau3/sdk
Node 22 or newer. The SDK runs on a server only: it refuses to start in a browser, where your API key would be public.
Authenticate
Create an API key on platform.haau3.com, then set it as
HAAU3_API_KEY or pass it as apiKey. To try the API with no key first, call the Sandbox (see
"The Sandbox" below).
Or make the key from your project's folder with the
haau3 command line: npx haau3 login, then
npx haau3 keys create, which writes it to the project's env file and never shows it. Load that
file when the program starts, such as with node --env-file=.env or process.loadEnvFile().
Next.js loads it into process.env itself.
import { Haau3 } from "@haau3/sdk";
const haau3 = new Haau3(); // reads HAAU3_API_KEY
A first call
// Open appointment slots, here in Cambridge.
const { slots } = await haau3.searchSlots({ city: "Cambridge", state: "MA", limit: 1 });
console.log(slots[0] ?? "No open slots matched.");
FHIR answers are @types/fhir's R4 types, also
exported as fhir4 (import type { fhir4 } from "@haau3/sdk").
One call per service
import { structureDosageRequest } from "@haau3/sdk";
// Scheduling: open appointment slots, here in Boston.
const { slots, total } = await haau3.searchSlots({ city: "Boston", state: "MA", limit: 10 });
// Provider directory: a practitioner by NPI, from CMS's National Provider Directory.
const practitioners = await haau3.searchPractitioner({ identifier: "1093209884" });
// Terminology: a LOINC code's display and properties.
const glucose = await haau3.codeSystemLookup({ system: "http://loinc.org", code: "2345-7" });
// Questionnaires: a form by its id, such as the PHQ-9.
const phq9 = await haau3.readQuestionnaire("44249-1");
// Medical Benefits: a Medicare Advantage or ACA Marketplace plan, and which providers are in its network.
const plan = await haau3.readInsurancePlan("H2406-013-000");
const network = await haau3.checkInsurancePlanNetwork("H3359-038-000", { npi: ["1518929058"] });
// Pharmacy Benefits: what a medication would cost, as the CARIN pharmacy benefit check, from a FHIR
// message Bundle. It is not yet open to customers.
const checked = await haau3.processMessage(message);
// MedList: one reconciled medication list from one patient's FHIR medication records. It receives
// patient data, so send it only under an executed agreement. Test data labelled as such works on
// every plan, and markAsTestData labels a request and every resource in it. Label only made-up data.
const list = await haau3.reconcileMedications(records);
// Structured Sig: a prescription's free-text directions as a FHIR Dosage, each element coded where the
// words support it and a review flag on anything to check. Send the directions, never a patient.
// structureDosageRequest builds the request.
const structured = await haau3.structureDosage(structureDosageRequest({ text: "Take 1 tablet by mouth twice daily" }));
// The Sandbox: the same calls, answered with fixed answers and a test insurer's synthetic data. A test
// key sends every call there (see "The Sandbox" below). Its pharmacy benefit check answers its test
// members only (https://docs.haau3.com/sandbox/example-health-plan).
const sandbox = new Haau3({ apiKey: testKey });
const sandboxChecked = await sandbox.processMessage(sandboxMessage);
Every method, grouped by service, with its request and a link to its page on docs.haau3.com, is in api.md. Each is named by its operationId, with its parameters and its answer typed from the published spec.
The Sandbox
The Sandbox, https://sandbox.haau3.com, is the API's environment to build and test against. It
serves production's operations at production's paths: each answers its documented example request
with a fixed answer, and the pharmacy benefit check is answered by a test insurer with synthetic
data. See docs.haau3.com for what it answers and its limits.
Your key's mode picks where the client sends every call. A test key (haau3_sk_test_…) goes to
the Sandbox, and a live key (haau3_sk_live_…) to production, so HAAU3_API_KEY alone moves an app
from one to the other. The Sandbox also answers with no key at all. With HAAU3_API_KEY unset, name
it as the environment:
const sandbox = new Haau3({ environment: "sandbox" }); // or set HAAU3_ENVIRONMENT=sandbox
const statement = await sandbox.fhirMetadata();
console.log(sandbox.environment, sandbox.baseURL); // "sandbox" "https://sandbox.haau3.com"
A key made before test and live keys goes to production, as a live key does. These are refused when
the client is made, before anything is sent. The error says where the key came from, and its code
says which it is:
- a test key with
environment: "production"(test-key-outside-sandbox); - a live key, or one made before test and live keys, with
"sandbox"or with the Sandbox's address as thebaseURL(live-key-in-sandbox,older-key-in-sandbox); - no key without the Sandbox named (
no-api-key); - an
environmentthat abaseURLon the other environment's address contradicts (environment-conflicts-with-base-url); - a key with anything before its
haau3_sk_prefix, such as the quotes an env file kept (api-key-not-alone).
environment and baseURL on the client say what it resolved.
sandboxProcessMessage and sandboxMetadata, the Sandbox's first address at
/v1/sandbox/fhir/r4, are deprecated: call processMessage and fhirMetadata instead. Until the
address goes, a client sending to the Sandbox's own host sends them to those operations there. The
raw request() sends a path as it is given, so a first-address path sent on a test key goes to the
Sandbox's host, which does not serve it.
With an AI coding agent
An agent can read the docs directly:
- docs.haau3.com/llms.txt lists every docs page as Markdown.
- docs.haau3.com/skill.md is an
Agent Skill that says what the platform does and how to call
it.
npx skills add https://docs.haau3.comadds it to your project's coding agents. https://docs.haau3.com/mcpis an MCP server that searches the docs. To add it:- Claude Code:
claude mcp add --transport http haau3 https://docs.haau3.com/mcp - Codex:
codex mcp add haau3 --url https://docs.haau3.com/mcp - Cursor, in
.cursor/mcp.json:{ "mcpServers": { "haau3": { "url": "https://docs.haau3.com/mcp" } } } - VS Code:
code --add-mcp '{"name":"haau3","type":"http","url":"https://docs.haau3.com/mcp"}'
- Claude Code:
The haau3 command line lets an agent act without ever seeing
a key. npx haau3 doctor --json checks the project's setup, and npx haau3 test --json makes one
call to each service, in the Sandbox when there is no key. npx haau3 login, then
npx haau3 keys create, puts a key in the project's env file after a person approves in the
browser.
Options
| Option | Default | |
|---|---|---|
apiKey | process.env.HAAU3_API_KEY | Your platform API key. A test key calls the Sandbox, a live key production. |
environment | process.env.HAAU3_ENVIRONMENT, then the key's mode | "production" or "sandbox". Name "sandbox" to call it with no key. |
baseURL | process.env.HAAU3_BASE_URL, then the environment's address | Where the API is, for a stand-in or a proxy. The API key is sent there only. |
timeout | 65000 | Milliseconds one attempt may take. |
maxRetries | 1 | Retries after a timeout, a network failure, a 429 or a 5xx. |
fetch | the global fetch | The fetch to send requests with. |
fetchOptions | { cache: "no-store" } | Passed on to fetch with every request, for any runtime. |
appInfo | none | Your app's name, version and URL, sent in the User-Agent after the SDK's own. |
Each call takes { timeout, maxRetries, signal, correlationId, headers, fetchOptions } as its last
argument, for that call only:
await haau3.searchSlots({ state: "MA" }, { timeout: 10_000, maxRetries: 0 });
An operation that declares a header of its own takes it as one more option, named from the header
and typed from the spec. processMessage takes payerAuthorization, sent as Payer-Authorization:
a member's own authorization at their insurer, Bearer and the access token your app got from the
member's login there. The SDK checks it against the form the API takes before sending, refuses one
the API would not take without repeating it, and holds it nowhere after the call.
const checked = await haau3.processMessage(message, { payerAuthorization: `Bearer ${accessToken}` });
fetchOptions passes anything your runtime's fetch takes, on the client or on one call: a proxy
dispatcher from undici in Node, Cloudflare's cf, Next.js's next, keepalive. The SDK's own
method, headers, body, signal and redirect always win.
import { ProxyAgent } from "undici";
const haau3 = new Haau3({ fetchOptions: { dispatcher: new ProxyAgent("http://proxy.internal:8080") } });
Unless fetchOptions sets cache, every request is sent with cache: "no-store" where the
runtime's fetch takes the field (Node's does; on a runtime that refuses it, the SDK sends none). An
answer is live data for your key, not something a fetch cache should keep. Frameworks that cache
fetch follow it: in Next.js it also keeps next build from sending a request while it prerenders
a page, and { next: { revalidate: 60 } } caches an answer there instead. { cache: undefined }
sends no cache at all.
appInfo names your app in the User-Agent, after the SDK's own, when you build a library, a plugin
or a command line on the SDK. It takes a name, and a version and a url if you have them, and
every request the client sends carries them:
const haau3 = new Haau3({ appInfo: { name: "my-plugin", version: "1.2.0" } });
// User-Agent: haau3-node/<version> (node 24) my-plugin/1.2.0
A name and a version each take letters, digits, -, ., _ and the other characters RFC 9110
allows in a User-Agent product, with no space or slash. A url is an http or https URL, sent in
parentheses after them. Anything else is refused when the client is made, before a request is sent.
A user-agent in a call's headers replaces the whole User-Agent, the SDK's part included.
A retry waits a short, growing interval, or what the API's Retry-After header says when that is
60 seconds or less. A longer Retry-After fails at once, carrying it.
Errors
Every error is a Haau3Error, with the requestId the API answered with. There are four kinds:
import { AuthError, ForbiddenError, NoAnswerError, RefusedError } from "@haau3/sdk";
try {
await haau3.readInsurancePlan(id);
} catch (error) {
if (error instanceof RefusedError) {
error.status; // 400, 404, 410 and so on
error.code; // why, when the API names it: "not-the-example" from the Sandbox
error.outcome; // the OperationOutcome; Scheduling's errors carry `problem`
} else if (error instanceof NoAnswerError) {
error.reason; // "timeout", "network", "rate-limited", "unavailable", "server-error" or "unreadable"
error.retryAfter; // seconds, when the API said
error.detail; // for a timeout or a network failure: what failed, such as "ECONNREFUSED" or "TimeoutError"
} else if (error instanceof ForbiddenError) {
// 403: the key was accepted, and it may not make this request
error.code; // why, when the API names it: "test-key-outside-sandbox", "live-key-in-sandbox", "phi-agreement-required", "not-open-to-customers"
error.outcome; // why, in the API's words
} else if (error instanceof AuthError) {
// 401: the key was missing, unknown or revoked
}
}
A 403 is a ForbiddenError, never an AuthError: the key was accepted, so there is nothing to
rotate. Its code says why when the API names it, and its message says the same in words. A test
key works only in the Sandbox (test-key-outside-sandbox: send a live key), and a live key does not
work there (live-key-in-sandbox: send a test key). The client sends each key to its own
environment, so you meet these with a baseURL of your own, or by calling the deprecated
sandbox… methods with a live key. phi-agreement-required means the organization
may not send patient data, and not every resource in the request is labelled as test data:
markAsTestData labels made-up data. not-open-to-customers means the operation is not yet open
to customers: an expected answer, not a fault in the request. Without a code, the body says what the
organization may not do.
A RefusedError's code names the API's reason when it gives one: not-the-example from the
Sandbox, which answers each operation's documented example only and refuses any other request.
A client that cannot be made throws a Haau3Error before anything is sent, with a code to branch
on, which the ClientErrorCode type lists. The message says the same for a person and names where
the value came from, the option or the variable:
import { Haau3, Haau3Error } from "@haau3/sdk";
try {
const haau3 = new Haau3();
} catch (error) {
if (error instanceof Haau3Error && error.code === "no-api-key") {
// set HAAU3_API_KEY, or name the Sandbox to call it with no key
}
}
The codes are no-api-key, invalid-api-key, api-key-not-alone, test-key-outside-sandbox,
live-key-in-sandbox, older-key-in-sandbox, invalid-environment, invalid-base-url,
environment-conflicts-with-base-url, invalid-app-info, no-fetch and in-browser. The two the API
also answers with keep the API's names.
When HAAU3_API_KEY has no value but .env.local or .env in the current folder sets it, the
no-api-key message names that file and says how to load it. The SDK looks there only when it has no
key from HAAU3_API_KEY, opens only a regular file, and never keeps or shows the value.
No answer is never reported as an empty result, and an empty result is never an error. An error's
message never includes the body the API answered with, and the body (outcome or problem) is
never printed when the error is logged. Every error the API answered carries attempts,
durationMs and statusText too.
A FHIR answer is checked against the resource types its operation answers with. Anything else, a
Bundle where an InsurancePlan was asked for, say, is a NoAnswerError with reason
"unreadable". The check is of the resource type, not of every element inside it: those are typed
as FHIR R4 declares them, and the SDK does not validate each one.
error.toJSON() gives an error as a plain object that is safe to log: its name, its message and the
fields above that are set, and never the body or the cause. JSON.stringify(error) prints the
same.
Request ids and timing
Every method's answer can be awaited as it is, or through .withResponse() for the request id and
timing that came with it, in the same names request() uses:
const { data: plan, requestId, durationMs, attempts } = await haau3.readInsurancePlan(id).withResponse();
It carries status and statusText too: the answer's own text, or the standard one ("OK") when it
came with none, as HTTP/2 answers do.
Quote the requestId when you ask for help: it finds the request in the API's own logs.
To find a request by an id of your own, such as your job's or your trace's, pass it as
correlationId. It must be a UUID, which is all the API keeps; anything else is refused before it
is sent. The API keeps it with its record of the request, and it comes back on the answer and on
every error the API answered:
const { data, correlationId } = await haau3.readInsurancePlan(id, { correlationId: jobId }).withResponse();
Paging
pages() yields a FHIR search's first page and every page after it, following each next link on
the client's own host and stopping at a link to a page already read:
const first = await haau3.searchInsurancePlan({ "coverage-area-state": "NC" });
for await (const page of haau3.pages(first)) {
for (const entry of page.entry ?? []) console.log(entry.resource?.id);
}
resources() yields every resource the search found, across every page:
for await (const resource of haau3.resources(first)) {
if (resource.resourceType === "InsurancePlan") console.log(resource.name);
}
It yields each entry whose search mode is match, or says none. A resource an _include or
_revinclude brought, and a search's own OperationOutcome, are not among them; pages() gives
every entry. Scheduling's searches page with limit and offset, and answer with a total.
matches() gives one page's matches of a type, typed, with no request, and resolve() finds the
resource a reference names in that page, such as one an _include brought:
const page = await haau3.searchHealthcareService({
"service-category": "pharm",
"location.address-state": "FL",
"location.address-postalcode": "33131",
_include: ["HealthcareService:organization", "HealthcareService:location"],
});
for (const pharmacy of haau3.matches(page, "HealthcareService")) {
const organization = haau3.resolve(page, pharmacy.providedBy, { type: "Organization" });
const store = haau3.resolve(page, pharmacy.location?.[0], { type: "Location" });
console.log(pharmacy.name, organization?.identifier?.[0]?.value, store?.address?.city);
}
resolve() follows FHIR's rules for references in a Bundle: an absolute reference is the entry with
that fullUrl; a relative one is resolved against the address of the entry holding it when you pass
that resource as from, and otherwise is the one entry whose address ends in that type and id; #id
is found in from's contained. It is undefined when the page does not hold the resource, and
throws when two entries could be the one meant or the resource is not of type.
Reading a Parameters answer
FHIR operations answer with a Parameters resource whose parts are named: $lookup's display and
property parts, $structure-dosage's dosage part. parameters() gives every part with a name and
parameter() the one, both with no request, as FHIR's own SDKs read one (Firely's Get and
GetSingleValue, HAPI's ParametersUtil). A part holds its value in the value[x] its operation
names. parameter() throws when two parts share the name.
const lookup = await haau3.codeSystemLookup({ system: "http://loinc.org", code: "2345-7" });
console.log(haau3.parameter(lookup, "display")?.valueString);
Each is a client method and a plain function exported by the package, so an answer you stored can be read with no client and no key, in a browser too:
import { parameter, type fhir4 } from "@haau3/sdk";
function dosageOf(stored: fhir4.Parameters): fhir4.Dosage | undefined {
return parameter(stored, "dosage")?.valueDosage;
}
Reading a lookup and a validation
lookupResult() reads a $lookup answer, typed: the code, its system and version, its display,
whether it is abstract (not for use, such as an ICD-10-CM header), every designation and every
property. A property's type names the FHIR type of its value, so checking it narrows the value.
designations() finds a code's names by use and language: a use by its system and code together, a
language as RFC 4647 matches one, so en finds en-US. ICD-10-CM's short title is its SYNONYM_USE
designation, where it differs from the display, and every code system the API holds names the display
again with PREFERRED_FOR_LANGUAGE_USE.
import { designations, SYNONYM_USE } from "@haau3/sdk";
const answer = await haau3.codeSystemLookup({ system: "http://hl7.org/fhir/sid/icd-10-cm", code: "E08.37X1" });
const lookup = haau3.lookupResult(answer);
console.log(lookup.display, lookup.abstract);
console.log(designations(lookup, { use: SYNONYM_USE, language: "en" })[0]?.value);
for (const property of lookup.properties) {
if (property.type === "boolean") console.log(property.code, property.value);
}
validationResult() reads a $validate-code answer, from a code system or a value set: result,
display and message. A display that does not match answers result: false with the code's own
display beside it, which means the code is valid and only the label differs.
const check = haau3.validationResult(
await haau3.codeSystemValidateCode({ url: "http://loinc.org", code: "2345-7", display: "Glucose" }),
);
if (!check.result) console.log(check.message, check.display);
A part either reader does not know is kept, as the answer gave it, in the other list of the level it
was found at, and a part FHIR allows once that comes twice throws. Each is a client method and a plain
function exported by the package, so an answer you stored can be read with no client.
Structured Sig
structureDosageRequest() builds the request $structure-dosage takes from the directions and,
optionally, the medication's codings, RxNorm or NDC, as a FHIR CodeableConcept. RXNORM_SYSTEM and
NDC_SYSTEM are their code systems. It is a plain function, so it builds a batch entry too
(b.structureDosage(structureDosageRequest({ text }))).
The answer is one dosage part, a FHIR Dosage, with a review flag on anything a person should
check. reviewFlags() reads each flag's code, display and the words of the directions it is about,
and the versions the Dosage names:
import { reviewFlags, RXNORM_SYSTEM, structureDosageRequest } from "@haau3/sdk";
const answer = await haau3.structureDosage(
structureDosageRequest({
text: "Take 1 tablet by mouth daily",
medication: { coding: [{ system: RXNORM_SYSTEM, code: "311354" }] },
}),
);
const dosage = haau3.parameter(answer, "dosage")?.valueDosage;
if (dosage) {
const review = reviewFlags(dosage);
for (const flag of review.flags) console.log(flag.code, flag.display, flag.words);
console.log(review.engineVersion, review.vocabularyVersion, review.rxnormRelease);
}
Several requests in one
batch() sends several operations of the FHIR base as one request. The function you pass gets a
builder with the client's own methods, called the same way, which make entries instead of sending.
Each entry gets its own result, in the order given:
const [plan, counties] = await haau3.batch((b) => [
b.readInsurancePlan("H2406-013-000"),
b.listInsurancePlanCounties({ state: "NC" }),
]);
if (plan.ok) {
plan.data; // fhir4.InsurancePlan
} else {
plan.error; // a RefusedError or a NoAnswerError, as readInsurancePlan alone would have thrown
}
A list built in code works the same way:
const lookups = await haau3.batch((b) =>
codes.map((code) => b.codeSystemLookup({ system: "http://loinc.org", code, property: "SHORTNAME" })),
);
Each entry is checked as the call alone is, and fails alone while the others answer. An entry that
fails is not retried. The batch itself is retried, and throws, as any call does, and
.withResponse() gives its request id. The API takes up to 100 entries in up to 1 MiB and gives a
batch 60 seconds, so send a longer list as several batches. Every operation on the FHIR base can go
in a batch except processMessage and reconcileMedications, which the spec marks
x-haau3-batchable: false.
To send a batch Bundle you built yourself, fhirBatch() takes it and returns the
batch-response as it is.
Any operation by its path
get() and post() call an operation by its path: one this version of the SDK has no method for
yet, or one a tool found in the spec. Each takes the path as the spec writes it, a value for each
{name} in pathParams, the query, the body (for post()) and the FHIR types the answer may be
in expects, beside every per-call option. They throw the same errors, and answer
.withResponse(), as every operation's own method does:
const { data: practitioner, requestId } = await haau3
.get<Fhir4.Practitioner>("/v1/fhir/r4/Practitioner/{id}", {
pathParams: { id: "Practitioner-1093209884" },
expects: ["Practitioner"],
})
.withResponse();
Each value is encoded into the path, and an error's message names the path as you wrote it, never a
value. A {name} with no value, or a value with no {name}, is refused before anything is sent.
Any request
request() sends a request as you give it and returns what the API answered, whatever the
status, with its status text, headers, request id, attempts and duration:
const { status, statusText, body, requestId } = await haau3.request({ method: "GET", path: "/v1/scheduling/publishers" });
Versions
The SDK is 0.y.z while the API is in preview: a minor release may change what a method takes or
answers, and a patch release never does. CHANGELOG.md lists every release, and a
release that takes a new version of the API's spec names that version; SPEC_VERSION is the one a
release was generated from.