stitchkit 0.0.1 → 0.2.0

package/dist/react/cursor-query.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cursor-paginated infinite query — the family's canonical pagination hook.
+ *
+ * Built on `react-query-kit`'s `createInfiniteQuery` (the family's hook layer),
+ * so the result keeps the full rqk surface: `.getKey()`, `.fetcher`,
+ * `useSuspenseInfiniteQuery`, every option. Cursor pagination is immune to
+ * concurrent inserts — offset paging drops or duplicates rows when a new row
+ * lands on top of the list.
+ *
+ * Pass the typed contract method as `endpoint` (e.g. `apiClient.media.list`).
+ * The helper injects `cursor` from the page param and bakes in
+ * `getNextPageParam` / `initialPageParam`. An infinite hook is therefore just
+ * `queryKey + endpoint` — no per-hook fetcher, no pagination plumbing. Every
+ * other rqk option (`staleTime`, `gcTime`, `refetch*`, …) passes through.
+ *
+ * Page size is NOT a client concern: the helper never sends `limit`, so the
+ * server applies the contract's `limit` default (`z.coerce.number().default(N)`).
+ * That default is the single source of truth — the client cannot diverge.
+ */
+import { type CompatibleError, type CreateInfiniteQueryOptions } from 'react-query-kit';
+/** The cursor field the helper owns — the caller never passes it. */
+interface CursorParam {
+    cursor?: string;
+}
+/** Options the helper computes itself; the caller cannot override them. */
+type ControlledKeys = 'fetcher' | 'initialPageParam' | 'getNextPageParam';
+export type CursorQueryConfig<TVars, TPage extends {
+    nextCursor: string | null;
+}, TError> = Omit<CreateInfiniteQueryOptions<TPage, TVars, TError, string | null>, ControlledKeys> & {
+    /** Contract method, e.g. `apiClient.media.list`. */
+    endpoint: (args: TVars & CursorParam) => Promise<TPage>;
+};
+export declare function createCursorQuery<TVars, TPage extends {
+    nextCursor: string | null;
+}, TError = CompatibleError>(config: CursorQueryConfig<TVars, TPage, TError>): import("react-query-kit").InfiniteQueryHook<TPage, TVars, TError, string | null>;
+export {};
+//# sourceMappingURL=cursor-query.d.ts.map

package/dist/react/cursor-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-query.d.ts","sourceRoot":"","sources":["../../src/react/cursor-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAEhC,MAAM,iBAAiB,CAAC;AAEzB,qEAAqE;AACrE,UAAU,WAAW;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,2EAA2E;AAC3E,KAAK,cAAc,GAAG,SAAS,GAAG,kBAAkB,GAAG,kBAAkB,CAAC;AAE1E,MAAM,MAAM,iBAAiB,CAC3B,KAAK,EACL,KAAK,SAAS;IAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC3C,MAAM,IACJ,IAAI,CAAC,0BAA0B,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,EAAE,cAAc,CAAC,GAAG;IAC1F,oDAAoD;IACpD,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,GAAG,WAAW,KAAK,OAAO,CAAC,KAAK,CAAC,CAAC;CACzD,CAAC;AAEF,wBAAgB,iBAAiB,CAC/B,KAAK,EACL,KAAK,SAAS;IAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC3C,MAAM,GAAG,eAAe,EACxB,MAAM,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,oFAYhD"}

package/dist/react.d.ts

@@ -0,0 +1,3 @@
+export { type CacheBridge, type CacheBridgeConfig, type CacheBridgeContext, type CacheBridgeHandler, type CacheBridgeHandlers, type CacheBridgeSocket, createCacheBridge, } from './react/cache-bridge';
+export { type CursorQueryConfig, createCursorQuery } from './react/cursor-query';
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/react.js

