stitchkit 0.21.0 → 0.22.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,
@@ -618,6 +619,7 @@ async function* parseSSE(response, options) {
   }
 }
 export {
+  zodIssues,
   webSocketLane,
   weakETag,
   verifyPkce,

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

@@ -2293,7 +2293,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 +2398,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 +3190,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) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.21.0",
+  "version": "0.22.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",