stitchkit 0.0.1 → 0.2.0

package/dist/server/middleware/auth.d.ts

@@ -0,0 +1,50 @@
+import type { RuntimeContext } from '../../contract';
+import type { MethodDef } from '../types';
+export interface JwtPayload {
+    [key: string]: unknown;
+}
+export declare function verifyJwt(token: string, secret: string): Promise<JwtPayload>;
+export declare function extractToken(req: Request, cookieName?: string): string | null;
+/**
+ * Per-scope access predicate. `endpoint.scope` selects which rule applies:
+ *  - `'public'`        — always pass (identity attached if present).
+ *  - `'authenticated'` — any resolved identity passes.
+ *  - function          — custom check; gets the identity and the full context
+ *    (so it can read `ctx.pathParams` for resource-scoped access). May be
+ *    async — resource-scoped checks usually need a DB lookup.
+ */
+export type AuthRule<TIdentity> = 'public' | 'authenticated' | ((identity: Awaited<TIdentity>, ctx: RuntimeContext) => boolean | Promise<boolean>);
+export interface AuthHookConfig<TIdentity> {
+    /** Resolve the request identity — cookie / bearer + DB lookup. */
+    resolve: (ctx: RuntimeContext) => Promise<TIdentity | null>;
+    /** Access rule per scope; `endpoint.scope` is the key. */
+    rules: Record<string, AuthRule<TIdentity>>;
+    /** Scope applied when an endpoint declares none. */
+    defaultScope?: string;
+    /** Write the resolved identity onto the context for handlers. */
+    inject?: (ctx: RuntimeContext, identity: Awaited<TIdentity> | null) => void;
+    /** Thrown when the scope needs an identity and there is none. */
+    onAnonymous?: () => never;
+    /** Thrown when an identity is present but the rule rejects it. */
+    onForbidden?: () => never;
+}
+export type AuthHook = (ctx: RuntimeContext, endpoint: MethodDef) => Promise<void>;
+/**
+ * Build a `beforeHandle` hook that enforces `endpoint.scope`.
+ *
+ * Identity resolution and the scope vocabulary stay in the project; the
+ * project annotates its `rules` object with `satisfies Record<MyScope, …>` to
+ * keep scope coverage exhaustive.
+ */
+export declare function createAuthHook<TIdentity>(config: AuthHookConfig<TIdentity>): AuthHook;
+/**
+ * Bearer-token identity resolver — the MCP / API-key counterpart of the
+ * cookie session hook. Strips `Authorization: Bearer <token>` and hands the
+ * raw token (plus the request, for IP / user-agent) to the project lookup.
+ */
+export interface BearerResolverConfig<TIdentity> {
+    /** Resolve a raw token to identity. Return `null` for unknown / revoked. */
+    lookup: (token: string, req: Request) => Promise<TIdentity | null>;
+}
+export declare function createBearerResolver<TIdentity>(config: BearerResolverConfig<TIdentity>): (req: Request) => Promise<TIdentity | null>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/server/middleware/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG1C,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AASD,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA4ClF;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU7E;AAUD;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,CAAC,SAAS,IAC1B,QAAQ,GACR,eAAe,GACf,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;AAExF,MAAM,WAAW,cAAc,CAAC,SAAS;IACvC,kEAAkE;IAClE,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC5D,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IAC3C,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;IAC5E,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,KAAK,CAAC;IAC1B,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,KAAK,CAAC;CAC3B;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnF;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,CAAC,SAAS,CAAC,GAAG,QAAQ,CAuBrF;AAID;;;;GAIG;AACH,MAAM,WAAW,oBAAoB,CAAC,SAAS;IAC7C,4EAA4E;IAC5E,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;CACpE;AAED,wBAAgB,oBAAoB,CAAC,SAAS,EAC5C,MAAM,EAAE,oBAAoB,CAAC,SAAS,CAAC,GACtC,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAM7C"}

package/dist/server/middleware/cookies.d.ts