@@ -0,0 +1,52 @@
+// src/react/cache-bridge.ts
+function createCacheBridge(config) {
+  const freshWindow = config.freshWindow ?? 500;
+  const freshAt = new Map;
+  let unsubscribers = [];
+  const isFresh = (key) => {
+    const ts = freshAt.get(JSON.stringify(key));
+    return ts !== undefined && Date.now() - ts < freshWindow;
+  };
+  return {
+    connect() {
+      if (unsubscribers.length > 0)
+        return;
+      const queryClient = typeof config.queryClient === "function" ? config.queryClient() : config.queryClient;
+      const ctx = { queryClient, isFresh };
+      const handlers = config.handlers;
+      const socket = config.socket;
+      for (const event of Object.keys(handlers)) {
+        const handler = handlers[event];
+        if (!handler)
+          continue;
+        const off = socket.on(event, (data) => handler(data, ctx));
+        unsubscribers.push(off);
+      }
+    },
+    disconnect() {
+      for (const off of unsubscribers)
+        off();
+      unsubscribers = [];
+    },
+    markFresh(key) {
+      freshAt.set(JSON.stringify(key), Date.now());
+    }
+  };
+}
+// src/react/cursor-query.ts
+import {
+  createInfiniteQuery
+} from "react-query-kit";
+function createCursorQuery(config) {
+  const { endpoint, ...rest } = config;
+  return createInfiniteQuery({
+    ...rest,
+    fetcher: (variables, { pageParam }) => endpoint({ ...variables, cursor: pageParam ?? undefined }),
+    initialPageParam: null,
+    getNextPageParam: (lastPage) => lastPage.nextCursor
+  });
+}
+export {
+  createCursorQuery,
+  createCacheBridge
+};

package/dist/server/cache.d.ts

@@ -0,0 +1,15 @@
+/**
+ * In-memory key/value cache with a per-entry TTL. Expired entries are swept on
+ * a 30-second timer; `destroy()` stops it. For response `Cache-Control`
+ * headers use `cacheHeaders()` instead.
+ */
+export declare function createCache(): {
+    destroy: () => void;
+    get(key: string): unknown | null;
+    set(key: string, data: unknown, maxAgeSeconds: number): void;
+    invalidate(prefix: string): void;
+    clear(): void;
+};
+/** Build a `Cache-Control` header capping freshness at `maxAge` seconds. */
+export declare function cacheHeaders(maxAge: number, scope?: 'public' | 'private'): Record<string, string>;
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/server/cache.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,wBAAgB,WAAW;;aAQd,MAAM,GAAG,OAAO,GAAG,IAAI;aAUvB,MAAM,QAAQ,OAAO,iBAAiB,MAAM;uBAIlC,MAAM;;EAU5B;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,QAAQ,GAAG,SAAoB,GACrC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAIxB"}

package/dist/server/context.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `RuntimeContext` assembly — parses params / body / multipart against the
+ * endpoint schemas and gathers request metadata (trace id, client info).
+ */
+import { type RuntimeContext } from '../contract';
+import type { MethodDef } from './types';
+export declare function buildContext(req: Request, url: URL, method: MethodDef, pathParams: Record<string, string>, traceId: string): Promise<RuntimeContext>;
+export declare function buildErrorContext(req: Request, url: URL, traceId: string): RuntimeContext;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/server/context.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAG9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AA2BzC,wBAAsB,YAAY,CAChC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,CAAC,CAyCzB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAWzF"}

package/dist/server/create.d.ts

@@ -0,0 +1,4 @@
+import type { BunServerConfig, HandlerConfig } from './types';
+export declare function createHandler(config: HandlerConfig): (req: Request) => Promise<Response>;
+export declare function createServer(config: BunServerConfig): Bun.Server<unknown>;
+//# sourceMappingURL=create.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/server/create.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAEV,eAAe,EACf,aAAa,EAGd,MAAM,SAAS,CAAC;AAEjB,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAiLxF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,uBAsBnD"}

package/dist/server/event-bus.d.ts

@@ -0,0 +1,24 @@
+type EventHandler<T = unknown> = (data: T) => void | Promise<void>;
+/** Default event map — untyped string-keyed events (ad-hoc buses). */
+export type DefaultEventMap = Record<string, unknown>;
+/**
+ * In-process pub/sub bus.
+ *
+ * Pass an event map for full type safety — `emit`/`on`/`once`/`off` are then
+ * typed per event:
+ *
+ * ```ts
+ * const bus = createEventBus<{ 'user:created': { id: string } }>();
+ * bus.emit('user:created', { id: '1' }); // typed
+ * ```
+ */
+export interface EventBus<M extends Record<string, unknown> = DefaultEventMap> {
+    emit<K extends keyof M & string>(event: K, data: M[K]): void;
+    on<K extends keyof M & string>(event: K, handler: EventHandler<M[K]>): () => void;
+    once<K extends keyof M & string>(event: K, handler: EventHandler<M[K]>): () => void;
+    off<K extends keyof M & string>(event: K, handler: EventHandler<M[K]>): void;
+    clear(): void;
+}
+export declare function createEventBus<M extends Record<string, unknown> = DefaultEventMap>(): EventBus<M>;
+export {};
+//# sourceMappingURL=event-bus.d.ts.map

