@mailwoman/api-kit 7.2.0 → 7.3.0

package/error.ts

@@ -0,0 +1,32 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The native error envelope. Surfaces that carry a vendor-compat contract (photon, nominatim,
+ *   libpostal) keep their own error shapes — this envelope is for surfaces OURS to design (the
+ *   `@mailwoman/api` native `/v1/*` routes), where nothing constrains the wire shape but us.
+ */
+
+import { z } from "@hono/zod-openapi"
+import type { Context } from "hono"
+import type { ContentfulStatusCode } from "hono/utils/http-status"
+
+/** The native error envelope: a short machine-stable `error` string plus an optional human `detail`. */
+export const APIErrorSchema = z
+	.object({
+		error: z.string(),
+		detail: z.string().optional(),
+	})
+	.openapi("APIError")
+
+/**
+ * Respond with the native error envelope. `status` is generic (not the flat `ContentfulStatusCode` union) so the
+ * returned `TypedResponse`'s status stays the CALLER'S literal (e.g. `503`), not the whole union — required for use
+ * inside an `app.openapi(route, handler)` handler body (`@mailwoman/api/routes.ts`), where the framework checks the
+ * handler's return type against that specific route's declared per-status `responses` map. A flat-typed `status` param
+ * would widen every branch to "any content-carrying status", which no single declared response branch matches.
+ */
+export function apiError<S extends ContentfulStatusCode>(c: Context, status: S, error: string, detail?: string) {
+	return c.json(detail === undefined ? { error } : { error, detail }, status)
+}

package/geo.ts

@@ -0,0 +1,39 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   GeoJSON wire atoms shared by the geo-shaped HTTP surfaces (photon, nominatim). Envelope
+ *   builders only — surface-specific property schemas live with their routes, per the anti-meta
+ *   guardrails in the 2026-07-12 design spec.
+ */
+
+import { z } from "@hono/zod-openapi"
+
+/** A GeoJSON Point geometry: `[lon, lat]`. */
+export const PointGeometrySchema = z
+	.object({
+		type: z.literal("Point"),
+		coordinates: z.tuple([z.number(), z.number()]),
+	})
+	.openapi("PointGeometry")
+
+/** A `[minLon, minLat, maxLon, maxLat]`-style 4-tuple (photon's `extent` uses `[minLon, maxLat, maxLon, minLat]`). */
+export const BBoxSchema = z.tuple([z.number(), z.number(), z.number(), z.number()])
+
+/** GeoJSON Feature envelope over a surface-specific properties schema. */
+export function featureSchema<P extends z.ZodTypeAny>(properties: P) {
+	return z.object({
+		type: z.literal("Feature"),
+		geometry: PointGeometrySchema,
+		properties,
+	})
+}
+
+/** GeoJSON FeatureCollection envelope over a feature schema. */
+export function featureCollectionSchema<F extends z.ZodTypeAny>(feature: F) {
+	return z.object({
+		type: z.literal("FeatureCollection"),
+		features: z.array(feature),
+	})
+}

