@honua/react 0.1.11-beta.0 → 0.1.13

package/geocoding/index.js

@@ -0,0 +1,293 @@
+/**
+ * `@honua/sdk-js/geocoding` — `HonuaGeocodingClient` for forward / reverse
+ * geocoding and typeahead suggestions over a Honua-hosted GeocodeServer.
+ *
+ * @example
+ * ```ts
+ * import { HonuaGeocodingClient } from "@honua/sdk-js/geocoding";
+ *
+ * const geo = new HonuaGeocodingClient({
+ *   baseUrl: "https://your-honua-server.example",
+ *   locatorName: "world-geocoder",
+ * });
+ *
+ * const results = await geo.forwardGeocode("1 Honolulu Pl, HI");
+ * // reverseGeocode is latitude-first, then longitude.
+ * const here = await geo.reverseGeocode(21.30, -157.85);
+ * const hints = await geo.suggest("honol");
+ * ```
+ *
+ * @example Debounced typeahead
+ * ```ts
+ * let timer: ReturnType<typeof setTimeout> | undefined;
+ * input.addEventListener("input", (event) => {
+ *   clearTimeout(timer);
+ *   const text = (event.target as HTMLInputElement).value;
+ *   timer = setTimeout(async () => {
+ *     render(await geo.suggest(text));
+ *   }, 200);
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { HonuaAbortError, HonuaHttpError, HonuaNetworkError, HonuaTimeoutError } from "../core/errors.js";
+import { encodeServiceIdPath, trimTrailingSlashes } from "../core/path-utils.js";
+export { assertGeocodingCapability, supportsGeocodingCapability } from "./provider.js";
+export { honuaGeocodingProvider } from "./providers/honua.js";
+export { nominatimGeocodingProvider } from "./providers/nominatim.js";
+export { peliasGeocodingProvider } from "./providers/pelias.js";
+export { photonGeocodingProvider } from "./providers/photon.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Redirect status codes that carry a `Location` header. */
+const GEOCODING_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+/** Maximum number of redirects {@link HonuaGeocodingClient} will follow. */
+const GEOCODING_MAX_REDIRECTS = 20;
+function isAbsoluteHttpUrl(value) {
+    return value.startsWith("http://") || value.startsWith("https://");
+}
+function normalizeBaseUrl(url) {
+    return trimTrailingSlashes(url);
+}
+function stringifyAttributes(attrs) {
+    const result = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value === null || value === undefined) {
+            result[key] = null;
+        }
+        else {
+            result[key] = String(value);
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+export class HonuaGeocodingClient {
+    baseUrl;
+    locatorName;
+    fetchFn;
+    defaultHeaders;
+    timeoutMs;
+    constructor(options) {
+        this.baseUrl = normalizeBaseUrl(options.baseUrl);
+        this.locatorName = options.locatorName ?? "World";
+        // Bind to `globalThis` at assignment: invoking an unbound `window.fetch`
+        // as `this.fetchFn(...)` throws "TypeError: Illegal invocation" in
+        // browsers. Binding is a no-op for Node's undici fetch and for
+        // caller-supplied wrappers.
+        this.fetchFn = (options.fetchFn ?? fetch).bind(globalThis);
+        this.timeoutMs = options.timeoutMs;
+        const headers = {};
+        if (options.apiKey) {
+            headers["X-API-Key"] = options.apiKey;
+        }
+        if (options.bearerToken) {
+            headers.Authorization = `Bearer ${options.bearerToken}`;
+        }
+        this.defaultHeaders = headers;
+    }
+    // -------------------------------------------------------------------------
+    // Public methods
+    // -------------------------------------------------------------------------
+    /**
+     * Forward-geocode a single-line address string into one or more candidate
+     * locations.
+     */
+    async forwardGeocode(address, options) {
+        const params = new URLSearchParams();
+        params.set("singleLine", address);
+        params.set("f", "json");
+        if (options?.maxResults !== undefined) {
+            params.set("maxLocations", String(options.maxResults));
+        }
+        if (options?.countryCodes !== undefined) {
+            params.set("countryCode", options.countryCodes);
+        }
+        if (options?.spatialReferenceWkid !== undefined) {
+            params.set("outSR", String(options.spatialReferenceWkid));
+        }
+        const url = `${this.serviceBasePath()}/findAddressCandidates?${params.toString()}`;
+        const { data, responseHeaders } = await this.request(url);
+        if (data.error) {
+            throw this.geoServicesError(data.error, "Geocode", responseHeaders);
+        }
+        return (data.candidates ?? []).map((c) => ({
+            address: c.address,
+            longitude: c.location.x,
+            latitude: c.location.y,
+            score: c.score,
+            attributes: stringifyAttributes(c.attributes ?? {}),
+        }));
+    }
+    /**
+     * Reverse-geocode a latitude/longitude pair to the nearest address.
+     * Returns `null` when the server cannot find an address for the given
+     * coordinates.
+     */
+    async reverseGeocode(latitude, longitude, options) {
+        const params = new URLSearchParams();
+        params.set("location", `${longitude},${latitude}`);
+        params.set("f", "json");
+        if (options?.spatialReferenceWkid !== undefined) {
+            params.set("outSR", String(options.spatialReferenceWkid));
+        }
+        const url = `${this.serviceBasePath()}/reverseGeocode?${params.toString()}`;
+        let data;
+        let responseHeaders;
+        try {
+            ({ data, responseHeaders } = await this.request(url));
+        }
+        catch (err) {
+            // Some geocode servers return an HTTP error when no address is found.
+            if (err instanceof HonuaHttpError && err.statusCode === 400) {
+                return null;
+            }
+            throw err;
+        }
+        if (data.error) {
+            // Server-level "no result" errors are not exceptional.
+            if (data.error.code === 400) {
+                return null;
+            }
+            throw this.geoServicesError(data.error, "Reverse geocode", responseHeaders);
+        }
+        if (!data.address || !data.location) {
+            return null;
+        }
+        const { Match_addr, ...rest } = data.address;
+        return {
+            address: Match_addr ?? "",
+            longitude: data.location.x,
+            latitude: data.location.y,
+            attributes: stringifyAttributes(rest),
+        };
+    }
+    /**
+     * Retrieve type-ahead suggestions for a partial address string.
+     */
+    async suggest(text, options) {
+        const params = new URLSearchParams();
+        params.set("text", text);
+        params.set("f", "json");
+        if (options?.maxSuggestions !== undefined) {
+            params.set("maxSuggestions", String(options.maxSuggestions));
+        }
+        if (options?.countryCodes !== undefined) {
+            params.set("countryCode", options.countryCodes);
+        }
+        const url = `${this.serviceBasePath()}/suggest?${params.toString()}`;
+        const { data, responseHeaders } = await this.request(url);
+        if (data.error) {
+            throw this.geoServicesError(data.error, "Suggest", responseHeaders);
+        }
+        return (data.suggestions ?? []).map((s) => ({
+            text: s.text,
+            magicKey: s.magicKey,
+            isCollection: s.isCollection,
+        }));
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    serviceBasePath() {
+        return `${this.baseUrl}/rest/services/${encodeServiceIdPath(this.locatorName)}/GeocodeServer`;
+    }
+    /**
+     * Fetch with `redirect: "manual"`, only following a redirect when its target
+     * stays on the configured base origin. The geocoding client attaches its API
+     * key as a custom `X-API-Key` header that the runtime does not strip across a
+     * cross-origin redirect, so auto-following one would leak the key to the
+     * redirect target's host. Cross-origin (or origin-unverifiable) redirects
+     * throw instead of replaying the credentialed request off-origin.
+     */
+    async fetchWithSafeRedirects(url, init) {
+        const baseOrigin = isAbsoluteHttpUrl(this.baseUrl) ? new URL(this.baseUrl).origin : undefined;
+        let currentUrl = url;
+        for (let redirects = 0;; redirects += 1) {
+            const response = await this.fetchFn(currentUrl, { ...init, redirect: "manual" });
+            if (response.type === "opaqueredirect") {
+                throw new HonuaNetworkError("Refusing to follow an opaque cross-origin redirect; the geocoding API key would be leaked to the redirect target.", undefined);
+            }
+            if (!GEOCODING_REDIRECT_STATUSES.has(response.status)) {
+                return response;
+            }
+            if (redirects >= GEOCODING_MAX_REDIRECTS) {
+                throw new HonuaNetworkError(`Exceeded the maximum of ${GEOCODING_MAX_REDIRECTS} redirects.`, undefined);
+            }
+            const location = response.headers.get("location");
+            if (!location) {
+                throw new HonuaNetworkError("Redirect response is missing a Location header.", undefined);
+            }
+            let target;
+            try {
+                target = new URL(location, currentUrl);
+            }
+            catch {
+                throw new HonuaNetworkError(`Redirect response has an invalid Location header: ${location}`, undefined);
+            }
+            if (baseOrigin === undefined || target.origin !== baseOrigin) {
+                throw new HonuaNetworkError(`Refusing to follow a cross-origin redirect to ${target.origin}; the geocoding API key would be leaked.`, undefined);
+            }
+            currentUrl = target.toString();
+            await response.body?.cancel().catch(() => undefined);
+        }
+    }
+    geoServicesError(error, operation, responseHeaders) {
+        return new HonuaHttpError(error.code, `${operation} server error: ${error.message}`, { error }, {
+            transportStatus: 200,
+            protocolCode: error.code,
+            ...(responseHeaders ? { responseHeaders } : {}),
+        });
+    }
+    async request(url) {
+        const controller = new AbortController();
+        let timeoutId;
+        if (this.timeoutMs !== undefined) {
+            timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        }
+        let response;
+        try {
+            response = await this.fetchWithSafeRedirects(url, {
+                method: "GET",
+                headers: this.defaultHeaders,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+            if (err instanceof DOMException && err.name === "AbortError") {
+                if (this.timeoutMs !== undefined) {
+                    throw new HonuaTimeoutError(this.timeoutMs);
+                }
+                throw new HonuaAbortError();
+            }
+            throw new HonuaNetworkError(err instanceof Error
+                ? `Geocoding request failed: ${err.message}`
+                : "Geocoding request failed due to a network error", err);
+        }
+        finally {
+            if (timeoutId !== undefined) {
+                clearTimeout(timeoutId);
+            }
+        }
+        if (!response.ok) {
+            let body;
+            try {
+                body = await response.json();
+            }
+            catch {
+                body = await response.text().catch(() => null);
+            }
+            throw new HonuaHttpError(response.status, `Geocoding request failed with status ${response.status}`, body, {
+                responseHeaders: response.headers,
+            });
+        }
+        return { data: (await response.json()), responseHeaders: response.headers };
+    }
+}

package/geocoding/provider-http.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Minimal shared HTTP helper for the third-party geocoding / routing provider
+ * adapters. Mirrors the request semantics of the SDK's core clients — timeout
+ * composition and the typed error envelope (`HonuaTimeoutError`,
+ * `HonuaAbortError`, `HonuaNetworkError`, `HonuaHttpError`) — without pulling
+ * the full request pipeline into these small subpath bundles.
+ *
+ * Unlike `HonuaGeocodingClient`, provider adapters never attach Honua
+ * credentials, so the default fetch redirect behavior is safe here.
+ *
+ * @packageDocumentation
+ */
+/** Transport options shared by every provider adapter. @experimental */
+export interface ProviderTransportOptions {
+    /** Custom fetch implementation (testing, interception, auth bridges). */
+    fetchFn?: typeof fetch;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+}
+/** @internal */
+export interface ProviderRequestInit extends ProviderTransportOptions {
+    /** Extra request headers (e.g. a Nominatim-policy `User-Agent`). */
+    headers?: Record<string, string>;
+    /** Label used in error messages, e.g. `"nominatim geocode"`. */
+    label: string;
+}
+/**
+ * GET a JSON document with the SDK's typed error mapping.
+ *
+ * @internal
+ */
+export declare function providerGetJson<T>(url: string, init: ProviderRequestInit): Promise<T>;
+/** Strip trailing slashes so adapters can join paths deterministically. @internal */
+export declare function trimProviderBaseUrl(baseUrl: string): string;
+/** Stringify provider attributes to the contract `Record<string, string | null>` shape. @internal */
+export declare function stringifyProviderAttributes(attrs: Record<string, unknown>): Record<string, string | null>;
+//# sourceMappingURL=provider-http.d.ts.map

package/geocoding/provider-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-http.d.ts","sourceRoot":"","sources":["../../../src/geocoding/provider-http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,wEAAwE;AACxE,MAAM,WAAW,wBAAwB;IACvC,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,gBAAgB;AAChB,MAAM,WAAW,mBAAoB,SAAQ,wBAAwB;IACnE,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC,CAqD3F;AAED,qFAAqF;AACrF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAU3D;AAED,qGAAqG;AACrG,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CASzG"}

package/geocoding/provider-http.js

@@ -0,0 +1,93 @@
+/**
+ * Minimal shared HTTP helper for the third-party geocoding / routing provider
+ * adapters. Mirrors the request semantics of the SDK's core clients — timeout
+ * composition and the typed error envelope (`HonuaTimeoutError`,
+ * `HonuaAbortError`, `HonuaNetworkError`, `HonuaHttpError`) — without pulling
+ * the full request pipeline into these small subpath bundles.
+ *
+ * Unlike `HonuaGeocodingClient`, provider adapters never attach Honua
+ * credentials, so the default fetch redirect behavior is safe here.
+ *
+ * @packageDocumentation
+ */
+import { HonuaAbortError, HonuaHttpError, HonuaNetworkError, HonuaTimeoutError } from "../core/errors.js";
+/**
+ * GET a JSON document with the SDK's typed error mapping.
+ *
+ * @internal
+ */
+export async function providerGetJson(url, init) {
+    // Bind to `globalThis` at call time: invoking an unbound `window.fetch`
+    // throws "TypeError: Illegal invocation" in browsers.
+    const fetchFn = (init.fetchFn ?? fetch).bind(globalThis);
+    const controller = new AbortController();
+    let timeoutId;
+    if (init.timeoutMs !== undefined) {
+        timeoutId = setTimeout(() => controller.abort(), init.timeoutMs);
+    }
+    let response;
+    try {
+        response = await fetchFn(url, {
+            method: "GET",
+            headers: { Accept: "application/json", ...init.headers },
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        if (err instanceof DOMException && err.name === "AbortError") {
+            if (init.timeoutMs !== undefined) {
+                throw new HonuaTimeoutError(init.timeoutMs);
+            }
+            throw new HonuaAbortError();
+        }
+        throw new HonuaNetworkError(err instanceof Error
+            ? `${init.label} request failed: ${err.message}`
+            : `${init.label} request failed due to a network error`, err);
+    }
+    finally {
+        if (timeoutId !== undefined) {
+            clearTimeout(timeoutId);
+        }
+    }
+    if (!response.ok) {
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            body = await response.text().catch(() => null);
+        }
+        throw new HonuaHttpError(response.status, `${init.label} request failed with status ${response.status}`, body, {
+            responseHeaders: response.headers,
+        });
+    }
+    try {
+        return (await response.json());
+    }
+    catch (err) {
+        throw new HonuaNetworkError(`${init.label} response was not valid JSON`, err);
+    }
+}
+/** Strip trailing slashes so adapters can join paths deterministically. @internal */
+export function trimProviderBaseUrl(baseUrl) {
+    let end = baseUrl.length;
+    while (end > 0 && baseUrl[end - 1] === "/") {
+        end -= 1;
+    }
+    const trimmed = baseUrl.slice(0, end);
+    if (!trimmed) {
+        throw new Error("Provider baseUrl must be a non-empty URL (no default third-party endpoint is baked in).");
+    }
+    return trimmed;
+}
+/** Stringify provider attributes to the contract `Record<string, string | null>` shape. @internal */
+export function stringifyProviderAttributes(attrs) {
+    const result = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value === undefined) {
+            continue;
+        }
+        result[key] = value === null ? null : String(value);
+    }
+    return result;
+}

package/geocoding/provider.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Provider-pluggable geocoding contract: `GeocodingProvider` plus the
+ * normalized result shapes every adapter maps into. The Honua facade
+ * (`honuaGeocodingProvider`) and the open-source adapters (Nominatim, Photon,
+ * Pelias) all implement this one interface so hosts can swap providers with
+ * configuration only.
+ *
+ * Capability differences between providers are declared up front via
+ * {@link GeocodingProvider.capabilities} and enforced with the SDK's existing
+ * capability policy: an unsupported operation throws
+ * `HonuaCapabilityNotSupportedError` under the default `"strict"` policy and
+ * degrades to an empty result under `"degraded"`.
+ *
+ * @packageDocumentation
+ */
+import type { CapabilityPolicy } from "../contract/types.js";
+/**
+ * Operations a {@link GeocodingProvider} may support.
+ *
+ * @experimental
+ */
+export type GeocodingCapability = "geocode" | "reverse" | "suggest";
+/**
+ * Identifies which provider produced a result and carries that provider's
+ * attribution / usage-policy obligations so hosts can surface them (for
+ * example in a map attribution control).
+ *
+ * @experimental
+ */
+export interface GeocodingProvenance {
+    /** Provider identifier, e.g. `"nominatim"`, `"photon"`, `"pelias"`, `"honua"`. */
+    readonly provider: string;
+    /** Human-readable data attribution the host is obliged to display. */
+    readonly attribution: string;
+    /** Usage/acceptable-use policy for the configured endpoint, when known. */
+    readonly usagePolicyUrl?: string;
+}
+/**
+ * Normalized forward-geocode candidate. Mirrors the contract shape of
+ * `GeocodeResult` with provider provenance stamped on every result.
+ *
+ * @experimental
+ */
+export interface ProviderGeocodeMatch {
+    /** Formatted address / place label. */
+    address: string;
+    latitude: number;
+    longitude: number;
+    /**
+     * Provider-reported match quality when available (Nominatim `importance`,
+     * Pelias `confidence`, Honua locator `score`). Scale is provider-specific.
+     */
+    score?: number;
+    /** Provider-specific attributes, stringified to the contract shape. */
+    attributes: Record<string, string | null>;
+    provenance: GeocodingProvenance;
+}
+/**
+ * Normalized reverse-geocode result.
+ *
+ * @experimental
+ */
+export interface ProviderReverseMatch {
+    address: string;
+    latitude: number;
+    longitude: number;
+    attributes: Record<string, string | null>;
+    provenance: GeocodingProvenance;
+}
+/**
+ * Normalized typeahead suggestion.
+ *
+ * @experimental
+ */
+export interface ProviderSuggestion {
+    text: string;
+    provenance: GeocodingProvenance;
+}
+/**
+ * Options for {@link GeocodingProvider.geocode}.
+ *
+ * @experimental
+ */
+export interface ProviderGeocodeOptions {
+    /** Maximum number of candidates to return. */
+    limit?: number;
+    /** Comma-separated ISO 3166-1 alpha-2 country codes, e.g. `"us,ca"`. */
+    countryCodes?: string;
+}
+/**
+ * Options for {@link GeocodingProvider.suggest}.
+ *
+ * @experimental
+ */
+export interface ProviderSuggestOptions {
+    /** Maximum number of suggestions to return. */
+    limit?: number;
+    /** Comma-separated ISO 3166-1 alpha-2 country codes, e.g. `"us,ca"`. */
+    countryCodes?: string;
+}
+/**
+ * Provider-pluggable geocoding contract. All adapters normalize into the same
+ * typed result shapes; capability differences are declared, not discovered at
+ * runtime.
+ *
+ * Operations outside {@link capabilities} throw
+ * `HonuaCapabilityNotSupportedError` under the `"strict"` capability policy
+ * (the default) and resolve to an empty result under `"degraded"`.
+ *
+ * @experimental
+ */
+export interface GeocodingProvider {
+    /** Stable provider identifier, e.g. `"nominatim"`. */
+    readonly id: string;
+    /** Operations this provider supports. */
+    readonly capabilities: ReadonlyArray<GeocodingCapability>;
+    /** Human-readable data attribution the host is obliged to display. */
+    readonly attribution: string;
+    /** Usage/acceptable-use policy for the configured endpoint, when known. */
+    readonly usagePolicyUrl?: string;
+    /** Forward-geocode a free-text query into candidate locations. */
+    geocode(query: string, options?: ProviderGeocodeOptions): Promise<ProviderGeocodeMatch[]>;
+    /** Reverse-geocode a latitude/longitude pair; `null` when nothing is found. */
+    reverse(latitude: number, longitude: number): Promise<ProviderReverseMatch | null>;
+    /** Typeahead suggestions for a partial query. */
+    suggest(text: string, options?: ProviderSuggestOptions): Promise<ProviderSuggestion[]>;
+}
+/**
+ * `true` when `provider` declares `capability`.
+ *
+ * @experimental
+ */
+export declare function supportsGeocodingCapability(provider: GeocodingProvider, capability: GeocodingCapability): boolean;
+/**
+ * Enforce a capability declaration against the active capability policy.
+ * Returns `true` when the capability is supported. When it is missing, throws
+ * `HonuaCapabilityNotSupportedError` under `"strict"` (the default) or returns
+ * `false` under `"degraded"` so callers can resolve to an empty result.
+ *
+ * @experimental
+ */
+export declare function assertGeocodingCapability(provider: Pick<GeocodingProvider, "id" | "capabilities">, capability: GeocodingCapability, policy?: CapabilityPolicy): boolean;
+/** Re-exported so provider hosts can type their policy without importing `/contract`. */
+export type { CapabilityPolicy };
+//# sourceMappingURL=provider.d.ts.map

package/geocoding/provider.d.ts.map

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

package/geocoding/provider.js

@@ -0,0 +1,41 @@
+/**
+ * Provider-pluggable geocoding contract: `GeocodingProvider` plus the
+ * normalized result shapes every adapter maps into. The Honua facade
+ * (`honuaGeocodingProvider`) and the open-source adapters (Nominatim, Photon,
+ * Pelias) all implement this one interface so hosts can swap providers with
+ * configuration only.
+ *
+ * Capability differences between providers are declared up front via
+ * {@link GeocodingProvider.capabilities} and enforced with the SDK's existing
+ * capability policy: an unsupported operation throws
+ * `HonuaCapabilityNotSupportedError` under the default `"strict"` policy and
+ * degrades to an empty result under `"degraded"`.
+ *
+ * @packageDocumentation
+ */
+import { HonuaCapabilityNotSupportedError } from "../core/errors.js";
+/**
+ * `true` when `provider` declares `capability`.
+ *
+ * @experimental
+ */
+export function supportsGeocodingCapability(provider, capability) {
+    return provider.capabilities.includes(capability);
+}
+/**
+ * Enforce a capability declaration against the active capability policy.
+ * Returns `true` when the capability is supported. When it is missing, throws
+ * `HonuaCapabilityNotSupportedError` under `"strict"` (the default) or returns
+ * `false` under `"degraded"` so callers can resolve to an empty result.
+ *
+ * @experimental
+ */
+export function assertGeocodingCapability(provider, capability, policy = "strict") {
+    if (provider.capabilities.includes(capability)) {
+        return true;
+    }
+    if (policy === "strict") {
+        throw new HonuaCapabilityNotSupportedError(capability, provider.id);
+    }
+    return false;
+}

package/geocoding/providers/honua.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Honua facade adapter: wraps the existing {@link HonuaGeocodingClient}
+ * (Honua-hosted GeocodeServer locator) in the provider-pluggable
+ * {@link GeocodingProvider} contract, making the Honua facade one provider
+ * among several.
+ *
+ * @packageDocumentation
+ */
+import type { CapabilityPolicy } from "../../contract/types.js";
+import type { HonuaGeocodingClient } from "../index.js";
+import { type GeocodingProvider } from "../provider.js";
+/** Options for {@link honuaGeocodingProvider}. @experimental */
+export interface HonuaGeocodingProviderOptions {
+    /** Capability policy; the Honua locator supports all declared operations. */
+    capabilityPolicy?: CapabilityPolicy;
+    /** Override the default attribution string for your deployment's data. */
+    attribution?: string;
+    /** Usage-policy URL for your deployment, when applicable. */
+    usagePolicyUrl?: string;
+}
+/**
+ * Wrap a {@link HonuaGeocodingClient} in the {@link GeocodingProvider}
+ * contract.
+ *
+ * @experimental
+ */
+export declare function honuaGeocodingProvider(client: HonuaGeocodingClient, options?: HonuaGeocodingProviderOptions): GeocodingProvider;
+//# sourceMappingURL=honua.d.ts.map

package/geocoding/providers/honua.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"honua.d.ts","sourceRoot":"","sources":["../../../../src/geocoding/providers/honua.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAGL,KAAK,iBAAiB,EAOvB,MAAM,gBAAgB,CAAC;AAExB,gEAAgE;AAChE,MAAM,WAAW,6BAA6B;IAC5C,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAKD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE,6BAAkC,GAC1C,iBAAiB,CAsDnB"}