@mailwoman/api-kit 9.0.0 → 9.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @mailwoman/api-kit
 
-Plumbing for [Mailwoman](https://mailwoman.sister.software)'s HTTP surfaces — a node `serve` wrapper and
+Plumbing for [Mailwoman](https://mailwoman.ai)'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)).
 

package/error.ts

@@ -29,6 +29,21 @@ export const APIErrorSchema = z
  * 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) {
+export function errorResponse<S extends ContentfulStatusCode>(c: Context, status: S, error: string, detail?: string) {
 	return c.json(detail === undefined ? { error } : { error, detail }, status)
 }
+
+const GEOCODER_UNAVAILABLE_DETAIL =
+	"install @mailwoman/neural + @mailwoman/resolver-wof-sqlite and provide gazetteer data (MAILWOMAN_WOF_DB / MAILWOMAN_CANDIDATE_DB)"
+
+/**
+ * The "engine method absent" 503, for the engine method the route actually needed.
+ *
+ * `subject` is a WIRE VALUE, not a label. `<subject> not available` is published verbatim in the HTTP API reference
+ * table and in the docker deploy guide, so a caller branching on it is doing what the docs told them to — and
+ * `/v1/resolve` answers `resolver`, not `geocoder`, because the method it found missing is `engine.resolveTree`. Rename
+ * this function freely; never the string it emits.
+ */
+export function geocoderUnavailableError(c: Context, subject: "geocoder" | "resolver" = "geocoder") {
+	return errorResponse(c, 503, `${subject} not available`, GEOCODER_UNAVAILABLE_DETAIL)
+}

package/openapi.ts

@@ -13,6 +13,8 @@ import { dirname } from "node:path"
 
 import type { OpenAPIHono } from "@hono/zod-openapi"
 
+type OpenAPISecurityRequirements = Parameters<OpenAPIHono["getOpenAPI31Document"]>[0]["security"]
+
 /**
  * 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
@@ -32,7 +34,7 @@ export interface OpenAPIDocInfo {
 		variables?: Record<string, { default: string; description?: string }>
 	}>
 	tags?: Array<{ name: string; description?: string }>
-	security?: unknown[]
+	security?: OpenAPISecurityRequirements
 }
 
 /**
@@ -54,18 +56,28 @@ function toDocumentConfig(info: OpenAPIDocInfo) {
  * 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)
+	const config: Parameters<OpenAPIHono["doc31"]>[1] = { openapi: "3.1.0", ...toDocumentConfig(info) }
+
+	app.doc31(path, config)
 }
 
 /**
  * Emit both document flavors programmatically (build artifacts, parity tests, client generation).
  */
 export function emitOpenAPIDocuments(app: OpenAPIHono, info: OpenAPIDocInfo): { v31: object; v30: object } {
+	const v31Config: Parameters<OpenAPIHono["getOpenAPI31Document"]>[0] = {
+		openapi: "3.1.0",
+		...toDocumentConfig(info),
+	}
+
+	const v30Config: Parameters<OpenAPIHono["getOpenAPIDocument"]>[0] = {
+		openapi: "3.0.3",
+		...toDocumentConfig(info),
+	}
+
 	return {
-		v31: app.getOpenAPI31Document({ openapi: "3.1.0", ...toDocumentConfig(info) } as never),
-		v30: app.getOpenAPIDocument({ openapi: "3.0.3", ...toDocumentConfig(info) } as never),
+		v31: app.getOpenAPI31Document(v31Config),
+		v30: app.getOpenAPIDocument(v30Config),
 	}
 }
 

package/out/error.d.ts

@@ -24,10 +24,24 @@ export declare const APIErrorSchema: z.ZodObject<{
  * 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<{
+export declare function errorResponse<S extends ContentfulStatusCode>(c: Context, status: S, error: string, detail?: string): Response & import("hono").TypedResponse<{
     error: string;
 } | {
     error: string;
     detail: string;
 }, S, "json">;
+/**
+ * The "engine method absent" 503, for the engine method the route actually needed.
+ *
+ * `subject` is a WIRE VALUE, not a label. `<subject> not available` is published verbatim in the HTTP API reference
+ * table and in the docker deploy guide, so a caller branching on it is doing what the docs told them to — and
+ * `/v1/resolve` answers `resolver`, not `geocoder`, because the method it found missing is `engine.resolveTree`. Rename
+ * this function freely; never the string it emits.
+ */
+export declare function geocoderUnavailableError(c: Context, subject?: "geocoder" | "resolver"): Response & import("hono").TypedResponse<{
+    error: string;
+} | {
+    error: string;
+    detail: string;
+}, 503, "json">;
 //# sourceMappingURL=error.d.ts.map

package/out/error.d.ts.map

@@ -1 +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;;GAEG;AACH,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"}
+{"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;;GAEG;AACH,eAAO,MAAM,cAAc;;;iBAKN,CAAA;AAErB;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,oBAAoB,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;;;;;cAElH;AAKD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,GAAE,UAAU,GAAG,UAAuB;;;;;gBAEjG"}

package/out/error.js

@@ -24,7 +24,19 @@ export const APIErrorSchema = z
  * 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) {
+export function errorResponse(c, status, error, detail) {
     return c.json(detail === undefined ? { error } : { error, detail }, status);
 }
+const GEOCODER_UNAVAILABLE_DETAIL = "install @mailwoman/neural + @mailwoman/resolver-wof-sqlite and provide gazetteer data (MAILWOMAN_WOF_DB / MAILWOMAN_CANDIDATE_DB)";
+/**
+ * The "engine method absent" 503, for the engine method the route actually needed.
+ *
+ * `subject` is a WIRE VALUE, not a label. `<subject> not available` is published verbatim in the HTTP API reference
+ * table and in the docker deploy guide, so a caller branching on it is doing what the docs told them to — and
+ * `/v1/resolve` answers `resolver`, not `geocoder`, because the method it found missing is `engine.resolveTree`. Rename
+ * this function freely; never the string it emits.
+ */
+export function geocoderUnavailableError(c, subject = "geocoder") {
+    return errorResponse(c, 503, `${subject} not available`, GEOCODER_UNAVAILABLE_DETAIL);
+}
 //# sourceMappingURL=error.js.map

package/out/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../error.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAIrC;;GAEG;AACH,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"}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../error.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,mBAAmB,CAAA;AAIrC;;GAEG;AACH,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,aAAa,CAAiC,CAAU,EAAE,MAAS,EAAE,KAAa,EAAE,MAAe;IAClH,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;AAED,MAAM,2BAA2B,GAChC,mIAAmI,CAAA;AAEpI;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,CAAU,EAAE,UAAmC,UAAU;IACjG,OAAO,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,gBAAgB,EAAE,2BAA2B,CAAC,CAAA;AACtF,CAAC"}

package/out/openapi.d.ts

@@ -8,6 +8,7 @@
  *   (progenitor), replacing the old hand-downgrade step.
  */
 import type { OpenAPIHono } from "@hono/zod-openapi";
+type OpenAPISecurityRequirements = Parameters<OpenAPIHono["getOpenAPI31Document"]>[0]["security"];
 /**
  * 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
@@ -42,7 +43,7 @@ export interface OpenAPIDocInfo {
         name: string;
         description?: string;
     }>;
-    security?: unknown[];
+    security?: OpenAPISecurityRequirements;
 }
 /**
  * Mount the OpenAPI 3.1 document endpoint on `app` (default `/openapi.json`).
@@ -83,4 +84,5 @@ export declare function errorContent<S>(description: string, schema: S): {
         };
     };
 };
+export {};
 //# sourceMappingURL=openapi.d.ts.map

package/out/openapi.d.ts.map

@@ -1 +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;AAiBD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,SAAkB,GAAG,IAAI,CAItG;AAED;;GAEG;AACH,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;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;;;;;;;EAK7D"}
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,KAAK,2BAA2B,GAAG,UAAU,CAAC,WAAW,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAA;AAEjG;;;;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,2BAA2B,CAAA;CACtC;AAiBD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,SAAkB,GAAG,IAAI,CAItG;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAezG;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;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;;;;;;;EAK7D"}

package/out/openapi.js

@@ -26,17 +26,24 @@ function toDocumentConfig(info) {
  * 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) });
+    const config = { openapi: "3.1.0", ...toDocumentConfig(info) };
+    app.doc31(path, config);
 }
 /**
  * Emit both document flavors programmatically (build artifacts, parity tests, client generation).
  */
 export function emitOpenAPIDocuments(app, info) {
+    const v31Config = {
+        openapi: "3.1.0",
+        ...toDocumentConfig(info),
+    };
+    const v30Config = {
+        openapi: "3.0.3",
+        ...toDocumentConfig(info),
+    };
     return {
-        v31: app.getOpenAPI31Document({ openapi: "3.1.0", ...toDocumentConfig(info) }),
-        v30: app.getOpenAPIDocument({ openapi: "3.0.3", ...toDocumentConfig(info) }),
+        v31: app.getOpenAPI31Document(v31Config),
+        v30: app.getOpenAPIDocument(v30Config),
     };
 }
 /**

package/out/openapi.js.map

@@ -1 +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;;GAEG;AACH,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;;GAEG;AACH,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;;GAEG;AACH,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;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAI,WAAmB,EAAE,MAAS;IAC7D,OAAO;QACN,WAAW;QACX,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,EAAE;KAC3C,CAAA;AACF,CAAC"}
+{"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;AA4BnC;;GAEG;AACH,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;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAgB,EAAE,IAAoB,EAAE,IAAI,GAAG,eAAe;IAC/F,MAAM,MAAM,GAAwC,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAA;IAEnG,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;AACxB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAgB,EAAE,IAAoB;IAC1E,MAAM,SAAS,GAAuD;QACrE,OAAO,EAAE,OAAO;QAChB,GAAG,gBAAgB,CAAC,IAAI,CAAC;KACzB,CAAA;IAED,MAAM,SAAS,GAAqD;QACnE,OAAO,EAAE,OAAO;QAChB,GAAG,gBAAgB,CAAC,IAAI,CAAC;KACzB,CAAA;IAED,OAAO;QACN,GAAG,EAAE,GAAG,CAAC,oBAAoB,CAAC,SAAS,CAAC;QACxC,GAAG,EAAE,GAAG,CAAC,kBAAkB,CAAC,SAAS,CAAC;KACtC,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;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAI,WAAmB,EAAE,MAAS;IAC7D,OAAO;QACN,WAAW;QACX,OAAO,EAAE,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,EAAE;KAC3C,CAAA;AACF,CAAC"}

package/out/serve.d.ts

@@ -7,14 +7,15 @@
  *   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;
+/**
+ * Options for `serveNode()`. Extracted since Hono doesn't seem to export them.
+ */
+export type ServeNodeOptions = Parameters<typeof serve>[0] & {
     /**
      * Called once the listener is bound — receives the actual port (useful with `port: 0`).
      */
@@ -22,7 +23,7 @@ export interface ServeNodeOptions {
         port: number;
         address: string;
     }) => void;
-}
+};
 export interface ServerHandle {
     close(): Promise<void>;
 }

package/out/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;GAEG;AACH,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;;OAEG;IACH,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;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAWjE"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAEzC;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;AAE5F;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG;IAC5D;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CAC5D,CAAA;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,YAAY,CAWjE"}

