@honua/react 0.1.11-beta.0 → 0.1.13

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

package/geocoding/providers/photon.js

@@ -0,0 +1,107 @@
+/**
+ * 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 { providerGetJson, stringifyProviderAttributes, trimProviderBaseUrl, } from "../provider-http.js";
+import { assertGeocodingCapability, } from "../provider.js";
+const PHOTON_ATTRIBUTION = "Data © OpenStreetMap contributors, ODbL 1.0";
+const PHOTON_USAGE_POLICY_URL = "https://photon.komoot.io/";
+const PHOTON_CAPABILITIES = ["geocode", "reverse", "suggest"];
+function photonLabel(feature) {
+    const p = feature.properties ?? {};
+    const streetLine = p.housenumber && p.street ? `${p.street} ${p.housenumber}` : p.street;
+    const parts = [p.name, streetLine, p.city, p.state, p.country].filter((part) => typeof part === "string" && part.length > 0);
+    // Photon repeats `name` for street-level results; drop consecutive duplicates.
+    return parts.filter((part, index) => part !== parts[index - 1]).join(", ");
+}
+/**
+ * Create a {@link GeocodingProvider} backed by a Photon instance.
+ *
+ * @experimental
+ */
+export function photonGeocodingProvider(options) {
+    const baseUrl = trimProviderBaseUrl(options.baseUrl);
+    const policy = options.capabilityPolicy ?? "strict";
+    const provenance = Object.freeze({
+        provider: "photon",
+        attribution: options.attribution ?? PHOTON_ATTRIBUTION,
+        usagePolicyUrl: options.usagePolicyUrl ?? PHOTON_USAGE_POLICY_URL,
+    });
+    const request = (path, params, label) => {
+        if (options.language) {
+            params.set("lang", options.language);
+        }
+        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: photonLabel(feature),
+            latitude,
+            longitude,
+            attributes: stringifyProviderAttributes({
+                osm_id: p.osm_id,
+                osm_type: p.osm_type,
+                osm_key: p.osm_key,
+                osm_value: p.osm_value,
+                postcode: p.postcode,
+                type: p.type,
+            }),
+            provenance,
+        };
+    };
+    const search = async (query, limit, label) => {
+        const params = new URLSearchParams({ q: query });
+        if (limit !== undefined) {
+            params.set("limit", String(limit));
+        }
+        const data = await request("/api", params, label);
+        return (data.features ?? []).map(toMatch);
+    };
+    return {
+        id: "photon",
+        capabilities: PHOTON_CAPABILITIES,
+        attribution: provenance.attribution,
+        usagePolicyUrl: provenance.usagePolicyUrl,
+        async geocode(query, geocodeOptions) {
+            assertGeocodingCapability({ id: "photon", capabilities: PHOTON_CAPABILITIES }, "geocode", policy);
+            return search(query, geocodeOptions?.limit, "photon geocode");
+        },
+        async reverse(latitude, longitude) {
+            assertGeocodingCapability({ id: "photon", capabilities: PHOTON_CAPABILITIES }, "reverse", policy);
+            const params = new URLSearchParams({ lat: String(latitude), lon: String(longitude) });
+            const data = await request("/reverse", params, "photon 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: "photon", capabilities: PHOTON_CAPABILITIES }, "suggest", policy);
+            const matches = await search(text, suggestOptions?.limit, "photon suggest");
+            return matches.map((match) => ({ text: match.address, provenance }));
+        },
+    };
+}

