stitchkit 0.7.0 → 0.8.1

package/README.md

@@ -352,10 +352,13 @@ A complete runnable app lives in [`packages/starter`](./packages/starter) — a
 notes CRUD with a contract, a typed client, `react-query-kit` hooks and a
 Socket.IO live-reload.
 
-## Documentation
+## Documentation — two roads
 
-This README is the quick start. The full guide and API reference are in
-[`docs/`](./docs/README.md):
+This README is the quick start. Where you go next depends on what you're doing:
+
+### 📦 Building an app **with** stitchkit
+
+The full guide and API reference, in [`docs/`](./docs/README.md):
 
 - **Guide** — [getting started](./docs/guide/getting-started.md) ·
   [contracts](./docs/guide/contracts.md) ·
@@ -364,16 +367,23 @@ This README is the quick start. The full guide and API reference are in
   [MCP & agents](./docs/guide/mcp-and-agents.md) ·
   [realtime](./docs/guide/realtime.md) ·
   [auth & errors](./docs/guide/auth-and-errors.md) ·
-  [testing & deployment](./docs/guide/testing-and-deployment.md)
+  [testing & deployment](./docs/guide/testing-and-deployment.md) ·
+  [multi-tenant](./docs/guide/multi-tenant.md) ·
+  [upgrading](./docs/guide/upgrading.md)
 - **[API reference](./docs/api/reference.md)** — every export, by entrypoint.
-- **[Roadmap](./ROADMAP.md)** — where stitchkit is going.
-- **[Architecture decisions](./docs/decisions/)** — the *why* behind the design.
+- **Coding agent?** The package ships **`llms.txt`** (a curated index) and
+  **`llms-full.txt`** (the whole guide inlined) — your agent reads them from
+  `node_modules/stitchkit/`. For Claude Code, the repo also provides a
+  [stitchkit skill](./skills/stitchkit) you can drop into `.claude/skills/`.
 
-## Contributing
+### 🔧 Developing stitchkit itself
 
-Issues and PRs are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Released
-changes are in [CHANGELOG.md](./CHANGELOG.md); security issues go through
-[SECURITY.md](./SECURITY.md).
+- **[AGENTS.md](./AGENTS.md)** — the development guide (setup, rules, hooks,
+  local-dev, breaking changes, release flow). One place for human and agent
+  contributors; [CONTRIBUTING.md](./CONTRIBUTING.md) points here.
+- **[Architecture decisions](./docs/decisions/)** — the *why* behind the design.
+- **[Roadmap](./ROADMAP.md)** · **[Changelog](./CHANGELOG.md)** ·
+  **[Backlog](./docs/backlog/)** · security via **[SECURITY.md](./SECURITY.md)**.
 
 ## License
 

package/dist/cli.js

@@ -4,14 +4,10 @@ import {
   emitResult,
   parseCliArgs,
   pollUntilDone
-} from "./index-p8byjw3e.js";
+} from "./index-f39j6twc.js";
 import"./index-0ed3bx43.js";
