@honua/app-platform 0.0.20-alpha.0 → 0.1.1-beta.0

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"}

package/geocoding/providers/honua.js

@@ -0,0 +1,68 @@
+/**
+ * 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 { assertGeocodingCapability, } from "../provider.js";
+const HONUA_ATTRIBUTION = "Honua-hosted locator service";
+const HONUA_CAPABILITIES = ["geocode", "reverse", "suggest"];
+/**
+ * Wrap a {@link HonuaGeocodingClient} in the {@link GeocodingProvider}
+ * contract.
+ *
+ * @experimental
+ */
+export function honuaGeocodingProvider(client, options = {}) {
+    const policy = options.capabilityPolicy ?? "strict";
+    const provenance = Object.freeze({
+        provider: "honua",
+        attribution: options.attribution ?? HONUA_ATTRIBUTION,
+        ...(options.usagePolicyUrl !== undefined ? { usagePolicyUrl: options.usagePolicyUrl } : {}),
+    });
+    return {
+        id: "honua",
+        capabilities: HONUA_CAPABILITIES,
+        attribution: provenance.attribution,
+        usagePolicyUrl: provenance.usagePolicyUrl,
+        async geocode(query, geocodeOptions) {
+            assertGeocodingCapability({ id: "honua", capabilities: HONUA_CAPABILITIES }, "geocode", policy);
+            const results = await client.forwardGeocode(query, {
+                maxResults: geocodeOptions?.limit,
+                countryCodes: geocodeOptions?.countryCodes,
+            });
+            return results.map((result) => ({
+                address: result.address,
+                latitude: result.latitude,
+                longitude: result.longitude,
+                score: result.score,
+                attributes: result.attributes,
+                provenance,
+            }));
+        },
+        async reverse(latitude, longitude) {
+            assertGeocodingCapability({ id: "honua", capabilities: HONUA_CAPABILITIES }, "reverse", policy);
+            const result = await client.reverseGeocode(latitude, longitude);
+            if (!result) {
+                return null;
+            }
+            return {
+                address: result.address,
+                latitude: result.latitude,
+                longitude: result.longitude,
+                attributes: result.attributes,
+                provenance,
+            };
+        },
+        async suggest(text, suggestOptions) {
+            assertGeocodingCapability({ id: "honua", capabilities: HONUA_CAPABILITIES }, "suggest", policy);
+            const suggestions = await client.suggest(text, {
+                maxSuggestions: suggestOptions?.limit,
+                countryCodes: suggestOptions?.countryCodes,
+            });
+            return suggestions.map((suggestion) => ({ text: suggestion.text, provenance }));
+        },
+    };
+}