package/dist/server/event-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/server/event-bus.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnE,sEAAsE;AACtE,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe;IAC3E,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC7D,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IAClF,IAAI,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IACpF,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC7E,KAAK,IAAI,IAAI,CAAC;CACf;AAYD,wBAAgB,cAAc,CAC5B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,KAChD,QAAQ,CAAC,CAAC,CAAC,CAuDf"}

package/dist/server/implement.d.ts

@@ -0,0 +1,16 @@
+import type { ContractDef, EndpointDef, RuntimeContext } from '../contract';
+import type { Handlers, ServiceDef } from './types';
+/**
+ * Bind a contract to its typed `handlers`, producing a `ServiceDef` to mount on
+ * `createServer`. Every handler is type-checked against its endpoint's schemas.
+ * Pass `TCtx` for a typed handler context — or use `createImplement` to fix it
+ * once.
+ */
+export declare function implement<T extends Record<string, EndpointDef>, TCtx extends RuntimeContext = RuntimeContext>(contract: ContractDef<T, string>, handlers: Handlers<T, TCtx>): ServiceDef;
+/**
+ * Fix the handler context type once — `const implement =
+ * createImplement<MyContext>()` — so each `implement()` call site stays free of
+ * the generic. The application declares its context shape in a single place.
+ */
+export declare function createImplement<TCtx extends RuntimeContext>(): <T extends Record<string, EndpointDef>>(contract: ContractDef<T, string>, handlers: Handlers<T, TCtx>) => ServiceDef;
+//# sourceMappingURL=implement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"implement.d.ts","sourceRoot":"","sources":["../../src/server/implement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,QAAQ,EAAa,UAAU,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACrC,IAAI,SAAS,cAAc,GAAG,cAAc,EAC5C,QAAQ,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,UAAU,CAoC3E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,SAAS,cAAc,MACjD,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAC3C,UAAU,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,EAChC,UAAU,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,KAC1B,UAAU,CACd"}

package/dist/server/index.d.ts

@@ -0,0 +1,17 @@
+export { AppError, appError, badRequest, conflict, forbidden, notFound, rateLimited, unauthorized, } from '../contract';
+export { cacheHeaders, createCache } from './cache';
+export { createHandler, createServer } from './create';
+export { createEventBus, type EventBus } from './event-bus';
+export { createImplement, implement } from './implement';
+export { type AuthHook, type AuthHookConfig, type AuthRule, type BearerResolverConfig, createAuthHook, createBearerResolver, extractToken, type JwtPayload, verifyJwt, } from './middleware/auth';
+export { type CookieDef, type CookieOptions, defineCookie, parseCookies, serializeCookie, } from './middleware/cookies';
+export { type CorsConfig, corsHeaders, corsPreflightResponse, } from './middleware/cors';
+export { parseMultipart } from './multipart';
+export { createRateLimiter, type RateLimitConfig } from './rate-limit';
+export { extractIp, generateTraceId, getClientInfo, resolveTraceId, } from './request';
+export { staticRoute } from './router';
+export type { SocketIOServerConfig, SocketIOServerHandle } from './socket-io';
+export { createSocketIOServer } from './socket-io';
+export { type ParseSSEOptions, parseSSE, streamSSE } from './stream';
+export type { BunServer, BunServerConfig, HandlerConfig, Handlers, LifecycleHooks, MethodDef, RawRoute, RawRouteContext, RouteGroup, ServerPassthrough, ServiceDef, StitchLogger, } from './types';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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,QAAQ,EACR,WAAW,EACX,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,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5D,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,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,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EACL,SAAS,EACT,eAAe,EACf,aAAa,EACb,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,MAAM,aAAa,CAAC;AACnD,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"}

package/dist/server/index.js