package/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/api-kit` — plumbing for Mailwoman's HTTP surfaces: the node serve wrapper, OpenAPI
+ *   emit helpers, generic timing metrics, and the native error envelope. Plumbing only, by rule:
+ *   domain schemas live next to their routes in the package that owns the wire contract (see the
+ *   2026-07-12 design spec's anti-meta guardrails).
+ */
+
+export * from "./error.ts"
+export * from "./geo.ts"
+export * from "./metrics.ts"
+export * from "./openapi.ts"
+export * from "./serve.ts"

package/metrics.ts

@@ -0,0 +1,104 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Generic in-process timing metrics (ported from `mailwoman/server/metrics.ts`, #485
+ *   observability, for the api-kit plumbing layer — see the 2026-07-12 Phase 4a plan's
+ *   dependency-arrow correction). Dependency-free: monotonic counters per string-keyed tier + a
+ *   bounded reservoir of recent latencies for percentile estimation. Callers own their tier
+ *   vocabulary (e.g. `mailwoman`'s `ResolutionTier`); this module only ever sees `string`.
+ *   Surfaced by `GET /metrics`; reset on process restart (no persistence — scrape it). Per-process
+ *   state: under `node:cluster` each worker reports its own snapshot — aggregate at the scraper.
+ */
+
+/** Recent-latency reservoir size. ~2k samples gives stable p99 without unbounded memory. */
+const MAX_SAMPLES = 2048
+
+const latencies: number[] = []
+let writeIdx = 0
+
+/** Null-prototype: tier keys are created lazily on first use, not eagerly pre-populated. */
+const tierCounts: Record<string, number> = Object.create(null)
+let total = 0
+let errors = 0
+const startedAt = Date.now()
+
+/**
+ * Record one completed timed operation: its wall-clock latency and which tier produced it (or `"error"`). Tier keys are
+ * created on first use; "error" is reserved and counts toward errors instead of a tier.
+ */
+export function recordTimed(latencyMs: number, tier: string): void {
+	total++
+
+	if (tier === "error") {
+		errors++
+	} else {
+		tierCounts[tier] = (tierCounts[tier] ?? 0) + 1
+	}
+
+	if (latencies.length < MAX_SAMPLES) {
+		latencies.push(latencyMs)
+	} else {
+		latencies[writeIdx] = latencyMs
+		writeIdx = (writeIdx + 1) % MAX_SAMPLES
+	}
+}
+
+function percentile(sorted: number[], p: number): number {
+	if (sorted.length === 0) return 0
+	const idx = Math.min(sorted.length - 1, Math.floor(p * sorted.length))
+
+	return Math.round(sorted[idx]! * 100) / 100
+}
+
+export interface MetricsSnapshot {
+	uptime_s: number
+	timings: {
+		total: number
+		errors: number
+		/**
+		 * Per-tier counts. Keys are created lazily on the first `recordTimed` call for that tier — a tier never recorded is
+		 * absent, not zero.
+		 */
+		tiers: Record<string, number>
+		latency_ms: { p50: number; p90: number; p99: number; max: number } | null
+		latency_samples: number
+	}
+}
+
+/** Current metrics snapshot — sorted-reservoir percentiles + counters. */
+export function metricsSnapshot(): MetricsSnapshot {
+	const sorted = [...latencies].sort((a, b) => a - b)
+
+	return {
+		uptime_s: Math.round((Date.now() - startedAt) / 1000),
+		timings: {
+			total,
+			errors,
+			tiers: { ...tierCounts },
+			latency_ms: sorted.length
+				? {
+						p50: percentile(sorted, 0.5),
+						p90: percentile(sorted, 0.9),
+						p99: percentile(sorted, 0.99),
+						max: Math.round(sorted[sorted.length - 1]! * 100) / 100,
+					}
+				: null,
+			latency_samples: sorted.length,
+		},
+	}
+}
+
+/** Test-only reset of all counters + the reservoir. */
+export function resetMetricsForTest(): void {
+	latencies.length = 0
+	writeIdx = 0
+
+	for (const key of Object.keys(tierCounts)) {
+		delete tierCounts[key]
+	}
+
+	total = 0
+	errors = 0
+}

package/openapi.ts

@@ -0,0 +1,89 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   OpenAPI emit helpers. The document is always derived from the route table — never
+ *   handwritten. 3.1 is the published flavor; 3.0 exists solely for client generators that lag
+ *   (progenitor), replacing the old hand-downgrade step.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs"
+import { dirname } from "node:path"
+
+import type { OpenAPIHono } from "@hono/zod-openapi"
+
+/**
+ * The document config stamped into emitted documents: `title`/`version`/`description`/`summary`/`license`/`contact`
+ * land under the document's `info` block; `externalDocs`/`servers`/`tags`/`security` are top-level document fields. All
+ * fields beyond `title`/`version` are optional — existing callers that only pass those two are unaffected.
+ */
+export interface OpenAPIDocInfo {
+	title: string
+	version: string
+	description?: string
+	summary?: string
+	license?: { name: string; identifier?: string }
+	contact?: { name?: string; url?: string }
+	externalDocs?: { description?: string; url: string }
+	servers?: Array<{
+		url: string
+		description?: string
+		variables?: Record<string, { default: string; description?: string }>
+	}>
+	tags?: Array<{ name: string; description?: string }>
+	security?: unknown[]
+}
+
+/** Split an `OpenAPIDocInfo` into the document's `info` block and its top-level sibling fields. */
+function toDocumentConfig(info: OpenAPIDocInfo) {
+	const { title, version, description, summary, license, contact, externalDocs, servers, tags, security } = info
+
+	return {
+		info: { title, version, description, summary, license, contact },
+		externalDocs,
+		servers,
+		tags,
+		security,
+	}
+}
+
+/** Mount the OpenAPI 3.1 document endpoint on `app` (default `/openapi.json`). */
+export function attachOpenAPIDocs(app: OpenAPIHono, info: OpenAPIDocInfo, path = "/openapi.json"): void {
+	// openapi3-ts's InfoObject/OpenAPIObject carry an `x-${string}` extension index signature that
+	// a plain interface can't satisfy — cast at the boundary rather than widening the public type.
+	app.doc31(path, { openapi: "3.1.0", ...toDocumentConfig(info) } as never)
+}
+
+/** Emit both document flavors programmatically (build artifacts, parity tests, client generation). */
+export function emitOpenAPIDocuments(app: OpenAPIHono, info: OpenAPIDocInfo): { v31: object; v30: object } {
+	return {
+		v31: app.getOpenAPI31Document({ openapi: "3.1.0", ...toDocumentConfig(info) } as never),
+		v30: app.getOpenAPIDocument({ openapi: "3.0.3", ...toDocumentConfig(info) } as never),
+	}
+}
+
+/**
+ * The shared body of every surface's `openapi` CLI subcommand (the three drop-ins + `mailwoman openapi`): pick the
+ * flavor `emitOpenAPIDocuments` produces (`--flavor 3.0` → the 3.0.3 diet client generators like progenitor want;
+ * default 3.1.0), then either print it to stdout or write it to `out`. Always compact (single-line) JSON — never
+ * pretty-printed — so the stdout form is a stable `startsWith('{"openapi":"3.1.0"')` smoke check, matching what a live
+ * `/openapi.json` response looks like. `out`'s parent directory is created if missing (the docs build writes into a
+ * gitignored, not-yet-existing `docs/static/openapi/`). One place owns this so the four emitters can't drift out of
+ * lockstep with each other.
+ */
+export function printOpenAPIDocument(
+	app: OpenAPIHono,
+	info: OpenAPIDocInfo,
+	opts: { flavor?: string; out?: string } = {}
+): void {
+	const { v31, v30 } = emitOpenAPIDocuments(app, info)
+	const json = JSON.stringify(opts.flavor === "3.0" ? v30 : v31)
+
+	if (opts.out) {
+		mkdirSync(dirname(opts.out), { recursive: true })
+		writeFileSync(opts.out, `${json}\n`)
+	} else {
+		console.log(json)
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailwoman/api-kit",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "description": "API plumbing for Mailwoman's HTTP surfaces — Hono node serve wrapper, OpenAPI emit helpers, shared wire atoms. Plumbing only: domain schemas live with their routes.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
@@ -13,19 +13,33 @@
     "out/**/*.js.map",
     "out/**/*.d.ts",
     "out/**/*.d.ts.map",
-    "README.md"
+    "README.md",
+    "*.ts",
+    "*.tsx",
+    "**/*.ts",
+    "**/*.tsx",
+    "!*.test.ts",
+    "!*.test.tsx",
+    "!**/*.test.ts",
+    "!**/*.test.tsx"
   ],
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "node": "./index.ts",
-      "default": "./out/index.js",
-      "types": "./out/index.d.ts"
+      "types": "./out/index.d.ts",
+      "default": "./out/index.js"
     }
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "exports": {
+      "./package.json": "./package.json",
+      ".": {
+        "types": "./out/index.d.ts",
+        "default": "./out/index.js"
+      }
+    }
   },
   "dependencies": {
     "@hono/node-server": "^2.0.8",

package/serve.ts

@@ -0,0 +1,40 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Node serve wrapper over `@hono/node-server`. The one place the node listener is created —
+ *   surface packages stay web-standard (they only export `fetch`-shaped apps) so an edge
+ *   deployment needs no changes to them.
+ */
+
+import { serve } from "@hono/node-server"
+
+/** A `fetch`-shaped request handler (what `OpenAPIHono.fetch` provides). */
+export type FetchLike = (request: Request, ...args: never[]) => Response | Promise<Response>
+
+export interface ServeNodeOptions {
+	fetch: FetchLike
+	port: number
+	hostname: string
+	/** Called once the listener is bound — receives the actual port (useful with `port: 0`). */
+	onListen?: (info: { port: number; address: string }) => void
+}
+
+export interface ServerHandle {
+	close(): Promise<void>
+}
+
+/** Boot a node HTTP listener for a Hono app. Returns a handle whose `close()` resolves when the listener is down. */
+export function serveNode(options: ServeNodeOptions): ServerHandle {
+	const server = serve({ fetch: options.fetch as never, port: options.port, hostname: options.hostname }, (info) =>
+		options.onListen?.({ port: info.port, address: info.address })
+	)
+
+	return {
+		close: () =>
+			new Promise<void>((resolve, reject) => {
+				server.close((error?: Error) => (error ? reject(error) : resolve()))
+			}),
+	}
+}