@honua/app-platform 0.0.20-alpha.0

package/core/client.js

@@ -0,0 +1,1716 @@
+import { HONUA_DEFAULT_METADATA_STALE_IF_ERROR_MS, createHonuaCacheState, honuaCacheValidatorFromHeaders, honuaMetadataRequestHeaders, isHonuaCacheEntryFresh, normalizeHonuaMetadataRequestOptions, withHonuaCacheState, withoutHonuaCacheState, } from "./cache-state.js";
+import { HONUA_MINIMUM_SUPPORTED_SERVER_VERSION, MINIMUM_SUPPORTED_SERVER_RELEASE_CHANNEL, describeCompatibilityError, evaluateCompatibility, parseCompatibilityEnvelope, } from "./compatibility.js";
+import { HonuaHttpError, HonuaNetworkError, HonuaTimeoutError } from "./errors.js";
+import { applyEdits, exportMap, findMap, getFeatureServiceMetadata, getLayerMetadata, getMapLayerMetadata, getMapLegend, getMapServiceMetadata, identifyMap, listServices, queryFeaturesRest, queryMapLayer, queryMapRelatedRecords, queryRelatedRecords, } from "./geoservices.js";
+import { HonuaOdataEntitySet } from "./odata.js";
+import { honuaFacadeFeaturesLayout, resolveOgcEndpointLayout } from "./ogc-endpoint-layout.js";
+import { createOgcItem, deleteOgcItem, getOgcCollection, getOgcFeaturesConformance, getOgcFeaturesLanding, getOgcItem, getOgcQueryables, listOgcCollections, listOgcItems, patchOgcItem, replaceOgcItem, } from "./ogc-features.js";
+import { HonuaOgcMaps, getOgcMapImage, getOgcMapsConformance, getOgcMapsLanding } from "./ogc-maps.js";
+import { HonuaOgcProcesses, cancelOgcProcessJob, executeOgcProcess, getOgcProcess, getOgcProcessJob, getOgcProcessJobResults, getOgcProcessesConformance, getOgcProcessesLanding, listOgcProcesses, } from "./ogc-processes.js";
+import { HonuaOgcRecords, fetchOgcRecordRaw, fetchOgcRecordsRaw, getOgcRecord, getOgcRecordCollection, getOgcRecordsConformance, getOgcRecordsLanding, listOgcRecordCollections, searchOgcRecords, } from "./ogc-records.js";
+import { HonuaOgcTiles, fetchOgcTile, getOgcCollectionTileset, getOgcTileMatrixSet, getOgcTilesConformance, getOgcTilesLanding, listOgcCollectionTilesets, listOgcTileMatrixSets, } from "./ogc-tiles.js";
+import { stripQuery, trimTrailingSlashes } from "./path-utils.js";
+import { decodePbfQueryResponse, isPbfResponse } from "./pbf-decoder.js";
+import { createGeoServicesGpAdapter, createGeospatialGrpcProcessAdapter, createHonuaProcessRunner, createOgcProcessesAdapter, } from "./process-runner.js";
+import { DEFAULT_RETRY_METHODS, createTimeoutSignal, normalizeNetworkError, normalizeRetryOptions, normalizeTimeoutMs, resolveGrpcRetryDelayMs, resolveRetryDelayMs, shouldRetryGrpcCall, shouldRetryRequest, sleep, toHttpError, } from "./request-pipeline.js";
+import { HonuaStacSearch, getStacCollection, getStacItem, getStacLanding, listStacCollections, searchStac, } from "./stac.js";
+import { HonuaFeatureLayer, HonuaGeometryService, HonuaGeoprocessingService, HonuaImageService, HonuaMapLayer, HonuaMapService, HonuaOgcFeatures, HonuaService, } from "./surfaces.js";
+import { HonuaWfs } from "./wfs.js";
+import { mergeHeaders } from "./wire-shared.js";
+import { HonuaWms, getWmsCapabilities, getWmsFeatureInfo, getWmsLegend, getWmsMap } from "./wms.js";
+import { HonuaWmts, fetchWmtsTile, getWmtsCapabilities, getWmtsFeatureInfo } from "./wmts.js";
+// Re-exported so the long-standing `@honua/sdk-js` public export path
+// (`export { HONUA_MINIMUM_SUPPORTED_SERVER_VERSION } from "./core/client.js"`)
+// is preserved now that the constant lives in the compatibility module.
+export { HONUA_MINIMUM_SUPPORTED_SERVER_VERSION } from "./compatibility.js";
+function normalizeBaseUrl(baseUrl) {
+    return trimTrailingSlashes(baseUrl);
+}
+function normalizePath(path) {
+    if (path.startsWith("http://") || path.startsWith("https://")) {
+        return path;
+    }
+    return path.startsWith("/") ? path : `/${path}`;
+}
+function isAbsoluteHttpUrl(value) {
+    return value.startsWith("http://") || value.startsWith("https://");
+}
+function resolveRequestUrl(baseUrl, path) {
+    if (isAbsoluteHttpUrl(path)) {
+        if (!isAbsoluteHttpUrl(baseUrl)) {
+            throw new Error("Absolute request URLs are not allowed when baseUrl is relative.");
+        }
+        const baseOrigin = new URL(baseUrl).origin;
+        const requestUrl = new URL(path);
+        if (requestUrl.origin !== baseOrigin) {
+            throw new Error(`Cross-origin request URL is not allowed: ${path}`);
+        }
+        return requestUrl.toString();
+    }
+    return `${baseUrl}${path}`;
+}
+/**
+ * The maximum number of HTTP redirects {@link HonuaClient.fetchWithSafeRedirects}
+ * will follow before giving up. Mirrors the conventional browser/undici limit of 20.
+ */
+const MAX_SAFE_REDIRECTS = 20;
+/**
+ * HTTP status codes that represent a redirect carrying a `Location` header.
+ */
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/**
+ * Resolve a redirect `Location` (which may be relative) against the URL that
+ * produced the redirect and assert it stays on the configured base origin.
+ *
+ * The SDK attaches the API key as a custom `X-API-Key` header. The Fetch/undici
+ * runtime only strips `Authorization`/`Cookie`/`Host` on a cross-origin redirect,
+ * so custom auth headers like `X-API-Key` would otherwise be replayed to an
+ * attacker-controlled `Location` host. To prevent that credential disclosure we
+ * never auto-follow redirects; we re-run the same origin guard used at request
+ * construction and refuse to follow any redirect that leaves the base origin.
+ *
+ * @throws if the target origin differs from the base origin, or if the
+ *   `Location` header is missing/unparsable.
+ */
+function resolveRedirectUrl(baseUrl, fromUrl, location) {
+    if (!location) {
+        throw new Error("Redirect response is missing a Location header.");
+    }
+    let target;
+    try {
+        target = new URL(location, fromUrl);
+    }
+    catch {
+        throw new Error(`Redirect response has an invalid Location header: ${location}`);
+    }
+    // Re-run the base-origin guard against the redirect target so the API key is
+    // never forwarded off the configured origin.
+    return resolveRequestUrl(baseUrl, target.toString());
+}
+function normalizeInterceptorRequestUrl(baseUrl, url) {
+    if (isAbsoluteHttpUrl(url)) {
+        return resolveRequestUrl(baseUrl, url);
+    }
+    if (!isAbsoluteHttpUrl(baseUrl)) {
+        return url;
+    }
+    return resolveRequestUrl(baseUrl, normalizePath(url));
+}
+const DEFAULT_AUTH_REFRESH_SKEW_MS = 60_000;
+const DEFAULT_METADATA_CACHE_MAX_ENTRIES = 256;
+/**
+ * The main Honua HTTP/gRPC-Web client.
+ *
+ * `HonuaClient` is the protocol-aware entry point into the Honua server. It speaks
+ * GeoServices (FeatureServer, MapServer, ImageServer, GeometryServer, GPServer),
+ * OGC API Features / Tiles / Maps / Processes, STAC, WMS, WMTS, WFS 2.0, and OData v4,
+ * with one consistent request/response shape, capability negotiation, optional retries,
+ * pluggable auth, and a small in-process metadata cache.
+ *
+ * For cross-protocol code that does not need to know the underlying service shape,
+ * prefer the protocol-neutral {@link createDataset} contract from `@honua/sdk-js/contract`
+ * — it wraps this client and exposes a single `Source.query(...)` surface that throws
+ * {@link HonuaCapabilityNotSupportedError} when a protocol cannot satisfy the request.
+ *
+ * @example Basic usage
+ * ```ts
+ * import { HonuaClient } from "@honua/sdk-js/honua";
+ *
+ * const client = new HonuaClient({
+ *   baseUrl: "https://your-honua-server.example",
+ *   apiKey: process.env.HONUA_API_KEY,
+ * });
+ *
+ * const { supported, reasons } = await client.checkCompatibility();
+ * if (!supported) {
+ *   throw new Error(`Unsupported Honua server: ${reasons.join("; ")}`);
+ * }
+ *
+ * const result = await client.queryFeatures({
+ *   serviceId: "natural-earth",
+ *   layerId: 0,
+ *   where: "1=1",
+ *   outFields: ["*"],
+ *   returnGeometry: true,
+ *   resultRecordCount: 25,
+ * });
+ *
+ * console.log(`Loaded ${result.features?.length ?? 0} features`);
+ * ```
+ *
+ * @example Per-service fluent wrappers
+ * ```ts
+ * const parcels = client.featureLayer<{ NAME: string }>("parcels", 0);
+ * const items = await client.ogcFeatures();
+ * const wms = client.wms("usgs-imagery");
+ * ```
+ *
+ * @public
+ */
+export class HonuaClient {
+    /** The minimum Honua server version this SDK is contractually tested against. */
+    static minimumSupportedServerVersion = HONUA_MINIMUM_SUPPORTED_SERVER_VERSION;
+    static minimumSupportedServerReleaseChannel = MINIMUM_SUPPORTED_SERVER_RELEASE_CHANNEL;
+    baseUrl;
+    fetchFn;
+    defaultHeaders;
+    authProvider;
+    authRefreshSkewMs;
+    interceptors;
+    timeoutMs;
+    retryOptions;
+    preferBinary;
+    transport;
+    /**
+     * Low-level transport handed to the per-protocol wire modules. Binds the
+     * client's private request primitives so each protocol family builds its own
+     * URLs/params/parsing without reaching into the client.
+     */
+    protocolTransport;
+    serverCompatibilityCache;
+    authCredentialsCache;
+    authRefreshPromise;
+    connectClient;
+    metadataCache = new Map();
+    ogcLayoutCache = new Map();
+    /**
+     * Create a new `HonuaClient`.
+     *
+     * @param options - Connection, auth, transport, retry, and interceptor configuration.
+     *   See {@link HonuaClientOptions} for every field and `@example` blocks for common shapes.
+     *
+     * @example Minimal
+     * ```ts
+     * const client = new HonuaClient({ baseUrl: "https://your-honua-server.example" });
+     * ```
+     *
+     * @example With API key + retries + timeout
+     * ```ts
+     * const client = new HonuaClient({
+     *   baseUrl: "https://your-honua-server.example",
+     *   apiKey: process.env.HONUA_API_KEY,
+     *   retry: { maxRetries: 3 },
+     *   timeoutMs: 30_000,
+     * });
+     * ```
+     */
+    constructor(options) {
+        this.baseUrl = normalizeBaseUrl(options.baseUrl);
+        // Bind to `globalThis` at assignment: the default browser `fetch` is an
+        // unbound `window.fetch`, and invoking it as `this.fetchFn(...)` rebinds
+        // its receiver to the client instance, which browsers reject with
+        // "TypeError: Illegal invocation". Binding is a no-op for Node's undici
+        // fetch and for caller-supplied wrappers (arrow/bound functions ignore it).
+        this.fetchFn = (options.fetchFn ?? fetch).bind(globalThis);
+        const headers = {};
+        if (options.apiKey) {
+            headers["X-API-Key"] = options.apiKey;
+        }
+        if (options.bearerToken) {
+            headers.Authorization = `Bearer ${options.bearerToken}`;
+        }
+        this.defaultHeaders = headers;
+        this.authProvider = normalizeAuthProvider(options.auth);
+        this.authRefreshSkewMs = normalizeAuthRefreshSkewMs(options.authRefreshSkewMs);
+        this.interceptors = options.interceptors ?? [];
+        this.timeoutMs = normalizeTimeoutMs(options.timeoutMs);
+        this.retryOptions = normalizeRetryOptions(options.retry);
+        this.preferBinary = options.preferBinary === true;
+        this.transport = options.transport ?? "rest";
+        this.protocolTransport = {
+            baseUrl: this.baseUrl,
+            requestJson: (method, path, init, signal) => this.requestJson(method, path, init, signal),
+            requestText: (method, path, requestTextOptions) => this.requestText(method, path, requestTextOptions),
+            requestBytes: (method, path, accept, init, signal) => this.requestBytes(method, path, accept, init, signal),
+            requestCachedMetadataJson: (cacheKey, path, metadataOptions) => this.requestCachedMetadataJson(cacheKey, path, metadataOptions),
+            pipelineFetch: (method, path, init, callerSignal, pipelineOptions) => this.pipelineFetch(method, path, init, callerSignal, pipelineOptions),
+            requestBinaryWithJsonFallback: (method, path, params, signal) => this.requestBinaryWithJsonFallback(method, path, params, signal),
+        };
+        if (this.transport === "grpc-web") {
+            this.initConnectClient();
+        }
+    }
+    /**
+     * Connect interceptor that injects the same credentials the REST pipeline
+     * uses (`apiKey`/`bearerToken` from {@link defaultHeaders} plus any provider
+     * credentials resolved via {@link resolveAuthHeaders}) onto every gRPC-web
+     * call. Without it the advertised `transport: "grpc-web"` path would send
+     * every RPC unauthenticated.
+     */
+    buildConnectAuthInterceptor() {
+        return (next) => async (req) => {
+            const headers = await this.composeHeaders();
+            for (const [key, value] of Object.entries(headers)) {
+                req.header.set(key, value);
+            }
+            return next(req);
+        };
+    }
+    /**
+     * Connect interceptor that applies the SDK's configured `retry` policy to
+     * gRPC-web calls, mirroring the REST request pipeline. It retries only
+     * replay-safe **unary** calls (server-streaming responses cannot be safely
+     * replayed mid-iteration, the gRPC analog of the REST
+     * {@link DEFAULT_RETRY_METHODS} idempotency gate) on the transient
+     * {@link shouldRetryGrpcCall} status codes, backing off with the shared
+     * exponential-with-jitter math (honoring any `retry-after` metadata) and
+     * stopping immediately once the call's abort signal fires (caller abort or the
+     * `timeoutMs` deadline). It wraps the auth interceptor so each attempt
+     * re-resolves fresh credentials.
+     */
+    buildConnectRetryInterceptor() {
+        return (next) => async (req) => {
+            // Only retry replay-safe unary calls; mirror REST idempotency scoping.
+            if (req.stream || !this.retryOptions) {
+                return next(req);
+            }
+            const retryOptions = this.retryOptions;
+            for (let attempt = 0;; attempt += 1) {
+                try {
+                    return await next(req);
+                }
+                catch (error) {
+                    const aborted = req.signal?.aborted === true;
+                    if (!shouldRetryGrpcCall(retryOptions, attempt, error, aborted)) {
+                        throw error;
+                    }
+                    await sleep(resolveGrpcRetryDelayMs(retryOptions, attempt, error), req.signal);
+                }
+            }
+        };
+    }
+    /**
+     * Shared gRPC-web transport options. The auth interceptor mirrors the REST
+     * credential pipeline, the retry interceptor (when `retry` is configured)
+     * applies the same retry/backoff policy as REST, and `defaultTimeoutMs`
+     * honors the documented `timeoutMs` contract on every RPC (per-call abort
+     * signals are threaded by the individual RPC methods).
+     */
+    connectTransportOptions() {
+        // Order matters: the retry interceptor must wrap the auth interceptor so
+        // every replayed attempt re-runs auth and re-resolves credential headers.
+        const interceptors = [this.buildConnectAuthInterceptor()];
+        if (this.retryOptions) {
+            interceptors.unshift(this.buildConnectRetryInterceptor());
+        }
+        return {
+            baseUrl: this.baseUrl,
+            fetch: this.fetchFn,
+            interceptors,
+            ...(this.timeoutMs !== undefined ? { defaultTimeoutMs: this.timeoutMs } : {}),
+        };
+    }
+    initConnectClient() {
+        // Dynamic imports are used to avoid bundling Connect dependencies
+        // when only the REST transport is used. The imports are resolved
+        // at module level since they are static ESM imports.
+        import("@connectrpc/connect").then(({ createClient }) => import("@connectrpc/connect-web").then(({ createGrpcWebTransport }) => import("../gen/honua/v1/feature_service_pb.js").then(({ FeatureService }) => {
+            const transport = createGrpcWebTransport(this.connectTransportOptions());
+            this.connectClient = createClient(FeatureService, transport);
+        })));
+    }
+    async ensureConnectClient() {
+        if (this.connectClient) {
+            return this.connectClient;
+        }
+        // If initConnectClient hasn't resolved yet, wait for it
+        const { createClient } = await import("@connectrpc/connect");
+        const { createGrpcWebTransport } = await import("@connectrpc/connect-web");
+        const { FeatureService } = await import("../gen/honua/v1/feature_service_pb.js");
+        const transport = createGrpcWebTransport(this.connectTransportOptions());
+        this.connectClient = createClient(FeatureService, transport);
+        return this.connectClient;
+    }
+    /**
+     * Perform a fetch that never auto-follows a cross-origin redirect.
+     *
+     * Browsers/undici forward custom request headers (such as the SDK's
+     * `X-API-Key`) across redirects, stripping only `Authorization`/`Cookie`/`Host`
+     * cross-origin. To avoid leaking the API key to an attacker-supplied
+     * `Location` host, this issues every request with `redirect: "manual"` and
+     * only follows a redirect when its target origin still matches the configured
+     * base origin (re-running the {@link resolveRequestUrl} origin guard).
+     * Cross-origin redirects throw before the credentialed request is replayed.
+     */
+    async fetchWithSafeRedirects(url, init) {
+        let currentUrl = url;
+        let currentInit = init;
+        for (let redirects = 0;; redirects += 1) {
+            const response = await this.fetchFn(currentUrl, { ...currentInit, redirect: "manual" });
+            // `redirect: "manual"` surfaces redirects as status 3xx with a usable
+            // `Location` header (and, in fetch, an "opaqueredirect" type with status 0
+            // in some runtimes — treated as a same-origin-unverifiable redirect we
+            // must refuse to follow blindly).
+            if (response.type === "opaqueredirect") {
+                throw new HonuaNetworkError("Refusing to follow an opaque cross-origin redirect; the request's API key would be leaked to the redirect target.", undefined);
+            }
+            if (!REDIRECT_STATUSES.has(response.status)) {
+                return response;
+            }
+            if (redirects >= MAX_SAFE_REDIRECTS) {
+                throw new HonuaNetworkError(`Exceeded the maximum of ${MAX_SAFE_REDIRECTS} redirects.`, undefined);
+            }
+            // Re-validate the redirect target against the base origin. A cross-origin
+            // target throws here, so the API key is never replayed off-origin.
+            const location = response.headers.get("location");
+            const nextUrl = resolveRedirectUrl(this.baseUrl, currentUrl, location);
+            // Apply the standard Fetch redirect method/body rewriting so the followed
+            // (same-origin) request matches what the runtime would have done natively:
+            // 303 always becomes GET; 301/302 turn a non-GET/HEAD into GET. The body
+            // is dropped whenever the method changes to GET.
+            const method = (currentInit.method ?? "GET").toUpperCase();
+            const downgradeToGet = response.status === 303 ||
+                ((response.status === 301 || response.status === 302) && method !== "GET" && method !== "HEAD");
+            currentInit = downgradeToGet ? { ...currentInit, method: "GET", body: null } : currentInit;
+            currentUrl = nextUrl;
+            // Drain the redirect body so the underlying connection can be reused.
+            await response.body?.cancel().catch(() => undefined);
+        }
+    }
+    static async loadGrpcAdapter() {
+        return import("./grpc-adapter.js");
+    }
+    get isGrpcWeb() {
+        return this.transport === "grpc-web";
+    }
+    /**
+     * Normalized base URL the client was constructed with (trailing slashes
+     * trimmed). Helpers that build absolute URLs without going through
+     * `request()` (e.g. tile URL generators) read this so they produce the
+     * same origin and base path the server actually serves from.
+     */
+    get serverBaseUrl() {
+        return this.baseUrl;
+    }
+    /**
+     * Force-refresh credentials from the configured auth provider. The SDK
+     * keeps the result in memory only; callers own durable and secure storage.
+     */
+    async refreshAuthCredentials(reason = "manual") {
+        const cached = await this.resolveAuthCredentials({
+            forceRefresh: true,
+            reason,
+        });
+        return cached?.credentials;
+    }
+    /**
+     * Resolve the auth headers the client would attach to an outgoing request
+     * right now, refreshing provider credentials first if they are expiring.
+     *
+     * Transports that build their own connection outside the REST/gRPC pipeline —
+     * notably realtime SSE streams, which must re-authenticate on every
+     * (re)connect so a refreshed token is picked up after a drop — call this per
+     * connect to obtain fresh credentials. Returns an empty object when no
+     * credentials are configured.
+     */
+    async getAuthHeaders() {
+        return this.composeHeaders();
+    }
+    /**
+     * Resolve just the current bearer/authorization token value (without the
+     * `Bearer ` scheme prefix when a plain bearer token is configured), or
+     * `undefined` if none. Convenience for realtime transports that must carry the
+     * token as a query parameter (native `EventSource` cannot set headers).
+     */
+    async getAuthToken() {
+        const headers = await this.composeHeaders();
+        const authorization = headers.Authorization ?? headers.authorization;
+        if (authorization) {
+            return authorization.startsWith("Bearer ") ? authorization.slice("Bearer ".length) : authorization;
+        }
+        return headers["X-API-Key"] ?? headers["x-api-key"];
+    }
+    /** Drop cached provider credentials without calling a revocation endpoint. */
+    clearAuthCredentials() {
+        this.authCredentialsCache = undefined;
+    }
+    /**
+     * Revoke the currently cached credentials through the provider, when it
+     * exposes a revocation hook, then clear the SDK's in-memory cache.
+     */
+    async revokeAuthCredentials(context = { reason: "manual" }) {
+        const cached = this.authCredentialsCache;
+        this.authCredentialsCache = undefined;
+        if (cached && this.authProvider?.revokeCredentials) {
+            await this.authProvider.revokeCredentials(cached.credentials, context);
+        }
+    }
+    /**
+     * Drive a paginated FeatureServer query as an async generator. Each yielded
+     * chunk is a `HonuaFeature[]` slice; iteration stops when the server stops
+     * advertising `exceededTransferLimit`. Lower-level than
+     * `dataset.source(...).queryAll()` but suitable for streaming pipelines that
+     * want backpressure between pages.
+     *
+     * @example
+     * ```ts
+     * for await (const page of client.queryFeaturesStream({ serviceId: "parcels", layerId: 0, where: "1=1" })) {
+     *   process(page);
+     * }
+     * ```
+     */
+    async *queryFeaturesStream(request) {
+        const client = await this.ensureConnectClient();
+        const grpcAdapter = await HonuaClient.loadGrpcAdapter();
+        const protoRequest = grpcAdapter.toProtoQueryRequest(request);
+        yield* grpcAdapter.streamProtoPages(client.queryFeaturesStream(protoRequest, request.signal ? { signal: request.signal } : undefined));
+    }
+    service(serviceId) {
+        return new HonuaService({
+            client: this,
+            serviceId,
+        });
+    }
+    /**
+     * Construct a typed wrapper for a single FeatureServer layer.
+     *
+     * The returned {@link HonuaFeatureLayer} carries the same `serviceId` / `layerId`
+     * on every call so you can write `await layer.queryFeatures({ where: "..." })`
+     * without restating the address.
+     *
+     * @typeParam T - The attribute shape of features in this layer.
+     *
+     * @example
+     * ```ts
+     * const parcels = client.featureLayer<{ NAME: string; STATUS: string }>("parcels", 0);
+     * const { features } = await parcels.queryFeatures({ where: "STATUS = 'ACTIVE'" });
+     * ```
+     */
+    featureLayer(serviceId, layerId) {
+        return new HonuaFeatureLayer({
+            client: this,
+            serviceId,
+            layerId,
+        });
+    }
+    mapService(serviceId) {
+        return new HonuaMapService({
+            client: this,
+            serviceId,
+        });
+    }
+    mapLayer(serviceId, layerId) {
+        return new HonuaMapLayer({
+            client: this,
+            serviceId,
+            layerId,
+        });
+    }
+    /**
+     * Construct the OGC API Features client wrapper.
+     *
+     * Use this to walk collections (`landing()`, `conformance()`, `collections()`),
+     * read items (`items()`, `item()`), and apply edits (`create*` / `replace*` /
+     * `patch*` / `delete*`) against an OGC API Features endpoint exposed by the
+     * Honua server.
+     *
+     * @example
+     * ```ts
+     * const features = client.ogcFeatures();
+     * const collections = await features.collections();
+     * const items = await features.items("parcels", { limit: 100 });
+     * ```
+     */
+    ogcFeatures() {
+        return new HonuaOgcFeatures({
+            client: this,
+        });
+    }
+    ogcTiles() {
+        return new HonuaOgcTiles({ client: this });
+    }
+    ogcMaps() {
+        return new HonuaOgcMaps({ client: this });
+    }
+    ogcRecords() {
+        return new HonuaOgcRecords({ client: this });
+    }
+    wms(serviceId) {
+        return new HonuaWms({ client: this, serviceId });
+    }
+    wmts(serviceId) {
+        return new HonuaWmts({ client: this, serviceId });
+    }
+    ogcProcesses() {
+        return new HonuaOgcProcesses({ client: this });
+    }
+    stac() {
+        return new HonuaStacSearch({ client: this });
+    }
+    imageService(serviceId) {
+        return new HonuaImageService({ client: this, serviceId });
+    }
+    geometryService() {
+        return new HonuaGeometryService({ client: this });
+    }
+    geoprocessing(serviceId, taskName) {
+        return new HonuaGeoprocessingService({ client: this, serviceId, taskName });
+    }
+    processRunner(adapter) {
+        return createHonuaProcessRunner(adapter);
+    }
+    ogcProcessRunner() {
+        return createHonuaProcessRunner(createOgcProcessesAdapter(this.ogcProcesses()));
+    }
+    geoprocessingRunner(serviceId, taskName) {
+        return createHonuaProcessRunner(createGeoServicesGpAdapter(this.geoprocessing(serviceId, taskName)));
+    }
+    geospatialGrpcProcessRunner(processClient) {
+        return createHonuaProcessRunner(createGeospatialGrpcProcessAdapter(processClient));
+    }
+    wfs(endpointUrl = "/wfs", options = {}) {
+        return new HonuaWfs({ client: this, endpointUrl, version: options.version });
+    }
+    odata(entitySet, options = {}) {
+        return new HonuaOdataEntitySet({ client: this, entitySet, basePath: options.basePath });
+    }
+    clearMetadataCache(options = {}) {
+        if (!options.keyPrefix) {
+            this.metadataCache.clear();
+            return;
+        }
+        const prefix = `metadata:${options.keyPrefix}`;
+        for (const key of this.metadataCache.keys()) {
+            if (key.startsWith(prefix)) {
+                this.metadataCache.delete(key);
+            }
+        }
+    }
+    async listServices(formatOrOptions = "json", options = {}) {
+        const format = typeof formatOrOptions === "string" ? formatOrOptions : "json";
+        const metadataOptions = typeof formatOrOptions === "string" ? options : formatOrOptions;
+        return listServices(this.protocolTransport, format, metadataOptions);
+    }
+    /**
+     * Fetch and parse the server's compatibility contract from `GET /api/v1/admin/capabilities`.
+     *
+     * The first call populates an in-process cache; subsequent calls return the cached value
+     * unless `options.refresh` is `true`. Use {@link HonuaClient.checkCompatibility} instead
+     * when you want a non-throwing pass/fail signal with a list of reasons.
+     *
+     * @throws {@link HonuaError} when the server response cannot be parsed into a valid
+     *   compatibility envelope (missing `serverVersion`, `controlPlaneApi`, etc.).
+     *
+     * @example
+     * ```ts
+     * const contract = await client.getCompatibility();
+     * console.log(contract.serverVersion, contract.releaseChannel);
+     * console.log(contract.metadataSchemas);
+     * ```
+     */
+    async getCompatibility(options = {}) {
+        if (!options.refresh && this.serverCompatibilityCache) {
+            return this.serverCompatibilityCache;
+        }
+        const response = (await this.requestJson("GET", "/api/v1/admin/capabilities", undefined, options.signal));
+        const compatibility = parseCompatibilityEnvelope(response);
+        this.serverCompatibilityCache = compatibility;
+        return compatibility;
+    }
+    /**
+     * Probe the server's compatibility contract and return a structured pass/fail status.
+     *
+     * Unlike {@link HonuaClient.getCompatibility}, this method does not throw on transport
+     * or parse failures — those are reported as `supported: false` with a human-readable
+     * `reasons` entry. Use this at app startup to fail loudly before exercising admin or
+     * control-plane flows.
+     *
+     * @example
+     * ```ts
+     * const { supported, reasons } = await client.checkCompatibility();
+     * if (!supported) {
+     *   throw new Error(`Unsupported Honua server: ${reasons.join("; ")}`);
+     * }
+     * ```
+     */
+    async checkCompatibility(options = {}) {
+        try {
+            const compatibility = await this.getCompatibility(options);
+            const reasons = evaluateCompatibility(compatibility);
+            return {
+                supported: reasons.length === 0,
+                minimumSupportedServerVersion: HonuaClient.minimumSupportedServerVersion,
+                compatibility,
+                reasons,
+            };
+        }
+        catch (error) {
+            return {
+                supported: false,
+                minimumSupportedServerVersion: HonuaClient.minimumSupportedServerVersion,
+                reasons: [describeCompatibilityError(error)],
+            };
+        }
+    }
+    /**
+     * Returns `true` if the server's `data.compatibility.features` map advertises the
+     * given coarse capability. Use this to gate experimental or admin-only workflows.
+     *
+     * @example
+     * ```ts
+     * if (await client.supportsFeature("manifestApply")) {
+     *   // safe to call the manifest apply admin endpoint
+     * }
+     * ```
+     */
+    async supportsFeature(feature, options = {}) {
+        const compatibility = await this.getCompatibility(options);
+        return compatibility.features[feature];
+    }
+    /**
+     * Scan a supported migration source through the admin import scanner.
+     *
+     * A successful HTTP response means the server returned a deterministic
+     * inventory artifact; callers still need to inspect
+     * `scanCompleteness.status`, which can be `"failed"` on `200 OK`.
+     */
+    async scanMigrationSource(request) {
+        const { signal, exportJson, ...body } = request;
+        const path = `/api/v1/admin/import/scan${exportJson ? "?export=json" : ""}`;
+        return this.requestJson("POST", path, {
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        }, signal);
+    }
+    async request(request) {
+        const method = request.method ?? "GET";
+        const params = new URLSearchParams();
+        params.set("f", request.responseFormat ?? "json");
+        if (request.query) {
+            for (const [key, value] of Object.entries(request.query)) {
+                params.set(key, String(value));
+            }
+        }
+        const normalizedPath = normalizePath(request.path);
+        const pathWithQuery = mergePathWithQueryParams(normalizedPath, params);
+        return this.requestJson(method, pathWithQuery, {
+            headers: request.headers,
+            body: request.body,
+        }, request.signal);
+    }
+    /**
+     * Pipeline-aware JSON request that bypasses the GeoServices `f=json`
+     * convention used by {@link request}. Adapters whose protocols do not
+     * model `f=` (OData, OGC API, …) call this directly so they keep the
+     * shared auth / retry / timeout / interceptor pipeline without sending
+     * a query parameter the server would reject as `InvalidQueryOption`.
+     *
+     * Caller-supplied query parameters belong on `path` itself; `init`
+     * carries the body, headers, and abort signal. The default `Accept`
+     * header is `application/json`; pass an explicit `Accept` in
+     * `init.headers` to override.
+     */
+    async pipelineRequestJson(method, path, init, signal) {
+        return this.requestJson(method, path, init, signal);
+    }
+    async composeHeaders(...headersList) {
+        const authHeaders = await this.resolveAuthHeaders();
+        return mergeHeaders(this.defaultHeaders, authHeaders, ...headersList);
+    }
+    async resolveAuthHeaders() {
+        const cached = await this.resolveAuthCredentials({ forceRefresh: false });
+        if (!cached)
+            return undefined;
+        return authHeadersFromCredentials(cached.credentials);
+    }
+    async resolveAuthCredentials(options) {
+        if (!this.authProvider) {
+            return undefined;
+        }
+        const cached = this.authCredentialsCache;
+        if (!options.forceRefresh && cached && !isAuthCredentialsExpiring(cached, this.authRefreshSkewMs)) {
+            return cached;
+        }
+        if (this.authRefreshPromise) {
+            return this.authRefreshPromise;
+        }
+        const reason = options.reason ?? resolveAuthRefreshReason(cached);
+        this.authRefreshPromise = this.loadAuthCredentials(reason, options.forceRefresh, cached?.credentials);
+        try {
+            return await this.authRefreshPromise;
+        }
+        finally {
+            this.authRefreshPromise = undefined;
+        }
+    }
+    async loadAuthCredentials(reason, forceRefresh, previousCredentials) {
+        const credentials = normalizeAuthCredentials(await this.authProvider?.getCredentials({
+            reason,
+            forceRefresh,
+            ...(previousCredentials ? { previousCredentials } : {}),
+        }));
+        if (!credentials) {
+            this.authCredentialsCache = undefined;
+            return undefined;
+        }
+        const cached = {
+            credentials,
+            expiresAtMs: normalizeAuthExpiresAtMs(credentials.expiresAt),
+        };
+        this.authCredentialsCache = cached;
+        return cached;
+    }
+    /**
+     * Pipeline-aware request that returns the raw `Response` after the
+     * shared auth / retry / timeout / interceptor pipeline finishes
+     * successfully. Used by adapters that need to consume non-JSON bodies
+     * (OData `$metadata` XML, raw passthrough) without inheriting the
+     * `Accept: application/json` default of {@link pipelineRequestJson}.
+     *
+     * The returned `Response` is unconsumed — the caller picks `.json()`,
+     * `.text()`, or `.arrayBuffer()`. Non-2xx responses still throw the
+     * normalized `HonuaHttpError` (and trigger retries) so error handling
+     * matches every other client method.
+     */
+    async pipelineFetch(method, path, init, callerSignal, options = {}) {
+        const request = {
+            url: resolveRequestUrl(this.baseUrl, path),
+            path,
+            method,
+            init: {
+                method,
+                headers: await this.composeHeaders(init?.headers),
+                body: init?.body ?? null,
+                ...(init?.signal ? { signal: init.signal } : {}),
+            },
+        };
+        return this.executeRequest(request, {
+            callerSignal,
+            ...(options.okStatuses ? { okStatuses: options.okStatuses } : {}),
+            finalize: async (response, _durationMs, _request, runAfter) => {
+                await runAfter();
+                return response;
+            },
+        });
+    }
+    async requestCachedMetadataJson(cacheKey, path, options = {}) {
+        const metadataOptions = normalizeHonuaMetadataRequestOptions(options);
+        const keyFingerprint = `metadata:${cacheKey}`;
+        const cached = this.metadataCache.get(keyFingerprint);
+        const bypass = metadataOptions.cache === "bypass";
+        const now = Date.now();
+        const freshCachedEntry = cached ? isHonuaCacheEntryFresh(cached.cachedAtMs, now, metadataOptions.ttlMs) : false;
+        if (!bypass && !metadataOptions.refresh && cached && freshCachedEntry) {
+            return withHonuaCacheState(cached.body, createMetadataCacheState(cached, "hit", {
+                now,
+                ttlMs: metadataOptions.ttlMs,
+                staleIfErrorMs: metadataOptions.staleIfErrorMs,
+            }));
+        }
+        const request = {
+            url: resolveRequestUrl(this.baseUrl, path),
+            path,
+            method: "GET",
+            init: {
+                method: "GET",
+                headers: await this.composeHeaders(honuaMetadataRequestHeaders({
+                    accept: "application/json",
+                    refresh: metadataOptions.refresh || Boolean(cached),
+                    bypass,
+                    validator: cached?.validator,
+                })),
+            },
+        };
+        return this.executeRequest(request, {
+            callerSignal: metadataOptions.signal,
+            // stale-if-error fallback on a terminal network or HTTP failure.
+            onTerminalError: (error) => this.staleMetadataFallback(cached, metadataOptions, error),
+            // 304 Not Modified: revalidate the cached entry without re-parsing a body.
+            shortCircuit: async (response, _durationMs, _currentRequest, runAfter) => {
+                if (response.status !== 304 || !cached || bypass) {
+                    return undefined;
+                }
+                await runAfter();
+                const updatedEntry = {
+                    ...cached,
+                    cachedAtMs: Date.now(),
+                    ...((honuaCacheValidatorFromHeaders(response.headers) ?? cached.validator)
+                        ? { validator: honuaCacheValidatorFromHeaders(response.headers) ?? cached.validator }
+                        : {}),
+                };
+                this.setMetadataCacheEntry(keyFingerprint, updatedEntry);
+                return {
+                    value: withHonuaCacheState(updatedEntry.body, createMetadataCacheState(updatedEntry, "refreshed", {
+                        now: Date.now(),
+                        ttlMs: metadataOptions.ttlMs,
+                        staleIfErrorMs: metadataOptions.staleIfErrorMs,
+                        revalidatedAt: new Date().toISOString(),
+                    })),
+                };
+            },
+            finalize: async (response, durationMs, currentRequest, runAfter) => {
+                const body = await parseResponseBody(this.hasAfterInterceptors() ? response.clone() : response);
+                // GeoServices reports metadata failures (layer not found, invalid token
+                // => code 499, …) as HTTP 200 with a top-level `{error}` envelope.
+                // Detect it before caching so a transient auth/permission error is never
+                // persisted as "valid" metadata for the cache TTL and surfaced
+                // downstream as `undefined` field access instead of a HonuaHttpError.
+                const envelopeError = geoServicesEnvelopeError(response.status, body);
+                if (envelopeError) {
+                    const stale = this.staleMetadataFallback(cached, metadataOptions, envelopeError);
+                    if (stale)
+                        return stale;
+                    await this.applyErrorInterceptors({
+                        request: cloneRequestContext(currentRequest),
+                        error: envelopeError,
+                        durationMs,
+                    });
+                    throw envelopeError;
+                }
+                await runAfter();
+                const cleanBody = withoutHonuaCacheState(body);
+                const validator = honuaCacheValidatorFromHeaders(response.headers);
+                const sourceUpdatedAt = response.headers.get("last-modified") ?? undefined;
+                const entry = {
+                    body: cleanBody,
+                    cachedAtMs: Date.now(),
+                    keyFingerprint,
+                    ...(validator ? { validator } : {}),
+                    ...(sourceUpdatedAt ? { sourceUpdatedAt } : {}),
+                };
+                const status = bypass ? "bypass" : cached ? "refreshed" : "miss";
+                if (!bypass) {
+                    this.setMetadataCacheEntry(keyFingerprint, entry);
+                }
+                return withHonuaCacheState(cleanBody, createMetadataCacheState(entry, status, {
+                    now: Date.now(),
+                    ttlMs: metadataOptions.ttlMs,
+                    staleIfErrorMs: metadataOptions.staleIfErrorMs,
+                    ...(status === "refreshed" ? { revalidatedAt: new Date().toISOString() } : {}),
+                }));
+            },
+        });
+    }
+    staleMetadataFallback(cached, options, error) {
+        if (!cached || options.cache === "bypass" || !options.staleIfError) {
+            return undefined;
+        }
+        const staleIfErrorMs = options.staleIfErrorMs ?? HONUA_DEFAULT_METADATA_STALE_IF_ERROR_MS;
+        if (Date.now() - cached.cachedAtMs > staleIfErrorMs) {
+            return undefined;
+        }
+        return withHonuaCacheState(cached.body, createMetadataCacheState(cached, "stale", {
+            now: Date.now(),
+            ttlMs: options.ttlMs,
+            staleIfErrorMs: options.staleIfErrorMs,
+            refreshErrorId: metadataRefreshErrorId(error),
+        }));
+    }
+    setMetadataCacheEntry(key, entry) {
+        this.metadataCache.set(key, entry);
+        while (this.metadataCache.size > DEFAULT_METADATA_CACHE_MAX_ENTRIES) {
+            const oldest = [...this.metadataCache.entries()].sort((a, b) => a[1].cachedAtMs - b[1].cachedAtMs)[0];
+            if (!oldest)
+                return;
+            this.metadataCache.delete(oldest[0]);
+        }
+    }
+    async getLayerMetadata(serviceId, layerId, options = {}) {
+        return getLayerMetadata(this.protocolTransport, serviceId, layerId, options);
+    }
+    async getFeatureServiceMetadata(serviceId, options = {}) {
+        return getFeatureServiceMetadata(this.protocolTransport, serviceId, options);
+    }
+    /**
+     * Resolve (and memoize) the OGC API Features endpoint layout for the
+     * given discovery `mode`. `honua-facade` (default) returns the fixed
+     * `/ogc/features/...` fast path with no network access; `ogc-api` and
+     * `auto` discover the layout from the server's landing page per OGC API
+     * - Common so the same typed surface works against pygeoapi / ldproxy /
+     * GeoServer. Discovery is cached per mode for the life of the client
+     * (the layout is a function of the fixed `baseUrl`).
+     */
+    resolveOgcFeaturesLayout(mode = "honua-facade") {
+        if (mode === "honua-facade")
+            return Promise.resolve(honuaFacadeFeaturesLayout());
+        let cached = this.ogcLayoutCache.get(mode);
+        if (!cached) {
+            cached = resolveOgcEndpointLayout(this.protocolTransport, mode).catch((err) => {
+                // Allow a later retry after a transient discovery failure.
+                this.ogcLayoutCache.delete(mode);
+                throw err;
+            });
+            this.ogcLayoutCache.set(mode, cached);
+        }
+        return cached;
+    }
+    async getOgcFeaturesLanding(request = {}) {
+        return getOgcFeaturesLanding(this.protocolTransport, request);
+    }
+    async getOgcFeaturesConformance(request = {}) {
+        return getOgcFeaturesConformance(this.protocolTransport, request);
+    }
+    async listOgcCollections(request = {}) {
+        return listOgcCollections(this.protocolTransport, request);
+    }
+    async getOgcCollection(request) {
+        return getOgcCollection(this.protocolTransport, request);
+    }
+    async getOgcQueryables(request) {
+        return getOgcQueryables(this.protocolTransport, request);
+    }
+    async listOgcItems(request) {
+        return listOgcItems(this.protocolTransport, request);
+    }
+    async getOgcItem(request) {
+        return getOgcItem(this.protocolTransport, request);
+    }
+    async createOgcItem(request) {
+        return createOgcItem(this.protocolTransport, request);
+    }
+    async replaceOgcItem(request) {
+        return replaceOgcItem(this.protocolTransport, request);
+    }
+    async patchOgcItem(request) {
+        return patchOgcItem(this.protocolTransport, request);
+    }
+    async deleteOgcItem(request) {
+        await deleteOgcItem(this.protocolTransport, request);
+    }
+    // ── OGC API Tiles ───────────────────────────────────────────
+    async getOgcTilesLanding(request = {}) {
+        return getOgcTilesLanding(this.protocolTransport, request);
+    }
+    async getOgcTilesConformance(request = {}) {
+        return getOgcTilesConformance(this.protocolTransport, request);
+    }
+    async listOgcTileMatrixSets(request = {}) {
+        return listOgcTileMatrixSets(this.protocolTransport, request);
+    }
+    async getOgcTileMatrixSet(request) {
+        return getOgcTileMatrixSet(this.protocolTransport, request);
+    }
+    async listOgcCollectionTilesets(request) {
+        return listOgcCollectionTilesets(this.protocolTransport, request);
+    }
+    async getOgcCollectionTileset(request) {
+        return getOgcCollectionTileset(this.protocolTransport, request);
+    }
+    async fetchOgcTile(request) {
+        return fetchOgcTile(this.protocolTransport, request);
+    }
+    // ── OGC API Maps ────────────────────────────────────────────
+    async getOgcMapsLanding(request = {}) {
+        return getOgcMapsLanding(this.protocolTransport, request);
+    }
+    async getOgcMapsConformance(request = {}) {
+        return getOgcMapsConformance(this.protocolTransport, request);
+    }
+    async getOgcMapImage(request) {
+        return getOgcMapImage(this.protocolTransport, request);
+    }
+    // ── OGC API Records ────────────────────────────────────────
+    async getOgcRecordsLanding(request = {}) {
+        return getOgcRecordsLanding(this.protocolTransport, request);
+    }
+    async getOgcRecordsConformance(request = {}) {
+        return getOgcRecordsConformance(this.protocolTransport, request);
+    }
+    async listOgcRecordCollections(request = {}) {
+        return listOgcRecordCollections(this.protocolTransport, request);
+    }
+    async getOgcRecordCollection(request) {
+        return getOgcRecordCollection(this.protocolTransport, request);
+    }
+    async searchOgcRecords(request) {
+        return searchOgcRecords(this.protocolTransport, request);
+    }
+    async getOgcRecord(request) {
+        return getOgcRecord(this.protocolTransport, request);
+    }
+    async fetchOgcRecordsRaw(request) {
+        return fetchOgcRecordsRaw(this.protocolTransport, request);
+    }
+    async fetchOgcRecordRaw(request) {
+        return fetchOgcRecordRaw(this.protocolTransport, request);
+    }
+    // ── WMS 1.3 ─────────────────────────────────────────────────
+    /**
+     * Fetch and parse a WMS `GetCapabilities` document for the addressed
+     * service. The XML body decodes through `requestText`; the parsed
+     * shape is the typed `WmsCapabilities` envelope (no XML node leaks
+     * through the public surface).
+     */
+    async getWmsCapabilities(request) {
+        return getWmsCapabilities(this.protocolTransport, request);
+    }
+    /** Render a WMS `GetMap`. Returns the raw image bytes. */
+    async getWmsMap(request) {
+        return getWmsMap(this.protocolTransport, request);
+    }
+    /**
+     * Issue a WMS `GetFeatureInfo`. When `INFO_FORMAT=application/json`
+     * the JSON body decodes into the canonical `HonuaTypedFeature[]`
+     * shape; non-JSON formats round-trip on `bytes` so callers retain the
+     * raw payload behind the protocol escape hatch.
+     */
+    async getWmsFeatureInfo(request) {
+        return getWmsFeatureInfo(this.protocolTransport, request);
+    }
+    /**
+     * Fetch a WMS `GetLegendGraphic`. honua-server does not implement
+     * GetLegendGraphic today; callers should branch on
+     * `WmsCapabilities.request.getLegendGraphic` before invoking. When
+     * the wire returns 5xx the underlying `HonuaHttpError` flows through.
+     */
+    async getWmsLegend(request) {
+        return getWmsLegend(this.protocolTransport, request);
+    }
+    // ── WMTS 1.0 ────────────────────────────────────────────────
+    async getWmtsCapabilities(request) {
+        return getWmtsCapabilities(this.protocolTransport, request);
+    }
+    /**
+     * Fetch a single WMTS tile. `mode` selects between KVP
+     * (`?REQUEST=GetTile&...`) and the RESTful path
+     * (`/{layer}/{style}/{tms}/{z}/{y}/{x}.{ext}`). honua-server
+     * advertises both; the SDK defaults to RESTful because the wire path
+     * is a single string substitution per tile and skips
+     * URLSearchParams serialisation on the hot path.
+     */
+    async fetchWmtsTile(request) {
+        return fetchWmtsTile(this.protocolTransport, request);
+    }
+    /**
+     * WMTS GetFeatureInfo. honua-server accepts both KVP and RESTful
+     * routing; mode default mirrors `fetchWmtsTile`.
+     */
+    async getWmtsFeatureInfo(request) {
+        return getWmtsFeatureInfo(this.protocolTransport, request);
+    }
+    // ── OGC API Processes ───────────────────────────────────────
+    async getOgcProcessesLanding(request = {}) {
+        return getOgcProcessesLanding(this.protocolTransport, request);
+    }
+    async getOgcProcessesConformance(request = {}) {
+        return getOgcProcessesConformance(this.protocolTransport, request);
+    }
+    async listOgcProcesses(request = {}) {
+        return listOgcProcesses(this.protocolTransport, request);
+    }
+    async getOgcProcess(request) {
+        return getOgcProcess(this.protocolTransport, request);
+    }
+    async executeOgcProcess(request) {
+        return executeOgcProcess(this.protocolTransport, request);
+    }
+    async getOgcProcessJob(request) {
+        return getOgcProcessJob(this.protocolTransport, request);
+    }
+    async getOgcProcessJobResults(request) {
+        return getOgcProcessJobResults(this.protocolTransport, request);
+    }
+    async cancelOgcProcessJob(request) {
+        return cancelOgcProcessJob(this.protocolTransport, request);
+    }
+    // ── STAC API ────────────────────────────────────────────────
+    async getStacLanding(request = {}) {
+        return getStacLanding(this.protocolTransport, request);
+    }
+    async listStacCollections(request = {}) {
+        return listStacCollections(this.protocolTransport, request);
+    }
+    async getStacCollection(request) {
+        return getStacCollection(this.protocolTransport, request);
+    }
+    async getStacItem(request) {
+        return getStacItem(this.protocolTransport, request);
+    }
+    async searchStac(request = {}) {
+        return searchStac(this.protocolTransport, request);
+    }
+    async getMapServiceMetadata(serviceId, options = {}) {
+        return getMapServiceMetadata(this.protocolTransport, serviceId, options);
+    }
+    async getMapLayerMetadata(serviceId, layerId, options = {}) {
+        return getMapLayerMetadata(this.protocolTransport, serviceId, layerId, options);
+    }
+    /**
+     * Run a GeoServices `FeatureServer/query` request against a Honua-hosted layer.
+     *
+     * This is the canonical low-level read path. It maps directly to the FeatureServer
+     * `query` endpoint and accepts the full ArcGIS query shape (`where`, `outFields`,
+     * `geometry`, `spatialRel`, `orderByFields`, `resultRecordCount`, `outSr`, ...).
+     *
+     * For cross-protocol code (OGC, WFS, OData, STAC), prefer the protocol-neutral
+     * {@link createDataset} contract — it normalizes capability differences and gives
+     * you `Source.query(...)` plus paginated `Source.queryAll(...)` with explicit
+     * `exceededTransferLimit` reporting.
+     *
+     * @example
+     * ```ts
+     * const { features, exceededTransferLimit } = await client.queryFeatures({
+     *   serviceId: "parcels",
+     *   layerId: 0,
+     *   where: "STATUS = 'ACTIVE'",
+     *   outFields: ["OBJECTID", "NAME"],
+     *   returnGeometry: true,
+     *   outSr: 4326,
+     *   resultRecordCount: 500,
+     * });
+     *
+     * if (exceededTransferLimit) {
+     *   // re-issue with `resultOffset` or use queryFeaturesStream / dataset.source().queryAll()
+     * }
+     * ```
+     */
+    async queryFeatures(request) {
+        if (this.transport === "grpc-web") {
+            const client = await this.ensureConnectClient();
+            const grpcAdapter = await HonuaClient.loadGrpcAdapter();
+            const protoRequest = grpcAdapter.toProtoQueryRequest(request);
+            try {
+                const response = await client.queryFeatures(protoRequest, request.signal ? { signal: request.signal } : undefined);
+                return grpcAdapter.fromProtoQueryResponse(response);
+            }
+            catch (error) {
+                throw grpcAdapter.wrapConnectError(error);
+            }
+        }
+        return queryFeaturesRest(this.protocolTransport, request, this.preferBinary);
+    }
+    async queryMapLayer(request) {
+        return queryMapLayer(this.protocolTransport, request);
+    }
+    async applyEdits(request) {
+        return applyEdits(this.protocolTransport, request);
+    }
+    async queryRelatedRecords(request) {
+        return queryRelatedRecords(this.protocolTransport, request);
+    }
+    async queryMapRelatedRecords(request) {
+        return queryMapRelatedRecords(this.protocolTransport, request);
+    }
+    async exportMap(request) {
+        return exportMap(this.protocolTransport, request);
+    }
+    async getMapLegend(request) {
+        return getMapLegend(this.protocolTransport, request);
+    }
+    async identifyMap(request) {
+        return identifyMap(this.protocolTransport, request);
+    }
+    async findMap(request) {
+        return findMap(this.protocolTransport, request);
+    }
+    async requestJson(method, path, init, callerSignal) {
+        const request = {
+            url: resolveRequestUrl(this.baseUrl, path),
+            path,
+            method,
+            init: {
+                method,
+                headers: await this.composeHeaders({ Accept: "application/json" }, init?.headers),
+                body: init?.body,
+            },
+        };
+        return this.executeRequest(request, {
+            callerSignal,
+            finalize: async (response, durationMs, currentRequest, runAfter) => {
+                // Parse the original body directly when no after-interceptor will read
+                // it; only clone when an interceptor needs an independent copy.
+                const body = await parseResponseBody(this.hasAfterInterceptors() ? response.clone() : response);
+                // GeoServices/Esri services return HTTP 200 with a top-level `{error}`
+                // envelope on failure (bad WHERE, invalid outFields, edit failures, …).
+                // Surface these through the unified error model instead of handing the
+                // failure envelope back as a "successful" response object.
+                const envelopeError = geoServicesEnvelopeError(response.status, body);
+                if (envelopeError) {
+                    await this.applyErrorInterceptors({
+                        request: cloneRequestContext(currentRequest),
+                        error: envelopeError,
+                        durationMs,
+                    });
+                    throw envelopeError;
+                }
+                await runAfter();
+                return body;
+            },
+        });
+    }
+    /**
+     * Request a PBF binary response and decode it. Falls back to JSON on failure.
+     */
+    async requestBinaryWithJsonFallback(method, path, params, callerSignal) {
+        const request = {
+            url: resolveRequestUrl(this.baseUrl, path),
+            path,
+            method,
+            init: {
+                method,
+                headers: await this.composeHeaders({ Accept: "application/x-protobuf, application/json;q=0.9" }),
+            },
+        };
+        return this.executeRequest(request, {
+            callerSignal,
+            finalize: async (response, durationMs, currentRequest, runAfter) => {
+                await runAfter();
+                // If the server returned PBF, decode it; on decode failure (including
+                // Z/M geometry the fast path can't handle) retry as f=json.
+                if (isPbfResponse(response)) {
+                    try {
+                        const buffer = await response.arrayBuffer();
+                        return decodePbfQueryResponse(buffer);
+                    }
+                    catch {
+                        params.set("f", "json");
+                        const jsonPath = `${stripQuery(path)}?${params.toString()}`;
+                        return this.requestJson("GET", jsonPath, undefined, callerSignal ?? currentRequest.init.signal ?? undefined);
+                    }
+                }
+                // Server returned JSON despite the PBF request (e.g. error or
+                // unsupported). GeoServices reports query failures (bad WHERE, invalid
+                // outFields, expired token => code 498/499) as HTTP 200 application/json
+                // even when f=pbf was requested. Detect the `{error}` envelope here so
+                // preferBinary callers throw a normalized HonuaHttpError exactly like
+                // the JSON path instead of receiving the failure envelope as success.
+                const body = await parseResponseBody(response);
+                const envelopeError = geoServicesEnvelopeError(response.status, body);
+                if (envelopeError) {
+                    await this.applyErrorInterceptors({
+                        request: cloneRequestContext(currentRequest),
+                        error: envelopeError,
+                        durationMs,
+                    });
+                    throw envelopeError;
+                }
+                return body;
+            },
+        });
+    }
+    /**
+     * Fetch a text response (e.g. XML / JSON / plain) with an explicit Accept
+     * negotiation. Used by the WFS adapter for `GetCapabilities`,
+     * `Transaction` responses, and ExceptionReport bodies, and by the
+     * WMS / WMTS Capabilities pipelines. Routes through the same
+     * interceptor / retry / abort pipeline as `requestJson` /
+     * `requestBytes`, so adapter callers do not need to bypass `HonuaClient`
+     * to reach `fetch` directly.
+     */
+    async requestText(method, path, options) {
+        const acceptHeader = options?.accept ?? "*/*";
+        const headers = { Accept: acceptHeader };
+        if (options?.contentType)
+            headers["Content-Type"] = options.contentType;
+        const request = {
+            url: resolveRequestUrl(this.baseUrl, path),
+            path,
+            method,
+            init: {
+                method,
+                headers: await this.composeHeaders(headers),
+                ...(options?.body !== undefined ? { body: options.body } : {}),
+            },
+        };
+        return this.executeRequest(request, {
+            callerSignal: options?.signal,
+            errorBody: async (response) => {
+                const text = await response.clone().text();
+                const contentType = response.headers.get("content-type") ?? acceptHeader;
+                return text ? { raw: text, contentType } : {};
+            },
+            finalize: async (response, _durationMs, _request, runAfter) => {
+                await runAfter();
+                const text = await response.text();
+                const contentType = response.headers.get("content-type") ?? acceptHeader;
+                return { text, contentType, status: response.status };
+            },
+        });
+    }
+    /**
+     * Fetch a binary response (raw bytes plus content type). Used by the
+     * OGC API Tiles and OGC API Maps wire methods, both of which negotiate
+     * non-JSON output formats. The interceptor / retry / abort plumbing
+     * mirrors `requestJson`.
+     */
+    async requestBytes(method, path, accept, init, callerSignal) {
+        const acceptHeader = accept ?? "application/octet-stream";
+        const request = {
+            url: resolveRequestUrl(this.baseUrl, path),
+            path,
+            method,
+            init: {
+                method,
+                headers: await this.composeHeaders({ Accept: acceptHeader }, init?.headers),
+                body: init?.body,
+            },
+        };
+        return this.executeRequest(request, {
+            callerSignal,
+            finalize: async (response, _durationMs, _request, runAfter) => {
+                await runAfter();
+                const buffer = await response.arrayBuffer();
+                const bytes = new Uint8Array(buffer);
+                return {
+                    bytes,
+                    contentType: response.headers.get("content-type") ?? acceptHeader,
+                    empty: response.status === 204 || bytes.byteLength === 0,
+                };
+            },
+        });
+    }
+    /**
+     * Single owner of the HTTP attempt loop shared by every typed request
+     * wrapper: before-interceptors, per-attempt timeout, network-error
+     * normalization + retry, replay-safe auth refresh, HTTP-status retry, and the
+     * after/error-interceptor calls. The previous implementation copy-pasted this
+     * loop across six methods (pipelineFetch / requestCachedMetadataJson /
+     * requestJson / requestBinaryWithJsonFallback / requestText / requestBytes),
+     * and the copies had drifted in signal, okStatuses, and 304 handling — the
+     * exact surface where an auth-replay / retry regression can appear in one
+     * transport but not the others.
+     *
+     * Wrappers supply only what differs:
+     * - `finalize` turns a successful `Response` into the wrapper's `T`. It is
+     *   handed a `runAfter` thunk so it controls *when* after-interceptors fire
+     *   (e.g. before vs. after a GeoServices error-envelope check) and can parse
+     *   the original body without a defensive clone (see `hasAfterInterceptors`).
+     * - `shortCircuit` (optional) inspects the response before the ok/!ok split,
+     *   e.g. a metadata `304 Not Modified`.
+     * - `okStatuses` (optional) treats specific non-2xx statuses as success.
+     * - `errorBody` (optional) builds the body fed to `toHttpError` on failure.
+     * - `onTerminalError` (optional) yields a fallback value instead of throwing
+     *   on a terminal network/HTTP error, e.g. stale-if-error metadata.
+     */
+    async executeRequest(initialRequest, options) {
+        let request = await this.applyBeforeInterceptors(initialRequest);
+        const retrySignal = options.callerSignal ?? request.init.signal ?? undefined;
+        let refreshedAuth = false;
+        for (let attempt = 0;; attempt += 1) {
+            let response;
+            const timeout = createTimeoutSignal(options.callerSignal ?? request.init.signal, this.timeoutMs);
+            const startTime = performance.now();
+            try {
+                response = await this.fetchWithSafeRedirects(request.url, {
+                    ...request.init,
+                    method: request.method,
+                    signal: timeout.signal,
+                });
+            }
+            catch (error) {
+                const durationMs = performance.now() - startTime;
+                const normalizedError = timeout.didTimeout
+                    ? new HonuaTimeoutError(this.timeoutMs ?? 0)
+                    : normalizeNetworkError(error);
+                if (shouldRetryRequest(this.retryOptions, request.method, attempt, undefined, normalizedError)) {
+                    await this.sleepBeforeRetry(attempt, undefined, retrySignal);
+                    continue;
+                }
+                const fallback = options.onTerminalError?.(normalizedError);
+                if (fallback !== undefined)
+                    return fallback;
+                await this.applyErrorInterceptors({
+                    request: cloneRequestContext(request),
+                    error: normalizedError,
+                    durationMs,
+                });
+                throw normalizedError;
+            }
+            finally {
+                timeout.dispose();
+            }
+            const durationMs = performance.now() - startTime;
+            const currentRequest = request;
+            const runAfter = async () => {
+                try {
+                    await this.applyAfterInterceptors(cloneRequestContext(currentRequest), response, durationMs);
+                }
+                catch (error) {
+                    await this.applyErrorInterceptors({ request: cloneRequestContext(currentRequest), error, durationMs });
+                    throw error;
+                }
+            };
+            if (options.shortCircuit) {
+                const shorted = await options.shortCircuit(response, durationMs, currentRequest, runAfter);
+                if (shorted)
+                    return shorted.value;
+            }
+            if (!response.ok && !options.okStatuses?.includes(response.status)) {
+                const body = options.errorBody ? await options.errorBody(response) : await parseResponseBody(response.clone());
+                const httpError = toHttpError(response.status, body);
+                const authRefreshedRequest = refreshedAuth
+                    ? undefined
+                    : await this.refreshReplaySafeRequestAuth(request, response.status);
+                if (authRefreshedRequest) {
+                    request = authRefreshedRequest;
+                    refreshedAuth = true;
+                    continue;
+                }
+                if (shouldRetryRequest(this.retryOptions, request.method, attempt, response.status, httpError)) {
+                    await this.sleepBeforeRetry(attempt, response, retrySignal);
+                    continue;
+                }
+                const fallback = options.onTerminalError?.(httpError);
+                if (fallback !== undefined)
+                    return fallback;
+                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error: httpError, durationMs });
+                throw httpError;
+            }
+            return options.finalize(response, durationMs, currentRequest, runAfter);
+        }
+    }
+    async applyBeforeInterceptors(request) {
+        let next = cloneRequestContext(request);
+        next = {
+            ...next,
+            url: normalizeInterceptorRequestUrl(this.baseUrl, next.url),
+        };
+        for (const interceptor of this.interceptors) {
+            const mutation = await interceptor.before?.(cloneRequestContext(next));
+            if (!mutation) {
+                continue;
+            }
+            next = applyRequestMutation(next, mutation);
+            next = {
+                ...next,
+                url: normalizeInterceptorRequestUrl(this.baseUrl, next.url),
+            };
+        }
+        return next;
+    }
+    async applyAfterInterceptors(request, response, durationMs) {
+        for (const interceptor of this.interceptors) {
+            // Only clone the response for interceptors that actually inspect it. This
+            // keeps the no-after-interceptor hot path free of `Response.clone()` (so
+            // typed wrappers can parse the original body directly) and avoids cloning
+            // for `before`/`error`-only interceptors.
+            if (!interceptor.after) {
+                continue;
+            }
+            const context = {
+                request: cloneRequestContext(request),
+                response: response.clone(),
+                durationMs,
+            };
+            await interceptor.after(context);
+        }
+    }
+    /** Whether any registered interceptor inspects responses (`after` hook). */
+    hasAfterInterceptors() {
+        return this.interceptors.some((interceptor) => interceptor.after !== undefined);
+    }
+    async applyErrorInterceptors(context) {
+        for (const interceptor of this.interceptors) {
+            try {
+                await interceptor.error?.(context);
+            }
+            catch {
+                // Preserve original request failure; interceptor failures should not mask it.
+            }
+        }
+    }
+    async refreshReplaySafeRequestAuth(request, statusCode) {
+        if ((statusCode !== 401 && statusCode !== 403) ||
+            !this.authProvider ||
+            !DEFAULT_RETRY_METHODS.has(request.method)) {
+            return undefined;
+        }
+        const refreshed = await this.resolveAuthCredentials({ forceRefresh: true, reason: "unauthorized" });
+        if (!refreshed)
+            return undefined;
+        return {
+            ...request,
+            init: {
+                ...request.init,
+                headers: mergeHeaders(request.init.headers, authHeadersFromCredentials(refreshed.credentials)),
+            },
+        };
+    }
+    async sleepBeforeRetry(attempt, response, signal) {
+        await sleep(resolveRetryDelayMs(this.retryOptions, attempt, response), signal);
+    }
+}
+/**
+ * Detect a GeoServices/Esri error envelope returned on an HTTP 2xx response.
+ *
+ * GeoServices services (FeatureServer/MapServer/GeocodeServer/…) report
+ * operation failures as HTTP 200 with a body of the shape
+ * `{ error: { code, message, ... } }`. Without this guard such failures are
+ * cast verbatim to the success response type and surface downstream as empty
+ * results or confusing `undefined` access. Returns a normalized
+ * {@link HonuaHttpError} when the envelope is present, otherwise `undefined`.
+ */
+function geoServicesEnvelopeError(httpStatus, body) {
+    if (!isObject(body) || !isObject(body.error)) {
+        return undefined;
+    }
+    const error = body.error;
+    const hasCode = typeof error.code === "number";
+    const hasMessage = typeof error.message === "string";
+    if (!hasCode && !hasMessage) {
+        return undefined;
+    }
+    const statusCode = hasCode ? error.code : httpStatus;
+    const message = hasMessage ? error.message : "Request failed";
+    return new HonuaHttpError(statusCode, message, body);
+}
+async function parseResponseBody(response) {
+    const text = await response.text();
+    if (!text) {
+        return {};
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function applyRequestMutation(request, mutation) {
+    const nextInit = mutation.init === undefined
+        ? request.init
+        : {
+            ...request.init,
+            ...mutation.init,
+            headers: mergeHeaders(request.init.headers, mutation.init.headers),
+        };
+    return {
+        url: mutation.url ?? request.url,
+        path: request.path,
+        method: mutation.method ?? request.method,
+        init: {
+            ...nextInit,
+            method: mutation.method ?? request.method,
+        },
+    };
+}
+function cloneRequestContext(request) {
+    return {
+        ...request,
+        init: {
+            ...request.init,
+            headers: cloneHeadersInit(request.init.headers),
+        },
+    };
+}
+function cloneHeadersInit(headers) {
+    return mergeHeaders(headers);
+}
+function normalizeAuthProvider(auth) {
+    if (!auth) {
+        return undefined;
+    }
+    if (typeof auth === "function") {
+        return { getCredentials: auth };
+    }
+    return {
+        getCredentials: (context) => auth.getCredentials(context),
+        ...(auth.revokeCredentials ? { revokeCredentials: auth.revokeCredentials.bind(auth) } : {}),
+    };
+}
+function normalizeAuthRefreshSkewMs(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return DEFAULT_AUTH_REFRESH_SKEW_MS;
+    }
+    return Math.max(0, Math.trunc(value));
+}
+function normalizeAuthCredentials(value) {
+    if (typeof value === "string") {
+        return value.length > 0 ? { bearerToken: value } : undefined;
+    }
+    if (!value) {
+        return undefined;
+    }
+    const credentials = {};
+    if (typeof value.apiKey === "string" && value.apiKey.length > 0) {
+        credentials.apiKey = value.apiKey;
+    }
+    if (typeof value.bearerToken === "string" && value.bearerToken.length > 0) {
+        credentials.bearerToken = value.bearerToken;
+    }
+    if (typeof value.authorization === "string" && value.authorization.length > 0) {
+        credentials.authorization = value.authorization;
+    }
+    if (value.expiresAt !== undefined) {
+        credentials.expiresAt = value.expiresAt;
+    }
+    if (!credentials.apiKey && !credentials.bearerToken && !credentials.authorization) {
+        return undefined;
+    }
+    return credentials;
+}
+function normalizeAuthExpiresAtMs(expiresAt) {
+    if (expiresAt === undefined) {
+        return undefined;
+    }
+    if (expiresAt instanceof Date) {
+        return Number.isFinite(expiresAt.getTime()) ? expiresAt.getTime() : undefined;
+    }
+    if (typeof expiresAt === "number") {
+        return Number.isFinite(expiresAt) ? expiresAt : undefined;
+    }
+    const parsed = Date.parse(expiresAt);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function isAuthCredentialsExpiring(cached, skewMs) {
+    if (cached.expiresAtMs === undefined) {
+        return false;
+    }
+    return cached.expiresAtMs - Date.now() <= skewMs;
+}
+function resolveAuthRefreshReason(cached) {
+    return cached ? "expired" : "initial";
+}
+function authHeadersFromCredentials(credentials) {
+    const headers = {};
+    if (credentials.apiKey) {
+        headers["X-API-Key"] = credentials.apiKey;
+    }
+    if (credentials.authorization) {
+        headers.Authorization = credentials.authorization;
+    }
+    else if (credentials.bearerToken) {
+        headers.Authorization = `Bearer ${credentials.bearerToken}`;
+    }
+    return Object.keys(headers).length > 0 ? headers : undefined;
+}
+function createMetadataCacheState(entry, status, options) {
+    return createHonuaCacheState({
+        scope: "metadata",
+        status,
+        keyFingerprint: entry.keyFingerprint,
+        ageMs: Math.max(0, options.now - entry.cachedAtMs),
+        ...(options.ttlMs !== undefined ? { ttlMs: options.ttlMs } : {}),
+        ...(options.staleIfErrorMs !== undefined ? { staleIfErrorMs: options.staleIfErrorMs } : {}),
+        ...(options.revalidatedAt ? { revalidatedAt: options.revalidatedAt } : {}),
+        ...(entry.sourceUpdatedAt ? { sourceUpdatedAt: entry.sourceUpdatedAt } : {}),
+        ...(entry.validator ? { validator: entry.validator } : {}),
+        ...(options.refreshErrorId ? { refreshErrorId: options.refreshErrorId } : {}),
+    });
+}
+function metadataRefreshErrorId(error) {
+    if (error instanceof HonuaHttpError) {
+        return `http-${error.statusCode}`;
+    }
+    if (error instanceof HonuaTimeoutError) {
+        return "timeout";
+    }
+    if (error instanceof HonuaNetworkError) {
+        return "network";
+    }
+    if (error instanceof Error && error.name) {
+        return error.name;
+    }
+    return "unknown";
+}
+function mergePathWithQueryParams(path, additionalParams) {
+    if (additionalParams.size === 0) {
+        return path;
+    }
+    const hashIndex = path.indexOf("#");
+    const hash = hashIndex >= 0 ? path.slice(hashIndex) : "";
+    const withoutHash = hashIndex >= 0 ? path.slice(0, hashIndex) : path;
+    const queryIndex = withoutHash.indexOf("?");
+    const basePath = queryIndex >= 0 ? withoutHash.slice(0, queryIndex) : withoutHash;
+    const existingQuery = queryIndex >= 0 ? withoutHash.slice(queryIndex + 1) : "";
+    const merged = new URLSearchParams(existingQuery);
+    for (const [key, value] of additionalParams.entries()) {
+        merged.set(key, value);
+    }
+    const nextQuery = merged.toString();
+    const withQuery = nextQuery.length > 0 ? `${basePath}?${nextQuery}` : basePath;
+    return `${withQuery}${hash}`;
+}