package/geometry/convert.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Esri-JSON ↔ GeoJSON conversion for the geometry package.
+ *
+ * These are re-exports of the single canonical converter utility in
+ * `src/core/esri-geojson.ts` (heritage of issue #264) — the geometry package
+ * deliberately does not fork its own Esri conversion logic. `esriToGeoJson` /
+ * `geoJsonToEsri` are the ergonomic aliases used by `@honua/geometry` and the
+ * `geometryEngine` compat shim.
+ *
+ * @module
+ */
+export { esriGeometryToGeoJSON as esriToGeoJson, esriFeatureToGeoJSON as esriFeatureToGeoJson, geoJsonToEsriGeometry as geoJsonToEsri, } from "../core/esri-geojson.js";
+//# sourceMappingURL=convert.d.ts.map

package/geometry/convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../../src/geometry/convert.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,qBAAqB,IAAI,aAAa,EACtC,oBAAoB,IAAI,oBAAoB,EAC5C,qBAAqB,IAAI,aAAa,GACvC,MAAM,yBAAyB,CAAC"}

package/geometry/convert.js

@@ -0,0 +1,12 @@
+/**
+ * Esri-JSON ↔ GeoJSON conversion for the geometry package.
+ *
+ * These are re-exports of the single canonical converter utility in
+ * `src/core/esri-geojson.ts` (heritage of issue #264) — the geometry package
+ * deliberately does not fork its own Esri conversion logic. `esriToGeoJson` /
+ * `geoJsonToEsri` are the ergonomic aliases used by `@honua/geometry` and the
+ * `geometryEngine` compat shim.
+ *
+ * @module
+ */
+export { esriGeometryToGeoJSON as esriToGeoJson, esriFeatureToGeoJSON as esriFeatureToGeoJson, geoJsonToEsriGeometry as geoJsonToEsri, } from "../core/esri-geojson.js";

package/geometry/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@honua/geometry` — curated, tree-shakeable client-side geometry operations
+ * for the Honua SDK.
+ *
+ * This subpath (`@honua/sdk-js/geometry`, split-packaged as `@honua/geometry`)
+ * wraps the individual `@turf/*` packages and `proj4`, typed against the SDK's
+ * own GeoJSON contract. Importing a single op only pulls that op's turf backing
+ * into a consumer bundle; the core SDK never imports this module, so core-only
+ * consumers never pay for turf/proj4.
+ *
+ * @module
+ */
+export { area, bbox, booleanContains, booleanIntersects, booleanWithin, buffer, centroid, convex, difference, intersect, length, nearestPoint, simplify, union, } from "./ops.js";
+export { defineProjection, normalizeCrs, project, toWebMercator, toWgs84 } from "./project.js";
+export { esriFeatureToGeoJson, esriToGeoJson, geoJsonToEsri } from "./convert.js";
+export type { GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, GeoJsonLineString, GeoJsonMultiLineString, GeoJsonMultiPoint, GeoJsonMultiPolygon, GeoJsonPoint, GeoJsonPolygon, GeometryInput, LinearUnit, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/geometry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/geometry/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,IAAI,EACJ,IAAI,EACJ,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,MAAM,EACN,QAAQ,EACR,MAAM,EACN,UAAU,EACV,SAAS,EACT,MAAM,EACN,YAAY,EACZ,QAAQ,EACR,KAAK,GACN,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE/F,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElF,YAAY,EACV,cAAc,EACd,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,cAAc,EACd,aAAa,EACb,UAAU,GACX,MAAM,YAAY,CAAC"}

package/geometry/index.js

@@ -0,0 +1,15 @@
+/**
+ * `@honua/geometry` — curated, tree-shakeable client-side geometry operations
+ * for the Honua SDK.
+ *
+ * This subpath (`@honua/sdk-js/geometry`, split-packaged as `@honua/geometry`)
+ * wraps the individual `@turf/*` packages and `proj4`, typed against the SDK's
+ * own GeoJSON contract. Importing a single op only pulls that op's turf backing
+ * into a consumer bundle; the core SDK never imports this module, so core-only
+ * consumers never pay for turf/proj4.
+ *
+ * @module
+ */
+export { area, bbox, booleanContains, booleanIntersects, booleanWithin, buffer, centroid, convex, difference, intersect, length, nearestPoint, simplify, union, } from "./ops.js";
+export { defineProjection, normalizeCrs, project, toWebMercator, toWgs84 } from "./project.js";
+export { esriFeatureToGeoJson, esriToGeoJson, geoJsonToEsri } from "./convert.js";

package/geometry/internal.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Internal bridge between the SDK's GeoJSON contract types and the `geojson`
+ * declarations that the `@turf/*` packages are typed against. The two are
+ * structurally identical for the primitive geometry types the geometry package
+ * supports, so the conversions are erased casts — kept in one place so the ops
+ * modules stay free of scattered `as unknown as` noise.
+ *
+ * @internal
+ * @module
+ */
+import type { Feature as TurfFeature, FeatureCollection as TurfFeatureCollection, Geometry as TurfGeometry } from "geojson";
+import type { GeoJsonFeature } from "../core/types.js";
+import type { GeoJsonGeometry } from "../expr/expression.js";
+import type { GeometryInput } from "./types.js";
+/** Narrow an input to its bare geometry, unwrapping a `Feature` if needed. */
+export declare function inputToGeometry(input: GeometryInput): GeoJsonGeometry;
+/** Present an SDK geometry to turf as a `geojson` geometry. */
+export declare function toTurfGeometry(geometry: GeoJsonGeometry): TurfGeometry;
+/** Present an SDK geometry input to turf as a `geojson` value. */
+export declare function toTurfInput(input: GeometryInput): TurfFeature | TurfFeatureCollection | TurfGeometry;
+/** Convert a turf geometry back into an SDK geometry. */
+export declare function fromTurfGeometry(geometry: TurfGeometry): GeoJsonGeometry;
+/** Convert a turf feature back into an SDK feature. */
+export declare function fromTurfFeature(feature: TurfFeature): GeoJsonFeature;
+//# sourceMappingURL=internal.d.ts.map

package/geometry/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../../src/geometry/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,OAAO,IAAI,WAAW,EACtB,iBAAiB,IAAI,qBAAqB,EAC1C,QAAQ,IAAI,YAAY,EACzB,MAAM,SAAS,CAAC;AAEjB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,eAAe,CAYrE;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,YAAY,CAEtE;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,WAAW,GAAG,qBAAqB,GAAG,YAAY,CAEpG;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,eAAe,CAExE;AAED,uDAAuD;AACvD,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,CAEpE"}