shelving 1.236.0 → 1.236.2

package/api/provider/MockAPIProvider.d.ts

@@ -3,33 +3,104 @@ import type { RequestHandler, RequestOptions } from "../../util/http.js";
 import type { AnyEndpoint, Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "./APIProvider.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
+/**
+ * Record of a single mocked fetch, pairing the request with the response the handler returned.
+ * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIFetchCall
+ */
 export type MockAPIFetchCall = {
     readonly request: Request;
     readonly response: Response;
 };
+/**
+ * Record of a single request build, capturing the endpoint, payload, options, and built request.
+ * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIRequestCall
+ */
 export type MockAPIRequestCall = {
     readonly endpoint: AnyEndpoint;
     readonly payload: unknown;
     readonly options: RequestOptions | undefined;
     readonly request: Request;
 };
+/**
+ * Record of a single response parse, capturing the endpoint, response, and parsed result.
+ * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIResponseCall
+ */
 export type MockAPIResponseCall = {
     readonly endpoint: AnyEndpoint;
     readonly response: Response;
     readonly result: unknown;
 };
 /**
- * Provider that logs API calls without sending network requests.
+ * Provider that records API calls and serves them from a handler without sending network requests.
  * - Extends `ThroughAPIProvider` to delegate request building and response parsing to a source `APIProvider`.
  * - The source provider's `fetch()` is never called — this provider intercepts all fetches and routes them through a `RequestHandler`.
+ * - Records `requestCalls`, `fetchCalls`, and `responseCalls` so tests can assert on what happened.
+ *
+ * @example
+ *  const api = new MockAPIProvider();
+ *  const result = await api.call(endpoint, payload);
+ *  expect(api.fetchCalls).toHaveLength(1);
+ * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider
  */
 export declare class MockAPIProvider<P = unknown, R = unknown> extends ThroughAPIProvider<P, R> {
+    /**
+     * Records of every request built by this provider.
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/requestCalls
+     */
     readonly requestCalls: MockAPIRequestCall[];
+    /**
+     * Records of every fetch handled by this provider.
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/fetchCalls
+     */
     readonly fetchCalls: MockAPIFetchCall[];
+    /**
+     * Records of every response parsed by this provider.
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/responseCalls
+     */
     readonly responseCalls: MockAPIResponseCall[];
+    /**
+     * The request handler that serves fetches in place of the network.
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/handler
+     */
     readonly handler: RequestHandler;
+    /**
+     * Create a mock provider that serves fetches from a handler.
+     *
+     * @param handler The handler that produces a response for each request (defaults to echoing the request).
+     * @param source The source provider used to build requests and parse responses.
+     * @example new MockAPIProvider()
+     */
     constructor(handler?: RequestHandler, source?: APIProvider<P, R>);
+    /**
+     * Build a request via the source provider, recording the endpoint and payload in `requestCalls`.
+     *
+     * @param endpoint The endpoint to build a request for.
+     * @param payload The payload to send.
+     * @param options Optional request options.
+     * @param caller The calling function used for error stack traces.
+     * @returns The built request.
+     * @example api.createRequest(endpoint, payload)
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/createRequest
+     */
     createRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
+    /**
+     * Parse a response via the source provider, recording the response and result in `responseCalls`.
+     *
+     * @param endpoint The endpoint the response came from.
+     * @param response The response to parse.
+     * @param caller The calling function used for error stack traces.
+     * @returns Promise resolving to the parsed result.
+     * @example await api.parseResponse(endpoint, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/parseResponse
+     */
     parseResponse<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
+    /**
+     * Serve a request through the handler instead of the network, recording it in `fetchCalls`.
+     *
+     * @param request The request to handle.
+     * @returns Promise resolving to the handler's response.
+     * @example await api.fetch(request)
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/fetch
+     */
     fetch(request: Request): Promise<Response>;
 }

package/api/provider/MockAPIProvider.js

@@ -6,32 +6,88 @@ async function _mockHandler(request) {
     return new Response(`Mocked response to ${debugRequest(request)}`, { status: 200, statusText: "OK" });
 }
 /**
- * Provider that logs API calls without sending network requests.
+ * Provider that records API calls and serves them from a handler without sending network requests.
  * - Extends `ThroughAPIProvider` to delegate request building and response parsing to a source `APIProvider`.
  * - The source provider's `fetch()` is never called — this provider intercepts all fetches and routes them through a `RequestHandler`.
+ * - Records `requestCalls`, `fetchCalls`, and `responseCalls` so tests can assert on what happened.
+ *
+ * @example
+ *  const api = new MockAPIProvider();
+ *  const result = await api.call(endpoint, payload);
+ *  expect(api.fetchCalls).toHaveLength(1);
+ * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider
  */
 export class MockAPIProvider extends ThroughAPIProvider {
+    /**
+     * Records of every request built by this provider.
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/requestCalls
+     */
     requestCalls = [];
+    /**
+     * Records of every fetch handled by this provider.
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/fetchCalls
+     */
     fetchCalls = [];
+    /**
+     * Records of every response parsed by this provider.
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/responseCalls
+     */
     responseCalls = [];
+    /**
+     * The request handler that serves fetches in place of the network.
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/handler
+     */
     handler;
+    /**
+     * Create a mock provider that serves fetches from a handler.
+     *
+     * @param handler The handler that produces a response for each request (defaults to echoing the request).
+     * @param source The source provider used to build requests and parse responses.
+     * @example new MockAPIProvider()
+     */
     constructor(handler = _mockHandler, source = new ClientAPIProvider({ url: "https://api.mock.com" })) {
         super(source);
         this.handler = handler;
     }
-    // Override `createRequest()` to log the endpoint and payload before delegating to the source provider for request building.
+    /**
+     * Build a request via the source provider, recording the endpoint and payload in `requestCalls`.
+     *
+     * @param endpoint The endpoint to build a request for.
+     * @param payload The payload to send.
+     * @param options Optional request options.
+     * @param caller The calling function used for error stack traces.
+     * @returns The built request.
+     * @example api.createRequest(endpoint, payload)
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/createRequest
+     */
     createRequest(endpoint, payload, options, caller = this.createRequest) {
         const request = super.createRequest(endpoint, payload, options, caller);
         this.requestCalls.push({ endpoint, payload, options, request });
         return request;
     }
-    // Override `parseResponse()` to log the response and result.
+    /**
+     * Parse a response via the source provider, recording the response and result in `responseCalls`.
+     *
+     * @param endpoint The endpoint the response came from.
+     * @param response The response to parse.
+     * @param caller The calling function used for error stack traces.
+     * @returns Promise resolving to the parsed result.
+     * @example await api.parseResponse(endpoint, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/parseResponse
+     */
     async parseResponse(endpoint, response, caller = this.parseResponse) {
         const result = await super.parseResponse(endpoint, response, caller);
         this.responseCalls.push({ endpoint, response, result });
         return result;
     }
-    // Override `fetch()` to route through the handler instead of the network.
+    /**
+     * Serve a request through the handler instead of the network, recording it in `fetchCalls`.
+     *
+     * @param request The request to handle.
+     * @returns Promise resolving to the handler's response.
+     * @example await api.fetch(request)
+     * @see https://dhoulb.github.io/shelving/api/provider/MockAPIProvider/MockAPIProvider/fetch
+     */
     async fetch(request) {
         const response = await this.handler(request);
         this.fetchCalls.push({ request, response });

package/api/provider/MockEndpointAPIProvider.d.ts

@@ -11,7 +11,16 @@ import { MockAPIProvider } from "./MockAPIProvider.js";
  * 	const api = new MockEnpdointAPIProvider(handlers); // Create a new mock provider.
  *  const result = await api.fetch(endpoint, 4); // Mock a call to the endpoint through the provider.
  *  expect(result).toBe(16);
+ * @see https://dhoulb.github.io/shelving/api/provider/MockEndpointAPIProvider/MockEndpointAPIProvider
  */
 export declare class MockEndpointAPIProvider<P, R, C> extends MockAPIProvider<P, R> {
+    /**
+     * Create a mock provider that routes calls through an array of endpoint handlers instead of the network.
+     *
+     * @param handlers The endpoint handlers (from `Endpoint.handler()`) that serve matching requests.
+     * @param context The context value passed to each handler.
+     * @param source Optional source provider used to build requests and parse responses.
+     * @example new MockEndpointAPIProvider(handlers, context)
+     */
     constructor(handlers: EndpointHandlers<C>, context: C, source?: ClientAPIProvider<P, R>);
 }

package/api/provider/MockEndpointAPIProvider.js

@@ -10,8 +10,17 @@ import { MockAPIProvider } from "./MockAPIProvider.js";
  * 	const api = new MockEnpdointAPIProvider(handlers); // Create a new mock provider.
  *  const result = await api.fetch(endpoint, 4); // Mock a call to the endpoint through the provider.
  *  expect(result).toBe(16);
+ * @see https://dhoulb.github.io/shelving/api/provider/MockEndpointAPIProvider/MockEndpointAPIProvider
  */
 export class MockEndpointAPIProvider extends MockAPIProvider {
+    /**
+     * Create a mock provider that routes calls through an array of endpoint handlers instead of the network.
+     *
+     * @param handlers The endpoint handlers (from `Endpoint.handler()`) that serve matching requests.
+     * @param context The context value passed to each handler.
+     * @param source Optional source provider used to build requests and parse responses.
+     * @example new MockEndpointAPIProvider(handlers, context)
+     */
     constructor(handlers, context, source) {
         super(request => handleEndpoints(this.url, handlers, request, context, this.call), source);
     }

package/api/provider/ThroughAPIProvider.d.ts

@@ -4,16 +4,82 @@ import type { Sourceable } from "../../util/source.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import { APIProvider } from "./APIProvider.js";
 /**
- * Provider wrapper that delegates API operations to a source provider.
+ * Provider wrapper that delegates every API operation to a wrapped `source` provider.
  * - Extend this when you want to intercept only selected API operations, such as injecting auth headers or logging.
+ * - Implements `Sourceable` so wrapped providers are discoverable via `getSource()` / `requireSource()`.
+ *
+ * @example
+ * class AuthAPIProvider extends ThroughAPIProvider {
+ * 	override createRequest(endpoint, payload, options, caller) {
+ * 		return super.createRequest(endpoint, payload, { ...options, headers: { authorization: TOKEN } }, caller);
+ * 	}
+ * }
+ *
+ * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider
  */
 export declare class ThroughAPIProvider<P, R> extends APIProvider<P, R> implements Sourceable<APIProvider<P, R>> {
+    /**
+     * The base URL, delegated to the wrapped `source` provider.
+     *
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider/url
+     */
     get url(): URL;
+    /**
+     * The wrapped source provider that operations delegate to.
+     *
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider/source
+     */
     readonly source: APIProvider<P, R>;
+    /**
+     * Wrap a source `APIProvider`.
+     *
+     * @param source The provider that every operation delegates to.
+     * @example new ThroughAPIProvider(clientProvider)
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider
+     */
     constructor(source: APIProvider<P, R>);
+    /**
+     * Render the request URL by delegating to the source provider.
+     *
+     * @param endpoint The endpoint whose path is rendered into the base URL.
+     * @param payload The payload supplying `{placeholder}` and query-param values.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The fully resolved request `URL`.
+     * @example provider.renderURL(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider/renderURL
+     */
     renderURL<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, caller?: AnyCaller): URL;
+    /**
+     * Create the request by delegating to the source provider.
+     *
+     * @param endpoint The endpoint the request targets.
+     * @param payload The payload to embed into the `Request`.
+     * @param options The `RequestOptions` to use, merged over the provider's own options.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The created `Request`.
+     * @example provider.createRequest(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider/createRequest
+     */
     createRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
+    /**
+     * Parse the response by delegating to the source provider.
+     *
+     * @param endpoint The endpoint the response was produced for.
+     * @param response The `Response` to parse.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns A promise resolving to the parsed result.
+     * @example await provider.parseResponse(getUser, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider/parseResponse
+     */
     parseResponse<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
+    /**
+     * Send the request by delegating to the source provider.
+     *
+     * @param request The `Request` to send.
+     * @returns A promise resolving to the `Response`.
+     * @example await provider.fetch(request)
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider/fetch
+     */
     fetch(request: Request): Promise<Response>;
     [Symbol.asyncDispose](): Promise<void>;
 }

package/api/provider/ThroughAPIProvider.js

@@ -1,27 +1,93 @@
 import { awaitDispose } from "../../util/dispose.js";
 import { APIProvider } from "./APIProvider.js";
 /**
- * Provider wrapper that delegates API operations to a source provider.
+ * Provider wrapper that delegates every API operation to a wrapped `source` provider.
  * - Extend this when you want to intercept only selected API operations, such as injecting auth headers or logging.
+ * - Implements `Sourceable` so wrapped providers are discoverable via `getSource()` / `requireSource()`.
+ *
+ * @example
+ * class AuthAPIProvider extends ThroughAPIProvider {
+ * 	override createRequest(endpoint, payload, options, caller) {
+ * 		return super.createRequest(endpoint, payload, { ...options, headers: { authorization: TOKEN } }, caller);
+ * 	}
+ * }
+ *
+ * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider
  */
 export class ThroughAPIProvider extends APIProvider {
+    /**
+     * The base URL, delegated to the wrapped `source` provider.
+     *
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider/url
+     */
     get url() {
         return this.source.url;
     }
+    /**
+     * The wrapped source provider that operations delegate to.
+     *
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider/source
+     */
     source;
+    /**
+     * Wrap a source `APIProvider`.
+     *
+     * @param source The provider that every operation delegates to.
+     * @example new ThroughAPIProvider(clientProvider)
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider
+     */
     constructor(source) {
         super();
         this.source = source;
     }
+    /**
+     * Render the request URL by delegating to the source provider.
+     *
+     * @param endpoint The endpoint whose path is rendered into the base URL.
+     * @param payload The payload supplying `{placeholder}` and query-param values.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The fully resolved request `URL`.
+     * @example provider.renderURL(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider/renderURL
+     */
     renderURL(endpoint, payload, caller = this.renderURL) {
         return this.source.renderURL(endpoint, payload, caller);
     }
+    /**
+     * Create the request by delegating to the source provider.
+     *
+     * @param endpoint The endpoint the request targets.
+     * @param payload The payload to embed into the `Request`.
+     * @param options The `RequestOptions` to use, merged over the provider's own options.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns The created `Request`.
+     * @example provider.createRequest(getUser, { id: "abc" })
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider/createRequest
+     */
     createRequest(endpoint, payload, options, caller = this.createRequest) {
         return this.source.createRequest(endpoint, payload, options, caller);
     }
+    /**
+     * Parse the response by delegating to the source provider.
+     *
+     * @param endpoint The endpoint the response was produced for.
+     * @param response The `Response` to parse.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns A promise resolving to the parsed result.
+     * @example await provider.parseResponse(getUser, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider/parseResponse
+     */
     parseResponse(endpoint, response, caller = this.parseResponse) {
         return this.source.parseResponse(endpoint, response, caller);
     }
+    /**
+     * Send the request by delegating to the source provider.
+     *
+     * @param request The `Request` to send.
+     * @returns A promise resolving to the `Response`.
+     * @example await provider.fetch(request)
+     * @see https://dhoulb.github.io/shelving/api/provider/ThroughAPIProvider/ThroughAPIProvider/fetch
+     */
     fetch(request) {
         return this.source.fetch(request);
     }

package/api/provider/ValidationAPIProvider.d.ts

@@ -2,8 +2,39 @@ import type { AnyCaller } from "../../util/function.js";
 import type { RequestOptions } from "../../util/http.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
-/** Validate an asynchronous source provider (source can have any type because validation guarantees the type). */
+/**
+ * Provider that validates payloads and results against the endpoint's schemas, so a source of any type is made type-safe.
+ * - Payload validation errors bubble up as user-readable strings; result validation errors are wrapped in `ResponseError`.
+ *
+ * @example
+ *  const api = new ValidationAPIProvider(source);
+ *  const result = await api.call(endpoint, payload); // validated payload and result
+ * @see https://dhoulb.github.io/shelving/api/provider/ValidationAPIProvider/ValidationAPIProvider
+ */
 export declare class ValidationAPIProvider<P, R> extends ThroughAPIProvider<P, R> {
+    /**
+     * Build a request via the source provider after validating the payload against the endpoint's payload schema.
+     *
+     * @param endpoint The endpoint to build a request for.
+     * @param payload The payload to validate and send.
+     * @param options Optional request options.
+     * @param caller The calling function used for error stack traces.
+     * @returns The built request.
+     * @throws {string} A user-readable validation message if the payload is invalid.
+     * @example api.createRequest(endpoint, payload)
+     * @see https://dhoulb.github.io/shelving/api/provider/ValidationAPIProvider/ValidationAPIProvider/createRequest
+     */
     createRequest<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, payload: PP, options?: RequestOptions, caller?: AnyCaller): Request;
+    /**
+     * Parse a response via the source provider, then validate the result against the endpoint's result schema.
+     *
+     * @param endpoint The endpoint the response came from.
+     * @param response The response to parse and validate.
+     * @param caller The calling function used for error stack traces.
+     * @returns Promise resolving to the validated result.
+     * @throws {ResponseError} If the result fails validation (treated as a server/transport problem).
+     * @example await api.parseResponse(endpoint, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/ValidationAPIProvider/ValidationAPIProvider/parseResponse
+     */
     parseResponse<PP extends P, RR extends R>(endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/ValidationAPIProvider.js

@@ -1,11 +1,42 @@
 import { ResponseError } from "../../error/ResponseError.js";
 import { ThroughAPIProvider } from "./ThroughAPIProvider.js";
-/** Validate an asynchronous source provider (source can have any type because validation guarantees the type). */
+/**
+ * Provider that validates payloads and results against the endpoint's schemas, so a source of any type is made type-safe.
+ * - Payload validation errors bubble up as user-readable strings; result validation errors are wrapped in `ResponseError`.
+ *
+ * @example
+ *  const api = new ValidationAPIProvider(source);
+ *  const result = await api.call(endpoint, payload); // validated payload and result
+ * @see https://dhoulb.github.io/shelving/api/provider/ValidationAPIProvider/ValidationAPIProvider
+ */
 export class ValidationAPIProvider extends ThroughAPIProvider {
+    /**
+     * Build a request via the source provider after validating the payload against the endpoint's payload schema.
+     *
+     * @param endpoint The endpoint to build a request for.
+     * @param payload The payload to validate and send.
+     * @param options Optional request options.
+     * @param caller The calling function used for error stack traces.
+     * @returns The built request.
+     * @throws {string} A user-readable validation message if the payload is invalid.
+     * @example api.createRequest(endpoint, payload)
+     * @see https://dhoulb.github.io/shelving/api/provider/ValidationAPIProvider/ValidationAPIProvider/createRequest
+     */
     createRequest(endpoint, payload, options, caller = this.createRequest) {
         // Validate payload — let thrown strings bubble up as user-readable messages for e.g. form handlers.
         return super.createRequest(endpoint, endpoint.payload.validate(payload), options, caller);
     }
+    /**
+     * Parse a response via the source provider, then validate the result against the endpoint's result schema.
+     *
+     * @param endpoint The endpoint the response came from.
+     * @param response The response to parse and validate.
+     * @param caller The calling function used for error stack traces.
+     * @returns Promise resolving to the validated result.
+     * @throws {ResponseError} If the result fails validation (treated as a server/transport problem).
+     * @example await api.parseResponse(endpoint, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/ValidationAPIProvider/ValidationAPIProvider/parseResponse
+     */
     async parseResponse(endpoint, response, caller = this.parseResponse) {
         try {
             // Validate result — wrap in ResponseError as this is a server/transport problem, not user error.

package/api/provider/XMLAPIProvider.d.ts

@@ -4,14 +4,30 @@ import { type RequestBodyMethod, type RequestOptions } from "../../util/http.js"
 import type { PossibleURL } from "../../util/url.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import { ClientAPIProvider } from "./ClientAPIProvider.js";
-/** API provider that always sends request bodies as XML and parses responses as plain text. */
+/**
+ * Client API provider that always sends request bodies as XML and parses responses as plain text.
+ * - Request payloads must be data objects (serialised to XML); results are returned as raw text strings.
+ *
+ * @example
+ * const provider = new XMLAPIProvider({ url: "https://api.example.com" });
+ * const xml = await provider.call(getFeed, { id: "abc" });
+ *
+ * @see https://dhoulb.github.io/shelving/api/provider/XMLAPIProvider/XMLAPIProvider
+ */
 export declare class XMLAPIProvider<P extends Data = Data, R extends string = string> extends ClientAPIProvider<P, R> {
     protected _createBodyRequest(method: RequestBodyMethod, url: PossibleURL, payload: P, options: RequestOptions, caller: AnyCaller): Request;
     /**
      * Parse a text `Response` for an endpoint.
-     *
      * - Non-2xx responses become `ResponseError`.
      * - The response body is always returned as raw text.
+     *
+     * @param _endpoint The endpoint the response was produced for.
+     * @param response The `Response` whose body is read as text.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns A promise resolving to the raw text result.
+     * @throws {ResponseError} if the response status is non-2xx.
+     * @example await provider.parseResponse(getFeed, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/XMLAPIProvider/XMLAPIProvider/parseResponse
      */
     parseResponse<PP extends P, RR extends R>(_endpoint: Endpoint<PP, RR>, response: Response, caller?: AnyCaller): Promise<RR>;
 }

package/api/provider/XMLAPIProvider.js

@@ -1,16 +1,32 @@
 import { ResponseError } from "../../error/ResponseError.js";
 import { createXMLRequest } from "../../util/http.js";
 import { ClientAPIProvider } from "./ClientAPIProvider.js";
-/** API provider that always sends request bodies as XML and parses responses as plain text. */
+/**
+ * Client API provider that always sends request bodies as XML and parses responses as plain text.
+ * - Request payloads must be data objects (serialised to XML); results are returned as raw text strings.
+ *
+ * @example
+ * const provider = new XMLAPIProvider({ url: "https://api.example.com" });
+ * const xml = await provider.call(getFeed, { id: "abc" });
+ *
+ * @see https://dhoulb.github.io/shelving/api/provider/XMLAPIProvider/XMLAPIProvider
+ */
 export class XMLAPIProvider extends ClientAPIProvider {
     _createBodyRequest(method, url, payload, options, caller) {
         return createXMLRequest(method, url, payload, options, caller);
     }
     /**
      * Parse a text `Response` for an endpoint.
-     *
      * - Non-2xx responses become `ResponseError`.
      * - The response body is always returned as raw text.
+     *
+     * @param _endpoint The endpoint the response was produced for.
+     * @param response The `Response` whose body is read as text.
+     * @param caller The function to attribute thrown errors to (defaults to this method).
+     * @returns A promise resolving to the raw text result.
+     * @throws {ResponseError} if the response status is non-2xx.
+     * @example await provider.parseResponse(getFeed, response)
+     * @see https://dhoulb.github.io/shelving/api/provider/XMLAPIProvider/XMLAPIProvider/parseResponse
      */
     async parseResponse(_endpoint, response, caller = this.parseResponse) {
         const { ok, status } = response;

package/api/store/EndpointStore.d.ts

@@ -1,10 +1,33 @@
 import { PayloadFetchStore } from "../../store/PayloadFetchStore.js";
 import type { Endpoint } from "../endpoint/Endpoint.js";
 import type { APIProvider } from "../provider/APIProvider.js";
-/** Store object that loads a result from an API endpoint and provider. */
+/**
+ * Store that loads and tracks the result of calling a single API endpoint with a fixed payload, through an `APIProvider`.
+ *
+ * @example
+ *  const store = new EndpointStore(endpoint, payload, provider);
+ *  const result = await store; // R
+ * @see https://dhoulb.github.io/shelving/api/store/EndpointStore/EndpointStore
+ */
 export declare class EndpointStore<P, R> extends PayloadFetchStore<P, R> {
+    /**
+     * The API provider this store calls the endpoint through.
+     * @see https://dhoulb.github.io/shelving/api/store/EndpointStore/EndpointStore/provider
+     */
     readonly provider: APIProvider<P, R>;
+    /**
+     * The endpoint this store calls to fetch its result.
+     * @see https://dhoulb.github.io/shelving/api/store/EndpointStore/EndpointStore/endpoint
+     */
     readonly endpoint: Endpoint<P, R>;
+    /**
+     * Create a store that tracks the result of an endpoint call.
+     *
+     * @param endpoint The endpoint to call.
+     * @param payload The payload to call the endpoint with.
+     * @param provider The API provider to call the endpoint through.
+     * @example new EndpointStore(endpoint, payload, provider)
+     */
     constructor(endpoint: Endpoint<P, R>, payload: P, provider: APIProvider<P, R>);
     protected _fetch(signal: AbortSignal): Promise<R>;
 }

package/api/store/EndpointStore.js

@@ -1,9 +1,32 @@
 import { PayloadFetchStore } from "../../store/PayloadFetchStore.js";
 import { NONE } from "../../util/constants.js";
-/** Store object that loads a result from an API endpoint and provider. */
+/**
+ * Store that loads and tracks the result of calling a single API endpoint with a fixed payload, through an `APIProvider`.
+ *
+ * @example
+ *  const store = new EndpointStore(endpoint, payload, provider);
+ *  const result = await store; // R
+ * @see https://dhoulb.github.io/shelving/api/store/EndpointStore/EndpointStore
+ */
 export class EndpointStore extends PayloadFetchStore {
+    /**
+     * The API provider this store calls the endpoint through.
+     * @see https://dhoulb.github.io/shelving/api/store/EndpointStore/EndpointStore/provider
+     */
     provider;
+    /**
+     * The endpoint this store calls to fetch its result.
+     * @see https://dhoulb.github.io/shelving/api/store/EndpointStore/EndpointStore/endpoint
+     */
     endpoint;
+    /**
+     * Create a store that tracks the result of an endpoint call.
+     *
+     * @param endpoint The endpoint to call.
+     * @param payload The payload to call the endpoint with.
+     * @param provider The API provider to call the endpoint through.
+     * @example new EndpointStore(endpoint, payload, provider)
+     */
     constructor(endpoint, payload, provider) {
         super(payload, NONE);
         this.endpoint = endpoint;