stitchkit 0.54.0 → 0.56.0

package/dist/index-5r13htq1.js

@@ -0,0 +1,283 @@
+import {
+  parseTrailingWildcard
+} from "./index-7eq9va6e.js";
+
+// src/contract/errors.ts
+var APP_ERROR_BRAND = Symbol.for("stitchkit.AppError");
+
+class AppError extends Error {
+  code;
+  status;
+  details;
+  hint;
+  traceId;
+  constructor(code, message, status = 500, details, hint, traceId) {
+    super(message ?? code);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.hint = hint;
+    this.traceId = traceId;
+    this.name = "AppError";
+    Object.defineProperty(this, APP_ERROR_BRAND, { value: true });
+  }
+  static is(err) {
+    return typeof err === "object" && err !== null && APP_ERROR_BRAND in err;
+  }
+  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,
+  FILE_INVALID_PATH: 400,
+  FILE_OUTSIDE_ROOT: 400,
+  FILE_NOT_FOUND: 404,
+  FILE_NOT_REGULAR: 422,
+  FILE_INSPECTION_REJECTED: 422,
+  FILE_TOO_LARGE: 413,
+  FILE_EXISTS: 409,
+  REALTIME_CONTRACT_VIOLATION: 500,
+  INTERNAL_SERVER_ERROR: 500
+};
+function isStitchErrorCode(code) {
+  return Object.hasOwn(STITCH_ERROR_STATUS, code);
+}
+function appError(code, message, details) {
+  throw new AppError(code, message, isStitchErrorCode(code) ? STITCH_ERROR_STATUS[code] : 500, details);
+}
+
+// src/contract/define.ts
+import { z } from "zod";
+
+// 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/contract/define.ts
+function defineContract(meta, endpoints) {
+  const toolTransports = new Map;
+  for (const [key, ep] of Object.entries(endpoints)) {
+    const wildcard = parseTrailingWildcard(ep.path);
+    if (wildcard) {
+      if (!ep.params) {
+        throw new Error(`Contract "${meta.prefix}": endpoint "${key}" wildcard "${wildcard.name}" requires a params schema field`);
+      }
+      const paramsJson = z.toJSONSchema(ep.params, { io: "input" });
+      if (!paramsJson.properties || !(wildcard.name in paramsJson.properties)) {
+        throw new Error(`Contract "${meta.prefix}": endpoint "${key}" params schema is missing wildcard field "${wildcard.name}"`);
+      }
+    }
+    if (ep.desc.trim() === "") {
+      throw new Error(`Contract "${meta.prefix}": endpoint "${key}" has an empty desc`);
+    }
+    if (ep.maxJsonBodyBytes !== undefined && (!Number.isSafeInteger(ep.maxJsonBodyBytes) || ep.maxJsonBodyBytes <= 0)) {
+      throw new Error(`Contract "${meta.prefix}": endpoint "${key}" maxJsonBodyBytes must be a positive safe integer, received ${ep.maxJsonBodyBytes}`);
+    }
+    if (ep.multipart)
+      assertMultipartEndpoint(meta.prefix, key, ep);
+    if (ep.rawResponse)
+      assertRawEndpoint(meta.prefix, key, ep);
+    if (ep.method === "HEAD")
+      assertHeadEndpoint(meta.prefix, key, ep);
+    if (ep.rawBody)
+      assertRawBodyEndpoint(meta.prefix, key, ep);
+    if ("responseMeta" in ep)
+      assertResponseMetaEndpoint(meta.prefix, key, ep);
+    if (!("toolName" in ep) || !ep.toolName)
+      continue;
+    const transports = new Set(ep.expose ? ep.expose.filter((t) => t !== "HTTP") : ["MCP", "AGENT"]);
+    if (transports.size === 0) {
+      throw new Error(`Contract "${meta.prefix}": endpoint "${key}" sets toolName "${ep.toolName}" but is not exposed on any tool transport (MCP / AGENT)`);
+    }
+    const existing = toolTransports.get(ep.toolName);
+    if (existing) {
+      for (const t of transports) {
+        if (existing.transports.has(t)) {
+          throw new Error(`Contract "${meta.prefix}": duplicate toolName "${ep.toolName}" on transport "${t}" (endpoints: "${existing.key}" and "${key}")`);
+        }
+        existing.transports.add(t);
+      }
+    } else {
+      toolTransports.set(ep.toolName, { key, transports });
+    }
+  }
+  return { meta, endpoints };
+}
+function assertPositiveLimit(where, name, value) {
+  if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
+    throw new Error(`${where} ${name} must be a positive safe integer, received ${value}`);
+  }
+}
+function assertMultipartEndpoint(prefix, key, ep) {
+  const where = `Contract "${prefix}": multipart endpoint "${key}"`;
+  if (ep.method !== "POST" && ep.method !== "PUT" && ep.method !== "PATCH") {
+    throw new Error(`${where} must use POST, PUT or PATCH`);
+  }
+  const multipart = ep.multipart;
+  if (!multipart || typeof multipart !== "object") {
+    throw new Error(`${where} must declare a multipart descriptor`);
+  }
+  assertPositiveLimit(where, "maxRequestBytes", multipart.maxRequestBytes);
+  assertPositiveLimit(where, "maxFieldBytes", multipart.maxFieldBytes);
+  const entries = Object.entries(multipart.files);
+  if (entries.length === 0)
+    throw new Error(`${where} must declare at least one file field`);
+  for (const [field, policy] of entries) {
+    if (!field || isUnsafeKey(field))
+      throw new Error(`${where} has an invalid file field name`);
+    assertPositiveLimit(`${where} field "${field}"`, "maxBytes", policy.maxBytes);
+    assertPositiveLimit(`${where} field "${field}"`, "maxFiles", policy.maxFiles);
+    if (policy.multiple !== true && policy.maxFiles !== undefined) {
+      throw new Error(`${where} field "${field}" may set maxFiles only with multiple: true`);
+    }
+    if (policy.contentTypes) {
+      if (policy.contentTypes.length === 0) {
+        throw new Error(`${where} field "${field}" contentTypes cannot be empty`);
+      }
+      for (const contentType of policy.contentTypes) {
+        if (!/^[a-z0-9!#$&^_.+-]+\/(?:[a-z0-9!#$&^_.+-]+|\*)$/i.test(contentType)) {
+          throw new Error(`${where} field "${field}" has invalid content type policy "${contentType}"`);
+        }
+      }
+    }
+  }
+}
+function assertRawEndpoint(prefix, key, ep) {
+  const where = `Contract "${prefix}": raw endpoint "${key}"`;
+  if (ep.output)
+    throw new Error(`${where} cannot declare an output schema`);
+  if ("toolName" in ep && ep.toolName)
+    throw new Error(`${where} cannot set a toolName`);
+  if ("ui" in ep && ep.ui)
+    throw new Error(`${where} cannot set MCP ui metadata`);
+  if ("annotations" in ep && ep.annotations) {
+    throw new Error(`${where} cannot set MCP annotations`);
+  }
+  const nonHttp = (ep.expose ?? []).filter((t) => t !== "HTTP");
+  if (nonHttp.length > 0) {
+    throw new Error(`${where} is HTTP-only — remove ${nonHttp.join(", ")} from expose`);
+  }
+}
+function assertHeadEndpoint(prefix, key, ep) {
+  const where = `Contract "${prefix}": HEAD endpoint "${key}"`;
+  if (!ep.rawResponse)
+    throw new Error(`${where} must declare rawResponse: true`);
+  if (ep.input)
+    throw new Error(`${where} cannot declare an input schema`);
+  if (ep.multipart)
+    throw new Error(`${where} cannot be multipart`);
+  if (ep.rawBody)
+    throw new Error(`${where} cannot retain a raw body`);
+}
+function assertRawBodyEndpoint(prefix, key, ep) {
+  const where = `Contract "${prefix}": rawBody endpoint "${key}"`;
+  if (!ep.input)
+    throw new Error(`${where} must declare an input schema`);
+  if (ep.multipart)
+    throw new Error(`${where} cannot be multipart`);
+  if (ep.method !== "POST" && ep.method !== "PUT" && ep.method !== "PATCH") {
+    throw new Error(`${where} must use POST, PUT or PATCH`);
+  }
+  if ("toolName" in ep && ep.toolName)
+    throw new Error(`${where} cannot set a toolName`);
+  if ("ui" in ep && ep.ui)
+    throw new Error(`${where} cannot set MCP ui metadata`);
+  if ("annotations" in ep && ep.annotations) {
+    throw new Error(`${where} cannot set MCP annotations`);
+  }
+  const nonHttp = (ep.expose ?? []).filter((transport) => transport !== "HTTP");
+  if (nonHttp.length > 0) {
+    throw new Error(`${where} is HTTP-only — remove ${nonHttp.join(", ")} from expose`);
+  }
+}
+function assertResponseMetaEndpoint(prefix, key, ep) {
+  const where = `Contract "${prefix}": responseMeta endpoint "${key}"`;
+  if (!ep.responseMeta || typeof ep.responseMeta !== "object") {
+    throw new Error(`${where} must declare responseMeta as an object`);
+  }
+  const status = ep.responseMeta.status;
+  if (status !== undefined && (!Number.isSafeInteger(status) || status < 200 || status > 299)) {
+    throw new Error(`${where} status must be a successful 2xx integer, received ${status}`);
+  }
+  if (ep.output && (status === 204 || status === 205)) {
+    throw new Error(`${where} cannot combine output with bodyless status ${status}`);
+  }
+  if (ep.rawResponse)
+    throw new Error(`${where} cannot also be a rawResponse endpoint`);
+  if ("toolName" in ep && ep.toolName)
+    throw new Error(`${where} cannot set a toolName`);
+  if ("ui" in ep && ep.ui)
+    throw new Error(`${where} cannot set MCP ui metadata`);
+  if ("annotations" in ep && ep.annotations) {
+    throw new Error(`${where} cannot set MCP annotations`);
+  }
+  const nonHttp = (ep.expose ?? []).filter((transport) => transport !== "HTTP");
+  if (nonHttp.length > 0) {
+    throw new Error(`${where} is HTTP-only — remove ${nonHttp.join(", ")} from expose`);
+  }
+}
+function mergeMeta(contractMeta, endpointMeta) {
+  if (!contractMeta)
+    return endpointMeta;
+  if (!endpointMeta)
+    return { ...contractMeta };
+  return { ...contractMeta, ...endpointMeta };
+}
+// src/contract/errors-factory.ts
+import { z as z2 } from "zod";
+// src/contract/pagination.ts
+import { z as z3 } from "zod";
+
+// src/internal/base64url.ts
+function bytesToBase64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlToBytes(segment) {
+  if (!/^[A-Za-z0-9_-]*$/.test(segment) || segment.length % 4 === 1) {
+    throw new Error("invalid base64url segment");
+  }
+  const b64 = segment.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = b64.padEnd(Math.ceil(b64.length / 4) * 4, "=");
+  return Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
+}
+export { isUnsafeKey, safeJsonParse, defineContract, mergeMeta, AppError, notFound, badRequest, unauthorized, forbidden, conflict, rateLimited, STITCH_ERROR_STATUS, isStitchErrorCode, appError, bytesToBase64Url, base64UrlToBytes };

package/dist/index-6k1937bx.js

@@ -0,0 +1,20 @@
+// src/contract/file-ref.ts
+import { z } from "zod";
+function isManagedFilePath(value) {
+  if (value.length === 0 || value.includes("\x00") || value.includes("\\"))
+    return false;
+  if (value.startsWith("/") || value.startsWith("//") || /^[A-Za-z]:/.test(value)) {
+    return false;
+  }
+  const parts = value.split("/");
+  return parts.every((part) => part.length > 0 && part !== "." && part !== "..");
+}
+var ManagedFilePathSchema = z.string().refine(isManagedFilePath, "expected a canonical relative managed-file path");
+var ManagedFileRefSchema = z.object({
+  path: ManagedFilePathSchema,
+  size: z.number().int().nonnegative(),
+  mediaType: z.string().min(1).optional(),
+  name: z.string().min(1).optional()
+});
+
+export { ManagedFilePathSchema, ManagedFileRefSchema };