package/geocoding/providers/nominatim.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Nominatim adapter for the {@link GeocodingProvider} contract.
+ *
+ * Supports `geocode` and `reverse`; Nominatim has no typeahead endpoint, so
+ * `suggest` is declared unsupported and throws
+ * `HonuaCapabilityNotSupportedError` under the strict capability policy.
+ *
+ * There is no default endpoint: pass the `baseUrl` of an instance you are
+ * entitled to use. If you point at the public
+ * `https://nominatim.openstreetmap.org` service you MUST follow the OSMF
+ * Nominatim usage policy — at most 1 request/second, a real `userAgent`
+ * identifying your application, and no heavy typeahead-style traffic.
+ *
+ * @packageDocumentation
+ */
+import type { CapabilityPolicy } from "../../contract/types.js";
+import { type ProviderTransportOptions } from "../provider-http.js";
+import { type GeocodingProvider } from "../provider.js";
+/** Options for {@link nominatimGeocodingProvider}. @experimental */
+export interface NominatimProviderOptions extends ProviderTransportOptions {
+    /**
+     * Base URL of the Nominatim instance, e.g. `https://nominatim.example.org`.
+     * Required — no third-party default is baked in (usage-policy safety).
+     */
+    baseUrl: string;
+    /**
+     * Value for the `User-Agent` header. The OSMF usage policy requires a real
+     * application identifier when using the public instance. Only settable in
+     * non-browser runtimes; browsers control their own `User-Agent`.
+     */
+    userAgent?: string;
+    /** Contact email forwarded as the `email` query parameter (public-instance etiquette). */
+    email?: string;
+    /** Capability policy; `"strict"` (default) throws on `suggest`. */
+    capabilityPolicy?: CapabilityPolicy;
+    /** Override the default attribution string (self-hosted instances). */
+    attribution?: string;
+    /** Override the default usage-policy URL (self-hosted instances). */
+    usagePolicyUrl?: string;
+}
+/**
+ * Create a {@link GeocodingProvider} backed by a Nominatim instance.
+ *
+ * @experimental
+ */
+export declare function nominatimGeocodingProvider(options: NominatimProviderOptions): GeocodingProvider;
+//# sourceMappingURL=nominatim.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nominatim.d.ts","sourceRoot":"","sources":["../../../../src/geocoding/providers/nominatim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EACL,KAAK,wBAAwB,EAI9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,iBAAiB,EAMvB,MAAM,gBAAgB,CAAC;AAExB,oEAAoE;AACpE,MAAM,WAAW,wBAAyB,SAAQ,wBAAwB;IACxE;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAmBD;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAqF/F"}

package/geocoding/providers/nominatim.js

@@ -0,0 +1,105 @@
+/**
+ * Nominatim adapter for the {@link GeocodingProvider} contract.
+ *
+ * Supports `geocode` and `reverse`; Nominatim has no typeahead endpoint, so
+ * `suggest` is declared unsupported and throws
+ * `HonuaCapabilityNotSupportedError` under the strict capability policy.
+ *
+ * There is no default endpoint: pass the `baseUrl` of an instance you are
+ * entitled to use. If you point at the public
+ * `https://nominatim.openstreetmap.org` service you MUST follow the OSMF
+ * Nominatim usage policy — at most 1 request/second, a real `userAgent`
+ * identifying your application, and no heavy typeahead-style traffic.
+ *
+ * @packageDocumentation
+ */
+import { providerGetJson, stringifyProviderAttributes, trimProviderBaseUrl, } from "../provider-http.js";
+import { assertGeocodingCapability, } from "../provider.js";
+const NOMINATIM_ATTRIBUTION = "Data © OpenStreetMap contributors, ODbL 1.0";
+const NOMINATIM_USAGE_POLICY_URL = "https://operations.osmfoundation.org/policies/nominatim/";
+const NOMINATIM_CAPABILITIES = ["geocode", "reverse"];
+/**
+ * Create a {@link GeocodingProvider} backed by a Nominatim instance.
+ *
+ * @experimental
+ */
+export function nominatimGeocodingProvider(options) {
+    const baseUrl = trimProviderBaseUrl(options.baseUrl);
+    const policy = options.capabilityPolicy ?? "strict";
+    const headers = {};
+    if (options.userAgent) {
+        headers["User-Agent"] = options.userAgent;
+    }
+    const provenance = Object.freeze({
+        provider: "nominatim",
+        attribution: options.attribution ?? NOMINATIM_ATTRIBUTION,
+        usagePolicyUrl: options.usagePolicyUrl ?? NOMINATIM_USAGE_POLICY_URL,
+    });
+    const request = (path, params, label) => {
+        params.set("format", "jsonv2");
+        if (options.email) {
+            params.set("email", options.email);
+        }
+        return providerGetJson(`${baseUrl}${path}?${params.toString()}`, {
+            fetchFn: options.fetchFn,
+            timeoutMs: options.timeoutMs,
+            headers,
+            label,
+        });
+    };
+    const toMatch = (place) => ({
+        address: place.display_name ?? "",
+        latitude: Number(place.lat),
+        longitude: Number(place.lon),
+        score: place.importance,
+        attributes: stringifyProviderAttributes({
+            place_id: place.place_id,
+            osm_type: place.osm_type,
+            osm_id: place.osm_id,
+            category: place.category,
+            type: place.type,
+        }),
+        provenance,
+    });
+    return {
+        id: "nominatim",
+        capabilities: NOMINATIM_CAPABILITIES,
+        attribution: provenance.attribution,
+        usagePolicyUrl: provenance.usagePolicyUrl,
+        async geocode(query, geocodeOptions) {
+            assertGeocodingCapability({ id: "nominatim", capabilities: NOMINATIM_CAPABILITIES }, "geocode", policy);
+            const params = new URLSearchParams({ q: query });
+            if (geocodeOptions?.limit !== undefined) {
+                params.set("limit", String(geocodeOptions.limit));
+            }
+            if (geocodeOptions?.countryCodes !== undefined) {
+                params.set("countrycodes", geocodeOptions.countryCodes);
+            }
+            const places = await request("/search", params, "nominatim geocode");
+            return (places ?? []).map(toMatch);
+        },
+        async reverse(latitude, longitude) {
+            assertGeocodingCapability({ id: "nominatim", capabilities: NOMINATIM_CAPABILITIES }, "reverse", policy);
+            const params = new URLSearchParams({ lat: String(latitude), lon: String(longitude) });
+            const place = await request("/reverse", params, "nominatim reverse");
+            // Nominatim reports "no result" as `{ "error": "Unable to geocode" }`.
+            if (!place || place.error !== undefined || place.lat === undefined) {
+                return null;
+            }
+            const match = toMatch(place);
+            return {
+                address: match.address,
+                latitude: match.latitude,
+                longitude: match.longitude,
+                attributes: match.attributes,
+                provenance,
+            };
+        },
+        async suggest() {
+            // Declared capability miss: Nominatim's usage policy forbids
+            // autocomplete-style traffic and it exposes no suggest endpoint.
+            assertGeocodingCapability({ id: "nominatim", capabilities: NOMINATIM_CAPABILITIES }, "suggest", policy);
+            return [];
+        },
+    };
+}