package/out/serve.js.map

@@ -1 +1 @@
-{"version":3,"file":"serve.js","sourceRoot":"","sources":["../serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAqBzC;;GAEG;AACH,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"}
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAqBzC;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,OAAyB;IAClD,MAAM,MAAM,GAAG,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE,CACvG,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

@@ -1,12 +1,12 @@
 {
   "name": "@mailwoman/api-kit",
-  "version": "9.0.0",
+  "version": "9.2.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"
+    "directory": "packages/api-kit"
   },
   "files": [
     "out/**/*.js",
@@ -21,7 +21,8 @@
     "!*.test.ts",
     "!*.test.tsx",
     "!**/*.test.ts",
-    "!**/*.test.tsx"
+    "!**/*.test.tsx",
+    "!test/**"
   ],
   "type": "module",
   "exports": {
@@ -29,6 +30,10 @@
     ".": {
       "types": "./out/index.d.ts",
       "default": "./out/index.js"
+    },
+    "./metrics": {
+      "types": "./out/metrics.d.ts",
+      "default": "./out/metrics.js"
     }
   },
   "publishConfig": {
@@ -38,13 +43,17 @@
       ".": {
         "types": "./out/index.d.ts",
         "default": "./out/index.js"
+      },
+      "./metrics": {
+        "types": "./out/metrics.d.ts",
+        "default": "./out/metrics.js"
       }
     }
   },
   "dependencies": {
     "@hono/node-server": "^2.0.12",
     "@hono/zod-openapi": "^1.5.1",
-    "hono": "^4.12.32",
+    "hono": "^4.13.0",
     "zod": "^4.4.3"
   }
 }

package/serve.ts

@@ -15,10 +15,10 @@ import { serve } from "@hono/node-server"
  */
 export type FetchLike = (request: Request, ...args: never[]) => Response | Promise<Response>
 
-export interface ServeNodeOptions {
-	fetch: FetchLike
-	port: number
-	hostname: string
+/**
+ * Options for `serveNode()`. Extracted since Hono doesn't seem to export them.
+ */
+export type ServeNodeOptions = Parameters<typeof serve>[0] & {
 	/**
 	 * Called once the listener is bound — receives the actual port (useful with `port: 0`).
 	 */
@@ -33,7 +33,7 @@ export interface ServerHandle {
  * 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) =>
+	const server = serve({ fetch: options.fetch, port: options.port, hostname: options.hostname }, (info) =>
 		options.onListen?.({ port: info.port, address: info.address })
 	)