@haau3/sdk 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian K. Fung Media LLC, doing business as haau3
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,9 +1,134 @@
 # @haau3/sdk
 
-This version, 0.0.0, is an empty placeholder. Install 0.1.0 or newer:
+The TypeScript SDK for the [haau3 platform API](https://docs.haau3.com): scheduling, the provider
+directory, terminology, questionnaires, plan benefits and MedList, as typed calls.
+
+The haau3 platform API is in preview: it may change as we build, usually to add features or improve performance.
+
+## Install
 
 ```sh
 npm install @haau3/sdk
 ```
 
-The SDK's source is [github.com/haau3/haau3-node](https://github.com/haau3/haau3-node).
+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](https://platform.haau3.com), then set it as
+`HAAU3_API_KEY` or pass it as `apiKey`.
+
+```ts
+import { Haau3 } from "@haau3/sdk";
+
+const haau3 = new Haau3(); // reads HAAU3_API_KEY
+```
+
+## A first call
+
+```ts
+const plan = await haau3.readInsurancePlan("H2406-013-000");
+console.log(plan.name);
+
+const { providerLocations } = await haau3.searchProviderLocations({ state: "MA", limit: 10 });
+```
+
+Every operation in the [API reference](https://docs.haau3.com) is a method named by its
+operationId, with its parameters and its answer typed from the published spec. FHIR answers are
+[@types/fhir](https://www.npmjs.com/package/@types/fhir)'s R4 types, also exported as `fhir4`:
+
+```ts
+import type { fhir4 } from "@haau3/sdk";
+
+const bundle: fhir4.Bundle = await haau3.searchPractitioner({ identifier: "http://hl7.org/fhir/sid/us-npi|1518929058" });
+```
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `apiKey` | `process.env.HAAU3_API_KEY` | Your platform API key. |
+| `baseURL` | `https://api.haau3.com` | Where the API is. |
+| `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. |
+
+Each call takes `{ timeout, maxRetries, signal, headers }` as its last argument, for that call only:
+
+```ts
+await haau3.searchSlots({ state: "MA" }, { timeout: 10_000, maxRetries: 0 });
+```
+
+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 three kinds:
+
+```ts
+import { AuthError, 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.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
+  } else if (error instanceof AuthError) {
+    // the key was missing, unknown or revoked
+  }
+}
+```
+
+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.
+
+## Paging
+
+`pages()` yields a FHIR search's first page and every page after it:
+
+```ts
+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);
+}
+```
+
+Scheduling's searches page with `limit` and `offset`, and answer with a `total`.
+
+## Several requests in one
+
+```ts
+const answers = await haau3.fhirBatch({
+  resourceType: "Bundle",
+  type: "batch",
+  entry: [
+    { request: { method: "GET", url: "CodeSystem/$lookup?system=http://loinc.org&code=2345-7" } },
+    { request: { method: "GET", url: "InsurancePlan/$counties?state=NC" } },
+  ],
+});
+```
+
+## Any request
+
+`request()` sends a request as you give it and returns what the API answered, whatever the
+status, with its headers, request id, attempts and duration:
+
+```ts
+const { status, 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.
+
+## License
+
+[MIT](LICENSE)