@mailwoman/api-kit 6.0.0

package/README.md

@@ -0,0 +1,29 @@
+# @mailwoman/api-kit
+
+Plumbing for [Mailwoman](https://mailwoman.sister.software)'s HTTP surfaces — a node `serve` wrapper and
+OpenAPI emit helpers shared by the drop-in packages ([`@mailwoman/libpostal`](../libpostal),
+[`@mailwoman/photon`](../photon), [`@mailwoman/nominatim`](../nominatim)).
+
+**Plumbing only.** Domain schemas, routes, and wire contracts live with the package that owns them — this
+package never grows a `ParseRequestSchema` or a `/parse` handler of its own.
+
+```ts
+import { attachOpenAPIDocs, serveNode } from "@mailwoman/api-kit"
+import { OpenAPIHono } from "@hono/zod-openapi"
+
+const app = new OpenAPIHono()
+// ...register routes with app.openapi(...)...
+
+attachOpenAPIDocs(app, { title: "my-api", version: "1.0.0" })
+serveNode({ fetch: app.fetch, port: 8081, hostname: "0.0.0.0" })
+```
+
+`serveNode` is the one place a node HTTP listener gets created — surface packages stay web-standard
+(`fetch`-shaped apps only), so deploying one to an edge runtime needs no changes to it.
+
+## OpenAPI
+
+`attachOpenAPIDocs` mounts a document endpoint (default `/openapi.json`) that's always derived from the
+app's route table — never handwritten. It serves OpenAPI 3.1. Need the 3.0.3 flavor too (client generators
+that lag behind 3.1)? `emitOpenAPIDocuments(app, info)` returns both `{ v31, v30 }` from the same route
+table, for build artifacts or parity tests.