package/geocoding/providers/pelias.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pelias adapter for the {@link GeocodingProvider} contract.
+ *
+ * Supports `geocode` (`/v1/search`), `reverse` (`/v1/reverse`), and `suggest`
+ * via the dedicated `/v1/autocomplete` endpoint.
+ *
+ * There is no default endpoint: pass the `baseUrl` of an instance you are
+ * entitled to use (self-hosted Pelias or a hosted service such as
+ * geocode.earth, whose terms and API key requirements you must follow).
+ * Attribution depends on the datasets the instance is built from — override
+ * `attribution` to match your instance's obligations.
+ *
+ * @packageDocumentation
+ */
+import type { CapabilityPolicy } from "../../contract/types.js";
+import { type ProviderTransportOptions } from "../provider-http.js";
+import { type GeocodingProvider } from "../provider.js";
+/** Options for {@link peliasGeocodingProvider}. @experimental */
+export interface PeliasProviderOptions extends ProviderTransportOptions {
+    /**
+     * Base URL of the Pelias instance, e.g. `https://pelias.example.org`.
+     * Required — no third-party default is baked in (usage-policy safety).
+     */
+    baseUrl: string;
+    /** API key forwarded as the `api_key` query parameter (hosted instances). */
+    apiKey?: string;
+    /** Capability policy; Pelias supports all declared operations. */
+    capabilityPolicy?: CapabilityPolicy;
+    /** Override the default attribution string to match your instance's datasets. */
+    attribution?: string;
+    /** Override the default usage-policy URL (hosted/self-hosted instances). */
+    usagePolicyUrl?: string;
+}
+/**
+ * Create a {@link GeocodingProvider} backed by a Pelias instance.
+ *
+ * @experimental
+ */
+export declare function peliasGeocodingProvider(options: PeliasProviderOptions): GeocodingProvider;
+//# sourceMappingURL=pelias.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pelias.d.ts","sourceRoot":"","sources":["../../../../src/geocoding/providers/pelias.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EACL,KAAK,wBAAwB,EAI9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,iBAAiB,EAOvB,MAAM,gBAAgB,CAAC;AAExB,iEAAiE;AACjE,MAAM,WAAW,qBAAsB,SAAQ,wBAAwB;IACrE;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAwBD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,qBAAqB,GAAG,iBAAiB,CAiGzF"}

