@mailwoman/photon 4.15.1

package/README.md

@@ -0,0 +1,40 @@
+# @mailwoman/photon
+
+A **Photon-compatible autocomplete geocoding API** over the [Mailwoman](https://mailwoman.sister.software) engine — search-as-you-type, returning GeoJSON `FeatureCollection`s. Where [`@mailwoman/nominatim`](../nominatim) is structured lookup, this is the type-ahead front door. No Elasticsearch.
+
+```bash
+npx @mailwoman/photon serve --port 2322 --data <gazetteer-or-bundle>
+```
+
+```bash
+curl "http://localhost:2322/api?q=1600 penn&limit=5&lat=38.9&lon=-77"
+curl "http://localhost:2322/reverse?lat=38.8977&lon=-77.0365"
+```
+
+## Endpoints
+
+| Endpoint   | Photon contract                                    |
+| ---------- | -------------------------------------------------- |
+| `/api`     | forward / autocomplete → GeoJSON FeatureCollection |
+| `/reverse` | `lat`/`lon` → GeoJSON FeatureCollection            |
+
+Backed by Mailwoman's FST autocomplete tier (#190/#587) + parse → resolve.
+
+## Library use
+
+```ts
+import express from "express"
+import { createPhotonRouter, type PhotonEngine } from "@mailwoman/photon"
+
+const engine: PhotonEngine = {
+	/* search, reverse — backed by your Mailwoman pipeline */
+}
+express().use(createPhotonRouter(engine)).listen(2322)
+```
+
+## Status
+
+Shipped. `/api` and `/reverse` resolve over the live engine and return Photon GeoJSON. `/api` runs the
+query through the geocoder today; the dedicated prefix-first FST front (the last bit of Photon's tuned
+type-ahead ordering) is a refinement. Pairs with [`@mailwoman/nominatim`](../nominatim) for the
+structured-lookup shape and the OpenCage-style annotations block.

package/out/cli.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-photon` — boot a Photon-compatible autocomplete endpoint via the `serve` command.
+ *   Usage
+ *
+ *   - Examples live in the package README.
+ *
+ *   Wires the real engine: `/api` over `geocodeAddress` (parse → resolve), `/reverse` over
+ *   `WofReverseGeocoder`, projecting results into Photon's GeoJSON FeatureCollection. The FST
+ *   autocomplete tier is the eventual front for `/api`; geocode resolution is the MVP path.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/out/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG"}

package/out/cli.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-photon` — boot a Photon-compatible autocomplete endpoint via the `serve` command.
+ *   Usage
+ *
+ *   - Examples live in the package README.
+ *
+ *   Wires the real engine: `/api` over `geocodeAddress` (parse → resolve), `/reverse` over
+ *   `WofReverseGeocoder`, projecting results into Photon's GeoJSON FeatureCollection. The FST
+ *   autocomplete tier is the eventual front for `/api`; geocode resolution is the MVP path.
+ */
+import { NeuralAddressClassifier } from "@mailwoman/neural";
+import { createWofResolver } from "@mailwoman/resolver";
+import { geocodeAddress, ShardProvider } from "mailwoman/geocode-core";
+import { createResolverBackend, mailwomanDataRoot, wofShardPaths } from "mailwoman/resolver-backend";
+import { existsSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { createPhotonRouter, photonCollection, photonFeature, } from "./index.js";
+/** WOF placetype → Photon property key. */
+const PLACETYPE_TO_KEY = {
+    street: "street",
+    locality: "city",
+    localadmin: "city",
+    county: "county",
+    region: "state",
+    country: "country",
+};
+/** A real address fits comfortably; longer is malformed input (and would exceed the model's window). */
+const MAX_QUERY_LEN = 512;
+async function serve() {
+    const { values } = parseArgs({
+        options: {
+            port: { type: "string", default: "2322" },
+            host: { type: "string", default: "0.0.0.0" },
+            data: { type: "string" },
+        },
+        allowPositionals: true,
+    });
+    const port = Number(values.port) || 2322;
+    const host = values.host ?? "0.0.0.0";
+    const resolverMod = await import("@mailwoman/resolver-wof-sqlite");
+    const wofPaths = wofShardPaths().filter(existsSync);
+    const adminDbPath = wofPaths[0];
+    const classifier = await NeuralAddressClassifier.loadFromWeights({ locale: "en-US" });
+    const backend = createResolverBackend(resolverMod, { wofPaths });
+    const resolver = createWofResolver(backend);
+    const shards = new ShardProvider(resolverMod, mailwomanDataRoot());
+    const reverseGeo = adminDbPath ? new resolverMod.WofReverseGeocoder({ adminDbPath }) : undefined;
+    const engine = {
+        async search(params) {
+            // Empty/whitespace → no query; absurdly long → not an address (and would blow the model's input).
+            const query = params.q?.trim();
+            if (!query || query.length > MAX_QUERY_LEN)
+                return photonCollection([]);
+            // No country constraint: the default-on #244 placer routes the query's country (Berlin→DE,
+            // Boston→US). Forcing "US" here is a HARD override (geocode-core.ts:102) that resolved every
+            // non-US query to its US namesake — wrong for a global autocomplete front.
+            const result = await geocodeAddress(query, { classifier, resolver, shards: shards.for });
+            if (result.lat == null || result.lon == null)
+                return photonCollection([]);
+            const properties = {
+                name: result.locality ?? result.region ?? undefined,
+                city: result.locality ?? undefined,
+                state: result.region ?? undefined,
+                postcode: result.postcode ?? undefined,
+            };
+            for (const h of result.hierarchy)
+                if (h.tag === "country")
+                    properties.country = h.value;
+            return photonCollection([photonFeature(result.lon, result.lat, properties)]);
+        },
+        async reverse(params) {
+            if (!reverseGeo)
+                return photonCollection([]);
+            const { hierarchy } = await reverseGeo.reverseGeocode(params.lat, params.lon);
+            if (hierarchy.length === 0)
+                return photonCollection([]);
+            const deepest = hierarchy[0];
+            const properties = { name: deepest.name, countrycode: deepest.country?.toLowerCase() };
+            for (const place of hierarchy) {
+                const key = PLACETYPE_TO_KEY[place.placetype];
+                if (key && properties[key] == null)
+                    properties[key] = place.name;
+            }
+            return photonCollection([photonFeature(deepest.lon, deepest.lat, properties)]);
+        },
+    };
+    const express = (await import("express")).default;
+    express()
+        .use(createPhotonRouter(engine))
+        .listen(port, host, () => {
+        console.error(`[@mailwoman/photon] listening on http://${host}:${port}`);
+        console.error(`  wof: ${adminDbPath ?? "(none found — set MAILWOMAN_WOF_DB)"}`);
+        console.error(`  endpoints: GET /api  GET /reverse`);
+    });
+}
+const command = process.argv[2];
+switch (command) {
+    case "serve":
+        await serve();
+        break;
+    default:
+        console.error("Usage: mailwoman-photon serve [--port 2322] [--host 0.0.0.0] [--data <path>]");
+        process.exit(command ? 1 : 0);
+}
+//# sourceMappingURL=cli.js.map

package/out/cli.js.map

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

package/out/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/photon` — a Photon-compatible autocomplete / type-ahead geocoding API over the
+ *   Mailwoman engine. Where `@mailwoman/nominatim` is structured lookup, Photon is
+ *   search-as-you-type: a GeoJSON `FeatureCollection` per query, biased by location, ranked for
+ *   prefixes. It maps onto Mailwoman's shipped FST autocomplete tier (#190/#587) + parse →
+ *   resolve.
+ *
+ *   Like its sibling, the package is engine-agnostic: {@link createPhotonRouter} takes a
+ *   {@link PhotonEngine}; the CLI wires the real engine. Implementation is staged on the epic (#801
+ *   / the Photon child); routes whose engine method is absent answer `501`.
+ */
+import { Router } from "express";
+/**
+ * Photon feature properties — OSM-derived tag names, populated from Mailwoman's `ComponentTag` /
+ * resolved place. `extent` is `[minLon, maxLat, maxLon, minLat]` per Photon's convention.
+ */
+export interface PhotonProperties {
+    osm_id?: number | string;
+    osm_type?: string;
+    osm_key?: string;
+    osm_value?: string;
+    type?: string;
+    name?: string;
+    housenumber?: string;
+    street?: string;
+    postcode?: string;
+    city?: string;
+    district?: string;
+    county?: string;
+    state?: string;
+    country?: string;
+    countrycode?: string;
+    extent?: [number, number, number, number];
+    [key: string]: unknown;
+}
+/** A Photon result feature: a GeoJSON Point with {@link PhotonProperties}. */
+export interface PhotonFeature {
+    type: "Feature";
+    geometry: {
+        type: "Point";
+        coordinates: [number, number];
+    };
+    properties: PhotonProperties;
+}
+/** The Photon response envelope — a GeoJSON FeatureCollection. */
+export interface PhotonFeatureCollection {
+    type: "FeatureCollection";
+    features: PhotonFeature[];
+}
+/** Parsed `/api` (forward / autocomplete) parameters. */
+export interface PhotonSearchParams {
+    q: string;
+    limit: number;
+    lang?: string;
+    /** Location bias. */
+    lat?: number;
+    lon?: number;
+    bbox?: [number, number, number, number];
+    osmTag?: string[];
+    layer?: string[];
+}
+/** Parsed `/reverse` parameters. */
+export interface PhotonReverseParams {
+    lat: number;
+    lon: number;
+    limit: number;
+    lang?: string;
+    radius?: number;
+}
+/**
+ * The engine the router delegates to. Each method is optional; a missing one answers `501`. The
+ * real implementation backs `/api` with the FST autocomplete tier + parse→resolve, and `/reverse`
+ * with the `WofReverseGeocoder`.
+ */
+export interface PhotonEngine {
+    search?(params: PhotonSearchParams): Promise<PhotonFeatureCollection>;
+    reverse?(params: PhotonReverseParams): Promise<PhotonFeatureCollection>;
+}
+/**
+ * Build the Photon-compatible router around an injected {@link PhotonEngine}. Param parsing lives
+ * here; the feature _projection_ (resolved place → {@link PhotonProperties}) is the staged work.
+ */
+export declare function createPhotonRouter(engine: PhotonEngine): Router;
+/** Build a Photon `Feature` from a coordinate + properties. */
+export declare function photonFeature(lon: number, lat: number, properties: PhotonProperties): PhotonFeature;
+/** Wrap features in a Photon `FeatureCollection`. */
+export declare function photonCollection(features: PhotonFeature[]): PhotonFeatureCollection;
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAuB,MAAM,EAAE,MAAM,SAAS,CAAA;AAErD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAChC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IACzC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACtB;AAED,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,SAAS,CAAA;IACf,QAAQ,EAAE;QACT,IAAI,EAAE,OAAO,CAAA;QACb,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAC7B,CAAA;IACD,UAAU,EAAE,gBAAgB,CAAA;CAC5B;AAED,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACvC,IAAI,EAAE,mBAAmB,CAAA;IACzB,QAAQ,EAAE,aAAa,EAAE,CAAA;CACzB;AAED,yDAAyD;AACzD,MAAM,WAAW,kBAAkB;IAClC,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qBAAqB;IACrB,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;IACvC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,oCAAoC;AACpC,MAAM,WAAW,mBAAmB;IACnC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B,MAAM,CAAC,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAA;IACrE,OAAO,CAAC,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAA;CACvE;AAgBD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAmE/D;AAED,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,GAAG,aAAa,CAEnG;AAED,qDAAqD;AACrD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,uBAAuB,CAEnF"}

package/out/index.js

@@ -0,0 +1,103 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/photon` — a Photon-compatible autocomplete / type-ahead geocoding API over the
+ *   Mailwoman engine. Where `@mailwoman/nominatim` is structured lookup, Photon is
+ *   search-as-you-type: a GeoJSON `FeatureCollection` per query, biased by location, ranked for
+ *   prefixes. It maps onto Mailwoman's shipped FST autocomplete tier (#190/#587) + parse →
+ *   resolve.
+ *
+ *   Like its sibling, the package is engine-agnostic: {@link createPhotonRouter} takes a
+ *   {@link PhotonEngine}; the CLI wires the real engine. Implementation is staged on the epic (#801
+ *   / the Photon child); routes whose engine method is absent answer `501`.
+ */
+import { Router } from "express";
+const DEFAULT_LIMIT = 15;
+function asString(raw) {
+    return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+}
+function asStringArray(raw) {
+    if (Array.isArray(raw))
+        return raw.filter((v) => typeof v === "string");
+    const s = asString(raw);
+    return s ? [s] : undefined;
+}
+const EMPTY = { type: "FeatureCollection", features: [] };
+/**
+ * Build the Photon-compatible router around an injected {@link PhotonEngine}. Param parsing lives
+ * here; the feature _projection_ (resolved place → {@link PhotonProperties}) is the staged work.
+ */
+export function createPhotonRouter(engine) {
+    const router = Router();
+    const search = async (req, res) => {
+        if (!engine.search) {
+            res.status(501).json({ ...EMPTY, message: "search not implemented" });
+            return;
+        }
+        const q = req.query;
+        const query = asString(q["q"]);
+        if (!query) {
+            res.status(400).json({ ...EMPTY, message: "q is required" });
+            return;
+        }
+        const params = {
+            q: query,
+            limit: Number(q["limit"] ?? DEFAULT_LIMIT) || DEFAULT_LIMIT,
+            lang: asString(q["lang"]),
+            lat: q["lat"] != null ? Number(q["lat"]) : undefined,
+            lon: q["lon"] != null ? Number(q["lon"]) : undefined,
+            osmTag: asStringArray(q["osm_tag"]),
+            layer: asStringArray(q["layer"]),
+        };
+        res.json(await engine.search(params));
+    };
+    const reverse = async (req, res) => {
+        if (!engine.reverse) {
+            res.status(501).json({ ...EMPTY, message: "reverse not implemented" });
+            return;
+        }
+        const q = req.query;
+        const lat = Number(q["lat"]);
+        const lon = Number(q["lon"]);
+        if (!Number.isFinite(lat) || !Number.isFinite(lon)) {
+            res.status(400).json({ ...EMPTY, message: "lat and lon are required" });
+            return;
+        }
+        if (lat < -90 || lat > 90 || lon < -180 || lon > 180) {
+            res.status(400).json({ ...EMPTY, message: "lat must be in [-90, 90] and lon in [-180, 180]" });
+            return;
+        }
+        const params = {
+            lat,
+            lon,
+            limit: Number(q["limit"] ?? DEFAULT_LIMIT) || DEFAULT_LIMIT,
+            lang: asString(q["lang"]),
+            radius: q["radius"] != null ? Number(q["radius"]) : undefined,
+        };
+        res.json(await engine.reverse(params));
+    };
+    // Safety net: malformed input or an engine fault returns an empty FeatureCollection, never a crash.
+    const safe = (fn) => async (req, res, next) => {
+        try {
+            await fn(req, res, next);
+        }
+        catch {
+            if (!res.headersSent)
+                res.status(500).json({ ...EMPTY, message: "internal error" });
+        }
+    };
+    router.get("/api", safe(search));
+    router.get("/reverse", safe(reverse));
+    return router;
+}
+/** Build a Photon `Feature` from a coordinate + properties. */
+export function photonFeature(lon, lat, properties) {
+    return { type: "Feature", geometry: { type: "Point", coordinates: [lon, lat] }, properties };
+}
+/** Wrap features in a Photon `FeatureCollection`. */
+export function photonCollection(features) {
+    return { type: "FeatureCollection", features };
+}
+//# sourceMappingURL=index.js.map

package/out/index.js.map

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

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mailwoman/photon",
+  "version": "4.15.1",
+  "description": "Photon drop-in — a Photon-compatible autocomplete/type-ahead geocoding API (GeoJSON FeatureCollection over /api + /reverse) on the Mailwoman engine. Run it with `npx @mailwoman/photon serve`.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "photon"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./out/index.js"
+  },
+  "dependencies": {
+    "@mailwoman/neural": "4.15.0",
+    "@mailwoman/resolver": "4.15.0",
+    "@mailwoman/resolver-wof-sqlite": "4.15.0",
+    "express": "^5.2.1",
+    "mailwoman": "4.15.0"
+  },
+  "files": [
+    "out/**/*.js",
+    "out/**/*.js.map",
+    "out/**/*.d.ts",
+    "out/**/*.d.ts.map",
+    "README.md"
+  ],
+  "bin": "./out/cli.js",
+  "publishConfig": {
+    "access": "public"
+  }
+}