stitchkit 0.7.0 → 0.8.1

package/llms.txt

@@ -0,0 +1,23 @@
+# stitchkit
+
+> Contract-first backend framework for Bun and Node. One `defineContract()` becomes an HTTP API, MCP tools, AI-agent tools, a CLI and a fully-typed client — one source of truth, no drift.
+
+Build with stitchkit: define a contract once, then `implement` it and serve it (`createServer` on Bun, `serveNode` on Node ≥ 22). The same contract drives MCP / agent tools and a typed client, so the transports cannot diverge. The pages below are the full guide; `llms-full.txt` (in this package) inlines all of them for offline reading.
+
+## Guide
+- [Getting started](https://github.com/max-listov/stitchkit/blob/master/docs/guide/getting-started.md): install, entrypoints, and a first contract → server → client app
+- [Contracts](https://github.com/max-listov/stitchkit/blob/master/docs/guide/contracts.md): every endpoint field — method, path, params/input/output, scope, expose, meta, multipart
+- [HTTP server](https://github.com/max-listov/stitchkit/blob/master/docs/guide/server.md): createServer/createHandler, implement, lifecycle hooks, raw routes + helpers, scopePrefixes, serveFile, primitives
+- [Typed client](https://github.com/max-listov/stitchkit/blob/master/docs/guide/client.md): createClient/createHttpClient, the typed call surface, scoped clients, SSE
+- [MCP & agents](https://github.com/max-listov/stitchkit/blob/master/docs/guide/mcp-and-agents.md): contracts as MCP tools (createMcpHandler) and AI-agent tools (mountAgent); tool lifecycle, extend, identity
+- [CLI](https://github.com/max-listov/stitchkit/blob/master/docs/guide/cli.md): contracts as a command-line program
+- [Realtime](https://github.com/max-listov/stitchkit/blob/master/docs/guide/realtime.md): Socket.IO server/client wrappers, handshake auth, the cache bridge, a raw WebSocket lane
+- [Auth & errors](https://github.com/max-listov/stitchkit/blob/master/docs/guide/auth-and-errors.md): scopes, createAuthHook, JWT/cookies, the AppError model, the stitch error-code registry
+- [Observability](https://github.com/max-listov/stitchkit/blob/master/docs/guide/observability.md): request and tool-call logging via hooks, W3C trace context, createAuditHook
+- [Testing & deployment](https://github.com/max-listov/stitchkit/blob/master/docs/guide/testing-and-deployment.md): in-process testing; deploying on Bun and on Node (serveNode)
+- [Multi-tenant](https://github.com/max-listov/stitchkit/blob/master/docs/guide/multi-tenant.md): a /tenants/:id/… scenario end-to-end — scopePrefixes, scoped client, extend
+- [Upgrading](https://github.com/max-listov/stitchkit/blob/master/docs/guide/upgrading.md): moving a project across stitchkit versions; how breaking changes are marked
+
+## Reference
+- [API reference](https://github.com/max-listov/stitchkit/blob/master/docs/api/reference.md): every public export, grouped by entrypoint, each linked to the guide
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "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",
@@ -38,6 +38,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "llms.txt",
+    "llms-full.txt",
     "README.md",
     "LICENSE"
   ],
@@ -80,11 +82,13 @@
   },
   "scripts": {
     "check": "bun x tsc --noEmit",
-    "build:js": "bun build src/index.ts src/react.ts src/tools.ts src/cli.ts src/contract/index.ts src/server/index.ts src/observability/index.ts src/node.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:browser": "bun build src/index.ts src/react.ts src/contract/index.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/cli.ts src/observability/index.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:js": "bun run build:browser && bun run build:server",
     "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly",
-    "build": "rm -rf dist && bun run build:js && bun run build:types",
+    "build": "rm -rf dist && bun run build:js && bun run build:types && bun scripts/check-browser-clean.mjs",
     "dev": "bun run build:js -- --watch",
-    "prepublishOnly": "cp ../../README.md ./README.md && bun run build",
+    "prepublishOnly": "cp ../../README.md ./README.md && bun ../../scripts/gen-llms.ts && bun run build",
     "test": "bun test",
     "smoke:node": "node scripts/node-smoke.mjs"
   },

package/dist/index-37x76zdn.js

@@ -1,4 +0,0 @@
-import { createRequire } from "node:module";
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-export { __require };

package/dist/index-4843j09b.js

@@ -1,37 +0,0 @@
-import {
-  AppError
-} from "./index-9bk6r5ff.js";
-
-// src/internal/errors.ts
-import { z } 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 z.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)}`
-  };
-}
-
-export { formatZodError, normalizeError, validateHandlerOutput };

package/dist/index-48ffdxgk.js

@@ -1,6 +0,0 @@
-// src/internal/http-input.ts
-function inputIsQuery(method) {
-  return method === "GET" || method === "DELETE";
-}
-
-export { inputIsQuery };

package/dist/index-809wc1tt.js

@@ -1,18 +0,0 @@
-// src/internal/typed.ts
-function typedEntries(value) {
-  return Object.entries(value);
-}
-function isRecord(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function mapObject(source, mapper) {
-  const result = {};
-  for (const [key, value] of typedEntries(source)) {
-    const mapped = mapper(key, value);
-    if (mapped !== undefined)
-      result[key] = mapped;
-  }
-  return result;
-}
-
-export { typedEntries, isRecord, mapObject };

package/dist/index-kdkvp26v.js

@@ -1,380 +0,0 @@
-import {
-  inputIsQuery
-} from "./index-48ffdxgk.js";
-import {
-  isRecord,
-  mapObject,
-  typedEntries
-} from "./index-809wc1tt.js";
-
-// src/browser/http.ts
-import ky, { isHTTPError } from "ky";
-class ApiError extends Error {
-  code;
-  status;
-  details;
-  hint;
-  constructor(code, status = 0, details, message, hint) {
-    super(message ?? `API Error: ${code}`);
-    this.code = code;
-    this.status = status;
-    this.details = details;
-    this.hint = hint;
-    this.name = "ApiError";
-  }
-  static is(error) {
-    return error instanceof ApiError;
-  }
-}
-function parseApiErrorBody(body) {
-  if (!isRecord(body) || !isRecord(body.error))
-    return null;
-  const error = body.error;
-  if (typeof error.code !== "string")
-    return null;
-  return {
-    code: error.code,
-    message: typeof error.message === "string" ? error.message : undefined,
-    details: error.details,
-    hint: typeof error.hint === "string" ? error.hint : undefined
-  };
-}
-function createHttpClient(config) {
-  let ssrCookies = null;
-  let isLoggedOut = false;
-  const listeners = new Set;
-  const authEndpoints = config.authEndpoints ?? ["/auth/"];
-  const parseError = config.parseError ?? parseApiErrorBody;
-  function emit(event) {
-    for (const fn of listeners) {
-      try {
-        fn(event);
-      } catch {}
-    }
-  }
-  const client = ky.create({
-    prefix: config.baseUrl,
-    credentials: config.credentials ?? "include",
-    timeout: config.timeout ?? 30000,
-    retry: {
-      limit: config.retry?.limit ?? 2,
-      methods: config.retry?.methods ?? ["get"],
-      statusCodes: config.retry?.statusCodes ?? []
-    },
-    hooks: {
-      beforeRequest: [
-        ({ request: request2 }) => {
-          if (ssrCookies) {
-            request2.headers.set("Cookie", ssrCookies);
-          }
-          const extra = typeof config.headers === "function" ? config.headers() : config.headers;
-          if (extra) {
-            for (const [key, value] of Object.entries(extra)) {
-              request2.headers.set(key, value);
-            }
-          }
-        }
-      ],
-      afterResponse: [
-        async ({ request: request2, response }) => {
-          if (response.status === 401) {
-            const url = new URL(request2.url).pathname;
-            if (!isLoggedOut && !authEndpoints.some((path) => url.startsWith(path))) {
-              isLoggedOut = true;
-              emit({ type: "unauthorized" });
-            }
-          }
-          if (!response.ok) {
-            const body = await response.clone().json().catch(() => null);
-            if (body) {
-              const parsed = parseError(body);
-              if (parsed) {
-                throw new ApiError(parsed.code, response.status, parsed.details, parsed.message, parsed.hint);
-              }
-            }
-          }
-        }
-      ]
-    }
-  });
-  async function request(method, url, data, options = {}) {
-    const kyOptions = {
-      timeout: options.timeout
-    };
-    if (options.params) {
-      const searchParams = new URLSearchParams;
-      for (const [key, value] of Object.entries(options.params)) {
-        if (value === undefined)
-          continue;
-        if (Array.isArray(value)) {
-          for (const item of value)
-            searchParams.append(key, String(item));
-        } else {
-          searchParams.set(key, String(value));
-        }
-      }
-      if (searchParams.size > 0) {
-        kyOptions.searchParams = searchParams;
-      }
-    }
-    if (data instanceof FormData) {
-      kyOptions.body = data;
-    } else if (data !== undefined) {
-      kyOptions.json = data;
-    }
-    try {
-      if (options.responseType === "blob") {
-        return client[method](url, kyOptions).blob();
-      }
-      const response = await client[method](url, kyOptions);
-      if (response.status === 204 || response.headers.get("content-length") === "0") {
-        return;
-      }
-      return response.json();
-    } catch (error) {
-      if (ApiError.is(error))
-        throw error;
-      const isAbort = error instanceof Error && error.name === "AbortError";
-      if (!isAbort) {
-        emit({ type: "network_error" });
-      }
-      const status = isAbort ? 0 : isHTTPError(error) ? error.response.status : 0;
-      const msg = error instanceof Error ? error.message : undefined;
-      throw new ApiError("UNKNOWN_ERROR", status, msg ? { message: msg } : undefined);
-    }
-  }
-  return {
-    get: (url, options) => request("get", url, undefined, options),
-    post: (url, data, options) => request("post", url, data, options),
-    put: (url, data, options) => request("put", url, data, options),
-    patch: (url, data, options) => request("patch", url, data, options),
-    delete: (url, options) => request("delete", url, undefined, options),
-    setServerContext(cookies) {
-      ssrCookies = cookies;
-    },
-    subscribe(listener) {
-      listeners.add(listener);
-      return () => listeners.delete(listener);
-    },
-    logout() {
-      isLoggedOut = true;
-      emit({ type: "logout" });
-    },
-    resetLogoutState() {
-      isLoggedOut = false;
-    }
-  };
-}
-
-// src/browser/client.ts
-function withTimeout(options, timeout) {
-  if (timeout === undefined)
-    return options;
-  return { ...options, timeout };
-}
-function isParamArray(value) {
-  return Array.isArray(value) && value.every((v) => typeof v === "string" || typeof v === "number");
-}
-function collectQueryParams(args, skipKeys) {
-  const params = {};
-  let hasParams = false;
-  for (const [key, value] of Object.entries(args)) {
-    if (skipKeys.has(key) || value === undefined || value === null)
-      continue;
-    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || isParamArray(value)) {
-      params[key] = value;
-      hasParams = true;
-    }
-  }
-  return hasParams ? params : undefined;
-}
-function createClient(contract, configOrClient, contractConfig) {
-  const client = {};
-  const makeMethod = isHttpAdapter(configOrClient) ? (endpoint) => createHttpMethod(endpoint, contract.meta.prefix, configOrClient, contractConfig) : (endpoint) => createFetchMethod(endpoint, contract.meta.prefix, configOrClient, contractConfig);
-  for (const [key, endpoint] of typedEntries(contract.endpoints)) {
-    if (endpoint.expose && !endpoint.expose.includes("HTTP"))
-      continue;
-    setClientMethod(client, key, makeMethod(endpoint));
-  }
-  return client;
-}
-function createClients(contracts, http) {
-  return mapObject(contracts, (_key, contract) => createClient(contract, http));
-}
-function isHttpAdapter(value) {
-  return typeof value === "object" && "get" in value && typeof value.get === "function";
-}
-function setClientMethod(target, key, method) {
-  target[key] = method;
-}
-function createHttpMethod(endpoint, prefix, client, config) {
-  const httpMethod = endpoint.method.toLowerCase();
-  const isGet = httpMethod === "get";
-  const paramNames = extractParamNames(endpoint.path);
-  const prefixKeys = new Set([...config?.stripPrefixKeys ?? [], ...paramNames]);
-  return (...args) => {
-    const firstArg = args[0] ?? {};
-    let pathPrefixStr = "";
-    if (config?.pathPrefix) {
-      pathPrefixStr = typeof config.pathPrefix === "function" ? config.pathPrefix(firstArg) : config.pathPrefix;
-      if (pathPrefixStr && !pathPrefixStr.endsWith("/"))
-        pathPrefixStr += "/";
-    }
-    let url = `${pathPrefixStr}${prefix}${endpoint.path}`;
-    for (const name of paramNames) {
-      const value = firstArg[name];
-      if (value === undefined || value === null) {
-        throw new Error(`Missing path param: ${name}`);
-      }
-      url = url.replace(`:${name}`, encodeURIComponent(String(value)));
-    }
-    if (url.endsWith("/"))
-      url = url.slice(0, -1);
-    if (endpoint.multipart) {
-      const file = firstArg[endpoint.multipart];
-      if (!(file instanceof Blob)) {
-        throw new Error(`Missing multipart file field: ${endpoint.multipart}`);
-      }
-      const formData = new FormData;
-      formData.append(endpoint.multipart, file);
-      appendFormFields(formData, firstArg, new Set([...prefixKeys, endpoint.multipart]));
-      return client.post(url, formData, withTimeout(undefined, endpoint.timeout));
-    }
-    if (isGet) {
-      const params = collectQueryParams(firstArg, prefixKeys);
-      return client.get(url, withTimeout(params ? { params } : undefined, endpoint.timeout));
-    }
-    if (httpMethod === "delete") {
-      const params = collectQueryParams(firstArg, prefixKeys);
-      return client.delete(url, withTimeout(params ? { params } : undefined, endpoint.timeout));
-    }
-    const payload = {};
-    for (const [key, value] of Object.entries(firstArg)) {
-      if (!prefixKeys.has(key) && value !== undefined) {
-        payload[key] = value;
-      }
-    }
-    return client[httpMethod](url, Object.keys(payload).length > 0 ? payload : undefined, withTimeout(undefined, endpoint.timeout));
-  };
-}
-function createFetchMethod(endpoint, prefix, config, contractConfig) {
-  const prefixKeys = new Set(contractConfig?.stripPrefixKeys ?? []);
-  return async (args) => {
-    let pathPrefixStr = "";
-    if (contractConfig?.pathPrefix) {
-      pathPrefixStr = typeof contractConfig.pathPrefix === "function" ? contractConfig.pathPrefix(args ?? {}) : contractConfig.pathPrefix;
-      if (pathPrefixStr && !pathPrefixStr.endsWith("/"))
-        pathPrefixStr += "/";
-    }
-    let url = buildFetchUrl(config.baseUrl, prefix, endpoint.path, args, pathPrefixStr);
-    const headers = {
-      Accept: "application/json",
-      ...typeof config.headers === "function" ? config.headers() : config.headers
-    };
-    const isQuery = inputIsQuery(endpoint.method);
-    const hasBody = !isQuery && !endpoint.multipart && endpoint.input && args;
-    if (isQuery && args) {
-      const remaining = stripParams(args, endpoint.path, prefixKeys);
-      const searchParams = new URLSearchParams;
-      for (const [k, v] of Object.entries(remaining)) {
-        if (v === undefined || v === null)
-          continue;
-        if (isParamArray(v)) {
-          for (const item of v)
-            searchParams.append(k, String(item));
-        } else if (typeof v !== "object") {
-          searchParams.set(k, String(v));
-        }
-      }
-      if (searchParams.size > 0)
-        url += `?${searchParams}`;
-    }
-    if (hasBody)
-      headers["Content-Type"] = "application/json";
-    if (endpoint.multipart && args) {
-      const file = args[endpoint.multipart];
-      if (!(file instanceof Blob)) {
-        throw new Error(`Missing multipart file field: ${endpoint.multipart}`);
-      }
-      const formData = new FormData;
-      formData.append(endpoint.multipart, file);
-      appendFormFields(formData, stripParams(args, endpoint.path, prefixKeys), new Set([endpoint.multipart]));
-      const res2 = await fetch(url, {
-        method: endpoint.method,
-        headers,
-        credentials: config.credentials,
-        body: formData
-      });
-      if (!res2.ok) {
-        await throwForErrorResponse(res2, config, null);
-      }
-      if (res2.status === 204)
-        return;
-      const json2 = await res2.json();
-      return endpoint.output ? endpoint.output.parse(json2) : json2;
-    }
-    const res = await fetch(url, {
-      method: endpoint.method,
-      headers,
-      credentials: config.credentials,
-      ...hasBody && {
-        body: JSON.stringify(stripParams(hasBody, endpoint.path, prefixKeys))
-      }
-    });
-    if (!res.ok) {
-      await throwForErrorResponse(res, config, { error: res.statusText });
-    }
-    if (res.status === 204)
-      return;
-    const json = await res.json();
-    return endpoint.output ? endpoint.output.parse(json) : json;
-  };
-}
-function appendFormFields(formData, values, skipKeys) {
-  for (const [key, value] of Object.entries(values)) {
-    if (skipKeys.has(key) || value === undefined || value === null)
-      continue;
-    formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
-  }
-}
-async function throwForErrorResponse(res, config, fallbackBody) {
-  const body = await res.json().catch(() => fallbackBody);
-  config.onError?.(res.status, body);
-  const parsed = parseApiErrorBody(body);
-  if (parsed) {
-    throw new ApiError(parsed.code, res.status, parsed.details, parsed.message, parsed.hint);
-  }
-  throw new ApiError("HTTP_ERROR", res.status, { body });
-}
-function extractParamNames(path) {
-  const matches = path.match(/:(\w+)/g);
-  return matches ? matches.map((m) => m.slice(1)) : [];
-}
-function buildFetchUrl(baseUrl, prefix, path, args, pathPrefix = "") {
-  let fullPath = `/${pathPrefix}${prefix}${path === "/" ? "" : path}`;
-  if (args) {
-    fullPath = fullPath.replace(/:(\w+)/g, (_, key) => {
-      const val = args[key];
-      if (val === undefined || val === null) {
-        throw new Error(`Missing path param: ${key}`);
-      }
-      return encodeURIComponent(String(val));
-    });
-  }
-  return `${baseUrl}${fullPath}`;
-}
-function stripParams(args, path, extra) {
-  const skip = new Set(extra);
-  for (const match of path.matchAll(/:(\w+)/g)) {
-    if (match[1])
-      skip.add(match[1]);
-  }
-  const result = {};
-  for (const [k, v] of Object.entries(args)) {
-    if (!skip.has(k))
-      result[k] = v;
-  }
-  return result;
-}
-
-export { ApiError, createHttpClient, createClient, createClients };

package/dist/index-kzfs85xp.js

@@ -1,9 +0,0 @@
-// src/internal/safe-json.ts
-function isUnsafeKey(key) {
-  return key === "__proto__";
-}
-function safeJsonParse(text) {
-  return JSON.parse(text, (key, value) => isUnsafeKey(key) ? undefined : value);
-}
-
-export { isUnsafeKey, safeJsonParse };

package/dist/index-mahbaen9.js

@@ -1,72 +0,0 @@
-import {
-  normalizeError
-} from "./index-4843j09b.js";
-
-// src/server/stream.ts
-function streamSSE(generator) {
-  const encoder = new TextEncoder;
-  const stream = new ReadableStream({
-    async start(controller) {
-      try {
-        for await (const chunk of generator) {
-          const data = JSON.stringify(chunk);
-          controller.enqueue(encoder.encode(`data: ${data}
-
-`));
-        }
-        controller.enqueue(encoder.encode(`data: [DONE]
-
-`));
-        controller.close();
-      } catch (err) {
-        const envelope = normalizeError(err).toJSON();
-        controller.enqueue(encoder.encode(`data: ${JSON.stringify(envelope)}
-
-`));
-        controller.close();
-      }
-    }
-  });
-  return new Response(stream, {
-    headers: {
-      "Content-Type": "text/event-stream",
-      "Cache-Control": "no-cache",
-      Connection: "keep-alive"
-    }
-  });
-}
-async function* parseSSE(response, options) {
-  const reader = response.body?.getReader();
-  if (!reader)
-    return;
-  const decoder = new TextDecoder;
-  let buffer = "";
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done)
-        break;
-      buffer += decoder.decode(value, { stream: true });
-      const lines = buffer.split(`
-`);
-      buffer = lines.pop() ?? "";
-      for (const rawLine of lines) {
-        const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
-        if (!line.startsWith("data:"))
-          continue;
-        const data = line.slice(5).replace(/^ /, "");
-        if (data === "[DONE]")
-          return;
-        try {
-          yield JSON.parse(data);
-        } catch (err) {
-          options?.onParseError?.(data, err instanceof Error ? err : new Error(String(err)));
-        }
-      }
-    }
-  } finally {
-    reader.releaseLock();
-  }
-}
-
-export { streamSSE, parseSSE };

package/dist/index-x3fcszf8.js

@@ -1,8 +0,0 @@
-// 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 { isWithinDir };