package/geocoding/providers/pelias.js

@@ -0,0 +1,115 @@
+/**
+ * Pelias adapter for the {@link GeocodingProvider} contract.
+ *
+ * Supports `geocode` (`/v1/search`), `reverse` (`/v1/reverse`), and `suggest`
+ * via the dedicated `/v1/autocomplete` endpoint.
+ *
+ * There is no default endpoint: pass the `baseUrl` of an instance you are
+ * entitled to use (self-hosted Pelias or a hosted service such as
+ * geocode.earth, whose terms and API key requirements you must follow).
+ * Attribution depends on the datasets the instance is built from — override
+ * `attribution` to match your instance's obligations.
+ *
+ * @packageDocumentation
+ */
+import { providerGetJson, stringifyProviderAttributes, trimProviderBaseUrl, } from "../provider-http.js";
+import { assertGeocodingCapability, } from "../provider.js";
+const PELIAS_ATTRIBUTION = "Geocoding by Pelias; data © OpenStreetMap contributors and other dataset licensors";
+const PELIAS_USAGE_POLICY_URL = "https://github.com/pelias/documentation/blob/master/data-licenses.md";
+const PELIAS_CAPABILITIES = ["geocode", "reverse", "suggest"];
+/**
+ * Create a {@link GeocodingProvider} backed by a Pelias instance.
+ *
+ * @experimental
+ */
+export function peliasGeocodingProvider(options) {
+    const baseUrl = trimProviderBaseUrl(options.baseUrl);
+    const policy = options.capabilityPolicy ?? "strict";
+    const provenance = Object.freeze({
+        provider: "pelias",
+        attribution: options.attribution ?? PELIAS_ATTRIBUTION,
+        usagePolicyUrl: options.usagePolicyUrl ?? PELIAS_USAGE_POLICY_URL,
+    });
+    const request = (path, params, label) => {
+        if (options.apiKey) {
+            params.set("api_key", options.apiKey);
+        }
+        return providerGetJson(`${baseUrl}${path}?${params.toString()}`, {
+            fetchFn: options.fetchFn,
+            timeoutMs: options.timeoutMs,
+            label,
+        });
+    };
+    const toMatch = (feature) => {
+        const [longitude, latitude] = feature.geometry?.coordinates ?? [Number.NaN, Number.NaN];
+        const p = feature.properties ?? {};
+        return {
+            address: p.label ?? p.name ?? "",
+            latitude,
+            longitude,
+            score: p.confidence,
+            attributes: stringifyProviderAttributes({
+                gid: p.gid,
+                layer: p.layer,
+                source: p.source,
+                country_code: p.country_code,
+                postalcode: p.postalcode,
+            }),
+            provenance,
+        };
+    };
+    const applyCountryFilter = (params, countryCodes) => {
+        if (countryCodes !== undefined) {
+            params.set("boundary.country", countryCodes);
+        }
+    };
+    return {
+        id: "pelias",
+        capabilities: PELIAS_CAPABILITIES,
+        attribution: provenance.attribution,
+        usagePolicyUrl: provenance.usagePolicyUrl,
+        async geocode(query, geocodeOptions) {
+            assertGeocodingCapability({ id: "pelias", capabilities: PELIAS_CAPABILITIES }, "geocode", policy);
+            const params = new URLSearchParams({ text: query });
+            if (geocodeOptions?.limit !== undefined) {
+                params.set("size", String(geocodeOptions.limit));
+            }
+            applyCountryFilter(params, geocodeOptions?.countryCodes);
+            const data = await request("/v1/search", params, "pelias geocode");
+            return (data.features ?? []).map(toMatch);
+        },
+        async reverse(latitude, longitude) {
+            assertGeocodingCapability({ id: "pelias", capabilities: PELIAS_CAPABILITIES }, "reverse", policy);
+            const params = new URLSearchParams({
+                "point.lat": String(latitude),
+                "point.lon": String(longitude),
+            });
+            const data = await request("/v1/reverse", params, "pelias reverse");
+            const feature = data.features?.[0];
+            if (!feature) {
+                return null;
+            }
+            const match = toMatch(feature);
+            return {
+                address: match.address,
+                latitude: match.latitude,
+                longitude: match.longitude,
+                attributes: match.attributes,
+                provenance,
+            };
+        },
+        async suggest(text, suggestOptions) {
+            assertGeocodingCapability({ id: "pelias", capabilities: PELIAS_CAPABILITIES }, "suggest", policy);
+            const params = new URLSearchParams({ text });
+            if (suggestOptions?.limit !== undefined) {
+                params.set("size", String(suggestOptions.limit));
+            }
+            applyCountryFilter(params, suggestOptions?.countryCodes);
+            const data = await request("/v1/autocomplete", params, "pelias suggest");
+            return (data.features ?? []).map((feature) => ({
+                text: feature.properties?.label ?? feature.properties?.name ?? "",
+                provenance,
+            }));
+        },
+    };
+}

