@mailwoman/libpostal 4.15.1

package/README.md

@@ -0,0 +1,42 @@
+# @mailwoman/libpostal
+
+A **libpostal-compatible** parse/expand HTTP API over [Mailwoman](https://mailwoman.sister.software)'s
+neural address parser. The lowest-dependency drop-in — `/parse` needs no gazetteer, just the model.
+
+```bash
+npx @mailwoman/libpostal serve --port 8081
+```
+
+```bash
+curl -s "http://localhost:8081/parse?query=1600 Pennsylvania Ave NW, Washington DC 20500"
+# [{"label":"house_number","value":"1600"},{"label":"road","value":"Pennsylvania Ave NW"},
+#  {"label":"city","value":"Washington"},{"label":"state","value":"DC"},{"label":"postcode","value":"20500"}]
+```
+
+## Endpoints
+
+| Endpoint  | libpostal contract                                        |
+| --------- | --------------------------------------------------------- |
+| `/parse`  | `parse_address` — ordered `[{label, value}]` components   |
+| `/expand` | `expand_address` — normalized forms (see the honest note) |
+
+`/parse` maps Mailwoman's `ComponentTag` classifications to libpostal's labels (`street`→`road`,
+`locality`→`city`, `region`→`state`, …) via `COMPONENT_TO_LIBPOSTAL`.
+
+**Honest note on `/expand`:** Mailwoman's normalization is deterministic, so `/expand` returns the
+original plus its normalized + abbreviation-expanded forms — not libpostal's probabilistic multi-variant
+expansion. One canonical alternative, not a hypothesis set.
+
+## Library use
+
+```ts
+import express from "express"
+import { createLibpostalRouter, type LibpostalEngine } from "@mailwoman/libpostal"
+
+const engine: LibpostalEngine = {
+	async parse(query) {
+		/* return [{ classification, value }] from your parser */
+	},
+}
+express().use(createLibpostalRouter(engine)).listen(8081)
+```

package/out/cli.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-libpostal` — boot a libpostal-compatible parse/expand endpoint via the `serve`
+ *   command. Usage + examples live in the package README.
+ *
+ *   Wires the real engine: `/parse` over Mailwoman's `createAddressParser` (the neural BIO tagger),
+ *   `/expand` over `@mailwoman/normalize`. `/expand` is honest-minimal: it returns the original
+ *   plus the deterministic normalized + abbreviation-expanded forms, not libpostal's probabilistic
+ *   variants.
+ */
+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;;;;;;;;;;;;GAYG"}

package/out/cli.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-libpostal` — boot a libpostal-compatible parse/expand endpoint via the `serve`
+ *   command. Usage + examples live in the package README.
+ *
+ *   Wires the real engine: `/parse` over Mailwoman's `createAddressParser` (the neural BIO tagger),
+ *   `/expand` over `@mailwoman/normalize`. `/expand` is honest-minimal: it returns the original
+ *   plus the deterministic normalized + abbreviation-expanded forms, not libpostal's probabilistic
+ *   variants.
+ */
+import { expandAbbreviations, normalize } from "@mailwoman/normalize";
+import express from "express";
+import { createAddressParser } from "mailwoman";
+import { parseArgs } from "node:util";
+import { createLibpostalRouter } from "./index.js";
+function serve() {
+    const { values } = parseArgs({
+        options: {
+            port: { type: "string", default: "8081" },
+            host: { type: "string", default: "0.0.0.0" },
+        },
+        allowPositionals: true,
+    });
+    const port = Number(values.port) || 8081;
+    const host = values.host ?? "0.0.0.0";
+    const parser = createAddressParser();
+    const engine = {
+        async parse(query) {
+            const result = await parser.parse(query, { verbose: true });
+            const solution = result.solutions[0];
+            if (!solution)
+                return [];
+            const json = solution.toJSON();
+            return (json.matches ?? []).map((m) => ({ classification: m.classification, value: m.value }));
+        },
+        async expand(address) {
+            const normalized = normalize(address).normalized;
+            const expanded = expandAbbreviations(normalized).text;
+            // Deterministic forms only; dedup while preserving order.
+            return [...new Set([address, normalized, expanded])];
+        },
+    };
+    express()
+        .use(createLibpostalRouter(engine))
+        .listen(port, host, () => {
+        console.error(`[@mailwoman/libpostal] listening on http://${host}:${port}`);
+        console.error(`  endpoints: POST/GET /parse  POST/GET /expand`);
+    });
+}
+const command = process.argv[2];
+switch (command) {
+    case "serve":
+        serve();
+        break;
+    default:
+        console.error("Usage: mailwoman-libpostal serve [--port 8081] [--host 0.0.0.0]");
+        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":";AACA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AACrE,OAAO,OAAO,MAAM,SAAS,CAAA;AAC7B,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAA;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AACrC,OAAO,EAAE,qBAAqB,EAAyC,MAAM,YAAY,CAAA;AAEzF,SAAS,KAAK;IACb,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;QAC5B,OAAO,EAAE;YACR,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE;YACzC,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE;SAC5C;QACD,gBAAgB,EAAE,IAAI;KACtB,CAAC,CAAA;IAEF,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,CAAA;IACxC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,SAAS,CAAA;IAErC,MAAM,MAAM,GAAG,mBAAmB,EAAE,CAAA;IAEpC,MAAM,MAAM,GAAoB;QAC/B,KAAK,CAAC,KAAK,CAAC,KAAK;YAChB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAA;YAC3D,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;YACpC,IAAI,CAAC,QAAQ;gBAAE,OAAO,EAAE,CAAA;YACxB,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,EAAgC,CAAA;YAC5D,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;QAC/F,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,OAAO;YACnB,MAAM,UAAU,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,UAAU,CAAA;YAChD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAC,IAAI,CAAA;YACrD,0DAA0D;YAC1D,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAA;QACrD,CAAC;KACD,CAAA;IAED,OAAO,EAAE;SACP,GAAG,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;SAClC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE;QACxB,OAAO,CAAC,KAAK,CAAC,8CAA8C,IAAI,IAAI,IAAI,EAAE,CAAC,CAAA;QAC3E,OAAO,CAAC,KAAK,CAAC,gDAAgD,CAAC,CAAA;IAChE,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AAE/B,QAAQ,OAAO,EAAE,CAAC;IACjB,KAAK,OAAO;QACX,KAAK,EAAE,CAAA;QACP,MAAK;IACN;QACC,OAAO,CAAC,KAAK,CAAC,iEAAiE,CAAC,CAAA;QAChF,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAC/B,CAAC"}

package/out/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/libpostal` — a libpostal-compatible parse/expand HTTP API over Mailwoman's neural
+ *   address parser. The lowest-dependency drop-in: `/parse` is a serializer over the BIO tagger's
+ *   labeled spans, no gazetteer or resolver needed.
+ *
+ *   Engine-agnostic, like the nominatim/photon packages: {@link createLibpostalRouter} takes a
+ *   {@link LibpostalEngine}; the CLI wires the real parser. The classification → libpostal-label
+ *   mapping lives here (it is libpostal-specific knowledge), so the engine yields raw Mailwoman
+ *   matches.
+ */
+import { Router } from "express";
+/** A libpostal `parse_address` component: a label + the text it covers, in order. */
+export interface LibpostalComponent {
+    label: string;
+    value: string;
+}
+/** A raw Mailwoman match the engine yields (our `ComponentTag` classification + the covered text). */
+export interface ParseMatch {
+    classification: string;
+    value: string;
+}
+/**
+ * Mailwoman `ComponentTag` → libpostal label. libpostal's label set is OSM-derived; ours is close
+ * but not identical, so map the overlap and pass unmapped classifications through unchanged.
+ */
+export declare const COMPONENT_TO_LIBPOSTAL: Record<string, string>;
+/** Map raw Mailwoman matches to libpostal's ordered `[{label, value}]` shape. */
+export declare function toLibpostalComponents(matches: ParseMatch[]): LibpostalComponent[];
+/**
+ * The parsing engine the router delegates to. `parse` is required; `expand` is optional (a missing
+ * one answers `501`). The CLI wires `parse` to Mailwoman's `createAddressParser` and `expand` to
+ * `@mailwoman/normalize`.
+ */
+export interface LibpostalEngine {
+    parse(query: string): Promise<ParseMatch[]>;
+    expand?(address: string): Promise<string[]>;
+}
+/** Build the libpostal-compatible router around an injected {@link LibpostalEngine}. */
+export declare function createLibpostalRouter(engine: LibpostalEngine): Router;
+//# 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;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAuB,MAAM,EAAE,MAAM,SAAS,CAAA;AAErD,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACb;AAED,sGAAsG;AACtG,MAAM,WAAW,UAAU;IAC1B,cAAc,EAAE,MAAM,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAkBzD,CAAA;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,kBAAkB,EAAE,CAEjF;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IAC3C,MAAM,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;CAC3C;AAED,wFAAwF;AACxF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CA4CrE"}

package/out/index.js

@@ -0,0 +1,82 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/libpostal` — a libpostal-compatible parse/expand HTTP API over Mailwoman's neural
+ *   address parser. The lowest-dependency drop-in: `/parse` is a serializer over the BIO tagger's
+ *   labeled spans, no gazetteer or resolver needed.
+ *
+ *   Engine-agnostic, like the nominatim/photon packages: {@link createLibpostalRouter} takes a
+ *   {@link LibpostalEngine}; the CLI wires the real parser. The classification → libpostal-label
+ *   mapping lives here (it is libpostal-specific knowledge), so the engine yields raw Mailwoman
+ *   matches.
+ */
+import { Router } from "express";
+/**
+ * Mailwoman `ComponentTag` → libpostal label. libpostal's label set is OSM-derived; ours is close
+ * but not identical, so map the overlap and pass unmapped classifications through unchanged.
+ */
+export const COMPONENT_TO_LIBPOSTAL = {
+    house_number: "house_number",
+    street: "road",
+    venue: "house",
+    house: "house",
+    unit: "unit",
+    level: "level",
+    po_box: "po_box",
+    postcode: "postcode",
+    locality: "city",
+    dependent_locality: "suburb",
+    neighbourhood: "suburb",
+    borough: "city_district",
+    region: "state",
+    macroregion: "state_district",
+    country: "country",
+    country_region: "country_region",
+    world_region: "world_region",
+};
+/** Map raw Mailwoman matches to libpostal's ordered `[{label, value}]` shape. */
+export function toLibpostalComponents(matches) {
+    return matches.map((m) => ({ label: COMPONENT_TO_LIBPOSTAL[m.classification] ?? m.classification, value: m.value }));
+}
+/** Build the libpostal-compatible router around an injected {@link LibpostalEngine}. */
+export function createLibpostalRouter(engine) {
+    const router = Router();
+    const parse = async (req, res) => {
+        const query = (req.body?.query ?? req.query?.query ?? req.body?.address ?? req.query?.address)?.trim();
+        if (!query) {
+            res.status(400).json({ error: "query is required" });
+            return;
+        }
+        res.json(toLibpostalComponents(await engine.parse(query)));
+    };
+    const expand = async (req, res) => {
+        if (!engine.expand) {
+            res.status(501).json({ error: "expand not implemented" });
+            return;
+        }
+        const address = (req.body?.address ?? req.query?.address)?.trim();
+        if (!address) {
+            res.status(400).json({ error: "address is required" });
+            return;
+        }
+        res.json({ expansions: await engine.expand(address) });
+    };
+    // Safety net: a malformed body or an engine fault returns a clean JSON error, never a crash.
+    const safe = (fn) => async (req, res, next) => {
+        try {
+            await fn(req, res, next);
+        }
+        catch {
+            if (!res.headersSent)
+                res.status(500).json({ error: "internal error" });
+        }
+    };
+    router.post("/parse", safe(parse));
+    router.get("/parse", safe(parse));
+    router.post("/expand", safe(expand));
+    router.get("/expand", safe(expand));
+    return router;
+}
+//# 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,32 @@
+{
+  "name": "@mailwoman/libpostal",
+  "version": "4.15.1",
+  "description": "libpostal drop-in — a libpostal-compatible parse/expand HTTP API over Mailwoman's neural address parser. The lowest-dependency drop-in: parse needs no gazetteer. Run it with `npx @mailwoman/libpostal serve`.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "libpostal"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./out/index.js"
+  },
+  "dependencies": {
+    "@mailwoman/normalize": "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"
+  }
+}