package/out/error.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @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 declare const APIErrorSchema: z.ZodObject<{
+    error: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 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 declare function apiError<S extends ContentfulStatusCode>(c: Context, status: S, error: string, detail?: string): Response & import("hono").TypedResponse<{
+    error: string;
+} | {
+    error: string;
+    detail: string;
+}, S, "json">;
+//# sourceMappingURL=error.d.ts.map

package/out/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../error.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AACrC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAElE,wGAAwG;AACxG,eAAO,MAAM,cAAc;;;iBAKN,CAAA;AAErB;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,oBAAoB,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;;;;;cAE7G"}

package/out/error.js

@@ -0,0 +1,28 @@
+/**
+ * @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";
+/** 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(c, status, error, detail) {
+    return c.json(detail === undefined ? { error } : { error, detail }, status);
+}
+//# sourceMappingURL=error.js.map

package/out/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../error.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAIrC,wGAAwG;AACxG,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC7B,MAAM,CAAC;IACP,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC;KACD,OAAO,CAAC,UAAU,CAAC,CAAA;AAErB;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAiC,CAAU,EAAE,MAAS,EAAE,KAAa,EAAE,MAAe;IAC7G,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,CAAA;AAC5E,CAAC"}

package/out/geo.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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 declare const PointGeometrySchema: z.ZodObject<{
+    type: z.ZodLiteral<"Point">;
+    coordinates: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+}, z.core.$strip>;
+/** A `[minLon, minLat, maxLon, maxLat]`-style 4-tuple (photon's `extent` uses `[minLon, maxLat, maxLon, minLat]`). */
+export declare const BBoxSchema: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+/** GeoJSON Feature envelope over a surface-specific properties schema. */
+export declare function featureSchema<P extends z.ZodTypeAny>(properties: P): z.ZodObject<{
+    type: z.ZodLiteral<"Feature">;
+    geometry: z.ZodObject<{
+        type: z.ZodLiteral<"Point">;
+        coordinates: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    }, z.core.$strip>;
+    properties: P;
+}, z.core.$strip>;
+/** GeoJSON FeatureCollection envelope over a feature schema. */
+export declare function featureCollectionSchema<F extends z.ZodTypeAny>(feature: F): z.ZodObject<{
+    type: z.ZodLiteral<"FeatureCollection">;
+    features: z.ZodArray<F>;
+}, z.core.$strip>;
+//# sourceMappingURL=geo.d.ts.map

package/out/geo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geo.d.ts","sourceRoot":"","sources":["../geo.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAErC,8CAA8C;AAC9C,eAAO,MAAM,mBAAmB;;;iBAKN,CAAA;AAE1B,sHAAsH;AACtH,eAAO,MAAM,UAAU,wEAA4D,CAAA;AAEnF,0EAA0E;AAC1E,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,CAAC;;;;;;;kBAMlE;AAED,gEAAgE;AAChE,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,OAAO,EAAE,CAAC;;;kBAKzE"}

package/out/geo.js

@@ -0,0 +1,35 @@
+/**
+ * @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(properties) {
+    return z.object({
+        type: z.literal("Feature"),
+        geometry: PointGeometrySchema,
+        properties,
+    });
+}
+/** GeoJSON FeatureCollection envelope over a feature schema. */
+export function featureCollectionSchema(feature) {
+    return z.object({
+        type: z.literal("FeatureCollection"),
+        features: z.array(feature),
+    });
+}
+//# sourceMappingURL=geo.js.map

package/out/geo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"geo.js","sourceRoot":"","sources":["../geo.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAErC,8CAA8C;AAC9C,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KAClC,MAAM,CAAC;IACP,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,WAAW,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;CAC9C,CAAC;KACD,OAAO,CAAC,eAAe,CAAC,CAAA;AAE1B,sHAAsH;AACtH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;AAEnF,0EAA0E;AAC1E,MAAM,UAAU,aAAa,CAAyB,UAAa;IAClE,OAAO,CAAC,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;QAC1B,QAAQ,EAAE,mBAAmB;QAC7B,UAAU;KACV,CAAC,CAAA;AACH,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,uBAAuB,CAAyB,OAAU;IACzE,OAAO,CAAC,CAAC,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC;QACpC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;KAC1B,CAAC,CAAA;AACH,CAAC"}

package/out/index.d.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";
+//# 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;;;;;;;;;GASG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/out/index.js

@@ -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.js";
+export * from "./geo.js";
+export * from "./metrics.js";
+export * from "./openapi.js";
+export * from "./serve.js";
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/out/metrics.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @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.
+ */
+/**
+ * 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 declare function recordTimed(latencyMs: number, tier: string): void;
+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 declare function metricsSnapshot(): MetricsSnapshot;
+/** Test-only reset of all counters + the reservoir. */
+export declare function resetMetricsForTest(): void;
+//# sourceMappingURL=metrics.d.ts.map

package/out/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAcH;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAejE;AASD,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE;QACR,KAAK,EAAE,MAAM,CAAA;QACb,MAAM,EAAE,MAAM,CAAA;QACd;;;WAGG;QACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC7B,UAAU,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAA;QACzE,eAAe,EAAE,MAAM,CAAA;KACvB,CAAA;CACD;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,IAAI,eAAe,CAoBjD;AAED,uDAAuD;AACvD,wBAAgB,mBAAmB,IAAI,IAAI,CAU1C"}

package/out/metrics.js

@@ -0,0 +1,80 @@
+/**
+ * @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 = [];
+let writeIdx = 0;
+/** Null-prototype: tier keys are created lazily on first use, not eagerly pre-populated. */
+const tierCounts = 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, tier) {
+    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, p) {
+    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;
+}
+/** Current metrics snapshot — sorted-reservoir percentiles + counters. */
+export function 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() {
+    latencies.length = 0;
+    writeIdx = 0;
+    for (const key of Object.keys(tierCounts)) {
+        delete tierCounts[key];
+    }
+    total = 0;
+    errors = 0;
+}
+//# sourceMappingURL=metrics.js.map

package/out/metrics.js.map

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