@@ -0,0 +1,34 @@
+export declare function parseCookies(header: string | null): Record<string, string>;
+export interface CookieOptions {
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+export declare function serializeCookie(name: string, value: string, opts?: CookieOptions): string;
+/** A cookie's name + options bundled into a typed read/set/clear handle. */
+export interface CookieDef {
+    /** Read this cookie's value from a request (`undefined` if absent). */
+    get(req: Request): string | undefined;
+    /** Build a `Set-Cookie` header value for `value` with the baked-in options. */
+    set(value: string): string;
+    /** Build a `Set-Cookie` header value that clears the cookie. */
+    clear(): string;
+}
+/**
+ * Bundle a cookie's name + options into a typed handle — define it once,
+ * then `get` / `set` / `clear` without repeating the config at every call site.
+ *
+ * ```ts
+ * const session = defineCookie({ name: 'sid', httpOnly: true, path: '/' });
+ * session.get(req);        // string | undefined
+ * session.set('abc123');   // → Set-Cookie value
+ * session.clear();         // → Set-Cookie value (Max-Age=0)
+ * ```
+ */
+export declare function defineCookie(config: CookieOptions & {
+    name: string;
+}): CookieDef;
+//# sourceMappingURL=cookies.d.ts.map

package/dist/server/middleware/cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/cookies.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAc1E;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;CACtC;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,aAAkB,GACvB,MAAM,CASR;AAED,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,GAAG,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IACtC,+EAA+E;IAC/E,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,gEAAgE;IAChE,KAAK,IAAI,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAahF"}

package/dist/server/middleware/cors.d.ts

@@ -0,0 +1,9 @@
+export interface CorsConfig {
+    origin?: string | string[];
+    credentials?: boolean;
+    methods?: string;
+    headers?: string;
+}
+export declare function corsHeaders(config: CorsConfig, requestOrigin?: string | null): Record<string, string>;
+export declare function corsPreflightResponse(config: CorsConfig, req: Request): Response;
+//# sourceMappingURL=cors.d.ts.map

package/dist/server/middleware/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../../src/server/middleware/cors.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,EAClB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmCxB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,GAAG,QAAQ,CAKhF"}

package/dist/server/multipart.d.ts

@@ -0,0 +1,14 @@
+import type { ZodType } from 'zod';
+/** A parsed multipart request — the uploaded `file` and the validated `fields`. */
+export interface MultipartResult {
+    file: File;
+    fields: Record<string, unknown>;
+}
+/**
+ * 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).
+ */
+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

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.d.ts","sourceRoot":"","sources":["../../src/server/multipart.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAGnC,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAKD;;;;;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,CAkC1B"}

package/dist/server/node.d.ts

@@ -0,0 +1,12 @@
+import type { HandlerConfig } from './types';
+export interface NodeServerConfig extends HandlerConfig {
+    port?: number;
+    hostname?: string;
+}
+export interface NodeServerHandle {
+    url: string;
+    port: number;
+    close(closeActive?: boolean): Promise<void>;
+}
+export declare function serveNode(config: NodeServerConfig): Promise<NodeServerHandle>;
+//# sourceMappingURL=node.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/server/node.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgBnF"}

package/dist/server/rate-limit.d.ts

@@ -0,0 +1,17 @@
+/** Token-bucket limit — at most `max` requests per `window` seconds. */
+export interface RateLimitConfig {
+    window: number;
+    max: number;
+}
+/**
+ * In-memory token-bucket rate limiter. `check(key, config)` consumes a token
+ * and returns whether the request is allowed; `remaining(key, config)` reports
+ * the count without consuming. Idle keys are swept on a 60-second timer;
+ * `destroy()` stops it.
+ */
+export declare function createRateLimiter(): {
+    destroy: () => void;
+    check(key: string, config: RateLimitConfig): boolean;
+    remaining(key: string, config: RateLimitConfig): number;
+};
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/server/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/server/rate-limit.ts"],"names":[],"mappings":"AAOA,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AASD;;;;;GAKG;AACH,wBAAgB,iBAAiB;;eAQlB,MAAM,UAAU,eAAe,GAAG,OAAO;mBAiBrC,MAAM,UAAU,eAAe,GAAG,MAAM;EAO1D"}

package/dist/server/request.d.ts

@@ -0,0 +1,22 @@
+/**
+ * HTTP request helpers — header parsing, client identification, trace ids.
+ * Pure `Request → value` functions; no framework state.
+ */
+/** Compact, time-sortable id — base36 timestamp + base36 random, ~14 chars. */
+export declare function generateTraceId(): string;
+/**
+ * Trace id for a request: a trusted inbound `x-request-id` / `x-trace-id`
+ * header (set by the edge proxy) when present and sane, else a fresh one.
+ * Shared by the router, the logger and any consumer that wants the same id.
+ */
+export declare function resolveTraceId(req: Request): string;
+/** Client IP from `x-forwarded-for` / `x-real-ip` (IPv4-mapped prefix stripped). */
+export declare function extractIp(req: Request): string;
+/** Client identity — IP + user-agent. The one place projects derive both. */
+export declare function getClientInfo(req: Request): {
+    ipAddress?: string;
+    userAgent?: string;
+};
+/** Flatten a URL query string — repeated keys collapse to arrays. */
+export declare function parseQueryParams(url: URL): Record<string, string | string[]>;
+//# sourceMappingURL=request.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/server/request.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+EAA+E;AAC/E,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CASnD;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAM9C;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAKA;AAED,qEAAqE;AACrE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAQ5E"}

package/dist/server/router.d.ts

@@ -0,0 +1,42 @@
+import type { LifecycleHooks, MethodDef, RawRoute, ServiceDef } from './types';
+/** A service mounted under a path prefix, carrying optional group hooks. */
+export interface NormalizedGroup {
+    prefix: string;
+    service: ServiceDef;
+    hooks?: LifecycleHooks;
+}
+interface RouteEntry {
+    method: MethodDef;
+    service: ServiceDef;
+    pattern: string;
+    segments: string[];
+    groupHooks?: LifecycleHooks;
+}
+/** Compiled route table — HTTP method → entries (param routes sorted last). */
+export type RouteMap = Map<string, RouteEntry[]>;
+export interface RouteMatch {
+    method: MethodDef;
+    service: ServiceDef;
+    pathParams: Record<string, string>;
+    groupHooks?: LifecycleHooks;
+}
+export declare function buildRouteMap(groups: NormalizedGroup[]): RouteMap;
+export declare function matchRoute(routeMap: RouteMap, httpMethod: string, pathname: string): RouteMatch | null;
+/**
+ * HTTP methods that have a route matching `pathname` — for a `405` `Allow`
+ * header when the path exists but not under the requested method.
+ */
+export declare function allowedMethods(routeMap: RouteMap, pathname: string): string[];
+/** Startup guard — throws when two routes collapse to the same shape. */
+export declare function validateRoutes(routeMap: RouteMap): void;
+export declare function matchRawRoute(rawRoutes: RawRoute[], httpMethod: string, pathname: string): {
+    route: RawRoute;
+    params: Record<string, string>;
+} | null;
+/**
+ * Build a `RawRoute` that serves files from `dir` under `prefix`.
+ * Rejects path traversal (`..`); 404 for a missing file.
+ */
+export declare function staticRoute(prefix: string, dir: string): RawRoute;
+export {};
+//# sourceMappingURL=router.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/server/router.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/E,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,MAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,cAAc,CAAC;CAC7B;AAqCD,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,QAAQ,CAmCjE;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,UAAU,GAAG,IAAI,CAmBnB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAc7E;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAiBvD;AAID,wBAAgB,aAAa,CAC3B,SAAS,EAAE,QAAQ,EAAE,EACrB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAAI,CAyB5D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,CAuBjE"}

package/dist/server/socket-io.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Socket.IO server setup — the family WebSocket server boilerplate.
+ *
+ * Every project repeats the same wiring: `new SocketIOServer(...)`, a
+ * `@socket.io/bun-engine` instance, `io.bind(engine)`, `engine.handler()` for
+ * the `Bun.serve` `websocket` field, and an `/socket.io/*` route delegating to
+ * `engine.handleRequest`. `createSocketIOServer` is exactly that wiring.
+ *
+ * Connection handlers, rooms and handshake auth stay in the project — they are
+ * domain logic. This helper owns only the transport plumbing: it returns the
+ * typed `io` to attach handlers to, the `websocket` handler for `Bun.serve`,
+ * and a ready-made `route` to drop into `createServer({ rawRoutes })`.
+ */
+import { Server as BunEngine } from '@socket.io/bun-engine';
+import { Server as SocketIOServer } from 'socket.io';
+import type { SocketEventMap } from '../browser/socket-io';
+import type { RawRoute } from './types';
+export interface SocketIOServerConfig {
+    /** CORS — the browser origin(s) allowed to open a socket. */
+    cors: {
+        origin: string | string[];
+        credentials?: boolean;
+    };
+    /** Socket.IO endpoint path. Default `/socket.io/`. */
+    path?: string;
+    /** Transports offered to clients. Default `['websocket', 'polling']`. */
+    transports?: Array<'websocket' | 'polling'>;
+    /** Heartbeat: ms without a pong before the connection is dropped. Default `20000`. */
+    pingTimeout?: number;
+    /** Heartbeat: ms between pings. Default `10000`. */
+    pingInterval?: number;
+}
+export interface SocketIOServerHandle<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap> {
+    /** The typed Socket.IO server — attach `io.on('connection', ...)` handlers. */
+    io: SocketIOServer<TClientEvents, TServerEvents>;
+    /** WebSocket handler for `Bun.serve({ websocket })`. */
+    websocket: ReturnType<BunEngine['handler']>['websocket'];
+    /** Ready `/socket.io/*` route — drop into `createServer({ rawRoutes })`. */
+    route: RawRoute;
+}
+export declare function createSocketIOServer<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap>(config: SocketIOServerConfig): SocketIOServerHandle<TServerEvents, TClientEvents>;
+//# sourceMappingURL=socket-io.d.ts.map

package/dist/server/socket-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-io.d.ts","sourceRoot":"","sources":["../../src/server/socket-io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,MAAM,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,MAAM,IAAI,cAAc,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3D,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,UAAU,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAC5C,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB,CACnC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc;IAEpC,+EAA+E;IAC/E,EAAE,EAAE,cAAc,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;IACjD,wDAAwD;IACxD,SAAS,EAAE,UAAU,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACzD,4EAA4E;IAC5E,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED,wBAAgB,oBAAoB,CAClC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc,EACpC,MAAM,EAAE,oBAAoB,GAAG,oBAAoB,CAAC,aAAa,EAAE,aAAa,CAAC,CAqClF"}

package/dist/server/stream.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Turn an async generator into a Server-Sent Events `Response` — each yielded
+ * value is one JSON `data:` event, the stream ends with a `[DONE]` sentinel,
+ * and a thrown error is emitted as a final `{ error }` event.
+ */
+export declare function streamSSE(generator: AsyncGenerator<unknown>): Response;
+/** Options for `parseSSE`. */
+export interface ParseSSEOptions {
+    /** Called for a `data:` line that is not valid JSON — the alternative to throwing. */
+    onParseError?: (raw: string, error: Error) => void;
+}
+/**
+ * Parse a Server-Sent Events `Response` body into an async generator of JSON
+ * values — the client counterpart of `streamSSE`. Stops at the `[DONE]`
+ * sentinel; the stream lock is released on every exit path.
+ */
+export declare function parseSSE<T>(response: Response, options?: ParseSSEOptions): AsyncGenerator<T>;
+//# sourceMappingURL=stream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/server/stream.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,cAAc,CAAC,OAAO,CAAC,GAAG,QAAQ,CA2BtE;AAED,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACpD;AAED;;;;GAIG;AACH,wBAAuB,QAAQ,CAAC,CAAC,EAC/B,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAAC,CAAC,CAAC,CAkCnB"}

package/dist/server/swept-map.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A string-keyed `Map` with a background sweep that evicts expired entries.
+ * The shared scaffold behind `createCache` and `createRateLimiter` — they
+ * differ only in the expiry predicate and the sweep interval.
+ */
+/** Config for `createSweptMap`. */
+export interface SweptMapOptions<V> {
+    /** Sweep interval, in milliseconds. */
+    intervalMs: number;
+    /** `true` for an entry that should be evicted — `now` is `Date.now()`. */
+    isExpired: (value: V, now: number) => boolean;
+}
+/** A swept map — its backing store plus a teardown. */
+export interface SweptMap<V> {
+    /** The backing map — read and written directly by the owner. */
+    store: Map<string, V>;
+    /** Stop the sweep timer and clear the map. */
+    destroy: () => void;
+}
+/** Build a `Map` that evicts expired entries on a background timer. */
+export declare function createSweptMap<V>(options: SweptMapOptions<V>): SweptMap<V>;
+//# sourceMappingURL=swept-map.d.ts.map

package/dist/server/swept-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swept-map.d.ts","sourceRoot":"","sources":["../../src/server/swept-map.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,mCAAmC;AACnC,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CAC/C;AAED,uDAAuD;AACvD,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,gEAAgE;IAChE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACtB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAmB1E"}

package/dist/server/types.d.ts

@@ -0,0 +1,127 @@
+import type { ZodType } from 'zod';
+import type { EndpointDef, HandlerContext, HttpMethod, RuntimeContext, Transport } from '../contract';
+import type { CorsConfig } from './middleware/cors';
+type Prop<T, K extends string> = K extends keyof T ? T[K] : undefined;
+type InferParams<E> = Prop<E, 'params'> extends ZodType<infer P> ? P : undefined;
+type InferInput<E> = Prop<E, 'input'> extends ZodType<infer I> ? I : undefined;
+type InferOutput<E> = Prop<E, 'output'> extends ZodType<infer O> ? O : never;
+export type Handlers<C extends Record<string, EndpointDef>, TCtx extends RuntimeContext = HandlerContext> = {
+    [K in keyof C]: (ctx: TCtx & {
+        params: InferParams<C[K]>;
+        input: InferInput<C[K]>;
+    }) => Prop<C[K], 'output'> extends ZodType ? Promise<InferOutput<C[K]>> | InferOutput<C[K]> : void | Promise<void>;
+};
+export interface MethodDef<TParams = unknown, TInput = unknown, TOutput = unknown> {
+    method: HttpMethod;
+    path: string;
+    desc: string;
+    toolName?: string;
+    expose?: readonly Transport[];
+    scope?: string;
+    paramsSchema?: ZodType<TParams>;
+    inputSchema?: ZodType<TInput>;
+    outputSchema?: ZodType<TOutput>;
+    multipart?: string;
+    handler: (ctx: RuntimeContext) => Promise<TOutput> | TOutput;
+}
+export interface ServiceDef {
+    name: string;
+    prefix: string;
+    scope: string;
+    methods: Record<string, MethodDef<unknown, unknown, unknown>>;
+}
+export interface LifecycleHooks {
+    onRequest?: (req: Request) => undefined | Response | Promise<undefined | Response>;
+    beforeHandle?: (ctx: RuntimeContext, endpoint: MethodDef) => void | Promise<void>;
+    afterHandle?: (ctx: RuntimeContext, result: unknown, endpoint: MethodDef) => unknown | Promise<unknown>;
+    onError?: (ctx: RuntimeContext, error: unknown, endpoint?: MethodDef) => Response | Promise<Response> | undefined;
+}
+export interface RouteGroup {
+    pathPrefix?: string;
+    services: ServiceDef[];
+    hooks?: LifecycleHooks;
+}
+/**
+ * A non-contract HTTP route — for things that cannot be a clean JSON
+ * request/response contract: auth bootstrap (cookies, OAuth redirects),
+ * external webhooks (signature/IP verification), static files, socket.io.
+ *
+ * Matched in the same router as contract routes (shared CORS / `onRequest`),
+ * but the handler is raw `Request → Response` — no schema parsing and no
+ * `beforeHandle` auth gate; the route authorizes itself.
+ */
+/** The concrete `Bun.serve` server instance, passed through to raw handlers. */
+export type BunServer = ReturnType<typeof Bun.serve>;
+/** Context passed to a `RawRoute` handler alongside the raw `Request`. */
+export interface RawRouteContext {
+    /** Matched `:param` path segments — empty object for exact / wildcard paths. */
+    params: Record<string, string>;
+    /**
+     * The `Bun.serve` instance — needed for connection upgrades (e.g. WebSocket).
+     * Absent when the handler runs via the bare `createHandler` fetch.
+     */
+    server?: BunServer;
+}
+export interface RawRoute {
+    method: HttpMethod | 'ALL';
+    /** Exact path, `:param` segments, or a trailing `/*` prefix wildcard. */
+    path: string;
+    /**
+     * Raw handler — a standard `Request → Response` fetch handler plus a routing
+     * `ctx` (matched path params, the server). Errors thrown here are caught by
+     * the router and run through `hooks.onError` — same shape as contract errors.
+     */
+    handler: (req: Request, ctx: RawRouteContext) => Response | Promise<Response>;
+}
+export interface StitchLogger {
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+    debug(msg: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Runtime-neutral handler config — everything `createHandler` needs.
+ * No Bun globals, no Bun types. This is the portability seam.
+ */
+export interface HandlerConfig {
+    services?: ServiceDef[];
+    groups?: RouteGroup[];
+    rawRoutes?: RawRoute[];
+    cors?: CorsConfig;
+    hooks?: LifecycleHooks;
+    logging?: boolean | StitchLogger;
+    traceId?: (req: Request) => string;
+}
+type BunServeOptions = Parameters<typeof Bun.serve>[0];
+type BunWebSocketHandlers = BunServeOptions extends {
+    websocket?: infer T;
+} ? T : never;
+type BunRoutes = BunServeOptions extends {
+    routes?: infer T;
+} ? T : never;
+type BunDevelopmentOptions = BunServeOptions extends {
+    development?: infer T;
+} ? T : never;
+export type ServerPassthrough = Omit<BunServeOptions, 'fetch' | 'port' | 'hostname' | 'unix' | 'routes' | 'websocket' | 'development'>;
+/**
+ * Full config for `createServer` — extends `HandlerConfig` with Bun-specific
+ * options (`Bun.serve` routes, websocket, development, passthrough).
+ */
+export interface BunServerConfig extends HandlerConfig {
+    port?: number;
+    hostname?: string;
+    routes?: BunRoutes;
+    websocket?: BunWebSocketHandlers;
+    development?: BunDevelopmentOptions;
+    bun?: ServerPassthrough;
+}
+export type StitchServeOptions = ServerPassthrough & {
+    port: number;
+    hostname?: string;
+    routes?: BunRoutes;
+    websocket?: BunWebSocketHandlers;
+    development?: BunDevelopmentOptions;
+    fetch(req: Request): Promise<Response>;
+};
+export {};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}

package/dist/tools/agent.d.ts

@@ -0,0 +1,27 @@
+import type { ToolSet } from 'ai';
+import type { ServiceDef } from '../server/types';
+import { type ToolCallHooks, type ToolLifecycle } from './execute';
+import { type ToolExtend } from './mount';
+export interface AgentContext {
+    [key: string]: unknown;
+}
+export interface AgentMountConfig {
+    context?: AgentContext;
+    /** Tool-call observability hooks. */
+    hooks?: ToolCallHooks;
+    /**
+     * Auth / scope gate and result transform for every tool call — the tool-side
+     * twin of `createServer`'s `beforeHandle` / `afterHandle`. Without it an
+     * agent tool call bypasses the auth a `createServer` `beforeHandle` enforces.
+     */
+    lifecycle?: ToolLifecycle;
+    extend?: ToolExtend;
+    /** Coerce JSON-stringified arrays/objects in tool arguments. Default: true. */
+    coerceJsonArgs?: boolean;
+    /** Flatten discriminated union inputs into a single object. Default: false. */
+    flattenUnionInput?: boolean;
+    /** Global error hint injected into every failed tool result. */
+    errorHint?: (toolName: string, errorCode: string) => string | null;
+}
+export declare function mountAgent(services: ServiceDef | ServiceDef[], config?: AgentMountConfig): ToolSet;
+//# sourceMappingURL=agent.d.ts.map

package/dist/tools/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/tools/agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAC;AAGlC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAuB,MAAM,WAAW,CAAC;AACxF,OAAO,EAAmD,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAE3F,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,qCAAqC;IACrC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gEAAgE;IAChE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACpE;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,UAAU,GAAG,UAAU,EAAE,EACnC,MAAM,GAAE,gBAAqB,GAC5B,OAAO,CAyCT"}

package/dist/tools/coerce.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+/**
+ * Wrap array/object fields with `z.preprocess(jsonCoerce)` — tolerant of
+ * LLM double-serialization (sending `"[1,2]"` instead of `[1,2]`).
+ * Preserves optional/nullable wrappers so the emitted JSON Schema is identical.
+ */
+export declare function withJsonCoercion(schema: z.ZodObject<z.ZodRawShape>): z.ZodObject<z.ZodRawShape>;
+//# sourceMappingURL=coerce.d.ts.map

package/dist/tools/coerce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coerce.d.ts","sourceRoot":"","sources":["../../src/tools/coerce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GACjC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAyB5B"}

package/dist/tools/execute.d.ts

@@ -0,0 +1,45 @@
+import type { RuntimeContext, TransportSource } from '../contract';
+import type { MethodDef } from '../server/types';
+export type ToolResult = {
+    ok: true;
+    data: unknown;
+} | {
+    ok: false;
+    code: string;
+    details?: unknown;
+    hint?: string;
+};
+export interface ToolCallContext {
+    source: TransportSource;
+    [key: string]: unknown;
+}
+export interface ToolCallHooks {
+    beforeToolCall?: (toolName: string, args: Record<string, unknown>, context: ToolCallContext) => void | Promise<void>;
+    afterToolCall?: (toolName: string, args: Record<string, unknown>, result: ToolResult, durationMs: number, context: ToolCallContext) => void | Promise<void>;
+}
+/**
+ * The tool-side twin of the HTTP server's `beforeHandle` / `afterHandle`. A
+ * tool call runs the same handler an HTTP request would — `ToolLifecycle` makes
+ * it run the same gate. Pass a `createAuthHook` result as `beforeHandle` here
+ * and tools are scope-guarded exactly as HTTP routes are; without it a tool
+ * call bypasses the auth a `createServer` `beforeHandle` enforces.
+ *
+ * Structurally a subset of `LifecycleHooks` — the same hook object used for
+ * `createServer({ hooks })` is assignable here.
+ */
+export interface ToolLifecycle {
+    /** Auth / scope gate — throw to reject the call. */
+    beforeHandle?: (ctx: RuntimeContext, endpoint: MethodDef) => void | Promise<void>;
+    /** Transform the handler result before it is returned. */
+    afterHandle?: (ctx: RuntimeContext, result: unknown, endpoint: MethodDef) => unknown | Promise<unknown>;
+}
+/**
+ * Normalise any thrown value into a failed `ToolResult` — the one place an
+ * `AppError` becomes a tool error. Shared by `executeToolMethod` and both
+ * transport mounts so every tool error has one shape.
+ */
+export declare function toolResultFromError(err: unknown): Extract<ToolResult, {
+    ok: false;
+}>;
+export declare function executeToolMethod(method: MethodDef<unknown, unknown, unknown>, toolName: string, rawArgs: Record<string, unknown>, context: ToolCallContext, hooks?: ToolCallHooks, lifecycle?: ToolLifecycle): Promise<ToolResult>;
+//# sourceMappingURL=execute.d.ts.map

package/dist/tools/execute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.d.ts","sourceRoot":"","sources":["../../src/tools/execute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAElE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,CACf,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,eAAe,KACrB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,aAAa,CAAC,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,UAAU,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,eAAe,KACrB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,0DAA0D;IAC1D,WAAW,CAAC,EAAE,CACZ,GAAG,EAAE,cAAc,EACnB,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,SAAS,KAChB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAQpF;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAC5C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,eAAe,EACxB,KAAK,CAAC,EAAE,aAAa,EACrB,SAAS,CAAC,EAAE,aAAa,GACxB,OAAO,CAAC,UAAU,CAAC,CA8FrB"}

package/dist/tools/flatten.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+/**
+ * Flatten a `ZodDiscriminatedUnion` into a single `ZodObject` for LLM
+ * transports that cannot represent `oneOf` (MCP).
+ *
+ * The discriminator becomes a `z.enum(...)` of all variant values; fields
+ * from each variant become optional with a `.describe()` hint indicating
+ * which variant requires them.
+ *
+ * **Lossy:** per-variant field requiredness is replaced with optional +
+ * description hint. The original union remains the validation schema in
+ * `executeToolMethod` — this is the advertised schema only.
+ */
+export declare function flattenDiscriminatedUnion(union: z.ZodDiscriminatedUnion): z.ZodObject<z.ZodRawShape>;
+//# sourceMappingURL=flatten.d.ts.map

package/dist/tools/flatten.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../src/tools/flatten.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,CAAC,CAAC,qBAAqB,GAC7B,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAkD5B"}

package/dist/tools/json-schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The single Zod → JSON Schema conversion point for the tools layer.
+ *
+ * MCP and agent both ultimately turn a contract schema into JSON Schema. This
+ * is the one place stitchkit converts — with the options that match what the
+ * transport SDKs emit, so a build-time validity probe tests the same thing the
+ * SDK will later emit, not a divergent code path.
+ */
+import { z } from 'zod';
+/** Conversion direction — `input` for tool arguments, `output` for results. */
+export type JsonSchemaIo = 'input' | 'output';
+/**
+ * Convert a Zod schema to JSON Schema. Throws on a construct JSON Schema cannot
+ * represent (`z.date()`, `z.bigint()`, `z.map()`, …). The caller decides what
+ * to do with that failure — see `onIncompatibleSchema`.
+ */
+export declare function toJsonSchema(schema: z.ZodType, io: JsonSchemaIo): Record<string, unknown>;
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/tools/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../../src/tools/json-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzF"}