-import"./index-x3fcszf8.js";
-import"./index-4843j09b.js";
-import"./index-9bk6r5ff.js";
-import"./index-kzfs85xp.js";
-import"./index-809wc1tt.js";
-import"./index-37x76zdn.js";
+import"./index-jgpsd7dy.js";
+import"./index-tm7dqzxc.js";
 export {
   pollUntilDone,
   parseCliArgs,

package/dist/contract/index.d.ts

@@ -1,4 +1,4 @@
 export { ALL_TRANSPORTS, type ContractDef, type ContractMeta, defineContract, type EndpointDef, type EndpointFn, type EndpointToolAnnotations, type EndpointUiMeta, type HandlerContext, type HttpMethod, type RuntimeContext, type ScopedEndpointFn, type ScopedHttpClient, type Transport, type TransportSource, type TypedClient, type TypedHttpClient, } from './define';
 export { AppError, appError, badRequest, conflict, type ErrorEnvelope, forbidden, isStitchErrorCode, notFound, rateLimited, STITCH_ERROR_STATUS, type StitchErrorCode, unauthorized, } from './errors';
-export { type Paginated, paginatedSchema } from './pagination';
+export { decodeCursor, encodeCursor, type Paginated, paginatedSchema, } from './pagination';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,KAAK,aAAa,EAClB,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,KAAK,SAAS,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,KAAK,aAAa,EAClB,SAAS,EACT,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,KAAK,eAAe,EACpB,YAAY,GACb,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,KAAK,SAAS,EACd,eAAe,GAChB,MAAM,cAAc,CAAC"}

package/dist/contract/index.js

@@ -5,15 +5,16 @@ import {
   appError,
   badRequest,
   conflict,
+  decodeCursor,
   defineContract,
+  encodeCursor,
   forbidden,
   isStitchErrorCode,
   notFound,
   paginatedSchema,
   rateLimited,
   unauthorized
-} from "../index-9bk6r5ff.js";
-import"../index-37x76zdn.js";
+} from "../index-eq29zkrx.js";
 export {
   unauthorized,
   rateLimited,
@@ -21,7 +22,9 @@ export {
   notFound,
   isStitchErrorCode,
   forbidden,
+  encodeCursor,
   defineContract,
+  decodeCursor,
   conflict,
   badRequest,
   appError,

package/dist/contract/pagination.d.ts

@@ -16,4 +16,15 @@ export declare function paginatedSchema<T extends ZodType>(itemSchema: T): z.Zod
     items: z.ZodArray<T>;
     nextCursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * Encode a JSON-serializable value (e.g. a keyset `{ v, id }`) into an opaque,
+ * URL-safe cursor string for `nextCursor`.
+ */
+export declare function encodeCursor(value: unknown): string;
+/**
+ * Decode a cursor produced by {@link encodeCursor} and validate it against
+ * `schema`. Returns `null` for a missing, malformed or schema-invalid cursor —
+ * so a garbage cursor in a URL is treated as "no cursor" rather than throwing.
+ */
+export declare function decodeCursor<T>(cursor: string | null | undefined, schema: ZodType<T>): T | null;
 //# sourceMappingURL=pagination.d.ts.map

package/dist/contract/pagination.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/contract/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,CAAC,SAAS,OAAO,EAAE,UAAU,EAAE,CAAC;;;kBAK/D"}
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/contract/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,EAAE,CAAC;IACX,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,CAAC,SAAS,OAAO,EAAE,UAAU,EAAE,CAAC;;;kBAK/D;AA4BD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GACjB,CAAC,GAAG,IAAI,CAQV"}

package/dist/{index-za2p453b.js → index-031q8xmx.js}

@@ -1,7 +1,7 @@
 import {
   getClientInfo,
   resolveSocketIp
-} from "./index-mwmpw6j1.js";
+} from "./index-p9m9c0jw.js";
 
 // src/observability/trace.ts
 var TRACEPARENT_RE = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/i;

package/dist/{index-hty3443r.js → index-9zrq8x5z.js}

@@ -1,14 +1,12 @@
 import {
   forbidden,
   unauthorized
-} from "./index-9bk6r5ff.js";
+} from "./index-jgpsd7dy.js";
 import {
+  isRecord,
   isUnsafeKey,
   safeJsonParse
-} from "./index-kzfs85xp.js";
-import {
-  isRecord
-} from "./index-809wc1tt.js";
+} from "./index-tm7dqzxc.js";
 
 // src/server/middleware/cookies.ts
 function parseCookies(header) {
@@ -216,4 +214,9 @@ async function verifyPkce(verifier, challenge) {
   return derived === challenge;
 }
 
-export { parseCookies, serializeCookie, defineCookie, verifyJwt, signJwt, extractToken, createAuthHook, createBearerResolver, deriveCodeChallenge, verifyPkce };
+// src/internal/http-input.ts
+function inputIsQuery(method) {
+  return method === "GET" || method === "DELETE";
+}
+
+export { parseCookies, serializeCookie, defineCookie, verifyJwt, signJwt, extractToken, createAuthHook, createBearerResolver, deriveCodeChallenge, verifyPkce, inputIsQuery };

package/dist/{index-9bk6r5ff.js → index-eq29zkrx.js}

@@ -97,4 +97,29 @@ function paginatedSchema(itemSchema) {
     nextCursor: z.string().nullable()
   });
 }