@@ -0,0 +1,399 @@
+import {
+  parseSSE,
+  streamSSE
+} from "../index-n7bmdwmz.js";
+import {
+  corsHeaders,
+  corsPreflightResponse,
+  createHandler,
+  createServer,
+  parseMultipart,
+  staticRoute
+} from "../index-v2z2v3mq.js";
+import"../index-a35v22fh.js";
+import {
+  AppError,
+  appError,
+  badRequest,
+  conflict,
+  forbidden,
+  notFound,
+  rateLimited,
+  unauthorized
+} from "../index-kckky6zw.js";
+import {
+  extractIp,
+  generateTraceId,
+  getClientInfo,
+  resolveTraceId
+} from "../index-ke4mx4ea.js";
+// src/server/swept-map.ts
+function createSweptMap(options) {
+  const store = new Map;
+  const timer = setInterval(() => {
+    const now = Date.now();
+    for (const [key, value] of store) {
+      if (options.isExpired(value, now))
+        store.delete(key);
+    }
+  }, options.intervalMs);
+  timer.unref();
+  return {
+    store,
+    destroy() {
+      clearInterval(timer);
+      store.clear();
+    }
+  };
+}
+
+// src/server/cache.ts
+function createCache() {
+  const { store, destroy } = createSweptMap({
+    intervalMs: 30000,
+    isExpired: (entry, now) => entry.expiresAt < now
+  });
+  return {
+    destroy,
+    get(key) {
+      const entry = store.get(key);
+      if (!entry)
+        return null;
+      if (entry.expiresAt < Date.now()) {
+        store.delete(key);
+        return null;
+      }
+      return entry.data;
+    },
+    set(key, data, maxAgeSeconds) {
+      store.set(key, { data, expiresAt: Date.now() + maxAgeSeconds * 1000 });
+    },
+    invalidate(prefix) {
+      for (const key of store.keys()) {
+        if (key.startsWith(prefix))
+          store.delete(key);
+      }
+    },
+    clear() {
+      store.clear();
+    }
+  };
+}
+function cacheHeaders(maxAge, scope = "public") {
+  return {
+    "Cache-Control": `${scope}, max-age=${maxAge}`
+  };
+}
+// src/server/event-bus.ts
+function createEventBus() {
+  const subscriptions = new Map;
+  function add(event, fn, once) {
+    let set = subscriptions.get(event);
+    if (!set) {
+      set = new Set;
+      subscriptions.set(event, set);
+    }
+    const sub = { fn, once };
+    set.add(sub);
+    return () => {
+      set.delete(sub);
+    };
+  }
+  return {
+    emit(event, data) {
+      const set = subscriptions.get(event);
+      if (!set)
+        return;
+      for (const sub of [...set]) {
+        if (sub.once)
+          set.delete(sub);
+        try {
+          const result = sub.fn(data);
+          if (result instanceof Promise)
+            result.catch(() => {
+              return;
+            });
+        } catch {}
+      }
+    },
+    on(event, handler) {
+      return add(event, handler, false);
+    },
+    once(event, handler) {
+      return add(event, handler, true);
+    },
+    off(event, handler) {
+      const set = subscriptions.get(event);
+      if (!set)
+        return;
+      for (const sub of set) {
+        if (sub.fn === handler)
+          set.delete(sub);
+      }
+    },
+    clear() {
+      subscriptions.clear();
+    }
+  };
+}
+// src/server/implement.ts
+function implement(contract, handlers) {
+  const methods = {};
+  const groupScope = contract.meta.scope ?? "public";
+  for (const [key, endpoint] of Object.entries(contract.endpoints)) {
+    const typedHandler = handlers[key];
+    methods[key] = {
+      method: endpoint.method,
+      path: endpoint.path,
+      desc: endpoint.desc,
+      toolName: "toolName" in endpoint ? endpoint.toolName : undefined,
+      expose: endpoint.expose,
+      scope: endpoint.scope ?? groupScope,
+      paramsSchema: endpoint.params,
+      inputSchema: endpoint.input,
+      outputSchema: endpoint.output,
+      multipart: endpoint.multipart,
+      handler: (ctx) => typedHandler(ctx)
+    };
+  }
+  return {
+    name: contract.meta.prefix,
+    prefix: contract.meta.prefix,
+    scope: groupScope,
+    methods
+  };
+}
+function createImplement() {
+  return (contract, handlers) => implement(contract, handlers);
+}
+// src/server/middleware/cookies.ts
+function parseCookies(header) {
+  if (!header)
+    return {};
+  const cookies = {};
+  for (const pair of header.split(";")) {
+    const [key, ...rest] = pair.split("=");
+    if (!key)
+      continue;
+    const raw = rest.join("=").trim();
+    try {
+      cookies[key.trim()] = decodeURIComponent(raw);
+    } catch {
+      cookies[key.trim()] = raw;
+    }
+  }
+  return cookies;
+}
+function serializeCookie(name, value, opts = {}) {
+  let cookie = `${name}=${encodeURIComponent(value)}`;
+  if (opts.maxAge !== undefined)
+    cookie += `; Max-Age=${opts.maxAge}`;
+  if (opts.path)
+    cookie += `; Path=${opts.path}`;
+  if (opts.domain)
+    cookie += `; Domain=${opts.domain}`;
+  if (opts.secure)
+    cookie += "; Secure";
+  if (opts.httpOnly)
+    cookie += "; HttpOnly";
+  if (opts.sameSite)
+    cookie += `; SameSite=${opts.sameSite}`;
+  return cookie;
+}
+function defineCookie(config) {
+  const { name, ...options } = config;
+  return {
+    get(req) {
+      return parseCookies(req.headers.get("cookie"))[name];
+    },
+    set(value) {
+      return serializeCookie(name, value, options);
+    },
+    clear() {
+      return serializeCookie(name, "", { ...options, maxAge: 0 });
+    }
+  };
+}
+
+// src/server/middleware/auth.ts
+function decodeBase64Url(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));
+}
+async function verifyJwt(token, secret) {
+  const [headerB64, payloadB64, signatureB64] = token.split(".");
+  if (!headerB64 || !payloadB64 || !signatureB64)
+    throw unauthorized("Invalid token format");
+  let header;
+  let payload;
+  let signature;
+  try {
+    const decoder = new TextDecoder;
+    header = JSON.parse(decoder.decode(decodeBase64Url(headerB64)));
+    payload = JSON.parse(decoder.decode(decodeBase64Url(payloadB64)));
+    signature = decodeBase64Url(signatureB64);
+  } catch {
+    throw unauthorized("Malformed token");
+  }
+  if (header.alg !== "HS256")
+    throw unauthorized("Unsupported token algorithm");
+  const encoder = new TextEncoder;
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+  const data = encoder.encode(`${headerB64}.${payloadB64}`);
+  const valid = await crypto.subtle.verify("HMAC", key, signature, data);
+  if (!valid)
+    throw unauthorized("Invalid token signature");
+  const now = Date.now() / 1000;
+  if (typeof payload.exp === "number" && payload.exp < now) {
+    throw unauthorized("Token expired");
+  }
+  if (typeof payload.nbf === "number" && payload.nbf > now) {
+    throw unauthorized("Token not yet valid");
+  }
+  return payload;
+}
+function extractToken(req, cookieName) {
+  const authHeader = req.headers.get("authorization");
+  if (authHeader?.startsWith("Bearer "))
+    return authHeader.slice(7);
+  if (cookieName) {
+    const cookies = parseCookies(req.headers.get("cookie"));
+    return cookies[cookieName] ?? null;
+  }
+  return null;
+}
+function createAuthHook(config) {
+  const onAnonymous = config.onAnonymous ?? (() => unauthorized());
+  const onForbidden = config.onForbidden ?? (() => forbidden());
+  return async (ctx, endpoint) => {
+    if (!(ctx.req instanceof Request))
+      return;
+    const identity = await config.resolve(ctx);
+    config.inject?.(ctx, identity);
+    const scope = endpoint.scope ?? config.defaultScope;
+    if (!scope)
+      return;
+    const rule = config.rules[scope];
+    if (!rule || rule === "public")
+      return;
+    if (!identity) {
+      onAnonymous();
+      return;
+    }
+    if (rule === "authenticated")
+      return;
+    if (!await rule(identity, ctx))
+      onForbidden();
+  };
+}
+function createBearerResolver(config) {
+  return async (req) => {
+    const token = extractToken(req);
+    if (!token)
+      return null;
+    return config.lookup(token, req);
+  };
+}
+// src/server/rate-limit.ts
+function refillBucket(entry, config, now) {
+  const elapsed = (now - entry.lastRefill) / 1000;
+  entry.tokens = Math.min(config.max, entry.tokens + elapsed / config.window * config.max);
+  entry.lastRefill = now;
+}
+function createRateLimiter() {
+  const { store: buckets, destroy } = createSweptMap({
+    intervalMs: 60000,
+    isExpired: (entry, now) => now - entry.lastRefill > 300000
+  });
+  return {
+    destroy,
+    check(key, config) {
+      const now = Date.now();
+      let entry = buckets.get(key);
+      if (!entry) {
+        entry = { tokens: config.max, lastRefill: now };
+        buckets.set(key, entry);
+      }
+      refillBucket(entry, config, now);
+      if (entry.tokens < 1)
+        return false;
+      entry.tokens -= 1;
+      return true;
+    },
+    remaining(key, config) {
+      const entry = buckets.get(key);
+      if (!entry)
+        return config.max;
+      refillBucket(entry, config, Date.now());
+      return Math.floor(entry.tokens);
+    }
+  };
+}
+// src/server/socket-io.ts
+import { Server as BunEngine } from "@socket.io/bun-engine";
+import { Server as SocketIOServer } from "socket.io";
+function createSocketIOServer(config) {
+  const path = config.path ?? "/socket.io/";
+  const io = new SocketIOServer({
+    path,
+    cors: {
+      origin: config.cors.origin,
+      credentials: config.cors.credentials ?? true,
+      methods: ["GET", "POST"]
+    },
+    transports: config.transports ?? ["websocket", "polling"],
+    pingTimeout: config.pingTimeout ?? 20000,
+    pingInterval: config.pingInterval ?? 1e4
+  });
+  const engine = new BunEngine({ path });
+  io.bind(engine);
+  const { websocket } = engine.handler();
+  const route = {
+    method: "ALL",
+    path: `${path.replace(/\/+$/, "")}/*`,
+    handler: (req, ctx) => {
+      if (!ctx.server) {
+        throw new Error("[stitchkit] createSocketIOServer route needs a running Bun server — mount it via createServer.");
+      }
+      return engine.handleRequest(req, ctx.server);
+    }
+  };
+  return { io, websocket, route };
+}
+export {
+  verifyJwt,
+  unauthorized,
+  streamSSE,
+  staticRoute,
+  serializeCookie,
+  resolveTraceId,
+  rateLimited,
+  parseSSE,
+  parseMultipart,
+  parseCookies,
+  notFound,
+  implement,
+  getClientInfo,
+  generateTraceId,
+  forbidden,
+  extractToken,
+  extractIp,
+  defineCookie,
+  createSocketIOServer,
+  createServer,
+  createRateLimiter,
+  createImplement,
+  createHandler,
+  createEventBus,
+  createCache,
+  createBearerResolver,
+  createAuthHook,
+  corsPreflightResponse,
+  corsHeaders,
+  conflict,
+  cacheHeaders,
+  badRequest,
+  appError,
+  AppError
+};

package/dist/server/logger.d.ts

@@ -0,0 +1,21 @@
+export declare function elapsedMs(startTime: bigint): number;
+/** Map an HTTP status to a log level. */
+export declare function levelForStatus(status: number): 'error' | 'warn' | 'info';
+/** The structured fields shared by every completed-request log line. */
+export declare function buildLogFields(method: string, path: string, status: number, durationMs: number, traceId: string): {
+    traceId: string;
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+};
+export interface RequestLog {
+    traceId: string;
+    startTime: bigint;
+}
+export declare function shouldLog(pathname: string, method: string): boolean;
+/** Open the timing window for a request. Development prints a `→` line. */
+export declare function logIncoming(req: Request, pathname: string, traceId: string): RequestLog;
+/** Close a request. Development: `←` line. Production: one structured JSON line. */
+export declare function logOutgoing(req: Request, pathname: string, status: number, log: RequestLog): void;
+//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/server/logger.ts"],"names":[],"mappings":"AA0CA,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,yCAAyC;AACzC,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAIxE;AAED,wEAAwE;AACxE,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAEvF;AA0BD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAID,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAGnE;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CASvF;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CACzB,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,UAAU,GACd,IAAI,CAoBN"}