package/out/openapi.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @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 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[];
+}
+/** Mount the OpenAPI 3.1 document endpoint on `app` (default `/openapi.json`). */
+export declare function attachOpenAPIDocs(app: OpenAPIHono, info: OpenAPIDocInfo, path?: string): void;
+/** Emit both document flavors programmatically (build artifacts, parity tests, client generation). */
+export declare function emitOpenAPIDocuments(app: OpenAPIHono, info: OpenAPIDocInfo): {
+    v31: object;
+    v30: object;
+};
+/**
+ * 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 declare function printOpenAPIDocument(app: OpenAPIHono, info: OpenAPIDocInfo, opts?: {
+    flavor?: string;
+    out?: string;
+}): void;
+//# sourceMappingURL=openapi.d.ts.map

package/out/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/C,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACzC,YAAY,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;IACpD,OAAO,CAAC,EAAE,KAAK,CAAC;QACf,GAAG,EAAE,MAAM,CAAA;QACX,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KACrE,CAAC,CAAA;IACF,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACpD,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;CACpB;AAeD,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,SAAkB,GAAG,IAAI,CAItG;AAED,sGAAsG;AACtG,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAKzG;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,WAAW,EAChB,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,IAAI,CAUN"}

package/out/openapi.js

@@ -0,0 +1,56 @@
+/**
+ * @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";
+/** Split an `OpenAPIDocInfo` into the document's `info` block and its top-level sibling fields. */
+function toDocumentConfig(info) {
+    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, info, path = "/openapi.json") {
+    // 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) });
+}
+/** Emit both document flavors programmatically (build artifacts, parity tests, client generation). */
+export function emitOpenAPIDocuments(app, info) {
+    return {
+        v31: app.getOpenAPI31Document({ openapi: "3.1.0", ...toDocumentConfig(info) }),
+        v30: app.getOpenAPIDocument({ openapi: "3.0.3", ...toDocumentConfig(info) }),
+    };
+}
+/**
+ * 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, info, opts = {}) {
+    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);
+    }
+}
+//# sourceMappingURL=openapi.js.map

package/out/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AA0BnC,mGAAmG;AACnG,SAAS,gBAAgB,CAAC,IAAoB;IAC7C,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAA;IAE9G,OAAO;QACN,IAAI,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE;QAChE,YAAY;QACZ,OAAO;QACP,IAAI;QACJ,QAAQ;KACR,CAAA;AACF,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,iBAAiB,CAAC,GAAgB,EAAE,IAAoB,EAAE,IAAI,GAAG,eAAe;IAC/F,+FAA+F;IAC/F,+FAA+F;IAC/F,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAW,CAAC,CAAA;AAC1E,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,oBAAoB,CAAC,GAAgB,EAAE,IAAoB;IAC1E,OAAO;QACN,GAAG,EAAE,GAAG,CAAC,oBAAoB,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAW,CAAC;QACvF,GAAG,EAAE,GAAG,CAAC,kBAAkB,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAW,CAAC;KACrF,CAAA;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CACnC,GAAgB,EAChB,IAAoB,EACpB,OAA0C,EAAE;IAE5C,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IAE9D,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACd,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACjD,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,IAAI,CAAC,CAAA;IACrC,CAAC;SAAM,CAAC;QACP,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAClB,CAAC;AACF,CAAC"}

package/out/serve.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @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.
+ */
+/** 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 declare function serveNode(options: ServeNodeOptions): ServerHandle;
+//# sourceMappingURL=serve.d.ts.map

package/out/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,4EAA4E;AAC5E,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;AAE5F,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,SAAS,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CAC5D;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAED,qHAAqH;AACrH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAWjE"}

package/out/serve.js

@@ -0,0 +1,20 @@
+/**
+ * @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";
+/** Boot a node HTTP listener for a Hono app. Returns a handle whose `close()` resolves when the listener is down. */
+export function serveNode(options) {
+    const server = serve({ fetch: options.fetch, port: options.port, hostname: options.hostname }, (info) => options.onListen?.({ port: info.port, address: info.address }));
+    return {
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => (error ? reject(error) : resolve()));
+        }),
+    };
+}
+//# sourceMappingURL=serve.js.map

package/out/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAiBzC,qHAAqH;AACrH,MAAM,UAAU,SAAS,CAAC,OAAyB;IAClD,MAAM,MAAM,GAAG,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAc,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE,CAChH,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAC9D,CAAA;IAED,OAAO;QACN,KAAK,EAAE,GAAG,EAAE,CACX,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;QACrE,CAAC,CAAC;KACH,CAAA;AACF,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@mailwoman/api-kit",
+  "version": "6.0.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": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "api-kit"
+  },
+  "files": [
+    "out/**/*.js",
+    "out/**/*.js.map",
+    "out/**/*.d.ts",
+    "out/**/*.d.ts.map",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./out/index.d.ts",
+      "default": "./out/index.js"
+    }
+  },
+  "publishConfig": {
+    "exports": {
+      "./package.json": "./package.json",
+      ".": {
+        "types": "./out/index.d.ts",
+        "default": "./out/index.js"
+      }
+    },
+    "access": "public"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.0.8",
+    "@hono/zod-openapi": "^1.4.0",
+    "hono": "^4.12.29",
+    "zod": "^4.4.3"
+  }
+}