@haau3/sdk 0.1.2 → 0.2.1

package/dist/index.mjs

@@ -1,3 +1,40 @@
+//#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 {
@@ -28,9 +65,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);
 	}
 };
@@ -42,9 +85,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);
 	}
 };
@@ -61,19 +110,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";
@@ -90,6 +142,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;
 }
@@ -137,6 +201,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";
@@ -147,6 +218,8 @@ function noAnswerReason(status) {
 var Transport = class {
 	#apiKey;
 	#fetch;
+	#fetchOptions;
+	#noStoreTaken;
 	/** Where requests go. */
 	baseURL;
 	/** Milliseconds one attempt may take. */
@@ -161,6 +234,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;
@@ -181,50 +256,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. */
@@ -256,6 +365,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 (;;) {
@@ -267,6 +381,7 @@ var Transport = class {
 			let text;
 			try {
 				response = await this.#fetch(url, {
+					...fetchOptions,
 					method,
 					headers,
 					body: payload,
@@ -284,6 +399,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
 				});
 			}
@@ -319,7 +435,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);
 	}
 	/**
@@ -333,7 +450,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/CodeSystem/$lookup",
-			query: params
+			query: params,
+			expects: ["Parameters"]
 		}, options);
 	}
 	/**
@@ -347,7 +465,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "POST",
 			path: "/v1/fhir/r4/CodeSystem/$lookup",
-			body
+			body,
+			expects: ["Parameters"]
 		}, options);
 	}
 	/**
@@ -361,7 +480,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);
 	}
 	/**
@@ -375,7 +495,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "POST",
 			path: "/v1/fhir/r4/CodeSystem/$validate-code",
-			body
+			body,
+			expects: ["Parameters"]
 		}, options);
 	}
 	/**
@@ -389,7 +510,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "POST",
 			path: "/v1/fhir/r4",
-			body
+			body,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -403,7 +525,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/metadata",
-			query: params
+			query: params,
+			expects: ["CapabilityStatement", "TerminologyCapabilities"]
 		}, options);
 	}
 	/**
@@ -417,7 +540,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/InsurancePlan/$counties",
-			query: params
+			query: params,
+			expects: ["Parameters"]
 		}, options);
 	}
 	/**
@@ -472,7 +596,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Endpoint/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["Endpoint"]
 		}, options);
 	}
 	/**
@@ -486,7 +611,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/HealthcareService/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["HealthcareService"]
 		}, options);
 	}
 	/**
@@ -500,7 +626,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/InsurancePlan/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["InsurancePlan"]
 		}, options);
 	}
 	/**
@@ -514,7 +641,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Location/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["Location"]
 		}, options);
 	}
 	/**
@@ -528,7 +656,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Organization/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["Organization"]
 		}, options);
 	}
 	/**
@@ -542,7 +671,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/OrganizationAffiliation/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["OrganizationAffiliation"]
 		}, options);
 	}
 	/**
@@ -556,7 +686,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Practitioner/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["Practitioner"]
 		}, options);
 	}
 	/**
@@ -570,7 +701,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/PractitionerRole/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["PractitionerRole"]
 		}, options);
 	}
 	/**
@@ -586,7 +718,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Questionnaire/{id}",
-			pathParams: { id }
+			pathParams: { id },
+			expects: ["Questionnaire"]
 		}, options);
 	}
 	/**
@@ -600,7 +733,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "POST",
 			path: "/v1/fhir/r4/$reconcile-medications",
-			body
+			body,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -614,7 +748,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Endpoint",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -628,7 +763,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/HealthcareService",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -648,7 +784,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/InsurancePlan",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -662,7 +799,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Location",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -680,7 +818,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Organization",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -694,7 +833,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/OrganizationAffiliation",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -712,7 +852,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Practitioner",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -730,7 +871,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/PractitionerRole",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -766,7 +908,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/Questionnaire",
-			query: params
+			query: params,
+			expects: ["Bundle"]
 		}, options);
 	}
 	/**
@@ -794,7 +937,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "GET",
 			path: "/v1/fhir/r4/ValueSet/$expand",
-			query: params
+			query: params,
+			expects: ["ValueSet"]
 		}, options);
 	}
 	/**
@@ -808,7 +952,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "POST",
 			path: "/v1/fhir/r4/ValueSet/$expand",
-			body
+			body,
+			expects: ["ValueSet"]
 		}, options);
 	}
 	/**
@@ -822,7 +967,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);
 	}
 	/**
@@ -836,7 +982,8 @@ var Operations = class extends Transport {
 		return this.operation({
 			method: "POST",
 			path: "/v1/fhir/r4/ValueSet/$validate-code",
-			body
+			body,
+			expects: ["Parameters"]
 		}, options);
 	}
 };
@@ -878,9 +1025,9 @@ 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
-export { AuthError, Haau3, Haau3Error, NoAnswerError, RefusedError, VERSION };
+export { APIPromise, AuthError, Haau3, Haau3Error, NoAnswerError, RefusedError, VERSION };

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@haau3/sdk",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "TypeScript SDK for the haau3 platform API: scheduling, provider directory, terminology, questionnaires, plan benefits and medication lists, as typed calls.",
   "license": "MIT",
-  "homepage": "https://docs.haau3.com",
+  "homepage": "https://platform.haau3.com",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/haau3/haau3-node.git"