@haau3/sdk 0.1.2 → 0.2.1

package/README.md

@@ -72,13 +72,32 @@ with its parameters and its answer typed from the published spec.
 | `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. |
 
-Each call takes `{ timeout, maxRetries, signal, headers }` as its last argument, for that call only:
+Each call takes `{ timeout, maxRetries, signal, headers, fetchOptions }` as its last argument, for
+that call only:
 
 ```ts
 await haau3.searchSlots({ state: "MA" }, { timeout: 10_000, maxRetries: 0 });
 ```
 
+`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.
+
+```ts
+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.
+
 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.
 
@@ -106,7 +125,23 @@ try {
 
 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.
+never printed when the error is logged. Every error the API answered carries `attempts` and
+`durationMs` 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"`,
+so what a method returns is always the type it says.
+
+## 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:
+
+```ts
+const { data: plan, requestId, durationMs, attempts } = await haau3.readInsurancePlan(id).withResponse();
+```
+
+Quote the `requestId` when you ask for help: it finds the request in the API's own logs.
 
 ## Paging
 

package/dist/index.cjs

@@ -1,4 +1,41 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/api-promise.ts
+/**
+* What every typed method returns: a promise of the answer, as before, that can also give the
+* request id and timing that came with it.
+*
+* ```ts
+* const plan = await haau3.readInsurancePlan(id);
+* const { data, requestId, durationMs } = await haau3.readInsurancePlan(id).withResponse();
+* ```
+*
+* The request is sent once, when the method is called, whichever way it is awaited.
+*/
+var APIPromise = class extends Promise {
+	#response;
+	constructor(response) {
+		super((resolve) => resolve(void 0));
+		this.#response = response;
+	}
+	/** The answer, its request id, its timing, its status and its headers. */
+	withResponse() {
+		return this.#response;
+	}
+	then(onfulfilled, onrejected) {
+		return this.#response.then((response) => response.data).then(onfulfilled, onrejected);
+	}
+	catch(onrejected) {
+		return this.then(void 0, onrejected);
+	}
+	finally(onfinally) {
+		return this.then().finally(onfinally);
+	}
+	/** `Promise.prototype.then` and friends build plain promises from an APIPromise. */
+	static get [Symbol.species]() {
+		return Promise;
+	}
+};
+//#endregion
 //#region src/errors.ts
 /** What every error this package throws has. */
 var Haau3Error = class extends Error {
@@ -29,9 +66,15 @@ function attachBody(error, body) {
 var AuthError = class extends Haau3Error {
 	name = "AuthError";
 	status;
-	constructor(message, status, requestId, body) {
+	/** How many attempts were made. */
+	attempts;
+	/** Milliseconds from the first attempt to the answer. */
+	durationMs;
+	constructor(message, status, requestId, body, timing) {
 		super(message, requestId);
 		this.status = status;
+		this.attempts = timing?.attempts ?? 1;
+		this.durationMs = timing?.durationMs;
 		attachBody(this, body);
 	}
 };
@@ -43,9 +86,15 @@ var AuthError = class extends Haau3Error {
 var RefusedError = class extends Haau3Error {
 	name = "RefusedError";
 	status;
-	constructor(message, status, requestId, body) {
+	/** How many attempts were made. */
+	attempts;
+	/** Milliseconds from the first attempt to the answer. */
+	durationMs;
+	constructor(message, status, requestId, body, timing) {
 		super(message, requestId);
 		this.status = status;
+		this.attempts = timing?.attempts ?? 1;
+		this.durationMs = timing?.durationMs;
 		attachBody(this, body);
 	}
 };
@@ -62,19 +111,22 @@ var NoAnswerError = class extends Haau3Error {
 	retryAfter;
 	/** How many attempts were made. */
 	attempts;
+	/** Milliseconds from the first attempt to the last failure, waits between attempts included. */
+	durationMs;
 	constructor(message, details) {
 		super(message, details.requestId, details.cause === void 0 ? void 0 : { cause: details.cause });
 		this.reason = details.reason;
 		this.status = details.status;
 		this.retryAfter = details.retryAfter;
 		this.attempts = details.attempts;
+		this.durationMs = details.durationMs;
 		attachBody(this, details.body);
 	}
 };
 //#endregion
 //#region src/version.ts
 /** This package's version, sent in the `User-Agent` header. A test holds it to package.json. */
-const VERSION = "0.1.2";
+const VERSION = "0.2.1";
 //#endregion
 //#region src/transport.ts
 const DEFAULT_BASE_URL = "https://api.haau3.com";
@@ -91,6 +143,18 @@ function inBrowser() {
 	const g = globalThis;
 	return typeof g.window !== "undefined" && typeof g.document !== "undefined" && !(g.navigator?.userAgent ?? "").includes("jsdom");
 }
+/**
+* Whether this runtime's fetch takes a `cache` field. Node's does. Some edge runtimes have refused
+* the field outright, so the no-store default is sent only where it is taken.
+*/
+function cacheFieldTaken() {
+	try {
+		new Request("https://api.haau3.com/", { cache: "no-store" });
+		return true;
+	} catch {
+		return false;
+	}
+}
 function envKey() {
 	return globalThis.process?.env?.HAAU3_API_KEY || void 0;
 }
@@ -138,6 +202,13 @@ function readErrorBody(body) {
 		value: body
 	};
 }
+/** A resource type with its article: "a Bundle", "an InsurancePlan". */
+const withArticle = (type) => `${/^[AEIOU]/.test(type) ? "an" : "a"} ${type}`;
+/** How an answer is named in a message: its resource type when it has a plausible one, never a value. */
+function describeAnswer(body) {
+	const type = body && typeof body === "object" ? body.resourceType : void 0;
+	return typeof type === "string" && /^[A-Z][A-Za-z]{0,63}$/.test(type) ? withArticle(type) : "something that is not a FHIR resource";
+}
 function noAnswerReason(status) {
 	if (status === 429) return "rate-limited";
 	if (status === 502 || status === 503) return "unavailable";
@@ -148,6 +219,8 @@ function noAnswerReason(status) {
 var Transport = class {
 	#apiKey;
 	#fetch;
+	#fetchOptions;
+	#noStoreTaken;
 	/** Where requests go. */
 	baseURL;
 	/** Milliseconds one attempt may take. */
@@ -162,6 +235,8 @@ var Transport = class {
 		if (!fetchImpl) throw new Haau3Error("No fetch: pass one as the fetch option. Node 22 and newer have one.");
 		this.#apiKey = apiKey;
 		this.#fetch = fetchImpl;
+		this.#fetchOptions = options.fetchOptions ?? {};
+		this.#noStoreTaken = cacheFieldTaken();
 		this.baseURL = (options.baseURL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
 		this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
 		this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
@@ -182,50 +257,84 @@ var Transport = class {
 			durationMs: sent.durationMs
 		};
 	}
-	/** Runs one operation of the spec and returns its answer, or throws one of the three errors. */
-	async operation(call, options = {}) {
+	/**
+	* Runs one operation of the spec and returns its answer, or throws one of the three errors. The
+	* answer's `.withResponse()` gives its request id and timing too.
+	*/
+	operation(call, options = {}) {
 		let path = call.path;
 		for (const [name, value] of Object.entries(call.pathParams ?? {})) path = path.replace(`{${name}}`, encodeURIComponent(value));
-		return this.answer(call.method, this.#url(path, call.query), call.body, options, call.path);
+		let url;
+		try {
+			url = this.#url(path, call.query);
+		} catch (error) {
+			return new APIPromise(Promise.reject(error));
+		}
+		return new APIPromise(this.respond(call.method, url, call.body, options, call.path, call.expects));
+	}
+	/** Sends a request and returns its answer only. See {@link Transport.respond}. */
+	async answer(method, url, body, options, label, expects) {
+		return (await this.respond(method, url, body, options, label, expects)).data;
 	}
 	/**
 	* Sends a request and reads its answer. `label` names the request in an error message: the
 	* operation's path with its `{id}` left in, so no value a caller sent ends up in a message.
+	* `expects`, when set, are the FHIR resource types the answer may be; any other is not an answer.
 	*/
-	async answer(method, url, body, options, label) {
-		const { response, text, attempts } = await this.#send(method, url, body, options, label);
+	async respond(method, url, body, options, label, expects) {
+		const { response, text, attempts, durationMs } = await this.#send(method, url, body, options, label);
 		const status = response.status;
 		const requestId = response.headers.get("x-request-id") ?? void 0;
 		const parsed = parseBody(text, response.headers.get("content-type"));
 		const name = `${method} ${label}`;
+		const timing = {
+			attempts,
+			durationMs
+		};
 		if (status >= 200 && status < 300) {
 			if (parsed === void 0) throw new NoAnswerError(`${name} answered ${status} with a body that is not JSON.`, {
 				reason: "unreadable",
-				attempts,
 				status,
-				requestId
+				requestId,
+				...timing
 			});
-			return parsed;
+			if (expects && !expects.includes(parsed?.resourceType)) {
+				const wanted = expects.map(withArticle).join(" or ");
+				throw new NoAnswerError(`${name} answered ${describeAnswer(parsed)} where ${wanted} was expected.`, {
+					reason: "unreadable",
+					status,
+					requestId,
+					...timing
+				});
+			}
+			return {
+				data: parsed,
+				requestId,
+				durationMs,
+				attempts,
+				status,
+				headers: response.headers
+			};
 		}
 		const errorBody = readErrorBody(parsed);
-		if (status === 401 || status === 403) throw new AuthError(`${name} was refused: the API key was not accepted (${status}).`, status, requestId, errorBody);
+		if (status === 401 || status === 403) throw new AuthError(`${name} was refused: the API key was not accepted (${status}).`, status, requestId, errorBody, timing);
 		if (status === 429 || status >= 500) {
 			const reason = noAnswerReason(status);
 			throw new NoAnswerError(`${name} got no answer (${reason}, ${status}) after ${attempts} attempt${attempts === 1 ? "" : "s"}.`, {
 				reason,
-				attempts,
 				status,
 				retryAfter: retryAfterSeconds(response.headers),
 				requestId,
-				body: errorBody
+				body: errorBody,
+				...timing
 			});
 		}
-		if (status >= 400) throw new RefusedError(`${name} was refused (${status}).`, status, requestId, errorBody);
+		if (status >= 400) throw new RefusedError(`${name} was refused (${status}).`, status, requestId, errorBody, timing);
 		throw new NoAnswerError(`${name} answered ${status}, which is not an answer.`, {
 			reason: "unreadable",
-			attempts,
 			status,
-			requestId
+			requestId,
+			...timing
 		});
 	}
 	/** A URL on this client's base, refusing any other host so the key is never sent to one. */
@@ -257,6 +366,11 @@ var Transport = class {
 		for (const [name, value] of Object.entries(options.headers ?? {})) headers[name.toLowerCase()] = value;
 		const timeout = options.timeout ?? this.timeout;
 		const maxRetries = options.maxRetries ?? this.maxRetries;
+		const fetchOptions = {
+			...this.#fetchOptions,
+			...options.fetchOptions
+		};
+		if (this.#noStoreTaken && !("cache" in fetchOptions) && !("next" in fetchOptions)) fetchOptions.cache = "no-store";
 		const started = Date.now();
 		let attempt = 0;
 		for (;;) {
@@ -268,6 +382,7 @@ var Transport = class {
 			let text;
 			try {
 				response = await this.#fetch(url, {
+					...fetchOptions,
 					method,
 					headers,
 					body: payload,
@@ -285,6 +400,7 @@ var Transport = class {
 				throw new NoAnswerError(`${method} ${label} got no answer (${reason}) after ${attempt} attempt${attempt === 1 ? "" : "s"}.`, {
 					reason,
 					attempts: attempt,
+					durationMs: Date.now() - started,
 					cause: error
 				});
 			}
@@ -320,7 +436,8 @@ var Operations = class extends Transport {
 			method: "GET",
 			path: "/v1/fhir/r4/InsurancePlan/{id}/$in-network",
 			pathParams: { id },
-			query: params
+			query: params,
+			expects: ["Parameters"]
 		}, options);
 	}
 	/**
@@ -334,7 +451,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/CodeSystem/$lookup",
-			query: params
+			query: params,
+			expects: ["Parameters"]
 		}, options);
 	}
 	/**
@@ -348,7 +466,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "POST",
 			path: "/v1/fhir/r4/CodeSystem/$lookup",
-			body
+			body,
+			expects: ["Parameters"]
 		}, options);
 	}
 	/**
@@ -362,7 +481,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/CodeSystem/$validate-code",
-			query: params
+			query: params,
+			expects: ["Parameters"]
 		}, options);
 	}
 	/**
@@ -376,7 +496,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "POST",
 			path: "/v1/fhir/r4/CodeSystem/$validate-code",
-			body
+			body,
+			expects: ["Parameters"]
 		}, options);
 	}
 	/**
@@ -390,7 +511,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "POST",
 			path: "/v1/fhir/r4",
-			body
+			body,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -404,7 +526,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/metadata",
-			query: params
+			query: params,
+			expects: ["CapabilityStatement", "TerminologyCapabilities"]
 		}, options);
 	}
 	/**
@@ -418,7 +541,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/InsurancePlan/$counties",
-			query: params
+			query: params,
+			expects: ["Parameters"]
 		}, options);
 	}
 	/**
@@ -473,7 +597,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Endpoint/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["Endpoint"]
 		}, options);
 	}
 	/**
@@ -487,7 +612,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/HealthcareService/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["HealthcareService"]
 		}, options);
 	}
 	/**
@@ -501,7 +627,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/InsurancePlan/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["InsurancePlan"]
 		}, options);
 	}
 	/**
@@ -515,7 +642,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Location/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["Location"]
 		}, options);
 	}
 	/**
@@ -529,7 +657,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Organization/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["Organization"]
 		}, options);
 	}
 	/**
@@ -543,7 +672,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/OrganizationAffiliation/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["OrganizationAffiliation"]
 		}, options);
 	}
 	/**
@@ -557,7 +687,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Practitioner/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["Practitioner"]
 		}, options);
 	}
 	/**
@@ -571,7 +702,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/PractitionerRole/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["PractitionerRole"]
 		}, options);
 	}
 	/**
@@ -587,7 +719,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Questionnaire/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["Questionnaire"]
 		}, options);
 	}
 	/**
@@ -601,7 +734,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "POST",
 			path: "/v1/fhir/r4/$reconcile-medications",
-			body
+			body,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -615,7 +749,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Endpoint",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -629,7 +764,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/HealthcareService",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -649,7 +785,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/InsurancePlan",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -663,7 +800,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Location",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -681,7 +819,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Organization",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -695,7 +834,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/OrganizationAffiliation",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -713,7 +853,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Practitioner",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -731,7 +872,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/PractitionerRole",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -767,7 +909,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Questionnaire",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -795,7 +938,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/ValueSet/$expand",
-			query: params
+			query: params,
+			expects: ["ValueSet"]
 		}, options);
 	}
 	/**
@@ -809,7 +953,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "POST",
 			path: "/v1/fhir/r4/ValueSet/$expand",
-			body
+			body,
+			expects: ["ValueSet"]
 		}, options);
 	}
 	/**
@@ -823,7 +968,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/ValueSet/$validate-code",
-			query: params
+			query: params,
+			expects: ["Parameters"]
 		}, options);
 	}
 	/**
@@ -837,7 +983,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "POST",
 			path: "/v1/fhir/r4/ValueSet/$validate-code",
-			body
+			body,
+			expects: ["Parameters"]
 		}, options);
 	}
 };
@@ -879,11 +1026,12 @@ var Haau3 = class extends Operations {
 			const next = page.link?.find((link) => link.relation === "next")?.url;
 			if (!next) return;
 			const url = this.url(next);
-			page = await this.answer("GET", url, void 0, options, url.pathname);
+			page = await this.answer("GET", url, void 0, options, url.pathname, ["Bundle"]);
 		}
 	}
 };
 //#endregion
+exports.APIPromise = APIPromise;
 exports.AuthError = AuthError;
 exports.Haau3 = Haau3;
 exports.Haau3Error = Haau3Error;