stitchkit 0.21.0 → 0.23.0

package/dist/cli.js

@@ -4,9 +4,9 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-xmncnw8z.js";
+} from "./index-x8m8e7dc.js";
 import"./index-0ed3bx43.js";
-import"./index-ng2v2ts4.js";
+import"./index-4gawbm74.js";
 import"./index-c7nyw0yt.js";
 export {
   pollUntilDone,

package/dist/{index-ng2v2ts4.js → index-4gawbm74.js}

@@ -84,17 +84,25 @@ function base64UrlToBytes(segment) {
 }
 // src/internal/errors.ts
 import { z as z2 } from "zod";
+function issuePath(path) {
+  return path.length > 0 ? path.map(String).join(".") : "(root)";
+}
 function formatZodError(error) {
   const issues = error.issues.slice(0, 5);
-  const lines = issues.map((issue) => {
-    const path = issue.path.length > 0 ? issue.path.join(".") : "(root)";
-    return `${path}: ${issue.message}`;
-  });
+  const lines = issues.map((issue) => `${issuePath(issue.path)}: ${issue.message}`);
   const suffix = error.issues.length > 5 ? `
 ...and ${error.issues.length - 5} more issues` : "";
   return lines.join(`
 `) + suffix;
 }
+function zodIssues(error) {
+  return error.issues.map((issue) => ({
+    path: issuePath(issue.path),
+    code: issue.code,
+    message: issue.message
+  }));
+}
+var MAX_DETAIL_ISSUES = 20;
 function errorCode(err) {
   if (AppError.is(err))
     return err.code;
@@ -106,7 +114,9 @@ function normalizeError(err) {
   if (AppError.is(err))
     return err;
   if (err instanceof z2.ZodError) {
-    return new AppError("VALIDATION_ERROR", formatZodError(err), 400);
+    return new AppError("VALIDATION_ERROR", formatZodError(err), 400, {
+      issues: zodIssues(err).slice(0, MAX_DETAIL_ISSUES)
+    });
   }
   console.error("[stitchkit] unhandled error:", err);
   return new AppError("INTERNAL_SERVER_ERROR", "Internal server error", 500);
@@ -128,4 +138,4 @@ function isWithinDir(root, target) {
   return target === root || target === base || target.startsWith(base + sep);
 }
 
-export { AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, bytesToBase64Url, base64UrlToBytes, formatZodError, errorCode, normalizeError, validateHandlerOutput, isWithinDir };
+export { AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, bytesToBase64Url, base64UrlToBytes, formatZodError, zodIssues, errorCode, normalizeError, validateHandlerOutput, isWithinDir };

package/dist/{index-ynnh9x6h.js → index-a9n8m4ec.js}

@@ -3,7 +3,7 @@ import {
   bytesToBase64Url,
   forbidden,
   unauthorized
-} from "./index-ng2v2ts4.js";
+} from "./index-4gawbm74.js";
 import {
   isRecord,
   isUnsafeKey,

package/dist/{index-f5e4efj1.js → index-g8kyab85.js}

@@ -10,7 +10,7 @@ import {
   isWithinDir,
   normalizeError,
   validateHandlerOutput
-} from "./index-ng2v2ts4.js";
+} from "./index-4gawbm74.js";
 import {
   extractIp,
   getClientInfo,

package/dist/{index-xmncnw8z.js → index-x8m8e7dc.js}

@@ -7,7 +7,7 @@ import {
   isWithinDir,
   normalizeError,
   validateHandlerOutput
-} from "./index-ng2v2ts4.js";
+} from "./index-4gawbm74.js";
 import {
   isRecord,
   isUnsafeKey,

package/dist/internal/errors.d.ts

@@ -1,6 +1,22 @@
 import { type ZodType, z } from 'zod';
 import { AppError } from '../contract';
 export declare function formatZodError(error: z.ZodError): string;
+/** One field-level validation issue — the structured sibling of `formatZodError`. */
+export interface ZodIssueSummary {
+    /** Dotted path to the offending field (`(root)` for a top-level issue). */
+    path: string;
+    /** Zod issue code (e.g. `invalid_type`, `too_small`). */
+    code: string;
+    /** Human-readable message for this field. */
+    message: string;
+}
+/**
+ * Project a `ZodError` into structured, wire-safe field issues — path / code /
+ * message only, nothing server-internal. For a machine client that matches on
+ * fields rather than parsing the text `message`. Returns every issue; a caller
+ * that bounds response size slices it (see `normalizeError`).
+ */
+export declare function zodIssues(error: z.ZodError): ZodIssueSummary[];
 /**
  * The stable error code for a thrown value — `AppError.code`, `VALIDATION_ERROR`
  * for a `ZodError`, else `undefined`. Side-effect-free (unlike `normalizeError`,

package/dist/internal/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CASxD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI1D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAYrD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,GACZ;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAO9D"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAOvC,wBAAgB,cAAc,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,MAAM,CAMxD;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,GAAG,eAAe,EAAE,CAM9D;AAKD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI1D;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAgBrD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,OAAO,GACZ;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAO9D"}

package/dist/node.js

@@ -3,7 +3,7 @@ import {
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-f5e4efj1.js";
+} from "./index-g8kyab85.js";
 import"./index-tje0q6gp.js";
 import {
   AppError,
@@ -14,7 +14,7 @@ import {
   notFound,
   rateLimited,
   unauthorized
-} from "./index-ng2v2ts4.js";
+} from "./index-4gawbm74.js";
 import"./index-dzx781tm.js";
 import"./index-khwedj16.js";
 import"./index-c7nyw0yt.js";

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
 export { AppError, appError, badRequest, conflict, forbidden, isStitchErrorCode, notFound, rateLimited, STITCH_ERROR_STATUS, type StitchErrorCode, unauthorized, } from '../contract';
-export { errorCode, formatZodError, normalizeError } from '../internal/errors';
+export { errorCode, formatZodError, normalizeError, type ZodIssueSummary, zodIssues, } from '../internal/errors';
 export { cacheHeaders, createCache } from './cache';
 export { createHandler, createServer } from './create';
 export { createErrorHook, type ErrorHookConfig, type ResolvedError, } from './error-hook';

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,KAAK,SAAS,EACd,cAAc,EACd,KAAK,gBAAgB,EACrB,SAAS,EACT,QAAQ,GACT,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,OAAO,EACP,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,UAAU,EACf,WAAW,EACX,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EACL,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,QAAQ,EACR,cAAc,EACd,SAAS,EACT,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,YAAY,EACjB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,aAAa,GACd,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,aAAa,CAAC;AAIrB,OAAO,EACL,SAAS,EACT,cAAc,EACd,cAAc,EACd,KAAK,eAAe,EACpB,SAAS,GACV,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,KAAK,SAAS,EACd,cAAc,EACd,KAAK,gBAAgB,EACrB,SAAS,EACT,QAAQ,GACT,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,OAAO,EACP,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,UAAU,EACf,WAAW,EACX,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,KAAK,UAAU,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,uBAAuB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,YAAY,GACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,EACL,KAAK,eAAe,EACpB,SAAS,EACT,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,QAAQ,EACR,cAAc,EACd,SAAS,EACT,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,YAAY,EACjB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,aAAa,GACd,MAAM,aAAa,CAAC"}

package/dist/server/index.js

@@ -10,7 +10,7 @@ import {
   socketIoLane,
   staticRoute,
   webSocketLane
-} from "../index-f5e4efj1.js";
+} from "../index-g8kyab85.js";
 import {
   createAuthHook,
   createBearerResolver,
@@ -23,7 +23,7 @@ import {
   signJwt,
   verifyJwt,
   verifyPkce
-} from "../index-ynnh9x6h.js";
+} from "../index-a9n8m4ec.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS,
   corsHeaders,
@@ -46,8 +46,9 @@ import {
   normalizeError,
   notFound,
   rateLimited,
-  unauthorized
-} from "../index-ng2v2ts4.js";
+  unauthorized,
+  zodIssues
+} from "../index-4gawbm74.js";
 import {
   extractIp,
   generateTraceId,
@@ -397,6 +398,8 @@ function generateOpenApiDocument(config) {
     for (const [key, method] of Object.entries(service.methods)) {
       if (method.expose && !method.expose.includes("HTTP"))
         continue;
+      if (config.includeMethod && !config.includeMethod(method))
+        continue;
       const servicePath = joinPath("/", service.prefix, method.path === "/" ? "" : method.path);
       const fullPath = toOpenApiPath(pathPrefix ? joinPath(pathPrefix, servicePath) : servicePath);
       const parameters = [];
@@ -618,6 +621,7 @@ async function* parseSSE(response, options) {
   }
 }
 export {
+  zodIssues,
   webSocketLane,
   weakETag,
   verifyPkce,

package/dist/server/openapi.d.ts

@@ -10,7 +10,7 @@
  * emits — not a divergent code path. Schemas are inlined (valid OpenAPI);
  * `$ref` de-duplication can come later if a spec grows unwieldy.
  */
-import type { RawRoute, ServiceDef } from './types';
+import type { MethodDef, RawRoute, ServiceDef } from './types';
 export interface OpenApiInfo {
     title: string;
     version: string;
@@ -31,6 +31,19 @@ export interface OpenApiConfig {
     }>;
     /** `servers` block for the spec. */
     servers?: OpenApiServer[];
+    /**
+     * Emit only the methods this predicate keeps — a curated public spec instead
+     * of the whole HTTP surface. The predicate decides the policy (the core stays
+     * generic): filter on `method.scope`, `method.meta` (the recommended
+     * declarative allowlist — mark endpoints `meta: { public: true }` and keep
+     * `(m) => m.meta?.public === true`), `method.key`, anything on the method.
+     * Omit to include every HTTP method (the default).
+     *
+     * This controls what the spec **advertises**, not access — a hidden endpoint
+     * is still callable; the auth `scope` gate is the actual guard. Build a
+     * separate filtered document for a public route (see the guide).
+     */
+    includeMethod?: (method: Readonly<MethodDef>) => boolean;
 }
 export interface OpenApiDocument {
     openapi: '3.1.0';
@@ -41,7 +54,9 @@ export interface OpenApiDocument {
 /**
  * Generate an OpenAPI 3.1 document from contract services. Only methods exposed
  * on HTTP are included — a method whose `expose` omits `'HTTP'` (an MCP/agent
- * only tool) is skipped, matching the router's own route-building rule.
+ * only tool) is skipped, matching the router's own route-building rule. Pass
+ * `includeMethod` to emit a curated subset (a public spec) instead of the whole
+ * surface.
  */
 export declare function generateOpenApiDocument(config: OpenApiConfig): OpenApiDocument;
 /**

package/dist/server/openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/server/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpD,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,iFAAiF;IACjF,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAC;IAChE,oCAAoC;IACpC,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChD;AAsED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAgH9E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,QAAQ,CAM9E"}
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/server/openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,CAAC;IAClB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,iFAAiF;IACjF,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC,CAAC;IAChE,oCAAoC;IACpC,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,KAAK,OAAO,CAAC;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChD;AAsED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAuH9E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,GAAG,QAAQ,CAM9E"}

package/dist/tools.js

@@ -2,7 +2,7 @@ import {
   inputIsQuery,
   signJwt,
   verifyPkce
-} from "./index-ynnh9x6h.js";
+} from "./index-a9n8m4ec.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS
 } from "./index-tje0q6gp.js";
@@ -18,14 +18,14 @@ import {
   pollUntil,
   readCapped,
   toolResultFromError
-} from "./index-xmncnw8z.js";
+} from "./index-x8m8e7dc.js";
 import {
   toJsonSchema
 } from "./index-0ed3bx43.js";
 import {
   AppError,
   isWithinDir
-} from "./index-ng2v2ts4.js";
+} from "./index-4gawbm74.js";
 import"./index-khwedj16.js";
 import {
   isRecord,

package/llms-full.txt

@@ -355,7 +355,10 @@ beforeHandle: (ctx, endpoint) => {
 }
 ```
 
-`meta` is **app-private** — it is never serialized into the OpenAPI document.
+`meta` is **app-private** — it is never serialized into the OpenAPI document. It
+can still *drive* generation: `generateOpenApiDocument`'s `includeMethod` reads
+it to curate a public spec (e.g. `meta: { public: true }`), without ever emitting
+`meta` itself — see [Curating the spec](./server.md#curating-the-spec--includemethod).
 
 > **Declare a meta type as a `type`, an inline literal, or with `satisfies` — not
 > an `interface`.** A TS `interface` has no implicit index signature (it can be
@@ -856,6 +859,60 @@ bus.emit('user.created', { id: '1' })
 A typed in-process pub/sub — decouple a handler from the side effects of its
 write without reaching for an external queue.
 
+## OpenAPI
+
+`generateOpenApiDocument` builds an OpenAPI 3.1 document straight from the
+contracts — the contract *is* the spec, no decorators or hand-maintained
+annotations (→ ADR 0018). `openApiRoute` serves it as a raw route:
+
+```ts
+import { generateOpenApiDocument, openApiRoute } from 'stitchkit/server'
+
+const doc = generateOpenApiDocument({
+  info: { title: 'My API', version: '1.0.0' },
+  services: [users, orders],
+})
+createServer({ services: [users, orders], rawRoutes: [openApiRoute('/openapi.json', doc)] })
+```
+
+Only HTTP-exposed methods appear (an MCP/agent-only tool is skipped).
+
+### Curating the spec — `includeMethod`
+
+To publish a **subset** — a public spec that advertises only some methods
+without revealing the rest — pass `includeMethod`. It keeps the core generic:
+*you* decide the policy, filtering on anything the method carries. The
+recommended declarative allowlist marks endpoints with the existing `meta`
+passthrough and keeps those:
+
+```ts
+// contract — declarative, one source of truth
+getBalance: { method: 'GET', path: '/balance', desc: '…', scope: 'account',
+              meta: { public: true }, output: BalanceSchema }
+
+// generation — the app's policy
+const publicDoc = generateOpenApiDocument({
+  info: { title: 'Public API', version: '1.0.0' },
+  services: [account],
+  includeMethod: (m) => m.meta?.public === true,
+})
+```
+
+An excluded method's whole entry — path *and* every schema inlined within it —
+is simply never emitted, so nothing about a hidden endpoint leaks.
+
+> **The filter advertises; it does not authorize.** Hiding a method from the
+> spec does **not** protect it — it is still callable, and the auth `scope` gate
+> is the only thing guarding it. And because `openApiRoute` closes over the
+> document you hand it, the filter only matters if you feed it a filtered one:
+> serve **two** documents — a full internal spec and a filtered public spec on
+> separate routes — never one unfiltered `openApiRoute` on a public path.
+
+```ts
+const internal = openApiRoute('/internal/openapi.json', fullDoc)   // behind auth
+const publicSpec = openApiRoute('/openapi.json', publicDoc)         // curated
+```
+
 
 ==============================================================================
 # Guide: Typed client  (docs/guide/client.md)
@@ -2293,7 +2350,27 @@ transport (HTTP, MCP, agent). → ADR 0032.
 `details` and `hint` are included when present. On HTTP this is the response
 body with the matching status; for an MCP or agent call the same `code` and
 `details` come back as a tool error. A schema-validation failure on the request
-is turned into a `400 VALIDATION_ERROR` automatically.
+is turned into a `400 VALIDATION_ERROR` automatically — and it carries the
+offending fields as structured `details.issues`, so a machine client matches on
+them instead of parsing the text `message`:
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "name: Invalid input\nage: Invalid input",
+    "details": {
+      "issues": [
+        { "path": "name", "code": "invalid_type", "message": "Invalid input" },
+        { "path": "age",  "code": "invalid_type", "message": "Invalid input" }
+      ]
+    }
+  }
+}
+```
+
+Use the exported `zodIssues(error)` to build the same structured list from a
+`ZodError` in your own hook.
 
 ### On the client
 
@@ -2378,10 +2455,14 @@ Codes you threw yourself (not stitchkit's) pass through `codeMap` unchanged; the
 `satisfies Record<StitchErrorCode, …>` keeps the map exhaustive across upgrades.
 
 Invalid input (a `ZodError`) is classified as `VALIDATION_ERROR` 400 before it
-reaches `render` — a client fault is an honest 400, not a 500. If you write a
-**bespoke** `onError` instead of using `createErrorHook`, run the thrown value
-through the exported `normalizeError` to get the same classification (a raw
-`ZodError` reaches your hook untouched, so the framework can inspect it):
+reaches `render` — a client fault is an honest 400, not a 500 — and the
+offending fields arrive as structured `info.details.issues`, so your `render`
+can surface them to a machine client without parsing the message.
+
+If you write a **bespoke** `onError` instead of using `createErrorHook`, run the
+thrown value through the exported `normalizeError` to get the same classification
+(a raw `ZodError` reaches your hook untouched, so the framework can inspect it —
+call `zodIssues(err)` yourself if you want the structured fields):
 
 ```ts
 import { normalizeError } from 'stitchkit/server'
@@ -3166,9 +3247,11 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `ByteRange` | _type_ | an inclusive `{ start, end }` byte range |
 | `respondJson` | function | a raw route's JSON response (`204` for null/undefined) |
 | `errorResponse` | function | any thrown value → the framework error envelope + `x-request-id` |
-| `normalizeError` | function | any thrown value → an `AppError` (`ZodError` → `VALIDATION_ERROR` 400, else generic 500) — the framework's canonical classification, for a bespoke `onError` |
+| `normalizeError` | function | any thrown value → an `AppError` (`ZodError` → `VALIDATION_ERROR` 400 with structured `details.issues`, else generic 500) — the framework's canonical classification, for a bespoke `onError` |
 | `errorCode` | function | the stable error code for a thrown value (side-effect-free — for log attribution) |
 | `formatZodError` | function | a `ZodError` → a readable, field-summarised string |
+| `zodIssues` | function | a `ZodError` → structured `{ path, code, message }[]` — the machine-readable sibling of `formatZodError` |
+| `ZodIssueSummary` | _type_ | one structured validation issue (`{ path, code, message }`) |
 | `parseBody` | function | parse + Zod-validate a JSON body → `data` or `null` (no throw) |
 | `HandlerConfig` | _type_ | config for `createHandler` (runtime-agnostic) |
 | `BunServerConfig` | _type_ | config for `createServer` (Bun) |
@@ -3260,7 +3343,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 |--------|------|---------|
 | `generateOpenApiDocument` | function | an OpenAPI 3.1 document from contract services — [ADR 0018](../decisions/0018-openapi-generation.md) |
 | `openApiRoute` | function | a `RawRoute` that serves the document as JSON |
-| `OpenApiConfig` | _type_ | config for `generateOpenApiDocument` |
+| `OpenApiConfig` | _type_ | config for `generateOpenApiDocument` (incl. `includeMethod` — curate a public subset) — [guide](../guide/server.md#curating-the-spec--includemethod) |
 | `OpenApiDocument` | _type_ | the generated document |
 | `OpenApiInfo` | _type_ | the spec `info` block |
 | `OpenApiServer` | _type_ | a spec `servers` entry |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",