@honua/app-platform 0.0.20-alpha.0

package/core/auth/token-endpoint.js

@@ -0,0 +1,133 @@
+/**
+ * Shared helpers for talking to an OAuth2 token endpoint and turning responses
+ * into {@link StoredCredential}s. Used by both the PKCE and client-credentials
+ * providers.
+ *
+ * @packageDocumentation
+ */
+import { HonuaAuthError } from "../errors.js";
+/**
+ * Project a {@link StoredCredential} into the {@link HonuaAuthCredentials} shape
+ * the client attaches to requests. Non-`Bearer` token types are emitted as a
+ * full `Authorization` value; the expiry drives the client's own refresh skew.
+ */
+export function toHonuaCredentials(credential) {
+    const result = {};
+    if (credential.tokenType && credential.tokenType.toLowerCase() !== "bearer") {
+        result.authorization = `${credential.tokenType} ${credential.accessToken}`;
+    }
+    else {
+        result.bearerToken = credential.accessToken;
+    }
+    if (credential.expiresAt !== undefined) {
+        result.expiresAt = credential.expiresAt;
+    }
+    return result;
+}
+/** Resolve `serviceKey`, defaulting to `${clientId}@${endpoint origin}`. */
+export function resolveServiceKey(serviceKey, clientId, endpoint) {
+    if (serviceKey) {
+        return serviceKey;
+    }
+    let origin = endpoint;
+    try {
+        origin = new URL(endpoint).origin;
+    }
+    catch {
+        // Non-absolute endpoint (tests) — fall back to the raw string.
+    }
+    return `${clientId}@${origin}`;
+}
+/** Default clock-skew tolerance (ms) applied to credential expiry checks. */
+export const DEFAULT_CLOCK_SKEW_MS = 60_000;
+/** True when a credential is missing or within `skewMs` of (or past) expiry. */
+export function isCredentialExpiring(credential, skewMs) {
+    if (!credential) {
+        return true;
+    }
+    if (credential.expiresAt === undefined) {
+        return false;
+    }
+    return credential.expiresAt - Date.now() <= skewMs;
+}
+/** Map a token response into a {@link StoredCredential} (clock-skew tolerant). */
+export function credentialFromTokenResponse(response, previous) {
+    const credential = {
+        accessToken: response.access_token,
+    };
+    if (response.token_type) {
+        credential.tokenType = response.token_type;
+    }
+    // Some authorization servers omit a rotated refresh token on refresh; keep
+    // the previous one so silent refresh keeps working (RFC 6749 §6).
+    const refreshToken = response.refresh_token ?? previous?.refreshToken;
+    if (refreshToken) {
+        credential.refreshToken = refreshToken;
+    }
+    if (typeof response.expires_in === "number" && Number.isFinite(response.expires_in)) {
+        credential.expiresAt = Date.now() + response.expires_in * 1000;
+    }
+    const scope = response.scope ?? previous?.scope;
+    if (scope) {
+        credential.scope = scope;
+    }
+    if (response.id_token) {
+        credential.idToken = response.id_token;
+    }
+    return credential;
+}
+/**
+ * POST an `application/x-www-form-urlencoded` grant to the token endpoint and
+ * return the parsed {@link StoredCredential}.
+ *
+ * Errors are normalized to {@link HonuaAuthError}: an `invalid_grant` OAuth
+ * error (expired/revoked/invalid grant → re-auth needed) maps to code
+ * `invalid_grant`; every other transport/HTTP/parse failure maps to
+ * `refresh_failed` (transient, retry may succeed).
+ */
+export async function requestToken(options) {
+    const body = new URLSearchParams(options.params);
+    let response;
+    try {
+        response = await options.fetchFn(options.tokenEndpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
+            body: body.toString(),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+    }
+    catch (cause) {
+        throw new HonuaAuthError("refresh_failed", "Token request failed at the transport layer.", { cause });
+    }
+    const text = await response.text();
+    let payload;
+    try {
+        payload = text ? JSON.parse(text) : {};
+    }
+    catch (cause) {
+        throw new HonuaAuthError("refresh_failed", `Token endpoint returned a non-JSON response (HTTP ${response.status}).`, {
+            cause,
+        });
+    }
+    if (!response.ok) {
+        const oauthError = isObject(payload) && typeof payload.error === "string" ? payload.error : undefined;
+        const description = isObject(payload) && typeof payload.error_description === "string" ? payload.error_description : undefined;
+        const message = `Token endpoint rejected the grant (HTTP ${response.status}${oauthError ? `, ${oauthError}` : ""})${description ? `: ${description}` : ""}`;
+        if (oauthError === "invalid_grant") {
+            throw new HonuaAuthError("invalid_grant", message, { cause: payload });
+        }
+        throw new HonuaAuthError("refresh_failed", message, { cause: payload });
+    }
+    if (!isObject(payload) || typeof payload.access_token !== "string") {
+        throw new HonuaAuthError("refresh_failed", "Token endpoint response is missing an access_token.", {
+            cause: payload,
+        });
+    }
+    return credentialFromTokenResponse(payload, options.previous);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}

package/core/auth/types.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Shared types for the built-in {@link HonuaAuthProvider} implementations
+ * (`oauth2`, `clientCredentials`, `apiKeyAuth`, `bearerTokenAuth`) and the
+ * pluggable {@link CredentialStore}.
+ *
+ * @packageDocumentation
+ */
+import type { HonuaAuthError } from "../errors.js";
+/**
+ * A persisted OAuth2 credential. Access/refresh tokens plus expiry are stored
+ * in a {@link CredentialStore}; the SDK only ever attaches `accessToken` as a
+ * bearer credential and uses `refreshToken`/`expiresAt` to drive silent
+ * refresh.
+ */
+export interface StoredCredential {
+    /** The bearer access token attached to outgoing requests. */
+    accessToken: string;
+    /** Token type from the token response; defaults to `Bearer`. */
+    tokenType?: string;
+    /** Refresh token, when the authorization server issued one. */
+    refreshToken?: string;
+    /** Absolute expiry as epoch milliseconds (from `expires_in`). */
+    expiresAt?: number;
+    /** Granted scope string, if the token response narrowed it. */
+    scope?: string;
+    /** OpenID Connect ID token, when present (never sent to resource servers). */
+    idToken?: string;
+}
+/**
+ * Pluggable credential persistence. The default is an in-memory store scoped to
+ * the provider instance. Browser adapters (`sessionStorageCredentialStore`,
+ * `localStorageCredentialStore`) are explicit opt-in because Web Storage is
+ * readable by any script on the origin (XSS exfiltration risk) — see
+ * `docs/auth.md`.
+ *
+ * Keys are namespaced per origin/service by the provider so tokens for one
+ * service are never returned for another.
+ */
+export interface CredentialStore {
+    get(key: string): StoredCredential | undefined | Promise<StoredCredential | undefined>;
+    set(key: string, value: StoredCredential): void | Promise<void>;
+    delete(key: string): void | Promise<void>;
+}
+/** Lifecycle events emitted by the OAuth2 / client-credentials providers. */
+export type HonuaAuthEvent = {
+    type: "signed-in";
+    credential: StoredCredential;
+} | {
+    type: "token-refreshed";
+    credential: StoredCredential;
+} | {
+    type: "refresh-failed";
+    error: HonuaAuthError;
+} | {
+    type: "signed-out";
+};
+/** Listener registered with `provider.on(...)`. */
+export type HonuaAuthEventListener = (event: HonuaAuthEvent) => void;
+/** Handle returned by `provider.on(...)`; call `remove()` to unsubscribe. */
+export interface HonuaAuthEventHandle {
+    remove(): void;
+}
+/** Interactive sign-in mode for the OAuth2 authorization-code + PKCE flow. */
+export type OAuth2SignInMode = "redirect" | "popup";
+/**
+ * Configuration for the OAuth2 authorization-code + PKCE provider produced by
+ * {@link oauth2}. Only WebCrypto is used for PKCE (Node ≥20 exposes
+ * `globalThis.crypto`); no new hard dependencies are introduced.
+ */
+export interface OAuth2Config {
+    /** Authorization endpoint (where the browser is redirected to sign in). */
+    authorizationEndpoint: string;
+    /** Token endpoint (code exchange + refresh). */
+    tokenEndpoint: string;
+    /** Public client identifier. */
+    clientId: string;
+    /** Registered redirect URI that receives the authorization `code`+`state`. */
+    redirectUri: string;
+    /** Requested scopes. */
+    scopes?: readonly string[];
+    /** Interactive mode. Defaults to `redirect`. */
+    mode?: OAuth2SignInMode;
+    /**
+     * Credential store. Defaults to an in-memory store. Scoped per
+     * origin/service via {@link OAuth2Config.serviceKey}.
+     */
+    store?: CredentialStore;
+    /**
+     * Stable key that scopes stored credentials to this service. Defaults to
+     * `${clientId}@${origin of tokenEndpoint}` so tokens are never shared across
+     * services or origins.
+     */
+    serviceKey?: string;
+    /**
+     * Clock-skew tolerance in milliseconds. A credential is treated as expiring
+     * this long before its real expiry so a refresh happens before requests fail.
+     * Defaults to 60_000.
+     */
+    clockSkewMs?: number;
+    /** Optional revocation endpoint (RFC 7009) called on `signOut()`. */
+    revocationEndpoint?: string;
+    /** Extra query params appended to the authorization request. */
+    extraAuthorizationParams?: Record<string, string>;
+    /** Extra body params appended to token/refresh requests. */
+    extraTokenParams?: Record<string, string>;
+    /** Popup window features string (popup mode). */
+    popupFeatures?: string;
+    /** Override `fetch` (Node/tests). Defaults to `globalThis.fetch`. */
+    fetchFn?: typeof fetch;
+    /**
+     * Window used for redirect/popup + transaction persistence. Defaults to
+     * `globalThis.window`. Injectable for tests / non-DOM hosts.
+     */
+    windowRef?: Window;
+    /** Auth lifecycle listener. */
+    onEvent?: HonuaAuthEventListener;
+}
+/**
+ * Configuration for the OAuth2 client-credentials provider produced by
+ * {@link clientCredentials}. Intended for confidential Node clients — the
+ * client secret must never ship to a browser.
+ */
+export interface ClientCredentialsConfig {
+    tokenEndpoint: string;
+    clientId: string;
+    clientSecret: string;
+    scopes?: readonly string[];
+    store?: CredentialStore;
+    serviceKey?: string;
+    clockSkewMs?: number;
+    extraTokenParams?: Record<string, string>;
+    fetchFn?: typeof fetch;
+    onEvent?: HonuaAuthEventListener;
+}
+/** Raw OAuth2 token endpoint response shape (RFC 6749 §5.1). */
+export interface OAuth2TokenResponse {
+    access_token: string;
+    token_type?: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+    id_token?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/core/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/core/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAAC;IACvF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,gBAAgB,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,UAAU,EAAE,gBAAgB,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC;AAE3B,mDAAmD;AACnD,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;AAErE,6EAA6E;AAC7E,MAAM,WAAW,oBAAoB;IACnC,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,8EAA8E;AAC9E,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,OAAO,CAAC;AAEpD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,2EAA2E;IAC3E,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,gDAAgD;IAChD,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB;;;OAGG;IACH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gEAAgE;IAChE,wBAAwB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,OAAO,CAAC,EAAE,sBAAsB,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,OAAO,CAAC,EAAE,sBAAsB,CAAC;CAClC;AAED,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/core/auth/types.js

@@ -0,0 +1,8 @@
+/**
+ * Shared types for the built-in {@link HonuaAuthProvider} implementations
+ * (`oauth2`, `clientCredentials`, `apiKeyAuth`, `bearerTokenAuth`) and the
+ * pluggable {@link CredentialStore}.
+ *
+ * @packageDocumentation
+ */
+export {};

package/core/batch.d.ts

@@ -0,0 +1,37 @@
+import type { HonuaClient } from "./client.js";
+import type { HonuaQueryResponse, MapLayerQueryRequest, QueryFeaturesRequest } from "./types.js";
+/** A single query item in a batch. */
+export interface BatchQueryItem {
+    /** When `"map-layer"`, calls `client.queryMapLayer()`; default is `"feature"`. */
+    type?: "feature" | "map-layer";
+    /** The query request payload. */
+    request: QueryFeaturesRequest | MapLayerQueryRequest;
+    /** Optional label to identify this query in the results. */
+    label?: string;
+}
+/** The result of a single query within a batch. */
+export interface BatchQueryResult {
+    /** The label from the corresponding `BatchQueryItem`, if provided. */
+    label?: string;
+    /** The successful query response, or `undefined` if the query failed. */
+    response?: HonuaQueryResponse;
+    /** The error thrown by the query, or `undefined` if the query succeeded. */
+    error?: Error;
+}
+/** Options for controlling batch query execution. */
+export interface BatchQueryOptions {
+    /** Maximum number of concurrent queries. Default: `5`. */
+    concurrency?: number;
+    /** An `AbortSignal` that, when aborted, skips all remaining unstarted queries. */
+    signal?: AbortSignal;
+}
+/**
+ * Execute multiple queries in parallel with bounded concurrency.
+ *
+ * Results are returned in the same order as the input `items`.
+ * Each result contains either a `response` (on success) or an `error` (on failure).
+ * If an `AbortSignal` is provided and aborted, remaining unstarted queries are
+ * skipped and their results will have an `error` set to an `AbortError`.
+ */
+export declare function batchQuery(client: HonuaClient, items: readonly BatchQueryItem[], options?: BatchQueryOptions): Promise<BatchQueryResult[]>;
+//# sourceMappingURL=batch.d.ts.map

package/core/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../../src/core/batch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEjG,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,IAAI,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC;IAC/B,iCAAiC;IACjC,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;IACrD,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAC9B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiF7B"}

package/core/batch.js

@@ -0,0 +1,79 @@
+import { HonuaAbortError } from "./errors.js";
+/**
+ * Execute multiple queries in parallel with bounded concurrency.
+ *
+ * Results are returned in the same order as the input `items`.
+ * Each result contains either a `response` (on success) or an `error` (on failure).
+ * If an `AbortSignal` is provided and aborted, remaining unstarted queries are
+ * skipped and their results will have an `error` set to an `AbortError`.
+ */
+export async function batchQuery(client, items, options) {
+    const concurrency = Math.max(1, options?.concurrency ?? 5);
+    const signal = options?.signal;
+    const results = new Array(items.length);
+    // Simple semaphore: track how many queries are currently in-flight.
+    let running = 0;
+    const queue = [];
+    function release() {
+        running--;
+        const next = queue.shift();
+        if (next) {
+            next();
+        }
+    }
+    function acquire() {
+        if (running < concurrency) {
+            running++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            queue.push(() => {
+                running++;
+                resolve();
+            });
+        });
+    }
+    const promises = [];
+    for (let i = 0; i < items.length; i++) {
+        const index = i;
+        const item = items[index];
+        const task = async () => {
+            // Check abort before acquiring a semaphore slot.
+            if (signal?.aborted) {
+                results[index] = {
+                    label: item.label,
+                    error: new HonuaAbortError("Batch query aborted before completion."),
+                };
+                return;
+            }
+            await acquire();
+            // Check abort again after acquiring the slot.
+            if (signal?.aborted) {
+                release();
+                results[index] = {
+                    label: item.label,
+                    error: new HonuaAbortError("Batch query aborted before completion."),
+                };
+                return;
+            }
+            try {
+                const response = item.type === "map-layer"
+                    ? await client.queryMapLayer(item.request)
+                    : await client.queryFeatures(item.request);
+                results[index] = { label: item.label, response };
+            }
+            catch (err) {
+                results[index] = {
+                    label: item.label,
+                    error: err instanceof Error ? err : new Error(String(err)),
+                };
+            }
+            finally {
+                release();
+            }
+        };
+        promises.push(task());
+    }
+    await Promise.all(promises);
+    return results;
+}

package/core/cache-state.d.ts

@@ -0,0 +1,79 @@
+export type HonuaCacheScope = "metadata" | "materialized-result";
+export type HonuaCacheStatus = "hit" | "miss" | "stale" | "refreshed" | "bypass";
+export type HonuaCacheReadMode = "default" | "bypass";
+export interface HonuaCacheValidator {
+    readonly etag?: string;
+    readonly lastModified?: string;
+}
+export interface HonuaCacheState {
+    readonly scope: HonuaCacheScope;
+    readonly status: HonuaCacheStatus;
+    readonly keyFingerprint: string;
+    readonly ageMs?: number;
+    readonly ttlMs?: number;
+    readonly staleIfErrorMs?: number;
+    readonly revalidatedAt?: string;
+    readonly sourceUpdatedAt?: string;
+    readonly validator?: HonuaCacheValidator;
+    readonly invalidationReason?: string;
+    readonly refreshErrorId?: string;
+}
+export interface HonuaMetadataRequestOptions {
+    readonly signal?: AbortSignal;
+    /**
+     * Revalidate even when an SDK-local metadata entry is present. Adapters send
+     * conditional validators when available and report `refreshed` on success.
+     */
+    readonly refresh?: boolean;
+    /**
+     * `default` reads and writes the adapter metadata cache. `bypass` skips cache
+     * lookup and write-through for endpoints that support SDK-local caching.
+     */
+    readonly cache?: HonuaCacheReadMode;
+    /**
+     * Allow a cached metadata entry to be returned as `stale` when refresh fails.
+     * Defaults to `true`; ignored when no cached metadata entry exists.
+     */
+    readonly staleIfError?: boolean;
+    /** Optional freshness budget surfaced to callers in `HonuaCacheState`. */
+    readonly ttlMs?: number;
+    /** Optional stale fallback window surfaced to callers in `HonuaCacheState`. */
+    readonly staleIfErrorMs?: number;
+}
+export interface NormalizedHonuaMetadataRequestOptions {
+    readonly signal?: AbortSignal;
+    readonly refresh: boolean;
+    readonly cache: HonuaCacheReadMode;
+    readonly staleIfError: boolean;
+    readonly ttlMs?: number;
+    readonly staleIfErrorMs?: number;
+}
+export declare const HONUA_DEFAULT_METADATA_CACHE_TTL_MS: number;
+export declare const HONUA_DEFAULT_METADATA_STALE_IF_ERROR_MS: number;
+export interface HonuaCacheStateInit {
+    readonly scope: HonuaCacheScope;
+    readonly status: HonuaCacheStatus;
+    readonly keyFingerprint: string;
+    readonly ageMs?: number;
+    readonly ttlMs?: number;
+    readonly staleIfErrorMs?: number;
+    readonly revalidatedAt?: string;
+    readonly sourceUpdatedAt?: string;
+    readonly validator?: HonuaCacheValidator;
+    readonly invalidationReason?: string;
+    readonly refreshErrorId?: string;
+}
+export declare function createHonuaCacheState(init: HonuaCacheStateInit): HonuaCacheState;
+export declare function normalizeHonuaMetadataRequestOptions(options?: HonuaMetadataRequestOptions): NormalizedHonuaMetadataRequestOptions;
+export declare function isHonuaCacheEntryFresh(cachedAtMs: number, now: number, ttlMs: number | undefined): boolean;
+export declare function isHonuaCacheStatus(value: unknown): value is HonuaCacheStatus;
+export declare function honuaCacheValidatorFromHeaders(headers: Headers): HonuaCacheValidator | undefined;
+export declare function honuaMetadataRequestHeaders(options: {
+    readonly accept?: string;
+    readonly refresh?: boolean;
+    readonly bypass?: boolean;
+    readonly validator?: HonuaCacheValidator;
+}): Record<string, string>;
+export declare function withHonuaCacheState<T>(value: T, cache: HonuaCacheState): T;
+export declare function withoutHonuaCacheState<T>(value: T): T;
+//# sourceMappingURL=cache-state.d.ts.map

package/core/cache-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-state.d.ts","sourceRoot":"","sources":["../../../src/core/cache-state.ts"],"names":[],"mappings":"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"}

package/core/cache-state.js

@@ -0,0 +1,87 @@
+export const HONUA_DEFAULT_METADATA_CACHE_TTL_MS = 5 * 60 * 1000;
+export const HONUA_DEFAULT_METADATA_STALE_IF_ERROR_MS = 60 * 60 * 1000;
+export function createHonuaCacheState(init) {
+    return {
+        scope: init.scope,
+        status: init.status,
+        keyFingerprint: init.keyFingerprint,
+        ...(init.ageMs !== undefined ? { ageMs: Math.max(0, Math.trunc(init.ageMs)) } : {}),
+        ...(init.ttlMs !== undefined ? { ttlMs: Math.max(0, Math.trunc(init.ttlMs)) } : {}),
+        ...(init.staleIfErrorMs !== undefined ? { staleIfErrorMs: Math.max(0, Math.trunc(init.staleIfErrorMs)) } : {}),
+        ...(init.revalidatedAt ? { revalidatedAt: init.revalidatedAt } : {}),
+        ...(init.sourceUpdatedAt ? { sourceUpdatedAt: init.sourceUpdatedAt } : {}),
+        ...(hasHonuaCacheValidator(init.validator) ? { validator: init.validator } : {}),
+        ...(init.invalidationReason ? { invalidationReason: init.invalidationReason } : {}),
+        ...(init.refreshErrorId ? { refreshErrorId: init.refreshErrorId } : {}),
+    };
+}
+export function normalizeHonuaMetadataRequestOptions(options = {}) {
+    const ttlMs = normalizeNonNegativeInteger(options.ttlMs) ?? HONUA_DEFAULT_METADATA_CACHE_TTL_MS;
+    const staleIfErrorMs = normalizeNonNegativeInteger(options.staleIfErrorMs) ?? HONUA_DEFAULT_METADATA_STALE_IF_ERROR_MS;
+    return {
+        ...(options.signal ? { signal: options.signal } : {}),
+        refresh: options.refresh === true,
+        cache: options.cache === "bypass" ? "bypass" : "default",
+        staleIfError: options.staleIfError !== false,
+        ttlMs,
+        staleIfErrorMs,
+    };
+}
+export function isHonuaCacheEntryFresh(cachedAtMs, now, ttlMs) {
+    return ttlMs === undefined || Math.max(0, now - cachedAtMs) < ttlMs;
+}
+export function isHonuaCacheStatus(value) {
+    return value === "hit" || value === "miss" || value === "stale" || value === "refreshed" || value === "bypass";
+}
+export function honuaCacheValidatorFromHeaders(headers) {
+    const etag = headers.get("etag") ?? undefined;
+    const lastModified = headers.get("last-modified") ?? undefined;
+    return hasHonuaCacheValidator({ etag, lastModified })
+        ? { ...(etag ? { etag } : {}), ...(lastModified ? { lastModified } : {}) }
+        : undefined;
+}
+export function honuaMetadataRequestHeaders(options) {
+    const headers = {
+        Accept: options.accept ?? "application/json",
+    };
+    if (options.bypass) {
+        headers["Cache-Control"] = "no-store";
+        headers.Pragma = "no-cache";
+        return headers;
+    }
+    if (options.refresh) {
+        headers["Cache-Control"] = "no-cache";
+        if (options.validator?.etag) {
+            headers["If-None-Match"] = options.validator.etag;
+        }
+        if (options.validator?.lastModified) {
+            headers["If-Modified-Since"] = options.validator.lastModified;
+        }
+    }
+    return headers;
+}
+export function withHonuaCacheState(value, cache) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return value;
+    }
+    return {
+        ...value,
+        cache,
+    };
+}
+export function withoutHonuaCacheState(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return value;
+    }
+    const { cache: _cache, ...rest } = value;
+    return rest;
+}
+function hasHonuaCacheValidator(value) {
+    return Boolean(value?.etag || value?.lastModified);
+}
+function normalizeNonNegativeInteger(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return undefined;
+    }
+    return Math.max(0, Math.trunc(value));
+}