@honua/sdk-esri-compat 0.0.6-alpha.0

package/core/client.js

@@ -0,0 +1,2625 @@
+import { createHonuaCacheState, honuaCacheValidatorFromHeaders, honuaMetadataRequestHeaders, normalizeHonuaMetadataRequestOptions, withHonuaCacheState, withoutHonuaCacheState, } from "./cache-state.js";
+import { HonuaAbortError, HonuaHttpError, HonuaNetworkError, HonuaTimeoutError } from "./errors.js";
+import { HonuaOgcMaps } from "./ogc-maps.js";
+import { HonuaOgcProcesses } from "./ogc-processes.js";
+import { HonuaOgcTiles } from "./ogc-tiles.js";
+import { decodePbfQueryResponse, isPbfResponse } from "./pbf-decoder.js";
+import { HonuaStacSearch } from "./stac.js";
+import { HonuaFeatureLayer, HonuaMapLayer, HonuaMapService, HonuaOgcFeatures, HonuaService } from "./surfaces.js";
+import { parseWmsCapabilities } from "./wms-capabilities.js";
+import { wmtsExtensionForFormat, } from "./wms-types.js";
+import { HonuaWms } from "./wms.js";
+import { parseWmtsCapabilities } from "./wmts-capabilities.js";
+import { HonuaWmts } from "./wmts.js";
+function normalizeBaseUrl(baseUrl) {
+    return baseUrl.replace(/\/+$/, "");
+}
+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}`;
+}
+function normalizeInterceptorRequestUrl(baseUrl, url) {
+    if (isAbsoluteHttpUrl(url)) {
+        return resolveRequestUrl(baseUrl, url);
+    }
+    if (!isAbsoluteHttpUrl(baseUrl)) {
+        return url;
+    }
+    return resolveRequestUrl(baseUrl, normalizePath(url));
+}
+function normalizeOutFields(outFields) {
+    if (outFields === undefined) {
+        return "*";
+    }
+    if (Array.isArray(outFields)) {
+        return outFields.length > 0 ? outFields.join(",") : "";
+    }
+    return outFields;
+}
+function encodeFormValue(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+    }
+    return JSON.stringify(value);
+}
+function encodeDeletesValue(value) {
+    if (Array.isArray(value)) {
+        return value.join(",");
+    }
+    return String(value);
+}
+function normalizeBBox(bbox) {
+    return Array.isArray(bbox) ? bbox.join(",") : bbox;
+}
+function normalizeSize(size) {
+    return Array.isArray(size) ? size.join(",") : size;
+}
+function normalizeLegendSize(size) {
+    if (typeof size === "number") {
+        return String(size);
+    }
+    if (Array.isArray(size)) {
+        return size.join(",");
+    }
+    return size;
+}
+function normalizeIdentifyGeometry(geometry) {
+    return typeof geometry === "string" ? geometry : JSON.stringify(geometry);
+}
+function normalizeMapExtent(mapExtent) {
+    return Array.isArray(mapExtent) ? mapExtent.join(",") : mapExtent;
+}
+function normalizeImageDisplay(imageDisplay) {
+    return Array.isArray(imageDisplay) ? imageDisplay.join(",") : imageDisplay;
+}
+function normalizeSearchFields(searchFields) {
+    if (!searchFields) {
+        return "";
+    }
+    return Array.isArray(searchFields) ? searchFields.join(",") : searchFields;
+}
+const DEFAULT_RETRY_STATUSES = new Set([429, 502, 503, 504]);
+const DEFAULT_RETRY_METHODS = new Set(["GET", "PUT", "DELETE"]);
+const DEFAULT_AUTH_REFRESH_SKEW_MS = 60_000;
+const SUPPORTED_CONTROL_PLANE_API_MAJOR = 1;
+const SUPPORTED_CONTROL_PLANE_API_BASE_PATH = "/api/v1/admin";
+const MINIMUM_SUPPORTED_SERVER_RELEASE_CHANNEL = "preview";
+export const HONUA_MINIMUM_SUPPORTED_SERVER_VERSION = "1.0.0";
+export class HonuaClient {
+    static minimumSupportedServerVersion = HONUA_MINIMUM_SUPPORTED_SERVER_VERSION;
+    static minimumSupportedServerReleaseChannel = MINIMUM_SUPPORTED_SERVER_RELEASE_CHANNEL;
+    baseUrl;
+    fetchFn;
+    defaultHeaders;
+    authProvider;
+    authRefreshSkewMs;
+    interceptors;
+    timeoutMs;
+    retryOptions;
+    preferBinary;
+    transport;
+    serverCompatibilityCache;
+    authCredentialsCache;
+    authRefreshPromise;
+    connectClient;
+    metadataCache = new Map();
+    constructor(options) {
+        this.baseUrl = normalizeBaseUrl(options.baseUrl);
+        this.fetchFn = options.fetchFn ?? fetch;
+        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";
+        if (this.transport === "grpc-web") {
+            this.initConnectClient();
+        }
+    }
+    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({
+                baseUrl: this.baseUrl,
+                fetch: this.fetchFn,
+            });
+            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({
+            baseUrl: this.baseUrl,
+            fetch: this.fetchFn,
+        });
+        this.connectClient = createClient(FeatureService, transport);
+        return this.connectClient;
+    }
+    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;
+    }
+    /** 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);
+        }
+    }
+    async *queryFeaturesStream(request) {
+        const client = await this.ensureConnectClient();
+        const grpcAdapter = await HonuaClient.loadGrpcAdapter();
+        const protoRequest = grpcAdapter.toProtoQueryRequest(request);
+        yield* grpcAdapter.streamProtoPages(client.queryFeaturesStream(protoRequest));
+    }
+    service(serviceId) {
+        return new HonuaService({
+            client: this,
+            serviceId,
+        });
+    }
+    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,
+        });
+    }
+    ogcFeatures() {
+        return new HonuaOgcFeatures({
+            client: this,
+        });
+    }
+    ogcTiles() {
+        return new HonuaOgcTiles({ client: this });
+    }
+    ogcMaps() {
+        return new HonuaOgcMaps({ 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 });
+    }
+    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;
+        const query = new URLSearchParams({ f: format });
+        const path = `/rest/services?${query.toString()}`;
+        return this.requestCachedMetadataJson(`geoservices:services:${format}`, path, metadataOptions);
+    }
+    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;
+    }
+    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)],
+            };
+        }
+    }
+    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 = {}) {
+        let 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 } : {}),
+            },
+        };
+        request = await this.applyBeforeInterceptors(request);
+        for (let attempt = 0;; attempt += 1) {
+            let response;
+            const timeout = createTimeoutSignal(callerSignal ?? request.init.signal, this.timeoutMs);
+            const startTime = performance.now();
+            try {
+                response = await this.fetchFn(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 (this.shouldRetryRequest(request.method, attempt, undefined, normalizedError)) {
+                    await sleep(this.resolveRetryDelayMs(attempt));
+                    continue;
+                }
+                await this.applyErrorInterceptors({
+                    request: cloneRequestContext(request),
+                    error: normalizedError,
+                    durationMs,
+                });
+                throw normalizedError;
+            }
+            finally {
+                timeout.dispose();
+            }
+            const durationMs = performance.now() - startTime;
+            if (!response.ok && !options.okStatuses?.includes(response.status)) {
+                const body = await parseResponseBody(response.clone());
+                const httpError = this.toHttpError(response.status, body);
+                if (this.shouldRetryRequest(request.method, attempt, response.status, httpError)) {
+                    await sleep(this.resolveRetryDelayMs(attempt, response));
+                    continue;
+                }
+                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error: httpError, durationMs });
+                throw httpError;
+            }
+            try {
+                await this.applyAfterInterceptors(cloneRequestContext(request), response, durationMs);
+            }
+            catch (error) {
+                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error, durationMs });
+                throw error;
+            }
+            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";
+        if (!bypass && !metadataOptions.refresh && cached) {
+            return withHonuaCacheState(cached.body, createMetadataCacheState(cached, "hit", {
+                now: Date.now(),
+                ttlMs: metadataOptions.ttlMs,
+                staleIfErrorMs: metadataOptions.staleIfErrorMs,
+            }));
+        }
+        let request = {
+            url: resolveRequestUrl(this.baseUrl, path),
+            path,
+            method: "GET",
+            init: {
+                method: "GET",
+                headers: await this.composeHeaders(honuaMetadataRequestHeaders({
+                    accept: "application/json",
+                    refresh: metadataOptions.refresh,
+                    bypass,
+                    validator: cached?.validator,
+                })),
+            },
+        };
+        request = await this.applyBeforeInterceptors(request);
+        for (let attempt = 0;; attempt += 1) {
+            let response;
+            const timeout = createTimeoutSignal(metadataOptions.signal ?? request.init.signal, this.timeoutMs);
+            const startTime = performance.now();
+            try {
+                response = await this.fetchFn(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 (this.shouldRetryRequest(request.method, attempt, undefined, normalizedError)) {
+                    await sleep(this.resolveRetryDelayMs(attempt));
+                    continue;
+                }
+                const stale = this.staleMetadataFallback(cached, metadataOptions, normalizedError);
+                if (stale)
+                    return stale;
+                await this.applyErrorInterceptors({
+                    request: cloneRequestContext(request),
+                    error: normalizedError,
+                    durationMs,
+                });
+                throw normalizedError;
+            }
+            finally {
+                timeout.dispose();
+            }
+            const durationMs = performance.now() - startTime;
+            if (response.status === 304 && cached && !bypass) {
+                try {
+                    await this.applyAfterInterceptors(cloneRequestContext(request), response, durationMs);
+                }
+                catch (error) {
+                    await this.applyErrorInterceptors({ request: cloneRequestContext(request), error, durationMs });
+                    throw error;
+                }
+                const updatedEntry = {
+                    ...cached,
+                    cachedAtMs: Date.now(),
+                    ...((honuaCacheValidatorFromHeaders(response.headers) ?? cached.validator)
+                        ? { validator: honuaCacheValidatorFromHeaders(response.headers) ?? cached.validator }
+                        : {}),
+                };
+                this.metadataCache.set(keyFingerprint, updatedEntry);
+                return withHonuaCacheState(updatedEntry.body, createMetadataCacheState(updatedEntry, "refreshed", {
+                    now: Date.now(),
+                    ttlMs: metadataOptions.ttlMs,
+                    staleIfErrorMs: metadataOptions.staleIfErrorMs,
+                    revalidatedAt: new Date().toISOString(),
+                }));
+            }
+            const body = await parseResponseBody(response.clone());
+            if (!response.ok) {
+                const httpError = this.toHttpError(response.status, body);
+                if (this.shouldRetryRequest(request.method, attempt, response.status, httpError)) {
+                    await sleep(this.resolveRetryDelayMs(attempt, response));
+                    continue;
+                }
+                const stale = this.staleMetadataFallback(cached, metadataOptions, httpError);
+                if (stale)
+                    return stale;
+                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error: httpError, durationMs });
+                throw httpError;
+            }
+            try {
+                await this.applyAfterInterceptors(cloneRequestContext(request), response, durationMs);
+            }
+            catch (error) {
+                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error, durationMs });
+                throw error;
+            }
+            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.metadataCache.set(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;
+        }
+        return withHonuaCacheState(cached.body, createMetadataCacheState(cached, "stale", {
+            now: Date.now(),
+            ttlMs: options.ttlMs,
+            staleIfErrorMs: options.staleIfErrorMs,
+            refreshErrorId: metadataRefreshErrorId(error),
+        }));
+    }
+    async getLayerMetadata(serviceId, layerId, options = {}) {
+        const query = new URLSearchParams({ f: "json" });
+        const path = `/rest/services/${encodeURIComponent(serviceId)}/FeatureServer/${layerId}?${query.toString()}`;
+        return this.requestCachedMetadataJson(`geoservices-feature:${serviceId}:${layerId}`, path, options);
+    }
+    async getFeatureServiceMetadata(serviceId, options = {}) {
+        const query = new URLSearchParams({ f: "json" });
+        const path = `/rest/services/${encodeURIComponent(serviceId)}/FeatureServer?${query.toString()}`;
+        return this.requestCachedMetadataJson(`geoservices-feature:${serviceId}:service`, path, options);
+    }
+    async getOgcFeaturesLanding(request = {}) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`ogc-features:landing:${params.toString()}`, `/ogc/features?${params.toString()}`, request);
+    }
+    async getOgcFeaturesConformance(request = {}) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`ogc-features:conformance:${params.toString()}`, `/ogc/features/conformance?${params.toString()}`, request);
+    }
+    async listOgcCollections(request = {}) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`ogc-features:collections:${params.toString()}`, `/ogc/features/collections?${params.toString()}`, request);
+    }
+    async getOgcCollection(request) {
+        const params = createOgcMetadataParams(request);
+        const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}`;
+        return this.requestCachedMetadataJson(`ogc-features:collection:${request.collectionId}:${params.toString()}`, `${path}?${params.toString()}`, request);
+    }
+    async getOgcQueryables(request) {
+        const params = createOgcMetadataParams(request);
+        const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}/queryables`;
+        return this.requestCachedMetadataJson(`ogc-features:queryables:${request.collectionId}:${params.toString()}`, `${path}?${params.toString()}`, request);
+    }
+    async listOgcItems(request) {
+        const params = createOgcMetadataParams(request);
+        if (request.limit !== undefined) {
+            params.set("limit", String(request.limit));
+        }
+        if (request.offset !== undefined) {
+            params.set("offset", String(request.offset));
+        }
+        if (request.bbox !== undefined) {
+            params.set("bbox", request.bbox);
+        }
+        if (request.datetime !== undefined) {
+            params.set("datetime", request.datetime);
+        }
+        if (request.filter !== undefined) {
+            params.set("filter", request.filter);
+        }
+        if (request.ids !== undefined) {
+            params.set("ids", normalizeCsv(request.ids));
+        }
+        if (request.properties !== undefined) {
+            params.set("properties", normalizeCsv(request.properties));
+        }
+        if (request.sortby !== undefined) {
+            params.set("sortby", request.sortby);
+        }
+        if (request.crs !== undefined) {
+            params.set("crs", request.crs);
+        }
+        const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}/items`;
+        return this.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
+    }
+    async getOgcItem(request) {
+        const params = createOgcMetadataParams(request);
+        if (request.crs !== undefined) {
+            params.set("crs", request.crs);
+        }
+        const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}` +
+            `/items/${encodeURIComponent(String(request.featureId))}`;
+        return this.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
+    }
+    async createOgcItem(request) {
+        const params = createOgcMetadataParams(request);
+        const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}/items`;
+        return this.requestJson("POST", `${path}?${params.toString()}`, {
+            headers: mergeHeaders({ "Content-Type": "application/geo+json" }, request.headers),
+            body: JSON.stringify(request.feature),
+        }, request.signal);
+    }
+    async replaceOgcItem(request) {
+        const params = createOgcMetadataParams(request);
+        if (request.crs !== undefined) {
+            params.set("crs", request.crs);
+        }
+        const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}` +
+            `/items/${encodeURIComponent(String(request.featureId))}`;
+        return this.requestJson("PUT", `${path}?${params.toString()}`, {
+            headers: mergeHeaders({ "Content-Type": "application/geo+json" }, request.headers),
+            body: JSON.stringify(request.feature),
+        }, request.signal);
+    }
+    async patchOgcItem(request) {
+        const params = createOgcMetadataParams(request);
+        if (request.crs !== undefined) {
+            params.set("crs", request.crs);
+        }
+        const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}` +
+            `/items/${encodeURIComponent(String(request.featureId))}`;
+        return this.requestJson("PATCH", `${path}?${params.toString()}`, {
+            headers: mergeHeaders({ "Content-Type": "application/merge-patch+json" }, request.headers),
+            body: JSON.stringify(request.patch),
+        }, request.signal);
+    }
+    async deleteOgcItem(request) {
+        const params = createOgcMetadataParams(request);
+        if (request.crs !== undefined) {
+            params.set("crs", request.crs);
+        }
+        const path = `/ogc/features/collections/${encodeURIComponent(String(request.collectionId))}` +
+            `/items/${encodeURIComponent(String(request.featureId))}`;
+        await this.requestJson("DELETE", `${path}?${params.toString()}`, undefined, request.signal);
+    }
+    // ── OGC API Tiles ───────────────────────────────────────────
+    async getOgcTilesLanding(request = {}) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`ogc-tiles:landing:${params.toString()}`, `/ogc/tiles?${params.toString()}`, request);
+    }
+    async getOgcTilesConformance(request = {}) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`ogc-tiles:conformance:${params.toString()}`, `/ogc/tiles/conformance?${params.toString()}`, request);
+    }
+    async listOgcTileMatrixSets(request = {}) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`ogc-tiles:tile-matrix-sets:${params.toString()}`, `/ogc/tiles/tileMatrixSets?${params.toString()}`, request);
+    }
+    async getOgcTileMatrixSet(request) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`ogc-tiles:tile-matrix-set:${request.tileMatrixSetId}:${params.toString()}`, `/ogc/tiles/tileMatrixSets/${encodeURIComponent(request.tileMatrixSetId)}?${params.toString()}`, request);
+    }
+    async listOgcCollectionTilesets(request) {
+        const params = createOgcMetadataParams(request);
+        const path = `/ogc/tiles/collections/${encodeURIComponent(String(request.collectionId))}/tiles`;
+        return this.requestCachedMetadataJson(`ogc-tiles:tilesets:${request.collectionId}:${params.toString()}`, `${path}?${params.toString()}`, request);
+    }
+    async getOgcCollectionTileset(request) {
+        const params = createOgcMetadataParams(request);
+        const path = `/ogc/tiles/collections/${encodeURIComponent(String(request.collectionId))}` +
+            `/tiles/${encodeURIComponent(request.tileMatrixSetId)}`;
+        return this.requestCachedMetadataJson(`ogc-tiles:tileset:${request.collectionId}:${request.tileMatrixSetId}:${params.toString()}`, `${path}?${params.toString()}`, request);
+    }
+    async fetchOgcTile(request) {
+        const params = new URLSearchParams();
+        if (request.extraParams) {
+            for (const [key, value] of Object.entries(request.extraParams)) {
+                params.set(key, String(value));
+            }
+        }
+        const collection = encodeURIComponent(String(request.collectionId));
+        const matrixSet = encodeURIComponent(request.tileMatrixSetId);
+        const matrix = encodeURIComponent(String(request.tileMatrix));
+        const query = params.size > 0 ? `?${params.toString()}` : "";
+        const path = `/ogc/tiles/collections/${collection}/tiles/${matrixSet}/${matrix}/${request.tileRow}/${request.tileCol}${query}`;
+        return this.requestBytes("GET", path, request.accept, undefined, request.signal);
+    }
+    // ── OGC API Maps ────────────────────────────────────────────
+    async getOgcMapsLanding(request = {}) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`ogc-maps:landing:${params.toString()}`, `/ogc/maps?${params.toString()}`, request);
+    }
+    async getOgcMapsConformance(request = {}) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`ogc-maps:conformance:${params.toString()}`, `/ogc/maps/conformance?${params.toString()}`, request);
+    }
+    async getOgcMapImage(request) {
+        const params = serializeOgcMapImageParams(request);
+        const collectionPart = request.collectionId !== undefined ? `/collections/${encodeURIComponent(String(request.collectionId))}` : "";
+        const stylePart = request.styleId ? `/styles/${encodeURIComponent(request.styleId)}` : "";
+        const path = `/ogc/maps${collectionPart}${stylePart}/map${params.size > 0 ? `?${params.toString()}` : ""}`;
+        const accept = ogcMapAcceptHeader(request.format) ?? "image/png";
+        const response = await this.requestBytes("GET", path, accept, undefined, request.signal);
+        return { bytes: response.bytes, contentType: response.contentType };
+    }
+    // ── 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) {
+        const params = new URLSearchParams();
+        params.set("SERVICE", "WMS");
+        params.set("REQUEST", "GetCapabilities");
+        params.set("VERSION", request.version ?? "1.3.0");
+        if (request.extraParams) {
+            for (const [key, value] of Object.entries(request.extraParams)) {
+                params.set(key, String(value));
+            }
+        }
+        const path = `${wmsBasePath(request.serviceId)}?${params.toString()}`;
+        const { text: xml } = await this.requestText("GET", path, {
+            accept: "text/xml,application/xml",
+            signal: request.signal,
+        });
+        return parseWmsCapabilities(xml);
+    }
+    /** Render a WMS `GetMap`. Returns the raw image bytes. */
+    async getWmsMap(request) {
+        const params = serializeWmsMapParams(request);
+        params.set("REQUEST", "GetMap");
+        const path = `${wmsBasePath(request.serviceId)}?${params.toString()}`;
+        const accept = request.format ?? "image/png";
+        const response = await this.requestBytes("GET", path, accept, undefined, request.signal);
+        return { bytes: response.bytes, contentType: response.contentType };
+    }
+    /**
+     * 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) {
+        const params = serializeWmsMapParams(request);
+        params.set("REQUEST", "GetFeatureInfo");
+        params.set("QUERY_LAYERS", request.queryLayers.join(","));
+        params.set("I", String(Math.trunc(request.i)));
+        params.set("J", String(Math.trunc(request.j)));
+        const infoFormat = request.infoFormat ?? "application/json";
+        params.set("INFO_FORMAT", infoFormat);
+        if (request.featureCount !== undefined) {
+            params.set("FEATURE_COUNT", String(Math.trunc(request.featureCount)));
+        }
+        const path = `${wmsBasePath(request.serviceId)}?${params.toString()}`;
+        const response = await this.requestBytes("GET", path, infoFormat, undefined, request.signal);
+        return decodeWmsFeatureInfoResponse(response.bytes, response.contentType, infoFormat);
+    }
+    /**
+     * 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) {
+        const params = new URLSearchParams();
+        params.set("SERVICE", "WMS");
+        params.set("VERSION", "1.3.0");
+        params.set("REQUEST", "GetLegendGraphic");
+        params.set("LAYER", request.layer);
+        if (request.style)
+            params.set("STYLE", request.style);
+        const format = request.format ?? "image/png";
+        params.set("FORMAT", format);
+        if (request.width !== undefined)
+            params.set("WIDTH", String(Math.trunc(request.width)));
+        if (request.height !== undefined)
+            params.set("HEIGHT", String(Math.trunc(request.height)));
+        if (request.extraParams) {
+            for (const [key, value] of Object.entries(request.extraParams)) {
+                params.set(key, String(value));
+            }
+        }
+        const path = `${wmsBasePath(request.serviceId)}?${params.toString()}`;
+        const response = await this.requestBytes("GET", path, format, undefined, request.signal);
+        return { bytes: response.bytes, contentType: response.contentType };
+    }
+    // ── WMTS 1.0 ────────────────────────────────────────────────
+    async getWmtsCapabilities(request) {
+        const params = new URLSearchParams();
+        params.set("SERVICE", "WMTS");
+        params.set("REQUEST", "GetCapabilities");
+        params.set("VERSION", "1.0.0");
+        const path = `${wmtsBasePath(request.serviceId)}?${params.toString()}`;
+        const { text: xml } = await this.requestText("GET", path, {
+            accept: "text/xml,application/xml",
+            signal: request.signal,
+        });
+        return parseWmtsCapabilities(xml);
+    }
+    /**
+     * 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) {
+        const mode = request.mode ?? "rest";
+        const format = request.format ?? "image/png";
+        const style = request.style ?? "default";
+        const tileMatrixSet = request.tileMatrixSet ?? "WebMercatorQuad";
+        if (mode === "kvp") {
+            const params = new URLSearchParams();
+            params.set("SERVICE", "WMTS");
+            params.set("VERSION", "1.0.0");
+            params.set("REQUEST", "GetTile");
+            params.set("LAYER", request.layer);
+            params.set("STYLE", style);
+            params.set("FORMAT", format);
+            params.set("TILEMATRIXSET", tileMatrixSet);
+            params.set("TILEMATRIX", String(request.tileMatrix));
+            params.set("TILEROW", String(request.tileRow));
+            params.set("TILECOL", String(request.tileCol));
+            if (request.extraParams) {
+                for (const [key, value] of Object.entries(request.extraParams)) {
+                    params.set(key, String(value));
+                }
+            }
+            const path = `${wmtsBasePath(request.serviceId)}?${params.toString()}`;
+            return this.requestBytes("GET", path, format, undefined, request.signal);
+        }
+        const ext = wmtsExtensionForFormat(format);
+        const base = wmtsBasePath(request.serviceId);
+        const layer = encodeURIComponent(request.layer);
+        const styleSeg = encodeURIComponent(style);
+        const tmsSeg = encodeURIComponent(tileMatrixSet);
+        const tm = encodeURIComponent(String(request.tileMatrix));
+        const tr = encodeURIComponent(String(request.tileRow));
+        const tc = encodeURIComponent(String(request.tileCol));
+        const extra = wmtsRestExtraParamsSuffix(request.extraParams);
+        const path = `${base}/${layer}/${styleSeg}/${tmsSeg}/${tm}/${tr}/${tc}.${ext}${extra}`;
+        return this.requestBytes("GET", path, format, undefined, request.signal);
+    }
+    /**
+     * WMTS GetFeatureInfo. honua-server accepts both KVP and RESTful
+     * routing; mode default mirrors `fetchWmtsTile`.
+     */
+    async getWmtsFeatureInfo(request) {
+        const mode = request.mode ?? "rest";
+        const infoFormat = request.infoFormat ?? "application/json";
+        const format = request.format ?? "image/png";
+        const style = request.style ?? "default";
+        const tileMatrixSet = request.tileMatrixSet ?? "WebMercatorQuad";
+        if (mode === "kvp") {
+            const params = new URLSearchParams();
+            params.set("SERVICE", "WMTS");
+            params.set("VERSION", "1.0.0");
+            params.set("REQUEST", "GetFeatureInfo");
+            params.set("LAYER", request.layer);
+            params.set("STYLE", style);
+            params.set("FORMAT", format);
+            params.set("TILEMATRIXSET", tileMatrixSet);
+            params.set("TILEMATRIX", String(request.tileMatrix));
+            params.set("TILEROW", String(request.tileRow));
+            params.set("TILECOL", String(request.tileCol));
+            params.set("I", String(Math.trunc(request.i)));
+            params.set("J", String(Math.trunc(request.j)));
+            params.set("INFOFORMAT", infoFormat);
+            if (request.extraParams) {
+                for (const [key, value] of Object.entries(request.extraParams)) {
+                    params.set(key, String(value));
+                }
+            }
+            const path = `${wmtsBasePath(request.serviceId)}?${params.toString()}`;
+            const response = await this.requestBytes("GET", path, infoFormat, undefined, request.signal);
+            return decodeWmsFeatureInfoResponse(response.bytes, response.contentType, infoFormat);
+        }
+        const ext = wmtsFeatureInfoExtensionForFormat(infoFormat);
+        const base = wmtsBasePath(request.serviceId);
+        const layer = encodeURIComponent(request.layer);
+        const styleSeg = encodeURIComponent(style);
+        const tmsSeg = encodeURIComponent(tileMatrixSet);
+        const tm = encodeURIComponent(String(request.tileMatrix));
+        const tr = encodeURIComponent(String(request.tileRow));
+        const tc = encodeURIComponent(String(request.tileCol));
+        const jSeg = encodeURIComponent(String(Math.trunc(request.j)));
+        const iSeg = encodeURIComponent(String(Math.trunc(request.i)));
+        const extra = wmtsRestExtraParamsSuffix(request.extraParams);
+        const path = `${base}/${layer}/${styleSeg}/${tmsSeg}/${tm}/${tr}/${tc}/${jSeg}/${iSeg}.${ext}${extra}`;
+        const response = await this.requestBytes("GET", path, infoFormat, undefined, request.signal);
+        return decodeWmsFeatureInfoResponse(response.bytes, response.contentType, infoFormat);
+    }
+    // ── OGC API Processes ───────────────────────────────────────
+    async getOgcProcessesLanding(request = {}) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`ogc-processes:landing:${params.toString()}`, `/ogc/processes?${params.toString()}`, request);
+    }
+    async getOgcProcessesConformance(request = {}) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`ogc-processes:conformance:${params.toString()}`, `/ogc/processes/conformance?${params.toString()}`, request);
+    }
+    async listOgcProcesses(request = {}) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`ogc-processes:processes:${params.toString()}`, `/ogc/processes/processes?${params.toString()}`, request);
+    }
+    async getOgcProcess(request) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`ogc-processes:process:${request.processId}:${params.toString()}`, `/ogc/processes/processes/${encodeURIComponent(request.processId)}?${params.toString()}`, request);
+    }
+    async executeOgcProcess(request) {
+        const headers = mergeHeaders({ "Content-Type": "application/json", Accept: "application/json" }, request.headers, preferHeaderForExecute(request));
+        const path = `/ogc/processes/processes/${encodeURIComponent(request.processId)}/execution`;
+        // honua-server only supports `response: "document"` and rejects "raw"
+        // with HTTP 501; the SDK pins the supported value here.
+        const body = JSON.stringify({
+            inputs: request.inputs ?? {},
+            outputs: request.outputs,
+            response: "document",
+        });
+        return this.requestJson("POST", path, { headers, body }, request.signal);
+    }
+    async getOgcProcessJob(request) {
+        const params = createOgcMetadataParams(request);
+        return this.requestJson("GET", `/ogc/processes/jobs/${encodeURIComponent(request.jobId)}?${params.toString()}`, undefined, request.signal);
+    }
+    async getOgcProcessJobResults(request) {
+        const params = createOgcMetadataParams(request);
+        return this.requestJson("GET", `/ogc/processes/jobs/${encodeURIComponent(request.jobId)}/results?${params.toString()}`, undefined, request.signal);
+    }
+    async cancelOgcProcessJob(request) {
+        const params = createOgcMetadataParams(request);
+        return this.requestJson("DELETE", `/ogc/processes/jobs/${encodeURIComponent(request.jobId)}?${params.toString()}`, undefined, request.signal);
+    }
+    // ── STAC API ────────────────────────────────────────────────
+    async getStacLanding(request = {}) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`stac:landing:${params.toString()}`, `/stac?${params.toString()}`, request);
+    }
+    async listStacCollections(request = {}) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`stac:collections:${params.toString()}`, `/stac/collections?${params.toString()}`, request);
+    }
+    async getStacCollection(request) {
+        const params = createOgcMetadataParams(request);
+        return this.requestCachedMetadataJson(`stac:collection:${request.collectionId}:${params.toString()}`, `/stac/collections/${encodeURIComponent(String(request.collectionId))}?${params.toString()}`, request);
+    }
+    async getStacItem(request) {
+        const params = createOgcMetadataParams(request);
+        const path = `/stac/collections/${encodeURIComponent(String(request.collectionId))}` +
+            `/items/${encodeURIComponent(String(request.itemId))}`;
+        return this.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
+    }
+    async searchStac(request = {}) {
+        if (request.usePost) {
+            return this.requestJson("POST", "/stac/search", {
+                headers: mergeHeaders({ "Content-Type": "application/json", Accept: "application/json" }),
+                body: JSON.stringify(stacSearchBody(request)),
+            }, request.signal);
+        }
+        const params = serializeStacSearchParams(request);
+        return this.requestJson("GET", `/stac/search?${params.toString()}`, undefined, request.signal);
+    }
+    async getMapServiceMetadata(serviceId, options = {}) {
+        const query = new URLSearchParams({ f: "json" });
+        const path = `/rest/services/${encodeURIComponent(serviceId)}/MapServer?${query.toString()}`;
+        return this.requestCachedMetadataJson(`geoservices-map:${serviceId}:service`, path, options);
+    }
+    async getMapLayerMetadata(serviceId, layerId, options = {}) {
+        const query = new URLSearchParams({ f: "json" });
+        const path = `/rest/services/${encodeURIComponent(serviceId)}/MapServer/${layerId}?${query.toString()}`;
+        return this.requestCachedMetadataJson(`geoservices-map:${serviceId}:${layerId}`, path, options);
+    }
+    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);
+                return grpcAdapter.fromProtoQueryResponse(response);
+            }
+            catch (error) {
+                throw grpcAdapter.wrapConnectError(error);
+            }
+        }
+        const method = request.method ?? "GET";
+        const usePbf = this.preferBinary && method === "GET";
+        const params = new URLSearchParams();
+        params.set("f", usePbf ? "pbf" : "json");
+        params.set("where", request.where ?? "1=1");
+        params.set("outFields", normalizeOutFields(request.outFields));
+        params.set("returnGeometry", String(request.returnGeometry ?? true));
+        serializeQueryParams(params, request);
+        appendQueryExtraParams(params, request);
+        const path = `/rest/services/${encodeURIComponent(request.serviceId)}/FeatureServer/${request.layerId}/query`;
+        if (usePbf) {
+            return this.requestBinaryWithJsonFallback("GET", `${path}?${params.toString()}`, params, request.signal);
+        }
+        if (method === "GET") {
+            return this.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
+        }
+        return this.requestJson("POST", path, {
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: params.toString(),
+        }, request.signal);
+    }
+    async queryMapLayer(request) {
+        const method = request.method ?? "GET";
+        const params = new URLSearchParams();
+        params.set("f", "json");
+        params.set("where", request.where ?? "1=1");
+        params.set("outFields", normalizeOutFields(request.outFields));
+        params.set("returnGeometry", String(request.returnGeometry ?? true));
+        serializeQueryParams(params, request);
+        appendQueryExtraParams(params, request);
+        const path = `/rest/services/${encodeURIComponent(request.serviceId)}/MapServer/${request.layerId}/query`;
+        if (method === "GET") {
+            return this.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
+        }
+        return this.requestJson("POST", path, {
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: params.toString(),
+        }, request.signal);
+    }
+    async applyEdits(request) {
+        const path = `/rest/services/${encodeURIComponent(request.serviceId)}/FeatureServer/${request.layerId}/applyEdits`;
+        const params = new URLSearchParams();
+        params.set("f", "json");
+        params.set("rollbackOnFailure", String(request.rollbackOnFailure ?? true));
+        if (request.adds !== undefined) {
+            params.set("adds", encodeFormValue(request.adds));
+        }
+        if (request.updates !== undefined) {
+            params.set("updates", encodeFormValue(request.updates));
+        }
+        if (request.deletes !== undefined) {
+            params.set("deletes", encodeDeletesValue(request.deletes));
+        }
+        return this.requestJson("POST", path, {
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: params.toString(),
+        }, request.signal);
+    }
+    async queryRelatedRecords(request) {
+        const method = request.method ?? "GET";
+        const params = new URLSearchParams();
+        params.set("f", "json");
+        params.set("relationshipId", String(request.relationshipId));
+        if (request.objectIds !== undefined) {
+            params.set("objectIds", Array.isArray(request.objectIds) ? request.objectIds.join(",") : String(request.objectIds));
+        }
+        params.set("where", request.where ?? "1=1");
+        params.set("outFields", normalizeOutFields(request.outFields));
+        params.set("returnGeometry", String(request.returnGeometry ?? true));
+        if (request.extraParams) {
+            for (const [key, value] of Object.entries(request.extraParams)) {
+                params.set(key, String(value));
+            }
+        }
+        const path = `/rest/services/${encodeURIComponent(request.serviceId)}` +
+            `/FeatureServer/${request.layerId}/queryRelatedRecords`;
+        if (method === "GET") {
+            return this.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
+        }
+        return this.requestJson("POST", path, {
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: params.toString(),
+        }, request.signal);
+    }
+    async queryMapRelatedRecords(request) {
+        const method = request.method ?? "GET";
+        const params = new URLSearchParams();
+        params.set("f", "json");
+        params.set("relationshipId", String(request.relationshipId));
+        if (request.objectIds !== undefined) {
+            params.set("objectIds", Array.isArray(request.objectIds) ? request.objectIds.join(",") : String(request.objectIds));
+        }
+        params.set("where", request.where ?? "1=1");
+        params.set("outFields", normalizeOutFields(request.outFields));
+        params.set("returnGeometry", String(request.returnGeometry ?? true));
+        if (request.extraParams) {
+            for (const [key, value] of Object.entries(request.extraParams)) {
+                params.set(key, String(value));
+            }
+        }
+        const path = `/rest/services/${encodeURIComponent(request.serviceId)}` + `/MapServer/${request.layerId}/queryRelatedRecords`;
+        if (method === "GET") {
+            return this.requestJson("GET", `${path}?${params.toString()}`, undefined, request.signal);
+        }
+        return this.requestJson("POST", path, {
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: params.toString(),
+        }, request.signal);
+    }
+    async exportMap(request) {
+        const method = request.method ?? "GET";
+        const params = new URLSearchParams();
+        params.set("f", request.responseFormat ?? "json");
+        params.set("bbox", normalizeBBox(request.bbox));
+        params.set("size", normalizeSize(request.size));
+        if (request.format !== undefined) {
+            params.set("format", request.format);
+        }
+        if (request.dpi !== undefined) {
+            params.set("dpi", String(request.dpi));
+        }
+        if (request.transparent !== undefined) {
+            params.set("transparent", String(request.transparent));
+        }
+        if (request.layers !== undefined) {
+            params.set("layers", request.layers);
+        }
+        if (request.bboxSr !== undefined) {
+            params.set("bboxSR", String(request.bboxSr));
+        }
+        if (request.imageSr !== undefined) {
+            params.set("imageSR", String(request.imageSr));
+        }
+        if (request.backgroundColor !== undefined) {
+            params.set("backgroundColor", request.backgroundColor);
+        }
+        if (request.extraParams) {
+            for (const [key, value] of Object.entries(request.extraParams)) {
+                params.set(key, String(value));
+            }
+        }
+        const path = `/rest/services/${encodeURIComponent(request.serviceId)}/MapServer/export`;
+        if (method === "GET") {
+            return this.requestJson("GET", `${path}?${params.toString()}`);
+        }
+        return this.requestJson("POST", path, {
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: params.toString(),
+        });
+    }
+    async getMapLegend(request) {
+        const params = new URLSearchParams();
+        params.set("f", request.responseFormat ?? "json");
+        if (request.size !== undefined) {
+            params.set("size", normalizeLegendSize(request.size));
+        }
+        if (request.dynamicLayers !== undefined) {
+            params.set("dynamicLayers", request.dynamicLayers);
+        }
+        if (request.extraParams) {
+            for (const [key, value] of Object.entries(request.extraParams)) {
+                params.set(key, String(value));
+            }
+        }
+        const path = `/rest/services/${encodeURIComponent(request.serviceId)}/MapServer/legend`;
+        return this.requestJson("GET", `${path}?${params.toString()}`);
+    }
+    async identifyMap(request) {
+        const method = request.method ?? "GET";
+        const params = new URLSearchParams();
+        params.set("f", request.responseFormat ?? "json");
+        params.set("geometry", normalizeIdentifyGeometry(request.geometry));
+        params.set("geometryType", request.geometryType ?? "esriGeometryPoint");
+        params.set("mapExtent", normalizeMapExtent(request.mapExtent));
+        params.set("imageDisplay", normalizeImageDisplay(request.imageDisplay));
+        params.set("returnGeometry", String(request.returnGeometry ?? true));
+        params.set("tolerance", String(request.tolerance ?? 3));
+        if (request.sr !== undefined) {
+            params.set("sr", String(request.sr));
+        }
+        if (request.layers !== undefined) {
+            params.set("layers", request.layers);
+        }
+        if (request.maxAllowableOffset !== undefined) {
+            params.set("maxAllowableOffset", String(request.maxAllowableOffset));
+        }
+        if (request.layerDefs !== undefined) {
+            params.set("layerDefs", request.layerDefs);
+        }
+        if (request.dynamicLayers !== undefined) {
+            params.set("dynamicLayers", request.dynamicLayers);
+        }
+        if (request.time !== undefined) {
+            params.set("time", request.time);
+        }
+        if (request.extraParams) {
+            for (const [key, value] of Object.entries(request.extraParams)) {
+                params.set(key, String(value));
+            }
+        }
+        const path = `/rest/services/${encodeURIComponent(request.serviceId)}/MapServer/identify`;
+        if (method === "GET") {
+            return this.requestJson("GET", `${path}?${params.toString()}`);
+        }
+        return this.requestJson("POST", path, {
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: params.toString(),
+        });
+    }
+    async findMap(request) {
+        const method = request.method ?? "GET";
+        const params = new URLSearchParams();
+        params.set("f", request.responseFormat ?? "json");
+        params.set("searchText", request.searchText);
+        params.set("contains", String(request.contains ?? true));
+        if (request.searchFields !== undefined) {
+            params.set("searchFields", normalizeSearchFields(request.searchFields));
+        }
+        if (request.layers !== undefined) {
+            params.set("layers", request.layers);
+        }
+        if (request.sr !== undefined) {
+            params.set("sr", String(request.sr));
+        }
+        if (request.layerDefs !== undefined) {
+            params.set("layerDefs", request.layerDefs);
+        }
+        if (request.returnGeometry !== undefined) {
+            params.set("returnGeometry", String(request.returnGeometry));
+        }
+        if (request.maxAllowableOffset !== undefined) {
+            params.set("maxAllowableOffset", String(request.maxAllowableOffset));
+        }
+        if (request.dynamicLayers !== undefined) {
+            params.set("dynamicLayers", request.dynamicLayers);
+        }
+        if (request.returnZ !== undefined) {
+            params.set("returnZ", String(request.returnZ));
+        }
+        if (request.returnM !== undefined) {
+            params.set("returnM", String(request.returnM));
+        }
+        if (request.gdbVersion !== undefined) {
+            params.set("gdbVersion", request.gdbVersion);
+        }
+        if (request.time !== undefined) {
+            params.set("time", request.time);
+        }
+        if (request.relationParam !== undefined) {
+            params.set("relationParam", request.relationParam);
+        }
+        if (request.extraParams) {
+            for (const [key, value] of Object.entries(request.extraParams)) {
+                params.set(key, String(value));
+            }
+        }
+        const path = `/rest/services/${encodeURIComponent(request.serviceId)}/MapServer/find`;
+        if (method === "GET") {
+            return this.requestJson("GET", `${path}?${params.toString()}`);
+        }
+        return this.requestJson("POST", path, {
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: params.toString(),
+        });
+    }
+    async requestJson(method, path, init, callerSignal) {
+        let request = {
+            url: resolveRequestUrl(this.baseUrl, path),
+            path,
+            method,
+            init: {
+                method,
+                headers: await this.composeHeaders({ Accept: "application/json" }, init?.headers),
+                body: init?.body,
+            },
+        };
+        request = await this.applyBeforeInterceptors(request);
+        for (let attempt = 0;; attempt += 1) {
+            let response;
+            const timeout = createTimeoutSignal(callerSignal ?? request.init.signal, this.timeoutMs);
+            const startTime = performance.now();
+            try {
+                response = await this.fetchFn(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 (this.shouldRetryRequest(request.method, attempt, undefined, normalizedError)) {
+                    await sleep(this.resolveRetryDelayMs(attempt));
+                    continue;
+                }
+                await this.applyErrorInterceptors({
+                    request: cloneRequestContext(request),
+                    error: normalizedError,
+                    durationMs,
+                });
+                throw normalizedError;
+            }
+            finally {
+                timeout.dispose();
+            }
+            const durationMs = performance.now() - startTime;
+            const body = await parseResponseBody(response.clone());
+            if (!response.ok) {
+                const httpError = this.toHttpError(response.status, body);
+                if (this.shouldRetryRequest(request.method, attempt, response.status, httpError)) {
+                    await sleep(this.resolveRetryDelayMs(attempt, response));
+                    continue;
+                }
+                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error: httpError, durationMs });
+                throw httpError;
+            }
+            try {
+                await this.applyAfterInterceptors(cloneRequestContext(request), response, durationMs);
+            }
+            catch (error) {
+                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error, durationMs });
+                throw error;
+            }
+            return body;
+        }
+    }
+    /**
+     * Request a PBF binary response and decode it. Falls back to JSON on failure.
+     */
+    async requestBinaryWithJsonFallback(method, path, params, callerSignal) {
+        let request = {
+            url: resolveRequestUrl(this.baseUrl, path),
+            path,
+            method,
+            init: {
+                method,
+                headers: await this.composeHeaders({ Accept: "application/x-protobuf, application/json;q=0.9" }),
+            },
+        };
+        request = await this.applyBeforeInterceptors(request);
+        for (let attempt = 0;; attempt += 1) {
+            let response;
+            const timeout = createTimeoutSignal(callerSignal ?? request.init.signal, this.timeoutMs);
+            const startTime = performance.now();
+            try {
+                response = await this.fetchFn(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 (this.shouldRetryRequest(request.method, attempt, undefined, normalizedError)) {
+                    await sleep(this.resolveRetryDelayMs(attempt));
+                    continue;
+                }
+                await this.applyErrorInterceptors({
+                    request: cloneRequestContext(request),
+                    error: normalizedError,
+                    durationMs,
+                });
+                throw normalizedError;
+            }
+            finally {
+                timeout.dispose();
+            }
+            const durationMs = performance.now() - startTime;
+            if (!response.ok) {
+                const body = await parseResponseBody(response.clone());
+                const httpError = this.toHttpError(response.status, body);
+                if (this.shouldRetryRequest(request.method, attempt, response.status, httpError)) {
+                    await sleep(this.resolveRetryDelayMs(attempt, response));
+                    continue;
+                }
+                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error: httpError, durationMs });
+                throw httpError;
+            }
+            try {
+                await this.applyAfterInterceptors(cloneRequestContext(request), response, durationMs);
+            }
+            catch (error) {
+                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error, durationMs });
+                throw error;
+            }
+            // If server returned PBF, decode it
+            if (isPbfResponse(response)) {
+                try {
+                    const buffer = await response.arrayBuffer();
+                    return decodePbfQueryResponse(buffer);
+                }
+                catch {
+                    // PBF decode failed — fall back to JSON request
+                    params.set("f", "json");
+                    const jsonPath = `${path.replace(/\?.*$/, "")}?${params.toString()}`;
+                    return this.requestJson("GET", jsonPath, undefined, callerSignal ?? request.init.signal ?? undefined);
+                }
+            }
+            // Server returned JSON despite PBF request (e.g. error or unsupported)
+            return parseResponseBody(response);
+        }
+    }
+    /**
+     * 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;
+        let request = {
+            url: resolveRequestUrl(this.baseUrl, path),
+            path,
+            method,
+            init: {
+                method,
+                headers: await this.composeHeaders(headers),
+                ...(options?.body !== undefined ? { body: options.body } : {}),
+            },
+        };
+        request = await this.applyBeforeInterceptors(request);
+        for (let attempt = 0;; attempt += 1) {
+            let response;
+            const timeout = createTimeoutSignal(options?.signal ?? request.init.signal, this.timeoutMs);
+            const startTime = performance.now();
+            try {
+                response = await this.fetchFn(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 (this.shouldRetryRequest(request.method, attempt, undefined, normalizedError)) {
+                    await sleep(this.resolveRetryDelayMs(attempt));
+                    continue;
+                }
+                await this.applyErrorInterceptors({
+                    request: cloneRequestContext(request),
+                    error: normalizedError,
+                    durationMs,
+                });
+                throw normalizedError;
+            }
+            finally {
+                timeout.dispose();
+            }
+            const durationMs = performance.now() - startTime;
+            const text = await response.clone().text();
+            const contentType = response.headers.get("content-type") ?? acceptHeader;
+            if (!response.ok) {
+                const httpError = this.toHttpError(response.status, text ? { raw: text, contentType } : {});
+                if (this.shouldRetryRequest(request.method, attempt, response.status, httpError)) {
+                    await sleep(this.resolveRetryDelayMs(attempt, response));
+                    continue;
+                }
+                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error: httpError, durationMs });
+                throw httpError;
+            }
+            try {
+                await this.applyAfterInterceptors(cloneRequestContext(request), response, durationMs);
+            }
+            catch (error) {
+                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error, durationMs });
+                throw error;
+            }
+            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";
+        let request = {
+            url: resolveRequestUrl(this.baseUrl, path),
+            path,
+            method,
+            init: {
+                method,
+                headers: await this.composeHeaders({ Accept: acceptHeader }, init?.headers),
+                body: init?.body,
+            },
+        };
+        request = await this.applyBeforeInterceptors(request);
+        for (let attempt = 0;; attempt += 1) {
+            let response;
+            const timeout = createTimeoutSignal(callerSignal ?? request.init.signal, this.timeoutMs);
+            const startTime = performance.now();
+            try {
+                response = await this.fetchFn(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 (this.shouldRetryRequest(request.method, attempt, undefined, normalizedError)) {
+                    await sleep(this.resolveRetryDelayMs(attempt));
+                    continue;
+                }
+                await this.applyErrorInterceptors({
+                    request: cloneRequestContext(request),
+                    error: normalizedError,
+                    durationMs,
+                });
+                throw normalizedError;
+            }
+            finally {
+                timeout.dispose();
+            }
+            const durationMs = performance.now() - startTime;
+            if (!response.ok) {
+                const body = await parseResponseBody(response.clone());
+                const httpError = this.toHttpError(response.status, body);
+                if (this.shouldRetryRequest(request.method, attempt, response.status, httpError)) {
+                    await sleep(this.resolveRetryDelayMs(attempt, response));
+                    continue;
+                }
+                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error: httpError, durationMs });
+                throw httpError;
+            }
+            try {
+                await this.applyAfterInterceptors(cloneRequestContext(request), response, durationMs);
+            }
+            catch (error) {
+                await this.applyErrorInterceptors({ request: cloneRequestContext(request), error, durationMs });
+                throw error;
+            }
+            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,
+            };
+        }
+    }
+    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) {
+            const context = {
+                request: cloneRequestContext(request),
+                response: response.clone(),
+                durationMs,
+            };
+            await interceptor.after?.(context);
+        }
+    }
+    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.
+            }
+        }
+    }
+    shouldRetryRequest(method, attempt, statusCode, error) {
+        if (!this.retryOptions || attempt >= this.retryOptions.maxRetries) {
+            return false;
+        }
+        if (!DEFAULT_RETRY_METHODS.has(method)) {
+            return false;
+        }
+        if (error instanceof HonuaAbortError) {
+            return false;
+        }
+        if (statusCode !== undefined) {
+            return this.retryOptions.retryStatuses.has(statusCode);
+        }
+        return error instanceof HonuaNetworkError || error instanceof HonuaTimeoutError;
+    }
+    resolveRetryDelayMs(attempt, response) {
+        const retryAfterMs = response ? parseRetryAfterMs(response) : undefined;
+        if (retryAfterMs !== undefined) {
+            return retryAfterMs;
+        }
+        if (!this.retryOptions) {
+            return 0;
+        }
+        const exponentialDelay = this.retryOptions.baseDelayMs * 2 ** attempt;
+        const cappedDelay = Math.min(this.retryOptions.maxDelayMs, exponentialDelay);
+        return cappedDelay * (0.5 + Math.random() * 0.5);
+    }
+    toHttpError(statusCode, body) {
+        const fallback = "Request failed";
+        if (isObject(body)) {
+            const error = body.error;
+            if (isObject(error) && typeof error.message === "string") {
+                return new HonuaHttpError(statusCode, error.message, body);
+            }
+            if (typeof body.message === "string") {
+                return new HonuaHttpError(statusCode, body.message, body);
+            }
+            if (typeof body.detail === "string") {
+                return new HonuaHttpError(statusCode, body.detail, body);
+            }
+        }
+        return new HonuaHttpError(statusCode, fallback, 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 parseCompatibilityEnvelope(payload) {
+    if (!isObject(payload)) {
+        throw new TypeError("Server capabilities response must be a JSON object.");
+    }
+    if (payload.success === false) {
+        const message = typeof payload.message === "string" ? payload.message : "Server capabilities request failed.";
+        throw new Error(message);
+    }
+    if (!isObject(payload.data)) {
+        throw new TypeError("Server capabilities response is missing a data object.");
+    }
+    return parseCompatibilityContract(payload.data.compatibility);
+}
+function parseCompatibilityContract(payload) {
+    if (!isObject(payload)) {
+        throw new TypeError("Server capabilities response is missing data.compatibility.");
+    }
+    return {
+        serverVersion: requireNonEmptyString(payload.serverVersion, "data.compatibility.serverVersion"),
+        releaseChannel: requireNonEmptyString(payload.releaseChannel, "data.compatibility.releaseChannel"),
+        controlPlaneApi: parseControlPlaneApi(payload.controlPlaneApi),
+        metadataSchemas: parseMetadataSchemas(payload.metadataSchemas),
+        features: parseCompatibilityFeatures(payload.features),
+    };
+}
+function parseControlPlaneApi(payload) {
+    if (!isObject(payload)) {
+        throw new TypeError("Server capabilities response is missing data.compatibility.controlPlaneApi.");
+    }
+    return {
+        major: requireInteger(payload.major, "data.compatibility.controlPlaneApi.major"),
+        basePath: requireNonEmptyString(payload.basePath, "data.compatibility.controlPlaneApi.basePath"),
+        deprecated: requireBoolean(payload.deprecated, "data.compatibility.controlPlaneApi.deprecated"),
+    };
+}
+function parseMetadataSchemas(payload) {
+    if (!Array.isArray(payload)) {
+        throw new TypeError("Server capabilities response is missing data.compatibility.metadataSchemas.");
+    }
+    return payload.map((entry, index) => {
+        if (!isObject(entry)) {
+            throw new TypeError(`Server capabilities response metadataSchemas[${index}] must be an object.`);
+        }
+        return {
+            version: requireNonEmptyString(entry.version, `data.compatibility.metadataSchemas[${index}].version`),
+            deprecated: requireBoolean(entry.deprecated, `data.compatibility.metadataSchemas[${index}].deprecated`),
+        };
+    });
+}
+function parseCompatibilityFeatures(payload) {
+    if (!isObject(payload)) {
+        throw new TypeError("Server capabilities response is missing data.compatibility.features.");
+    }
+    return {
+        metadataResources: requireBoolean(payload.metadataResources, "data.compatibility.features.metadataResources"),
+        manifestExport: requireBoolean(payload.manifestExport, "data.compatibility.features.manifestExport"),
+        manifestApply: requireBoolean(payload.manifestApply, "data.compatibility.features.manifestApply"),
+        manifestDryRun: requireBoolean(payload.manifestDryRun, "data.compatibility.features.manifestDryRun"),
+        manifestPrune: requireBoolean(payload.manifestPrune, "data.compatibility.features.manifestPrune"),
+    };
+}
+function requireNonEmptyString(value, fieldName) {
+    if (typeof value !== "string") {
+        throw new TypeError(`${fieldName} must be a string.`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new TypeError(`${fieldName} must not be empty.`);
+    }
+    return trimmed;
+}
+function requireBoolean(value, fieldName) {
+    if (typeof value !== "boolean") {
+        throw new TypeError(`${fieldName} must be a boolean.`);
+    }
+    return value;
+}
+function requireInteger(value, fieldName) {
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new TypeError(`${fieldName} must be an integer.`);
+    }
+    return value;
+}
+function evaluateCompatibility(compatibility) {
+    const reasons = [];
+    const minimumVersion = parseVersion(HONUA_MINIMUM_SUPPORTED_SERVER_VERSION);
+    const serverVersion = parseVersion(compatibility.serverVersion);
+    if (!minimumVersion) {
+        reasons.push(`SDK minimum supported version '${HONUA_MINIMUM_SUPPORTED_SERVER_VERSION}' is not parseable for compatibility checks.`);
+        return reasons;
+    }
+    if (!serverVersion) {
+        reasons.push(`Server version '${compatibility.serverVersion}' is not parseable for compatibility checks.`);
+    }
+    else if (compareVersions(serverVersion, minimumVersion) < 0) {
+        reasons.push(`Server version ${compatibility.serverVersion} is older than the minimum supported ${HONUA_MINIMUM_SUPPORTED_SERVER_VERSION}.`);
+    }
+    if (compatibility.controlPlaneApi.major !== SUPPORTED_CONTROL_PLANE_API_MAJOR) {
+        reasons.push(`Control-plane API major ${compatibility.controlPlaneApi.major} is unsupported; expected ${SUPPORTED_CONTROL_PLANE_API_MAJOR}.`);
+    }
+    if (normalizePathValue(compatibility.controlPlaneApi.basePath) !== SUPPORTED_CONTROL_PLANE_API_BASE_PATH) {
+        reasons.push(`Control-plane API base path ${compatibility.controlPlaneApi.basePath} is unsupported; expected ${SUPPORTED_CONTROL_PLANE_API_BASE_PATH}.`);
+    }
+    if (compatibility.controlPlaneApi.deprecated) {
+        reasons.push(`Control-plane API major ${compatibility.controlPlaneApi.major} is marked deprecated by the server.`);
+    }
+    const actualReleaseChannelRank = getReleaseChannelRank(compatibility.releaseChannel);
+    const minimumReleaseChannelRank = getReleaseChannelRank(MINIMUM_SUPPORTED_SERVER_RELEASE_CHANNEL) ?? 0;
+    if (actualReleaseChannelRank === undefined) {
+        reasons.push(`Server release channel '${compatibility.releaseChannel}' is not recognized by this SDK baseline.`);
+    }
+    else if (actualReleaseChannelRank < minimumReleaseChannelRank) {
+        reasons.push(`Server release channel '${compatibility.releaseChannel}' is below the minimum supported '${MINIMUM_SUPPORTED_SERVER_RELEASE_CHANNEL}'.`);
+    }
+    return reasons;
+}
+function parseVersion(version) {
+    const normalized = version.trim().replace(/^v/i, "");
+    if (normalized.length === 0) {
+        return undefined;
+    }
+    const coreAndPrerelease = normalized.split("+", 1)[0] ?? normalized;
+    const [core, prerelease = ""] = coreAndPrerelease.split("-", 2);
+    const numbers = core.split(".").map((segment) => Number.parseInt(segment, 10));
+    if (numbers.length === 0 || numbers.some((segment) => !Number.isFinite(segment))) {
+        return undefined;
+    }
+    const prereleaseParts = prerelease.length > 0
+        ? prerelease
+            .split(".")
+            .map((segment) => segment.trim())
+            .filter((segment) => segment.length > 0)
+        : [];
+    return {
+        numbers,
+        prerelease: prereleaseParts,
+    };
+}
+function compareVersions(left, right) {
+    const length = Math.max(left.numbers.length, right.numbers.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftPart = left.numbers[index] ?? 0;
+        const rightPart = right.numbers[index] ?? 0;
+        if (leftPart !== rightPart) {
+            return leftPart < rightPart ? -1 : 1;
+        }
+    }
+    if (left.prerelease.length === 0 && right.prerelease.length === 0) {
+        return 0;
+    }
+    if (left.prerelease.length === 0) {
+        return 1;
+    }
+    if (right.prerelease.length === 0) {
+        return -1;
+    }
+    const prereleaseLength = Math.max(left.prerelease.length, right.prerelease.length);
+    for (let index = 0; index < prereleaseLength; index += 1) {
+        const leftPart = left.prerelease[index];
+        const rightPart = right.prerelease[index];
+        if (leftPart === undefined) {
+            return -1;
+        }
+        if (rightPart === undefined) {
+            return 1;
+        }
+        if (leftPart === rightPart) {
+            continue;
+        }
+        const leftNumeric = Number.parseInt(leftPart, 10);
+        const rightNumeric = Number.parseInt(rightPart, 10);
+        const leftIsNumeric = String(leftNumeric) === leftPart;
+        const rightIsNumeric = String(rightNumeric) === rightPart;
+        if (leftIsNumeric && rightIsNumeric) {
+            return leftNumeric < rightNumeric ? -1 : 1;
+        }
+        if (leftIsNumeric) {
+            return -1;
+        }
+        if (rightIsNumeric) {
+            return 1;
+        }
+        return leftPart < rightPart ? -1 : 1;
+    }
+    return 0;
+}
+function describeCompatibilityError(error) {
+    if (error instanceof HonuaHttpError && error.statusCode === 404) {
+        return "Server does not expose GET /api/v1/admin/capabilities.";
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function normalizePathValue(path) {
+    const trimmed = path.trim();
+    if (trimmed.length === 0) {
+        return "";
+    }
+    const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return prefixed.replace(/\/+$/, "");
+}
+function getReleaseChannelRank(releaseChannel) {
+    switch (releaseChannel.trim().toLowerCase()) {
+        case "nightly":
+            return 0;
+        case "dev":
+            return 1;
+        case "alpha":
+            return 2;
+        case "preview":
+            return 3;
+        case "beta":
+            return 4;
+        case "rc":
+            return 5;
+        case "stable":
+            return 6;
+        case "lts":
+            return 7;
+        default:
+            return undefined;
+    }
+}
+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 mergeHeaders(...headersList) {
+    const merged = {};
+    for (const headers of headersList) {
+        if (!headers) {
+            continue;
+        }
+        if (headers instanceof Headers) {
+            for (const [key, value] of headers.entries()) {
+                merged[key] = value;
+            }
+            continue;
+        }
+        if (Array.isArray(headers)) {
+            for (const [key, value] of headers) {
+                merged[key] = value;
+            }
+            continue;
+        }
+        for (const [key, value] of Object.entries(headers)) {
+            if (value === undefined || value === null) {
+                continue;
+            }
+            merged[key] = String(value);
+        }
+    }
+    return merged;
+}
+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 normalizeTimeoutMs(timeoutMs) {
+    if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs)) {
+        return undefined;
+    }
+    return Math.max(1, Math.trunc(timeoutMs));
+}
+function normalizeRetryOptions(options) {
+    if (!options) {
+        return undefined;
+    }
+    const maxRetries = typeof options.maxRetries === "number" && Number.isFinite(options.maxRetries)
+        ? Math.max(0, Math.trunc(options.maxRetries))
+        : 0;
+    if (maxRetries < 1) {
+        return undefined;
+    }
+    const baseDelayMs = typeof options.baseDelayMs === "number" && Number.isFinite(options.baseDelayMs)
+        ? Math.max(1, Math.trunc(options.baseDelayMs))
+        : 100;
+    const maxDelayMs = typeof options.maxDelayMs === "number" && Number.isFinite(options.maxDelayMs)
+        ? Math.max(baseDelayMs, Math.trunc(options.maxDelayMs))
+        : 2_000;
+    const retryStatuses = new Set((options.retryStatuses ?? Array.from(DEFAULT_RETRY_STATUSES))
+        .map((status) => Math.trunc(status))
+        .filter((status) => Number.isFinite(status) && status >= 100 && status <= 599));
+    if (retryStatuses.size === 0) {
+        for (const status of DEFAULT_RETRY_STATUSES) {
+            retryStatuses.add(status);
+        }
+    }
+    return {
+        maxRetries,
+        baseDelayMs,
+        maxDelayMs,
+        retryStatuses,
+    };
+}
+function parseRetryAfterMs(response) {
+    const value = response.headers.get("retry-after");
+    if (!value) {
+        return undefined;
+    }
+    const seconds = Number.parseInt(value, 10);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return seconds * 1_000;
+    }
+    const targetTime = Date.parse(value);
+    if (!Number.isFinite(targetTime)) {
+        return undefined;
+    }
+    return Math.max(0, targetTime - Date.now());
+}
+async function sleep(ms) {
+    if (ms <= 0) {
+        return;
+    }
+    await new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function normalizeNetworkError(error) {
+    if (error instanceof Error && error.name === "AbortError") {
+        return new HonuaAbortError();
+    }
+    if (error instanceof Error) {
+        return new HonuaNetworkError(error.message, error);
+    }
+    return new HonuaNetworkError(String(error), error);
+}
+function createTimeoutSignal(existingSignal, timeoutMs) {
+    if (timeoutMs === undefined) {
+        return {
+            signal: existingSignal ?? undefined,
+            didTimeout: false,
+            dispose: () => undefined,
+        };
+    }
+    const controller = new AbortController();
+    let didTimeout = false;
+    let timer;
+    let onAbort;
+    timer = setTimeout(() => {
+        didTimeout = true;
+        controller.abort();
+    }, timeoutMs);
+    if (existingSignal) {
+        if (existingSignal.aborted) {
+            controller.abort();
+        }
+        else {
+            onAbort = () => {
+                controller.abort();
+            };
+            existingSignal.addEventListener("abort", onAbort, { once: true });
+        }
+    }
+    return {
+        signal: controller.signal,
+        get didTimeout() {
+            return didTimeout;
+        },
+        dispose: () => {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            if (existingSignal && onAbort) {
+                existingSignal.removeEventListener("abort", onAbort);
+                onAbort = undefined;
+            }
+        },
+    };
+}
+function createOgcMetadataParams(request) {
+    const params = new URLSearchParams();
+    params.set("f", request.responseFormat ?? "json");
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    return params;
+}
+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}`;
+}
+function serializeQueryParams(params, request) {
+    if (request.outSr !== undefined) {
+        params.set("outSR", typeof request.outSr === "object" && request.outSr !== null
+            ? JSON.stringify(request.outSr)
+            : String(request.outSr));
+    }
+    if (request.orderByFields !== undefined) {
+        params.set("orderByFields", request.orderByFields);
+    }
+    if (request.objectIds !== undefined) {
+        params.set("objectIds", Array.isArray(request.objectIds) ? request.objectIds.join(",") : String(request.objectIds));
+    }
+    if (request.geometry !== undefined) {
+        params.set("geometry", typeof request.geometry === "object" && request.geometry !== null
+            ? JSON.stringify(request.geometry)
+            : String(request.geometry));
+    }
+    if (request.geometryType !== undefined) {
+        params.set("geometryType", request.geometryType);
+    }
+    if (request.spatialRel !== undefined) {
+        params.set("spatialRel", request.spatialRel);
+    }
+    if (request.returnDistinctValues !== undefined) {
+        params.set("returnDistinctValues", String(request.returnDistinctValues));
+    }
+    if (request.returnCentroid !== undefined) {
+        params.set("returnCentroid", String(request.returnCentroid));
+    }
+    if (request.groupByFieldsForStatistics !== undefined) {
+        params.set("groupByFieldsForStatistics", request.groupByFieldsForStatistics);
+    }
+    if (request.outStatistics !== undefined) {
+        params.set("outStatistics", Array.isArray(request.outStatistics) ? JSON.stringify(request.outStatistics) : String(request.outStatistics));
+    }
+    if (request.resultOffset !== undefined) {
+        params.set("resultOffset", String(request.resultOffset));
+    }
+    if (request.resultRecordCount !== undefined) {
+        params.set("resultRecordCount", String(request.resultRecordCount));
+    }
+}
+function appendQueryExtraParams(params, request) {
+    if (!request.extraParams) {
+        return;
+    }
+    for (const [key, value] of Object.entries(request.extraParams)) {
+        if (request.outSr !== undefined && (key === "outSr" || key === "outSR")) {
+            continue;
+        }
+        params.set(key, String(value));
+    }
+}
+function normalizeCsv(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    return Array.from(value).join(",");
+}
+function serializeOgcMapImageParams(request) {
+    const params = new URLSearchParams();
+    const f = ogcMapShortFormat(request.format);
+    if (f !== undefined)
+        params.set("f", f);
+    if (request.width !== undefined)
+        params.set("width", String(request.width));
+    if (request.height !== undefined)
+        params.set("height", String(request.height));
+    if (request.bbox !== undefined) {
+        params.set("bbox", typeof request.bbox === "string" ? request.bbox : request.bbox.join(","));
+    }
+    if (request.bboxCrs !== undefined)
+        params.set("bbox-crs", request.bboxCrs);
+    if (request.crs !== undefined)
+        params.set("crs", request.crs);
+    if (request.collections !== undefined && request.collections.length > 0) {
+        params.set("collections", request.collections.join(","));
+    }
+    if (request.transparent !== undefined)
+        params.set("transparent", String(request.transparent));
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    return params;
+}
+const OGC_MAP_FORMAT_TO_SHORT = new Map([
+    ["image/png", "png"],
+    ["image/jpeg", "jpeg"],
+    ["image/jpg", "jpg"],
+    ["image/tiff", "tiff"],
+    ["image/tif", "tif"],
+]);
+const OGC_MAP_SHORT_TO_MEDIA = new Map([
+    ["png", "image/png"],
+    ["jpeg", "image/jpeg"],
+    ["jpg", "image/jpeg"],
+    ["tiff", "image/tiff"],
+    ["tif", "image/tiff"],
+]);
+function ogcMapShortFormat(format) {
+    if (format === undefined)
+        return undefined;
+    const lower = format.toLowerCase();
+    return OGC_MAP_FORMAT_TO_SHORT.get(lower) ?? lower;
+}
+function ogcMapAcceptHeader(format) {
+    if (format === undefined)
+        return undefined;
+    const lower = format.toLowerCase();
+    return OGC_MAP_SHORT_TO_MEDIA.get(lower) ?? format;
+}
+/**
+ * Build the `Prefer` header for an OGC API Processes execution request.
+ * honua-server is async-only: `mode: "async"` sends an explicit
+ * `Prefer: respond-async` so OGC-conformance checkers see the header;
+ * `mode: "auto"` (or unset) omits it and lets the server default apply.
+ */
+function preferHeaderForExecute(request) {
+    if (request.mode === "async") {
+        return { Prefer: "respond-async" };
+    }
+    return undefined;
+}
+function serializeStacSearchParams(request) {
+    const params = new URLSearchParams();
+    if (request.bbox !== undefined)
+        params.set("bbox", request.bbox.join(","));
+    if (request.datetime !== undefined)
+        params.set("datetime", request.datetime);
+    if (request.ids !== undefined && request.ids.length > 0)
+        params.set("ids", request.ids.join(","));
+    if (request.collections !== undefined && request.collections.length > 0) {
+        params.set("collections", request.collections.join(","));
+    }
+    // honua-server accepts `intersects` on GET as a JSON-encoded geometry
+    // and `fields` as a CSV with `-` prefix marking excludes (matches
+    // STAC Item Search GET conventions and the server's parser).
+    if (request.intersects !== undefined)
+        params.set("intersects", JSON.stringify(request.intersects));
+    const fields = stacFieldsCsv(request.fields);
+    if (fields !== undefined)
+        params.set("fields", fields);
+    if (request.filter !== undefined)
+        params.set("filter", request.filter);
+    if (request.filterLang !== undefined)
+        params.set("filter-lang", request.filterLang);
+    if (request.limit !== undefined)
+        params.set("limit", String(request.limit));
+    // honua-server uses numeric `offset` paging on GET. `next` is kept as
+    // optional support for STAC servers that advertise an opaque token.
+    if (request.offset !== undefined)
+        params.set("offset", String(request.offset));
+    if (request.next !== undefined)
+        params.set("next", request.next);
+    if (request.sortby !== undefined)
+        params.set("sortby", request.sortby);
+    return params;
+}
+function stacSearchBody(request) {
+    const out = {};
+    if (request.bbox !== undefined)
+        out.bbox = request.bbox;
+    if (request.datetime !== undefined)
+        out.datetime = request.datetime;
+    if (request.intersects !== undefined)
+        out.intersects = request.intersects;
+    if (request.ids !== undefined)
+        out.ids = request.ids;
+    if (request.collections !== undefined)
+        out.collections = request.collections;
+    if (request.filter !== undefined)
+        out.filter = request.filter;
+    if (request.filterLang !== undefined)
+        out["filter-lang"] = request.filterLang;
+    if (request.limit !== undefined)
+        out.limit = request.limit;
+    if (request.offset !== undefined)
+        out.offset = request.offset;
+    if (request.next !== undefined)
+        out.next = request.next;
+    if (request.sortby !== undefined)
+        out.sortby = request.sortby;
+    if (request.fields !== undefined)
+        out.fields = request.fields;
+    return out;
+}
+function stacFieldsCsv(fields) {
+    if (!fields)
+        return undefined;
+    const parts = [];
+    if (fields.include) {
+        for (const f of fields.include) {
+            if (typeof f === "string" && f.length > 0)
+                parts.push(f);
+        }
+    }
+    if (fields.exclude) {
+        for (const f of fields.exclude) {
+            if (typeof f === "string" && f.length > 0)
+                parts.push(`-${f}`);
+        }
+    }
+    return parts.length > 0 ? parts.join(",") : undefined;
+}
+// ── WMS / WMTS helpers ──────────────────────────────────────────
+/** Canonical WMS endpoint path. honua-server publishes both `/rest/services/{id}/MapServer/WMS` and `/ogc/services/{id}/wms`; the SDK targets the GeoServices-aliased path because every Honua deployment exposes it. */
+function wmsBasePath(serviceId) {
+    return `/rest/services/${encodeURIComponent(serviceId)}/MapServer/WMS`;
+}
+/** Canonical WMTS endpoint path. */
+function wmtsBasePath(serviceId) {
+    return `/rest/services/${encodeURIComponent(serviceId)}/MapServer/WMTS`;
+}
+/**
+ * CRS table for WMS 1.3 axis order. WMS 1.3 honors authority axis order,
+ * which means `EPSG:4326` is `(lat, lon)` and `CRS:84` / `EPSG:3857` are
+ * `(x, y)`. The `BBOX` envelope tuple supplied by callers is the
+ * canonical `[minx, miny, maxx, maxy]`; this map decides whether the
+ * tuple is swapped on the wire.
+ */
+const WMS_AXIS_SWAP_CRS = new Set(["EPSG:4326"]);
+function serializeWmsMapParams(request) {
+    const params = new URLSearchParams();
+    params.set("SERVICE", "WMS");
+    params.set("VERSION", "1.3.0");
+    params.set("LAYERS", request.layers.join(","));
+    params.set("STYLES", request.styles ? request.styles.join(",") : "");
+    const crs = request.crs ?? "EPSG:3857";
+    params.set("CRS", crs);
+    const [minx, miny, maxx, maxy] = request.bbox;
+    const wireBbox = WMS_AXIS_SWAP_CRS.has(crs) ? [miny, minx, maxy, maxx] : [minx, miny, maxx, maxy];
+    params.set("BBOX", wireBbox.join(","));
+    params.set("WIDTH", String(Math.trunc(request.width)));
+    params.set("HEIGHT", String(Math.trunc(request.height)));
+    params.set("FORMAT", request.format ?? "image/png");
+    params.set("TRANSPARENT", String(request.transparent ?? true).toUpperCase());
+    if (request.bgcolor !== undefined)
+        params.set("BGCOLOR", request.bgcolor);
+    if (request.time !== undefined)
+        params.set("TIME", request.time);
+    if (request.elevation !== undefined)
+        params.set("ELEVATION", request.elevation);
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    return params;
+}
+function decodeWmsFeatureInfoResponse(bytes, contentType, requestedFormat) {
+    const isJson = contentType.toLowerCase().includes("application/json") ||
+        requestedFormat.toLowerCase().includes("application/json");
+    if (!isJson) {
+        return { contentType, bytes };
+    }
+    const text = new TextDecoder("utf-8").decode(bytes);
+    if (text.length === 0) {
+        return { contentType, features: [] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // Server emitted a non-JSON body despite the JSON Accept; preserve as bytes.
+        return { contentType, bytes };
+    }
+    const features = extractFeatureInfoFeatures(parsed);
+    return { contentType, features };
+}
+function extractFeatureInfoFeatures(parsed) {
+    if (!parsed || typeof parsed !== "object")
+        return [];
+    // honua-server emits `{ type: "FeatureInfoResponse", features: [{ layer, attributes }, ...] }`
+    // and a fallback GeoJSON `{ type: "FeatureCollection", features: [...] }`; both decode here.
+    const obj = parsed;
+    const featuresRaw = Array.isArray(obj.features) ? obj.features : [];
+    const out = [];
+    for (const raw of featuresRaw) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const feat = raw;
+        const attributes = (feat.attributes ?? feat.properties ?? {});
+        const geometry = feat.geometry ?? null;
+        out.push({ attributes, geometry });
+    }
+    return out;
+}
+const WMTS_FEATURE_INFO_FORMAT_TO_EXTENSION = new Map([
+    ["application/json", "json"],
+    ["text/plain", "txt"],
+    ["text/html", "html"],
+    ["application/geo+json", "geojson"],
+]);
+function wmtsFeatureInfoExtensionForFormat(format) {
+    return WMTS_FEATURE_INFO_FORMAT_TO_EXTENSION.get(format.toLowerCase()) ?? "txt";
+}
+const WMTS_REST_RESERVED_KEYS = new Set([
+    "service",
+    "version",
+    "request",
+    "layer",
+    "style",
+    "format",
+    "infoformat",
+    "tilematrixset",
+    "tilematrix",
+    "tilerow",
+    "tilecol",
+    "i",
+    "j",
+]);
+/**
+ * Serialize `extraParams` for the RESTful WMTS routes. Path-encoded WMTS
+ * keys take precedence — any extraParams whose key (case-insensitively)
+ * matches a path-derived value is dropped so the same URL never carries
+ * the value twice. Returns the query-string suffix to append (empty
+ * string when there is nothing left after filtering).
+ */
+function wmtsRestExtraParamsSuffix(extraParams) {
+    if (!extraParams)
+        return "";
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(extraParams)) {
+        if (value === undefined || value === null)
+            continue;
+        if (WMTS_REST_RESERVED_KEYS.has(key.toLowerCase()))
+            continue;
+        params.set(key, String(value));
+    }
+    const serialized = params.toString();
+    return serialized.length > 0 ? `?${serialized}` : "";
+}