-export { ALL_TRANSPORTS, defineContract, AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, paginatedSchema };
+function toBase64Url(str) {
+  const bytes = new TextEncoder().encode(str);
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(value) {
+  const base64 = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+  return new TextDecoder().decode(Uint8Array.from(atob(padded), (c) => c.charCodeAt(0)));
+}
+function encodeCursor(value) {
+  return toBase64Url(JSON.stringify(value));
+}
+function decodeCursor(cursor, schema) {
+  if (!cursor)
+    return null;
+  try {
+    const parsed = schema.safeParse(JSON.parse(fromBase64Url(cursor)));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+export { ALL_TRANSPORTS, defineContract, AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, paginatedSchema, encodeCursor, decodeCursor };

package/dist/{index-p8byjw3e.js → index-f39j6twc.js}

@@ -2,21 +2,17 @@ import {
   jsonSchemaFields,
   toJsonSchema
 } from "./index-0ed3bx43.js";
-import {
-  isWithinDir
-} from "./index-x3fcszf8.js";
 import {
   formatZodError,
+  isWithinDir,
   normalizeError,
   validateHandlerOutput
-} from "./index-4843j09b.js";
+} from "./index-jgpsd7dy.js";
 import {
+  isRecord,
   isUnsafeKey,
   safeJsonParse
-} from "./index-kzfs85xp.js";
-import {
-  isRecord
-} from "./index-809wc1tt.js";
+} from "./index-tm7dqzxc.js";
 
 // src/tools/coerce.ts
 import { z } from "zod";

package/dist/index-jgpsd7dy.js

@@ -0,0 +1,105 @@
+// src/contract/errors.ts
+class AppError extends Error {
+  code;
+  status;
+  details;
+  hint;
+  constructor(code, message, status = 500, details, hint) {
+    super(message ?? code);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.hint = hint;
+    this.name = "AppError";
+  }
+  static is(err) {
+    return err instanceof AppError;
+  }
+  toJSON() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        ...this.details && { details: this.details },
+        ...this.hint && { hint: this.hint }
+      }
+    };
+  }
+}
+function notFound(message = "Not found") {
+  throw new AppError("NOT_FOUND", message, 404);
+}
+function badRequest(message, details) {
+  throw new AppError("BAD_REQUEST", message, 400, details);
+}
+function unauthorized(message = "Unauthorized") {
+  throw new AppError("UNAUTHORIZED", message, 401);
+}
+function forbidden(message = "Forbidden") {
+  throw new AppError("FORBIDDEN", message, 403);
+}
+function conflict(message = "Conflict", details) {
+  throw new AppError("CONFLICT", message, 409, details);
+}
+function rateLimited(message = "Too many requests") {
+  throw new AppError("RATE_LIMITED", message, 429);
+}
+var STITCH_ERROR_STATUS = {
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  METHOD_NOT_ALLOWED: 405,
+  CONFLICT: 409,
+  RATE_LIMITED: 429,
+  VALIDATION_ERROR: 400,
+  INTERNAL_SERVER_ERROR: 500
+};
+function isStitchErrorCode(code) {
+  return code in STITCH_ERROR_STATUS;
+}
+function appError(code, message, details) {
+  throw new AppError(code, message, isStitchErrorCode(code) ? STITCH_ERROR_STATUS[code] : 500, details);
+}
+// src/contract/pagination.ts
+import { z } from "zod";
+// src/internal/errors.ts
+import { z as z2 } from "zod";
+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 suffix = error.issues.length > 5 ? `
+...and ${error.issues.length - 5} more issues` : "";
+  return lines.join(`
+`) + suffix;
+}
+function normalizeError(err) {
+  if (AppError.is(err))
+    return err;
+  if (err instanceof z2.ZodError) {
+    return new AppError("VALIDATION_ERROR", formatZodError(err), 400);
+  }
+  console.error("[stitchkit] unhandled error:", err);
+  return new AppError("INTERNAL_SERVER_ERROR", "Internal server error", 500);
+}
+function validateHandlerOutput(schema, data) {
+  const parsed = schema.safeParse(data);
+  if (parsed.success)
+    return { ok: true, data: parsed.data };
+  return {
+    ok: false,
+    message: `Handler output does not match the contract: ${formatZodError(parsed.error)}`
+  };
+}
+
+// src/internal/within-dir.ts
+import { sep } from "node:path";
+function isWithinDir(root, target) {
+  const base = root.endsWith(sep) ? root.slice(0, -sep.length) : root;
+  return target === root || target === base || target.startsWith(base + sep);
+}
+
+export { AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, formatZodError, normalizeError, validateHandlerOutput, isWithinDir };

