@mailwoman/api 9.1.0 → 9.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @mailwoman/api
 
-The **native [Mailwoman](https://mailwoman.sister.software) HTTP API** — an engine-agnostic `/v1` surface
+The **native [Mailwoman](https://mailwoman.ai) HTTP API** — an engine-agnostic `/v1` surface
 (parse, geocode, batch, resolve, format) plus health, metrics, and an emitted OpenAPI document. Unlike its
 drop-in siblings ([`@mailwoman/nominatim`](../nominatim), [`@mailwoman/photon`](../photon),
 [`@mailwoman/libpostal`](../libpostal)), nothing here mimics a third-party API — this is Mailwoman's own

package/{app.ts → lib/app.ts}

@@ -9,13 +9,24 @@
  */
 
 import { OpenAPIHono } from "@hono/zod-openapi"
-import { apiError, attachOpenAPIDocs, type OpenAPIDocInfo } from "@mailwoman/api-kit"
-import packageJson from "@mailwoman/api/package.json" with { type: "json" }
+import { attachOpenAPIDocs, engineHeaders, errorResponse, type OpenAPIDocInfo } from "@mailwoman/api-kit"
+import { readLocalJSONFile } from "@mailwoman/core/fs/readers"
+import type { EngineStamp } from "@mailwoman/core/license"
+import { resolvePackagePath } from "@mailwoman/core/module/resolvers"
 import { bodyLimit } from "hono/body-limit"
 import { cors } from "hono/cors"
 
-import type { MailwomanAPIEngine } from "./engine.ts"
-import { DEFAULT_BATCH_MAX, registerMailwomanAPIRoutes } from "./routes.ts"
+import type { MailwomanAPIEngine } from "#engine"
+import { DEFAULT_BATCH_MAX, registerMailwomanAPIRoutes } from "#routes"
+import type { GeocodeOutcomeLike } from "#schema"
+
+/**
+ * This package's own manifest, read at load rather than imported as a module: a JSON import makes `tsc` copy the file
+ * into `out/`, where it becomes the package scope for the compiled tree and breaks every `#` import in it.
+ */
+const packageJson = await readLocalJSONFile<{ name: string; version: string; description: string }>(
+	resolvePackagePath("@mailwoman/api", "package.json")
+)
 
 /**
  * 2 MiB — carried from the express server's `express.json({ limit: "2mb" })` (`mailwoman/server/index.ts`).
@@ -43,6 +54,13 @@ export interface MailwomanAPIOptions {
 	 * Max `addresses` rows accepted by `POST /v1/batch`. Default 500 (see `routes.ts`'s `DEFAULT_BATCH_MAX`).
 	 */
 	batchMax?: number
+
+	/**
+	 * The engine stamp to carry on every response: `engine` in each `/v1` body and the `Server` + `Link: rel="license"`
+	 * headers everywhere. Absent when an embedding application builds the app without the `mailwoman` package; the
+	 * `mailwoman serve` command always passes one.
+	 */
+	engine?: EngineStamp
 }
 
 /**
@@ -63,7 +81,7 @@ export const MAILWOMAN_API_DOC_INFO: OpenAPIDocInfo = {
 	version: packageJson.version,
 	description: packageJson.description,
 	license: { name: "AGPL-3.0-only OR LicenseRef-Commercial", identifier: "AGPL-3.0-only" },
-	contact: { name: "Sister Software", url: "https://mailwoman.sister.software" },
+	contact: { name: "Sister Software", url: "https://mailwoman.ai" },
 	servers: [
 		{
 			url: "http://{host}:{port}",
@@ -83,7 +101,10 @@ export const MAILWOMAN_API_DOC_INFO: OpenAPIDocInfo = {
 /**
  * Build the native Mailwoman app around an injected {@link MailwomanAPIEngine}.
  */
-export function createMailwomanAPI(engine: MailwomanAPIEngine, options: MailwomanAPIOptions = {}): OpenAPIHono {
+export function createMailwomanAPI<T extends Partial<GeocodeOutcomeLike> = GeocodeOutcomeLike>(
+	engine: MailwomanAPIEngine<T>,
+	options: MailwomanAPIOptions = {}
+): OpenAPIHono {
 	const app = new OpenAPIHono({
 		// This surface is ours (no vendor contract to preserve): every declared body/query schema is
 		// validator-enforced, and a failure maps through the shared api-kit envelope — never the raw zod
@@ -92,7 +113,7 @@ export function createMailwomanAPI(engine: MailwomanAPIEngine, options: Mailwoma
 		// just `/v1/format`).
 		defaultHook: (result, c) => {
 			if (!result.success) {
-				return apiError(c, 400, "invalid request body", summarizeValidationError(result.error))
+				return errorResponse(c, 400, "invalid request body", summarizeValidationError(result.error))
 			}
 
 			return undefined
@@ -105,6 +126,10 @@ export function createMailwomanAPI(engine: MailwomanAPIEngine, options: Mailwoma
 		app.use(cors({ origin: "*", allowMethods: ["GET", "POST", "OPTIONS"], allowHeaders: ["*"], maxAge: 86_400 }))
 	}
 
+	if (options.engine) {
+		app.use(engineHeaders(options.engine))
+	}
+
 	// Safety net: an engine fault answers the native envelope, never a crash. `detail` carries the raw message —
 	// this surface is ours to design, so (unlike the vendor-constrained drop-in envelopes) we can be helpful.
 	app.onError((error, c) => {
@@ -112,10 +137,10 @@ export function createMailwomanAPI(engine: MailwomanAPIEngine, options: Mailwoma
 		// validator throws before a route's own hook ever sees the body, so it lands here instead of the
 		// per-route 400s in routes.ts. Answer 400, not the 500 net (which stays reserved for engine faults).
 		if (error instanceof Error && error.message.includes("Malformed JSON")) {
-			return apiError(c, 400, "invalid request body", "malformed JSON")
+			return errorResponse(c, 400, "invalid request body", "malformed JSON")
 		}
 
-		return apiError(c, 500, "internal error", error instanceof Error ? error.message : String(error))
+		return errorResponse(c, 500, "internal error", error instanceof Error ? error.message : String(error))
 	})
 
 	// Ahead of the handlers (which buffer the body into memory) so an oversized POST is rejected before that
@@ -124,11 +149,14 @@ export function createMailwomanAPI(engine: MailwomanAPIEngine, options: Mailwoma
 		"/v1/*",
 		bodyLimit({
 			maxSize: options.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES,
-			onError: (c) => apiError(c, 413, "request body too large"),
+			onError: (c) => errorResponse(c, 413, "request body too large"),
 		})
 	)
 
-	registerMailwomanAPIRoutes(app, engine, { batchMax: options.batchMax ?? DEFAULT_BATCH_MAX })
+	registerMailwomanAPIRoutes(app, engine, {
+		batchMax: options.batchMax ?? DEFAULT_BATCH_MAX,
+		engine: options.engine,
+	})
 
 	attachOpenAPIDocs(app, MAILWOMAN_API_DOC_INFO)
 

package/{engine.ts → lib/engine.ts}

@@ -10,6 +10,8 @@
 
 import type { AddressTree } from "@mailwoman/core"
 
+import type { GeocodeOutcomeLike } from "#schema"
+
 /**
  * One parsed component in reading order (a `ComponentTag` + the covered text).
  */
@@ -21,22 +23,22 @@ export interface ParseComponent {
 /**
  * One parse outcome: ordered components + the full decoded tree (the same language `/v1/resolve` speaks).
  */
-export interface ParseOutcome {
+export interface ParsedAddressResult {
 	input: string
 	components: ParseComponent[]
 	tree: AddressTree
 	debug?: string
 }
 
-/**
- * A geocode outcome — the engine returns the geocode-core `GeocodeResult` shape verbatim (passthrough).
- */
-export type GeocodeOutcome = Record<string, unknown>
+export interface BatchResultFailure {
+	input: string
+	error: string
+}
 
 /**
- * A batch row: a GeocodeOutcome, or an `{ input, error }` slot (per-row isolation).
+ * A batch row slot (per-row isolation).
  */
-export type BatchRow = GeocodeOutcome | { input: string; error: string }
+export type BatchResultEntry<T extends Partial<GeocodeOutcomeLike> = GeocodeOutcomeLike> = T | BatchResultFailure
 
 export interface ResolveTreeOutcome {
 	tree: AddressTree
@@ -53,11 +55,21 @@ export type HealthData = Record<string, unknown>
  */
 export type WireInputMode = "fragmented" | "formatted"
 
-export interface MailwomanAPIEngine {
-	parse?(address: string, opts: { debug: boolean; inputMode?: WireInputMode }): Promise<ParseOutcome>
-	geocode?(address: string, opts?: { inputMode?: WireInputMode }): Promise<GeocodeOutcome>
-	batch?(addresses: string[], opts?: { inputMode?: WireInputMode }): Promise<{ results: BatchRow[] }>
+export interface ParseInit {
+	inputMode?: WireInputMode
+	debug?: boolean
+}
+
+export type GeocodeCallback<T extends Partial<GeocodeOutcomeLike> = GeocodeOutcomeLike> = (
+	address: string,
+	opts?: ParseInit
+) => Promise<T>
+
+export interface MailwomanAPIEngine<T extends Partial<GeocodeOutcomeLike> = GeocodeOutcomeLike> {
+	parse?(address: string, opts: ParseInit): Promise<ParsedAddressResult>
+	geocode?: GeocodeCallback<T>
+	batch?(addresses: string[], opts?: ParseInit): Promise<{ results: BatchResultEntry<T>[] }>
 	resolveTree?(tree: AddressTree, opts: Record<string, unknown>): Promise<ResolveTreeOutcome>
 	reload?(): Promise<{ reloaded: boolean; versions: unknown }>
-	health?(): HealthData
+	health?(): Promise<HealthData>
 }

package/{index.ts → lib/index.ts}

@@ -16,7 +16,7 @@
  *   engine contract in `engine.ts`; the zod wire schemas in `schema.ts`.
  */
 
-export * from "./app.ts"
-export * from "./engine.ts"
-export * from "./routes.ts"
-export * from "./schema.ts"
+export * from "#app"
+export * from "#engine"
+export * from "#routes"
+export * from "#schema"

package/{routes.ts → lib/routes.ts}

@@ -20,12 +20,19 @@
  */
 
 import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi"
-import { apiError, metricsSnapshot, recordTimed } from "@mailwoman/api-kit"
+import {
+	geocoderUnavailableError,
+	metricsSnapshot,
+	recordTimed,
+	stampedResponseSchema,
+	withEngineStamp,
+} from "@mailwoman/api-kit"
 import type { AddressTree } from "@mailwoman/core/decoder"
+import type { EngineStamp } from "@mailwoman/core/license"
 import type { ComponentTag } from "@mailwoman/core/types"
 import { canonicalKey, type ComponentDict, formatAddress, type FormatAddressOptions } from "@mailwoman/formatter"
 
-import type { MailwomanAPIEngine } from "./engine.ts"
+import type { MailwomanAPIEngine } from "#engine"
 import {
 	APIErrorSchema,
 	BatchRequestSchema,
@@ -39,26 +46,18 @@ import {
 	ParseRequestSchema,
 	ResolveRequestSchema,
 	ResolveResponseSchema,
-} from "./schema.ts"
+	type GeocodeOutcome,
+} from "#schema"
 
 /**
  * Default `POST /v1/batch` row cap when {@link RegisterMailwomanAPIRoutesOptions.batchMax} is omitted. This is the
  * standalone-engine default, not derived from env — `mailwoman serve` always passes the env-derived value explicitly
- * (`$public.MAILWOMAN_BATCH_MAX`, default 1000; see `core/env/schema.ts`).
+ * (`$public.MAILWOMAN_BATCH_MAX`, default 1000; see `mailwoman/lib/env/schema.ts`).
  */
 export const DEFAULT_BATCH_MAX = 500
 
 const startedAt = Date.now()
 
-/**
- * `detail` text for every 503 "engine method absent" response (`/v1/geocode`, `/v1/batch`, `/v1/resolve`, `/v1/reload`)
- * — the express-era remediation carried forward: a stranger hitting a 503 must see the exact fix, not just "not
- * available". Matches `mailwoman/api-engine.ts`'s `buildPreflightMessage()` boot-time banner in spirit (same two
- * missing pieces — the packages, and the gazetteer data), condensed to one line for a JSON error body.
- */
-const GEOCODER_UNAVAILABLE_DETAIL =
-	"install @mailwoman/neural + @mailwoman/resolver-wof-sqlite and provide gazetteer data (MAILWOMAN_WOF_DB / MAILWOMAN_CANDIDATE_DB)"
-
 /**
  * Options for {@link registerMailwomanAPIRoutes}.
  */
@@ -67,6 +66,11 @@ export interface RegisterMailwomanAPIRoutesOptions {
 	 * Max `addresses` rows accepted by `POST /v1/batch`. Default {@link DEFAULT_BATCH_MAX}.
 	 */
 	batchMax?: number
+
+	/**
+	 * The engine stamp attached as `engine` to every `/v1` success body. Absent: no field is added.
+	 */
+	engine?: EngineStamp
 }
 
 const errorContent = (description: string) => ({
@@ -86,7 +90,7 @@ const parseQueryParams = z.object({
 const parseResponses = {
 	200: {
 		description: "The tokenized input span + ranked solutions.",
-		content: { "application/json": { schema: ParseOutcomeSchema } },
+		content: { "application/json": { schema: stampedResponseSchema(ParseOutcomeSchema) } },
 	},
 	400: errorContent("`address` is required."),
 	501: errorContent("The backing engine method is not wired for this deployment."),
@@ -95,7 +99,7 @@ const parseResponses = {
 const geocodeResponses = {
 	200: {
 		description: "One geocode result (parse → resolve cascade), passed through from the engine verbatim.",
-		content: { "application/json": { schema: GeocodeOutcomeSchema } },
+		content: { "application/json": { schema: stampedResponseSchema(GeocodeOutcomeSchema) } },
 	},
 	400: errorContent("`address` is required."),
 	503: errorContent("The geocoding engine is not wired for this deployment (dependencies missing)."),
@@ -104,7 +108,7 @@ const geocodeResponses = {
 const batchResponses = {
 	200: {
 		description: "One result per input address, in input order (per-row error isolation).",
-		content: { "application/json": { schema: BatchResponseSchema } },
+		content: { "application/json": { schema: stampedResponseSchema(BatchResponseSchema) } },
 	},
 	400: errorContent("Body must be `{ addresses: string[] }`."),
 	413: errorContent("`addresses.length` exceeds the configured batch cap."),
@@ -114,7 +118,7 @@ const batchResponses = {
 const resolveResponses = {
 	200: {
 		description: "The same tree, decorated in place with gazetteer coordinates + attribution.",
-		content: { "application/json": { schema: ResolveResponseSchema } },
+		content: { "application/json": { schema: stampedResponseSchema(ResolveResponseSchema) } },
 	},
 	400: errorContent("Body must be `{ tree: AddressTree, opts? }`."),
 	503: errorContent("The resolver is not wired for this deployment (dependencies missing)."),
@@ -122,7 +126,7 @@ const resolveResponses = {
 
 const reloadResponses = {
 	200: {
-		description: "Versioned data switchover result — the new per-shard version map.",
+		description: "Versioned data switchover result — the new per-extract version map.",
 		content: {
 			"application/json": { schema: z.looseObject({ reloaded: z.boolean(), versions: z.unknown() }) },
 		},
@@ -133,7 +137,7 @@ const reloadResponses = {
 const formatResponses = {
 	200: {
 		description: "The rendered address string + the deterministic canonical match key.",
-		content: { "application/json": { schema: FormatResponseSchema } },
+		content: { "application/json": { schema: stampedResponseSchema(FormatResponseSchema) } },
 	},
 	400: errorContent("Invalid request body."),
 }
@@ -206,7 +210,7 @@ const reloadRoute = createRoute({
 	method: "post",
 	path: "/v1/reload",
 	operationId: "reload",
-	summary: "Reload versioned data shards (deploy-only; gate at ingress)",
+	summary: "Reload versioned data extracts (deploy-only; check at ingress)",
 	tags: ["meta"],
 	responses: reloadResponses,
 })
@@ -261,15 +265,17 @@ function toComponentDict(components: Record<string, string | string[]>): Compone
 /**
  * Register the native `/v1` routes + `/health` + `/metrics` against an injected engine.
  */
-export function registerMailwomanAPIRoutes(
+export function registerMailwomanAPIRoutes<T extends Partial<GeocodeOutcome> = GeocodeOutcome>(
 	app: OpenAPIHono,
-	engine: MailwomanAPIEngine,
+	engine: MailwomanAPIEngine<T>,
 	options: RegisterMailwomanAPIRoutesOptions = {}
 ): void {
 	const batchMax = options.batchMax ?? DEFAULT_BATCH_MAX
+	const stamp = options.engine
 
 	app.openapi(parseGetRoute, async (c) => {
 		if (!engine.parse) return c.json({ error: "parse not implemented" }, 501)
+
 		const address = c.req.query("address")?.trim()
 
 		if (!address) return c.json({ error: "address is required" }, 400)
@@ -278,20 +284,26 @@ export function registerMailwomanAPIRoutes(
 		const inputMode = inputModeRaw === "fragmented" || inputModeRaw === "formatted" ? inputModeRaw : undefined
 		const outcome = await engine.parse(address, { debug, inputMode })
 
-		return c.json(outcome, 200)
+		return c.json(withEngineStamp(outcome, stamp), 200)
 	})
 
 	app.openapi(
 		parsePostRoute,
 		async (c) => {
-			if (!engine.parse) return c.json({ error: "parse not implemented" }, 501)
+			if (!engine.parse) {
+				return c.json({ error: "parse not implemented" }, 501)
+			}
+
 			const { address, debug, input_mode } = c.req.valid("json")
 			const trimmed = address.trim()
 
-			if (!trimmed) return c.json({ error: "address is required" }, 400)
+			if (!trimmed) {
+				return c.json({ error: "address is required" }, 400)
+			}
+
 			const outcome = await engine.parse(trimmed, { debug: debug ?? false, inputMode: input_mode })
 
-			return c.json(outcome, 200)
+			return c.json(withEngineStamp(outcome, stamp), 200)
 		},
 		(result, c) => {
 			if (!result.success) return c.json({ error: "address is required" }, 400)
@@ -303,29 +315,33 @@ export function registerMailwomanAPIRoutes(
 	app.openapi(
 		geocodeRoute,
 		async (c) => {
-			if (!engine.geocode) return apiError(c, 503, "geocoder not available", GEOCODER_UNAVAILABLE_DETAIL)
+			if (!engine.geocode) {
+				return geocoderUnavailableError(c)
+			}
+
 			const { address, input_mode } = c.req.valid("json")
 			const trimmed = address.trim()
 
 			if (!trimmed) return c.json({ error: "address is required" }, 400)
 			const t0 = performance.now()
 
-			try {
-				const outcome = await engine.geocode(trimmed, { inputMode: input_mode })
-				recordTimed(performance.now() - t0, String(outcome["resolution_tier"] ?? "admin"))
-
-				// `GeocodeOutcome` (the engine contract) is a deliberate `Record<string, unknown>` passthrough —
-				// `GeocodeOutcomeSchema` is now a REAL typed shape (doc-accuracy only, per its own docstring), so a
-				// local cast at this wire boundary is needed, matching the established idiom below (`/v1/resolve`'s
-				// `tree as unknown as AddressTree`) for "documented wire shape looser than the domain type".
-				return c.json(outcome as unknown as z.infer<typeof GeocodeOutcomeSchema>, 200)
-			} catch (error) {
-				recordTimed(performance.now() - t0, "error")
-				throw error
-			}
+			return engine
+				.geocode(trimmed, { inputMode: input_mode })
+				.then((outcome) => {
+					recordTimed(performance.now() - t0, String(outcome.resolution_tier ?? "admin"))
+
+					return c.json(withEngineStamp(outcome as GeocodeOutcome, stamp), 200)
+				})
+				.catch((error) => {
+					recordTimed(performance.now() - t0, "error")
+
+					throw error
+				})
 		},
 		(result, c) => {
-			if (!result.success) return c.json({ error: "address is required" }, 400)
+			if (!result.success) {
+				return c.json({ error: "address is required" }, 400)
+			}
 
 			return undefined
 		}
@@ -336,13 +352,15 @@ export function registerMailwomanAPIRoutes(
 		async (c) => {
 			const { addresses, input_mode } = c.req.valid("json")
 
-			if (!addresses.length) return c.json({ results: [] }, 200)
+			if (!addresses.length) return c.json(withEngineStamp({ results: [] }, stamp), 200)
 
 			if (addresses.length > batchMax) {
 				return c.json({ error: `batch too large: ${addresses.length} > ${batchMax}` }, 413)
 			}
 
-			if (!engine.batch) return apiError(c, 503, "geocoder not available", GEOCODER_UNAVAILABLE_DETAIL)
+			if (!engine.batch) {
+				return geocoderUnavailableError(c)
+			}
 
 			// Whole-call latency, recorded under the "batch" tier. Per-row tier metrics are the ENGINE's
 			// responsibility (phase 4b) — this app only times the call as a unit.
@@ -356,7 +374,7 @@ export function registerMailwomanAPIRoutes(
 				// Same wire-vs-domain cast as `/v1/geocode` above — `BatchRow`'s `GeocodeOutcome` half is a
 				// `Record<string, unknown>` passthrough; `BatchResponseSchema` now types its `GeocodeOutcome` union
 				// member as the real shape.
-				return c.json(outcome as unknown as z.infer<typeof BatchResponseSchema>, 200)
+				return c.json(withEngineStamp(outcome as z.infer<typeof BatchResponseSchema>, stamp), 200)
 			} catch (error) {
 				recordTimed(performance.now() - t0, "error")
 				throw error
@@ -375,14 +393,17 @@ export function registerMailwomanAPIRoutes(
 		// street node's stamped resolution tier per call — the wired engine must carry that over, and
 		// must trim batch rows the same way (the route passes raw input through).
 		async (c) => {
-			if (!engine.resolveTree) return apiError(c, 503, "resolver not available", GEOCODER_UNAVAILABLE_DETAIL)
+			// `resolver`, not `geocoder` — the missing method is `engine.resolveTree`, and the 503's `error`
+			// value is what a caller branches on.
+			if (!engine.resolveTree) {
+				return geocoderUnavailableError(c, "resolver")
+			}
+
 			const { tree, opts } = c.req.valid("json")
-			// The wire schema keeps `tree` loose (`{ roots: unknown[] }`, forward-compat) — a local cast at the
-			// boundary onto the engine's `AddressTree` contract, matching the established idiom (api-kit's
-			// `openapi.ts`, the drop-ins' response casts) for "documented wire shape looser than the domain type".
-			const outcome = await engine.resolveTree(tree as unknown as AddressTree, opts ?? {})
 
-			return c.json(outcome, 200)
+			const outcome = await engine.resolveTree(tree as AddressTree, opts ?? {})
+
+			return c.json(withEngineStamp(outcome, stamp), 200)
 		},
 		(result, c) => {
 			if (!result.success) return c.json({ error: "body must be { tree: AddressTree, opts? }" }, 400)
@@ -392,7 +413,10 @@ export function registerMailwomanAPIRoutes(
 	)
 
 	app.openapi(reloadRoute, async (c) => {
-		if (!engine.reload) return apiError(c, 503, "geocoder not available", GEOCODER_UNAVAILABLE_DETAIL)
+		if (!engine.reload) {
+			return geocoderUnavailableError(c)
+		}
+
 		const outcome = await engine.reload()
 
 		return c.json(outcome, 200)
@@ -403,13 +427,13 @@ export function registerMailwomanAPIRoutes(
 		const dict = toComponentDict(components)
 		const formatted = formatAddress(dict, country, formatOptions as FormatAddressOptions | undefined)
 
-		return c.json({ formatted, canonicalKey: canonicalKey(dict) }, 200)
+		return c.json(withEngineStamp({ formatted, canonicalKey: canonicalKey(dict) }, stamp), 200)
 	})
 
-	app.openapi(healthRoute, (c) => {
+	app.openapi(healthRoute, async (c) => {
 		const uptimeSeconds = Math.round((Date.now() - startedAt) / 1000)
 
-		return c.json({ status: "ok", uptime_s: uptimeSeconds, ...engine.health?.() }, 200)
+		return c.json({ status: "ok", uptime_s: uptimeSeconds, ...(await engine.health?.()) }, 200)
 	})
 
 	app.openapi(metricsRoute, (c) => c.json(metricsSnapshot(), 200))