package/geocoding/providers/photon.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Photon adapter for the {@link GeocodingProvider} contract.
+ *
+ * Photon (komoot) is typeahead-first, so it supports all three operations:
+ * `geocode`, `reverse`, and `suggest` (suggest reuses the search endpoint,
+ * which is designed for as-you-type queries).
+ *
+ * There is no default endpoint: pass the `baseUrl` of an instance you are
+ * entitled to use (e.g. a self-hosted Photon, or `https://photon.komoot.io`
+ * within its fair-use terms).
+ *
+ * @packageDocumentation
+ */
+import type { CapabilityPolicy } from "../../contract/types.js";
+import { type ProviderTransportOptions } from "../provider-http.js";
+import { type GeocodingProvider } from "../provider.js";
+/** Options for {@link photonGeocodingProvider}. @experimental */
+export interface PhotonProviderOptions extends ProviderTransportOptions {
+    /**
+     * Base URL of the Photon instance, e.g. `https://photon.example.org`.
+     * Required — no third-party default is baked in (usage-policy safety).
+     */
+    baseUrl: string;
+    /** BCP-47 language for results, forwarded as `lang` when set. */
+    language?: string;
+    /** Capability policy; Photon supports all declared operations. */
+    capabilityPolicy?: CapabilityPolicy;
+    /** Override the default attribution string (self-hosted instances). */
+    attribution?: string;
+    /** Override the default usage-policy URL (self-hosted instances). */
+    usagePolicyUrl?: string;
+}
+/**
+ * Create a {@link GeocodingProvider} backed by a Photon instance.
+ *
+ * @experimental
+ */
+export declare function photonGeocodingProvider(options: PhotonProviderOptions): GeocodingProvider;
+//# sourceMappingURL=photon.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"photon.d.ts","sourceRoot":"","sources":["../../../../src/geocoding/providers/photon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EACL,KAAK,wBAAwB,EAI9B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAGL,KAAK,iBAAiB,EAOvB,MAAM,gBAAgB,CAAC;AAExB,iEAAiE;AACjE,MAAM,WAAW,qBAAsB,SAAQ,wBAAwB;IACrE;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,uEAAuE;IACvE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAsCD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,qBAAqB,GAAG,iBAAiB,CAmFzF"}