stitchkit 0.19.0 → 0.21.0

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

@@ -73,13 +73,8 @@ async function parseMultipart(req, fileField, fieldsSchema, maxBytes = DEFAULT_M
       continue;
     if (isUnsafeKey(key))
       continue;
-    if (typeof value === "string") {
-      try {
-        fields[key] = safeJsonParse(value);
-      } catch {
-        fields[key] = value;
-      }
-    }
+    if (typeof value === "string")
+      fields[key] = value;
   }
   return { file, fields: fieldsSchema ? fieldsSchema.parse(fields) : fields };
 }

package/dist/node.js

@@ -3,7 +3,7 @@ import {
   createImplement,
   createSocketIOServer,
   implement
-} from "./index-wpbn133x.js";
+} from "./index-f5e4efj1.js";
 import"./index-tje0q6gp.js";
 import {
   AppError,

package/dist/server/error-hook.d.ts

@@ -9,6 +9,10 @@
  * of leaking stitchkit's code to the wire. The envelope stays app-owned via
  * `render`, so the core prescribes no domain shape (ADR 0002).
  *
+ * The thrown value is classified through the framework's own `normalizeError`
+ * first, so a `ZodError` (invalid input) is an honest `VALIDATION_ERROR` 400 —
+ * not a 500 — exactly as the framework default would render it.
+ *
  * ```ts
  * const onError = createErrorHook({
  *   codeMap: {
@@ -31,7 +35,7 @@ export interface ResolvedError {
     code: string;
     /** HTTP status. */
     status: number;
-    /** Safe message — the `AppError` message, or a generic string for a raw throw. */
+    /** Safe message — the `AppError` / `ZodError` summary, or a generic string for a raw throw. */
     message: string;
     /** Structured details, when the thrown `AppError` carried them. */
     details?: Record<string, unknown>;

package/dist/server/error-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-hook.d.ts","sourceRoot":"","sources":["../../src/server/error-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAA+B,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM;IAChE;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;IAC7C,uDAAuD;IACvD,MAAM,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC;IACzC,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CACzD;AAED,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM,EAC/D,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAoBxC"}
+{"version":3,"file":"error-hook.d.ts","sourceRoot":"","sources":["../../src/server/error-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM;IAChE;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;IAC7C,uDAAuD;IACvD,MAAM,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC;IACzC,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,KAAK,IAAI,CAAC;CACzD;AAED,mEAAmE;AACnE,wBAAgB,eAAe,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM,EAC/D,MAAM,EAAE,eAAe,CAAC,SAAS,CAAC,GACjC,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAyBxC"}

package/dist/server/index.d.ts

@@ -1,4 +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 { 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;AACrB,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,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"}

package/dist/server/index.js

@@ -10,7 +10,7 @@ import {
   socketIoLane,
   staticRoute,
   webSocketLane
-} from "../index-wpbn133x.js";
+} from "../index-f5e4efj1.js";
 import {
   createAuthHook,
   createBearerResolver,
@@ -39,7 +39,9 @@ import {
   appError,
   badRequest,
   conflict,
+  errorCode,
   forbidden,
+  formatZodError,
   isStitchErrorCode,
   normalizeError,
   notFound,
@@ -118,15 +120,14 @@ function cacheHeaders(maxAge, scope = "public") {
 // src/server/error-hook.ts
 function createErrorHook(config) {
   return (_ctx, error) => {
-    const isApp = AppError.is(error);
-    const rawCode = isApp ? error.code : "INTERNAL_SERVER_ERROR";
-    const code = config.codeMap && isStitchErrorCode(rawCode) ? config.codeMap[rawCode] : rawCode;
+    const appErr = normalizeError(error);
+    const code = config.codeMap && isStitchErrorCode(appErr.code) ? config.codeMap[appErr.code] : appErr.code;
     const info = {
       code,
-      status: isApp ? error.status : 500,
-      message: isApp ? error.message : "Internal server error",
-      details: isApp ? error.details : undefined,
-      hint: isApp ? error.hint : undefined
+      status: appErr.status,
+      message: appErr.message,
+      details: appErr.details,
+      hint: appErr.hint
     };
     config.onError?.(error, info);
     return new Response(JSON.stringify(config.render(info)), {
@@ -639,15 +640,18 @@ export {
   parseBody,
   openApiRoute,
   notFound,
+  normalizeError,
   isStitchErrorCode,
   implement,
   getClientInfo,
   generateTraceId,
   generateOpenApiDocument,
+  formatZodError,
   forbidden,
   extractToken,
   extractIp,
   errorResponse2 as errorResponse,
+  errorCode,
   deriveCodeChallenge,
   defineCookie,
   createSocketIOServer,

package/dist/server/multipart.d.ts

@@ -7,9 +7,17 @@ export interface MultipartResult {
 }
 /**
  * Parse a `multipart/form-data` request — extract the file at `fileField` and
- * the remaining fields (each JSON-decoded, then validated by `fieldsSchema`
- * when given). Rejects with a 400 if the file is missing or the upload exceeds
- * `maxBytes` (default 25 MB).
+ * the remaining fields, then validate them with `fieldsSchema` when given.
+ * Rejects with a 400 if the file is missing or the upload exceeds `maxBytes`
+ * (default 25 MB).
+ *
+ * A multipart text field is always a **string** (per the spec) and is handed to
+ * the schema as one — the schema decides its type, exactly as with query params:
+ * `z.coerce.number()` for a number, `z.stringbool()` for a boolean (NOT
+ * `z.coerce.boolean()`, which is `Boolean(str)` — `'false'` would become `true`),
+ * and `z.preprocess((v) => JSON.parse(String(v)), Schema)` to opt a field into JSON.
+ * Content is never sniffed to guess a type — the contract owns the type, not the
+ * value (so an id like `'33111715'` never turns into a number under a `z.string()`).
  */
 export declare function parseMultipart(req: Request, fileField: string, fieldsSchema?: ZodType<unknown>, maxBytes?: number): Promise<MultipartResult>;
 //# sourceMappingURL=multipart.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"multipart.d.ts","sourceRoot":"","sources":["../../src/server/multipart.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAInC,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,IAAI,CAAC;IACX,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;CACjB;AA0CD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,EAC/B,QAAQ,SAA2B,GAClC,OAAO,CAAC,eAAe,CAAC,CA6B1B"}
+{"version":3,"file":"multipart.d.ts","sourceRoot":"","sources":["../../src/server/multipart.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAInC,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,IAAI,CAAC;IACX,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;CACjB;AA0CD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,EAC/B,QAAQ,SAA2B,GAClC,OAAO,CAAC,eAAe,CAAC,CAyB1B"}

package/llms-full.txt

@@ -289,8 +289,9 @@ await api.search({ q: 'x', filter: { status: 'active' } })
 
 Flatten the field (`status: 'active'`) or move the operation to a body verb
 (`POST`). Remember the server parses query values from **strings** — use
-`z.coerce.number()` / `z.coerce.boolean()` in a query-input schema for
-non-string fields.
+`z.coerce.number()` for numbers and `z.stringbool()` for booleans in a
+query-input schema (not `z.coerce.boolean()`, which is `Boolean(str)`, so
+`'false'` would become `true`).
 
 ## Transports
 
@@ -383,6 +384,25 @@ upload: {
 The client sends a `multipart/form-data` request; the field value must be a
 `Blob`. See [HTTP server → multipart](./server.md#multipart).
 
+### Multipart text fields
+
+Any non-file fields sent alongside the file are validated by the endpoint's
+`input` schema. A multipart text field is **always a string** (per the spec) —
+the schema owns its type, exactly as with [query input](#query-input-get--delete):
+
+```ts
+input: z.object({
+  id: z.string(),               // an id like '33111715' stays a string
+  count: z.coerce.number(),     // '5' → 5
+  active: z.stringbool(),       // 'true' → true, 'false' → false
+  meta: z.preprocess((v) => JSON.parse(String(v)), MetaSchema),  // opt a field into JSON
+})
+```
+
+The content is never sniffed to guess a type — a field is a string until the
+schema coerces it. Send a JSON blob as a stringified field and parse it with
+`z.preprocess`; do not rely on the framework to auto-decode it.
+
 ## Pagination
 
 Every list endpoint should return the cursor envelope — one shape, one infinite-
@@ -2357,6 +2377,21 @@ createServer({ services, hooks: { onError } })
 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):
+
+```ts
+import { normalizeError } from 'stitchkit/server'
+
+onError: (ctx, err) => {
+  const e = normalizeError(err)   // ZodError → VALIDATION_ERROR 400, else generic 500
+  return jsonError(e.code, e.status, e.message)
+}
+```
+
 
 ==============================================================================
 # Guide: Observability  (docs/guide/observability.md)
@@ -3131,6 +3166,9 @@ 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` |
+| `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 |
 | `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.19.0",
+  "version": "0.21.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",