package/dist/{index-mwmpw6j1.js → index-p9m9c0jw.js}

@@ -1,9 +1,7 @@
 import {
+  isRecord,
   isUnsafeKey
-} from "./index-kzfs85xp.js";
-import {
-  isRecord
-} from "./index-809wc1tt.js";
+} from "./index-tm7dqzxc.js";
 
 // src/server/request.ts
 function generateTraceId() {

package/dist/{index-8hsj2qm9.js → index-svvpy5bz.js}

@@ -1,31 +1,23 @@
 import {
-  isWithinDir
-} from "./index-x3fcszf8.js";
-import {
+  AppError,
+  badRequest,
+  isWithinDir,
   normalizeError,
   validateHandlerOutput
-} from "./index-4843j09b.js";
-import {
-  AppError,
-  badRequest
-} from "./index-9bk6r5ff.js";
+} from "./index-jgpsd7dy.js";
 import {
   extractIp,
   getClientInfo,
   parseQueryParams,
   resolveSocketIp,
   resolveTraceId
-} from "./index-mwmpw6j1.js";
+} from "./index-p9m9c0jw.js";
 import {
+  __require,
   isUnsafeKey,
-  safeJsonParse
-} from "./index-kzfs85xp.js";
-import {
+  safeJsonParse,
   typedEntries
-} from "./index-809wc1tt.js";
-import {
-  __require
-} from "./index-37x76zdn.js";
+} from "./index-tm7dqzxc.js";
 
 // src/server/multipart.ts
 var DEFAULT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
@@ -266,9 +258,16 @@ function matchRawRoute(rawRoutes, httpMethod, pathname) {
     if (route.method !== "ALL" && route.method !== httpMethod)
       continue;
     if (route.path.endsWith("/*")) {
-      const prefix = route.path.slice(0, -2);
-      if (pathname === prefix || pathname.startsWith(`${prefix}/`)) {
-        return { route, params: {} };
+      const prefixSegs = route.path.slice(0, -2).split("/").filter(Boolean);
+      const pathSegs = pathname.split("/").filter(Boolean);
+      if (pathSegs.length < prefixSegs.length)
+        continue;
+      const params = matchSegments(prefixSegs, pathSegs.slice(0, prefixSegs.length));
+      if (params) {
+        return {
+          route,
+          params: { ...params, "*": pathSegs.slice(prefixSegs.length).join("/") }
+        };
       }
       continue;
     }

package/dist/index-tm7dqzxc.js

@@ -0,0 +1,20 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/internal/safe-json.ts
+function isUnsafeKey(key) {
+  return key === "__proto__";
+}
+function safeJsonParse(text) {
+  return JSON.parse(text, (key, value) => isUnsafeKey(key) ? undefined : value);
+}
+
+// src/internal/typed.ts
+function typedEntries(value) {
+  return Object.entries(value);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export { __require, isUnsafeKey, safeJsonParse, typedEntries, isRecord };