stitchkit 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Listov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,376 @@
-# StitchKit
+<p align="center">
+  <strong>Contract-first backend framework for Bun.</strong><br/>
+  Define your API once — get an HTTP API, MCP tools, AI-agent tools and a typed client.
+</p>
 
-Contract-first fullstack framework for Bun.
+<p align="center">
+  <a href="https://www.npmjs.com/package/stitchkit"><img src="https://img.shields.io/npm/v/stitchkit?color=2563eb" alt="npm version" /></a>
+  <a href="https://github.com/max-listov/stitchkit/actions/workflows/ci.yml"><img src="https://github.com/max-listov/stitchkit/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/stitchkit?color=2563eb" alt="MIT license" /></a>
+  <img src="https://img.shields.io/badge/runtime-Bun-fbf0df?logo=bun&logoColor=000" alt="Bun" />
+</p>
 
-One `defineContract()` → HTTP API + MCP tools + Agent tools + typed client + React Query hooks.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/max-listov/stitchkit/master/assets/infographic-hero.jpg" alt="One contract becomes an HTTP API, MCP tools, AI-agent tools and a typed client" width="100%" />
+</p>
 
-Coming soon.
+<p align="center">
+  <em>One <code>defineContract()</code> → an HTTP API, MCP tools and AI-agent tools on the server — plus a fully-typed client to call them.</em>
+</p>
+
+---
+
+## Why
+
+- **One contract, four surfaces.** Define your API once — get HTTP routes, MCP tools (for Claude/Cursor), AI SDK tools (for agents), and a typed client.
+- **Zero HTTP framework deps.** Built on `Bun.serve()` directly. No Hono, no Elysia, no Express.
+- **Fullstack type safety.** Server handlers, client calls, MCP tools — all typed from the same contract.
+- **Small.** ~4000 lines of source. No magic, no codegen, no build step.
+- **Thin over what you already use.** WebSocket = Socket.IO (`createSocketIOClient` / `createSocketIOServer`). React data layer = `react-query-kit` (`createCursorQuery`). stitchkit owns the contract and the transport — not its own competing WebSocket or hook engine.
+
+### The problem it solves
+
+A modern backend exposes the *same* operations three ways — an HTTP API for the
+app, MCP tools for assistants like Claude and Cursor, and tool definitions for AI
+agents. Written by hand, that is one surface described three times: three places
+to drift, three places to keep in sync. stitchkit collapses them into a single
+contract — change it once, every surface and the typed client move together.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/max-listov/stitchkit/master/assets/infographic-compare.jpg" alt="Without stitchkit: the same API hand-written three times. With stitchkit: one contract drives them all." width="100%" />
+</p>
+
+## Status
+
+Pre-1.0. The core is stable and covered by tests, but the public API may still
+change between minor versions until 1.0. Bun-only — there is no Node/Deno
+compatibility layer.
+
+## Install
+
+```bash
+bun add stitchkit
+```
+
+## Import policy
+
+Browser code imports browser-safe entrypoints:
+
+```ts
+import { defineContract, createClient, createHttpClient } from 'stitchkit'
+import { createSocketIOClient } from 'stitchkit'
+import { createCursorQuery, createCacheBridge } from 'stitchkit/react'
+import { parseSSE } from 'stitchkit'
+```
+
+Server code imports server entrypoints:
+
+```ts
+import { createServer, createHandler, implement } from 'stitchkit/server'
+import { createSocketIOServer, createAuthHook } from 'stitchkit/server'
+import { createMcpHandler, mountAgent } from 'stitchkit/tools'
+```
+
+The root `stitchkit` entrypoint is browser-safe. Server and tool code live behind `stitchkit/server` and `stitchkit/tools`.
+
+## Quick Start
+
+### 1. Define a contract
+
+```ts
+// shared/contracts.ts
+import { defineContract } from 'stitchkit'
+import { z } from 'zod'
+
+const UserSchema = z.object({ id: z.string(), name: z.string() })
+const CreateUserSchema = z.object({ name: z.string() })
+const IdSchema = z.object({ id: z.string() })
+
+export const users = defineContract({ prefix: 'users' }, {
+  list:   { method: 'GET',    path: '/',    desc: 'List all users',  output: z.array(UserSchema) },
+  create: { method: 'POST',   path: '/',    desc: 'Create a user',   input: CreateUserSchema, output: UserSchema },
+  get:    { method: 'GET',    path: '/:id', desc: 'Get user by ID',  params: IdSchema, output: UserSchema },
+  delete: { method: 'DELETE', path: '/:id', desc: 'Delete a user',   params: IdSchema },
+})
+```
+
+### 2. Implement handlers
+
+```ts
+// server/index.ts
+import { implement, createServer } from 'stitchkit/server'
+import { users } from '../shared/contracts'
+
+const service = implement(users, {
+  list:   (ctx) => db.users.findMany(),
+  create: (ctx) => db.users.create({ name: ctx.input.name }),
+  get:    (ctx) => db.users.findById(ctx.params.id),
+  delete: (ctx) => db.users.delete(ctx.params.id),
+})
+
+createServer({ services: [service], port: 3000 })
+```
+
+### 3. Use from the client
+
+```ts
+// client/api.ts
+import { createClient, createHttpClient } from 'stitchkit'
+import { users } from '../shared/contracts'
+
+const http = createHttpClient({ baseUrl: '/api' })
+export const api = createClient(users, http)
+
+await api.list()                  // GET /users → User[]
+await api.create({ name: 'Max' }) // POST /users → User
+await api.get({ id: '123' })      // GET /users/123 → User
+```
+
+For many contracts at once, use `createClients(contractRegistry, http)`.
+
+### 4. React data layer (react-query-kit)
+
+stitchkit does not ship its own hook engine — pair the typed client with
+[`react-query-kit`](https://github.com/liaoliao666/react-query-kit), wrapping
+the client methods directly:
+
+```ts
+import { createMutation, createQuery } from 'react-query-kit'
+import { api } from './api'
+
+export const useUsers = createQuery({ queryKey: ['users'], fetcher: () => api.list() })
+export const useCreateUser = createMutation({ mutationFn: api.create })
+```
+
+For cursor-paginated lists, `createCursorQuery` is the canonical helper:
+
+```ts
+import { createCursorQuery } from 'stitchkit/react'
+import { api } from './api'
+
+export const useFeed = createCursorQuery({ queryKey: ['feed'], endpoint: api.feed.list })
+```
+
+It injects `cursor` from the page param and bakes in `getNextPageParam`. Page
+size is the server's call — the contract's `limit` default — never the client's.
+
+### 5. MCP tools (for Claude, Cursor, etc.)
+
+```ts
+import { createMcpHandler } from 'stitchkit/tools'
+
+const handleMcp = createMcpHandler({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth: (req) => resolveApiKey(req),     // → identity, or null for 401
+  services: [service],                   // contract endpoints with expose: ['MCP']
+})
+// mount `handleMcp` under /mcp — no @modelcontextprotocol/sdk import in your app
+```
+
+### 6. AI Agent tools
+
+```ts
+import { mountAgent } from 'stitchkit/tools'
+import { generateText } from 'ai'
+
+const tools = mountAgent(service, { context: { userId: 'agent-1' } })
+const result = await generateText({ model, tools, prompt: 'Create a user named Max' })
+```
+
+### 7. WebSocket (Socket.IO)
+
+stitchkit's WebSocket layer is Socket.IO — `polling` fallback, heartbeat, acks,
+a mature client. The wrappers cover the boilerplate.
+
+```ts
+// Server
+import { createServer, createSocketIOServer } from 'stitchkit/server'
+
+const socket = createSocketIOServer<ServerToClientEvents, ClientToServerEvents>({
+  cors: { origin: 'https://app.example.com' },
+})
+
+socket.io.on('connection', (s) => { /* rooms, handshake auth — your domain logic */ })
+
+createServer({
+  services: [service],
+  websocket: socket.websocket,    // → Bun.serve
+  rawRoutes: [socket.route],      // ready /socket.io/* route
+})
+```
+
+```ts
+// Client
+import { createSocketIOClient } from 'stitchkit'
+
+const socket = createSocketIOClient<ServerToClientEvents, ClientToServerEvents>({
+  url: 'https://api.example.com',
+})
+socket.connect()
+socket.on('notification', (data) => console.log(data))  // typed
+socket.emit('join', { room: 'r1' })                     // typed
+```
+
+### 8. Cache Bridge
+
+Sync Socket.IO events into the TanStack Query cache. Transport-agnostic — it
+takes any emitter with `on(event, handler) => unsubscribe` (the
+`createSocketIOClient` result qualifies).
+
+```ts
+import { createCacheBridge } from 'stitchkit/react'
+
+const bridge = createCacheBridge({
+  socket,
+  queryClient,
+  handlers: {
+    notification: (data, ctx) => {
+      if (ctx.isFresh(['notes'])) return            // skip echo of own mutation
+      ctx.queryClient.setQueryData(['notes'], data)
+    },
+  },
+})
+bridge.connect()
+// in a mutation: onSuccess: () => bridge.markFresh(['notes'])
+```
+
+### 9. SSE Streaming
+
+```ts
+import { streamSSE } from 'stitchkit/server'   // server: AsyncGenerator → SSE Response
+import { parseSSE } from 'stitchkit'           // client: Response → AsyncGenerator
+```
+
+## Features
+
+| Feature | API |
+|---------|-----|
+| **Contract** | `defineContract()` — single source of truth for your API |
+| **HTTP Server** | `createServer()` / `createHandler()` — Bun.serve, validation, hooks, raw routes |
+| **MCP Tools** | `createMcpHandler()` / `mountMcp()` — MCP tools from contracts |
+| **Agent Tools** | `mountAgent()` — Vercel AI SDK tools from contracts |
+| **Typed Client** | `createClient()` / `createClients()` — typed fetch from contracts |
+| **Cursor Pagination** | `createCursorQuery()` — `react-query-kit` infinite query from a contract method |
+| **WebSocket** | `createSocketIOClient()` / `createSocketIOServer()` — typed Socket.IO wrappers |
+| **Cache Bridge** | `createCacheBridge()` — socket events → TanStack Query cache |
+| **Auth** | `createAuthHook()` / `createBearerResolver()` — scope-aware auth from `contract.scope` |
+| **SSE Streaming** | `streamSSE()` / `parseSSE()` — async generator ↔ SSE |
+| **Events** | `createEventBus<EventMap>()` — typed in-process pub/sub |
+| **Multipart** | `parseMultipart()` — file upload with field validation |
+| **Rate Limiting** | `createRateLimiter()` — token bucket, per-key |
+| **Cache** | `createCache()` — in-memory with TTL + `cacheHeaders()` |
+| **Errors** | `AppError`, `notFound()`, `badRequest()`, `unauthorized()` |
+
+## How it compares
+
+A modern backend exposes the same operations as an HTTP API, as MCP tools and as
+AI-agent tools. Most stacks make you describe each surface separately.
+
+| | **Without stitchkit** | **With stitchkit** |
+|--|----------------------|--------------------|
+| Define an operation | once per surface — HTTP, MCP, agent (3×) | once — `defineContract()` |
+| Keep the surfaces in sync | manual; they drift apart | cannot drift — one source |
+| Typed client | hand-written, or a codegen step | inferred from the contract |
+| Expose a new surface | re-describe every endpoint | flip `expose` — already typed |
+
+Versus other typed-API tools:
+
+| Capability | stitchkit | tRPC | ts-rest | Hono / Elysia |
+|------------|:---:|:---:|:---:|:---:|
+| Contract is plain data — no decorators, no codegen | ✅ | ⚠️ router type | ✅ | ❌ |
+| Inferred typed client | ✅ | ✅ | ✅ | ⚠️ Eden / hc |
+| Plain HTTP REST routes | ✅ | ⚠️ RPC-style | ✅ | ✅ |
+| **MCP tools from the same contract** | ✅ | ❌ | ❌ | ❌ |
+| **AI-agent tools from the same contract** | ✅ | ❌ | ❌ | ❌ |
+| No HTTP-framework dependency | ✅ | ✅ | ✅ | — it is one |
+
+The line no other tool draws: **the same contract becomes MCP tools and AI-agent
+tools** — not just an HTTP API and a client. That is what stitchkit is for.
+
+## Lifecycle Hooks
+
+```ts
+createServer({
+  services: [service],
+  hooks: {
+    onRequest(req) { },              // logging, rate limiting
+    beforeHandle(ctx, endpoint) { }, // auth, scope checks
+    afterHandle(ctx, result) { },    // transform, cache headers
+    onError(ctx, error) { },         // error formatting
+  },
+})
+```
+
+## Auth & Scopes
+
+Contracts carry a `scope`; `createAuthHook` enforces it on every transport from
+one declarative `rules` map:
+
+```ts
+import { createAuthHook, createBearerResolver } from 'stitchkit/server'
+
+const authHook = createAuthHook<User>({
+  resolve: (ctx) => resolveSession(ctx),
+  rules: {
+    public: 'public',
+    user: 'authenticated',
+    admin: (user) => user.isAdmin,
+  },
+})
+
+createServer({ services, hooks: { beforeHandle: authHook } })
+```
+
+## Dependencies
+
+stitchkit ships with **one runtime dependency**. Everything else is an optional
+peer — an install pulls in only what the project actually uses.
+
+| Dependency | Kind | Why this one |
+|------------|------|--------------|
+| `ky` | bundled, runtime | The HTTP client behind the typed client — ~13 KB, `fetch`-based, with retry, hooks and timeouts built in. The only thing stitchkit installs for you. |
+| `zod` | peer, **required** | Schemas are the single source of truth. A peer so your app and stitchkit share **one** `zod` instance — `z.infer` types and `instanceof` checks break across two copies. |
+| `@modelcontextprotocol/sdk` | peer, optional | Only `stitchkit/tools` — the MCP server. |
+| `ai` | peer, optional | Only `stitchkit/tools` — agent tools (Vercel AI SDK). |
+| `@tanstack/react-query` + `react-query-kit` | peer, optional | Only `stitchkit/react` — `createCursorQuery`, `createCacheBridge`. |
+| `socket.io` / `@socket.io/bun-engine` / `socket.io-client` | peer, optional | Only the Socket.IO wrappers. |
+
+**Why peers, not bundled.** A peer is resolved once, by your app — framework and
+app code share a single instance. Bundled copies would double `zod`, split the
+`react` hook runtime and break `instanceof`. Optional peers mean an app that
+never touches MCP never installs the MCP SDK. → [DECISIONS.md](./docs/DECISIONS.md#adr-0011)
+
+The framework itself is small — ~4000 lines, no codegen, no build step in your app.
+
+## Example
+
+A complete runnable app lives in [`packages/starter`](./packages/starter) — a
+notes CRUD with a contract, a typed client, `react-query-kit` hooks and a
+Socket.IO live-reload.
+
+## Documentation
+
+This README is the quick start. The full guide and API reference are in
+[`docs/`](./docs/README.md):
+
+- **Guide** — [getting started](./docs/guide/getting-started.md) ·
+  [contracts](./docs/guide/contracts.md) ·
+  [HTTP server](./docs/guide/server.md) ·
+  [typed client](./docs/guide/client.md) ·
+  [MCP & agents](./docs/guide/mcp-and-agents.md) ·
+  [realtime](./docs/guide/realtime.md) ·
+  [auth & errors](./docs/guide/auth-and-errors.md) ·
+  [testing & deployment](./docs/guide/testing-and-deployment.md)
+- **[API reference](./docs/api/reference.md)** — every export, by entrypoint.
+- **[Roadmap](./ROADMAP.md)** — where stitchkit is going.
+- **[Architecture decisions](./docs/DECISIONS.md)** — the *why* behind the design.
+
+## Contributing
+
+Issues and PRs are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Released
+changes are in [CHANGELOG.md](./CHANGELOG.md); security issues go through
+[SECURITY.md](./SECURITY.md).
+
+## License
+
+[MIT](./LICENSE) © Max Listov

package/dist/browser/client.d.ts

@@ -0,0 +1,30 @@
+import type { ContractDef, EndpointDef, TypedHttpClient } from '../contract';
+import { type HttpClient as HttpAdapter } from './http';
+/** Config for the built-in fetch client — used when no `HttpClient` is passed. */
+export interface ClientConfig {
+    baseUrl: string;
+    headers?: Record<string, string> | (() => Record<string, string>);
+    credentials?: RequestCredentials;
+    onError?: (status: number, body: unknown) => void;
+}
+/** Per-contract client tweaks — a dynamic URL `pathPrefix` and the keys it consumes. */
+export interface ContractClientConfig {
+    pathPrefix?: string | ((args: Record<string, unknown>) => string);
+    stripPrefixKeys?: string[];
+}
+/**
+ * Build a fully-typed client from a contract. Every endpoint becomes a typed
+ * method — arguments and result inferred from its schemas. Pass an `HttpClient`
+ * (from `createHttpClient`) for cookie auth, SSR and retry, or a plain
+ * `ClientConfig` for a bare fetch client.
+ */
+export declare function createClient<T extends Record<string, EndpointDef>>(contract: ContractDef<T, string>, configOrClient: ClientConfig | HttpAdapter, contractConfig?: ContractClientConfig): TypedHttpClient<T>;
+/**
+ * Batch form of `createClient` — one fully-typed client per contract, built
+ * from a `name → contract` registry. Each key keeps its own client type, so
+ * the project lists its contracts once and gets the whole typed API.
+ */
+export declare function createClients<T extends Record<string, ContractDef<Record<string, EndpointDef>, string>>>(contracts: T, http: HttpAdapter): {
+    [K in keyof T]: TypedHttpClient<T[K]['endpoints']>;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/browser/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/browser/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EAEL,KAAK,UAAU,IAAI,WAAW,EAG/B,MAAM,QAAQ,CAAC;AA8ChB,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClE,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;CACnD;AAED,wFAAwF;AACxF,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,CAAC;IAClE,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAChE,QAAQ,EAAE,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,EAChC,cAAc,EAAE,YAAY,GAAG,WAAW,EAC1C,cAAc,CAAC,EAAE,oBAAoB,GACpC,eAAe,CAAC,CAAC,CAAC,CAepB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC,EAC1E,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;CAAE,CAKzF"}

package/dist/browser/http.d.ts

@@ -0,0 +1,77 @@
+import type { ErrorEnvelope } from '../contract';
+export type ApiEvent = {
+    type: 'unauthorized';
+} | {
+    type: 'network_error';
+} | {
+    type: 'logout';
+};
+export type ApiEventListener = (event: ApiEvent) => void;
+export declare class ApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    readonly hint?: string | undefined;
+    constructor(code: string, status?: number, details?: unknown | undefined, message?: string, hint?: string | undefined);
+    static is(error: unknown): error is ApiError;
+}
+/**
+ * Parse a response body into an `ErrorEnvelope['error']` — the default
+ * `HttpClientConfig.parseError`. Returns `null` when the body is not a
+ * stitchkit error envelope. Shared by `createHttpClient` and `createClient`.
+ */
+export declare function parseApiErrorBody(body: unknown): ErrorEnvelope['error'] | null;
+export type HeaderProvider = Record<string, string> | (() => Record<string, string> | null | undefined);
+/** Configuration for `createHttpClient`. */
+export interface HttpClientConfig {
+    baseUrl: string;
+    timeout?: number;
+    credentials?: RequestCredentials;
+    /**
+     * Transport retry. Defaults: 2 attempts, GET only, network errors only
+     * (empty `statusCodes`). Retrying a server that *responded* (5xx) belongs
+     * in the data layer (e.g. TanStack Query), not the transport — keeping it
+     * here too would multiply attempts. Override per project if really needed.
+     */
+    retry?: {
+        limit?: number;
+        methods?: string[];
+        statusCodes?: number[];
+    };
+    parseError?: (body: unknown) => ErrorEnvelope['error'] | null;
+    authEndpoints?: string[];
+    /**
+     * Extra headers added to every request. A function is re-evaluated per
+     * request — use it for runtime tokens (e.g. a short-lived auth token).
+     */
+    headers?: HeaderProvider;
+}
+type ParamValue = string | number | boolean | undefined;
+type ParamArrayValue = Array<string | number>;
+export interface RequestOptions {
+    params?: Record<string, ParamValue | ParamArrayValue>;
+    timeout?: number;
+    responseType?: 'json' | 'blob';
+}
+/** The HTTP transport adapter `createClient` builds typed methods on. */
+export interface HttpClient {
+    get<T>(url: string, options?: RequestOptions): Promise<T>;
+    post<T>(url: string, data?: unknown, options?: RequestOptions): Promise<T>;
+    put<T>(url: string, data?: unknown, options?: RequestOptions): Promise<T>;
+    patch<T>(url: string, data?: unknown, options?: RequestOptions): Promise<T>;
+    delete<T>(url: string, options?: RequestOptions): Promise<T>;
+    setServerContext(cookies: string): void;
+    subscribe(listener: ApiEventListener): () => void;
+    /** Mark the client as logged out — suppresses further `unauthorized` events. */
+    logout(): void;
+    /** Clear the logged-out flag — call after a successful re-login. */
+    resetLogoutState(): void;
+}
+/**
+ * Create a Ky-based `HttpClient` — the transport `createClient` builds on.
+ * Handles cookie auth, SSR cookie forwarding, error parsing into `ApiError`, a
+ * `401 → unauthorized` event stream, and safe transport retry.
+ */
+export declare function createHttpClient(config: HttpClientConfig): HttpClient;
+export {};
+//# sourceMappingURL=http.d.ts.map

package/dist/browser/http.d.ts.map

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

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

@@ -0,0 +1,69 @@
+/**
+ * Typed Socket.IO client — the family WebSocket client.
+ *
+ * The whole family runs on Socket.IO (`polling` fallback, heartbeat, acks,
+ * mature reconnection) — not a hand-rolled WebSocket. Every project copied the
+ * same ~150-line client: `io()` config, connection-state machine, a typed
+ * `on/emit`, a connection-change subscription. `createSocketIOClient` is that
+ * shared kernel.
+ *
+ * Subscriptions are durable: `on()` registers a handler once and the client
+ * re-attaches it onto every socket it builds — so a handler survives an
+ * explicit `disconnect()` / `connect()` cycle, and (because re-attach happens
+ * before `socket.connect()`) no handshake-time event is ever missed. A thin
+ * per-project layer can therefore subscribe once at construction.
+ *
+ * Auth identity (`userId`, `clientId`) is project-specific — it arrives in an
+ * app `authenticated` event — so it stays in that per-project layer on top.
+ * This client owns only the transport: connection lifecycle + typed events.
+ *
+ * The returned client satisfies `CacheBridgeSocket` (`on()` returns an
+ * unsubscribe), so it plugs straight into `createCacheBridge`.
+ */
+import type { EventsMap } from '@socket.io/component-emitter';
+/**
+ * Socket.IO event map — `{ event: (...args) => void }`. Aliases Socket.IO's
+ * own `EventsMap` constraint, which intentionally maps to `any`: that is what
+ * lets a plain `interface ServerToClientEvents { … }` (no index signature) be
+ * passed as a type argument. Per-event typing is fully preserved on the
+ * public `on` / `emit` signatures.
+ */
+export type SocketEventMap = EventsMap;
+export interface SocketIOClientConfig {
+    /** Server origin, e.g. `https://api.example.com`. */
+    url: string;
+    /** Socket.IO endpoint path. Default `/socket.io/`. */
+    path?: string;
+    /** Send cookies on the handshake (cookie-based auth). Default `true`. */
+    withCredentials?: boolean;
+    /** Transports, in preference order. Default `['websocket', 'polling']`. */
+    transports?: Array<'websocket' | 'polling'>;
+    /** Reconnection attempts. Default `Infinity`. */
+    reconnectionAttempts?: number;
+    /** Initial reconnection delay (ms). Default `1000`. */
+    reconnectionDelay?: number;
+    /** Max reconnection delay (ms). Default `5000`. */
+    reconnectionDelayMax?: number;
+    /** Connection timeout (ms). Default `20000`. */
+    timeout?: number;
+}
+export interface SocketIOClient<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap> {
+    /** Create the socket (if absent) and connect. Idempotent. */
+    connect(): void;
+    /** Disconnect and drop the socket instance. */
+    disconnect(): void;
+    /** True while the underlying socket is connected. */
+    readonly connected: boolean;
+    /**
+     * Subscribe to a server → client event. Returns an unsubscribe. The handler
+     * is durable — it is re-attached onto every socket the client builds, so it
+     * survives a `disconnect()` / `connect()` cycle.
+     */
+    on<E extends keyof TServerEvents & string>(event: E, handler: TServerEvents[E]): () => void;
+    /** Emit a client → server event. No-op while disconnected. */
+    emit<E extends keyof TClientEvents & string>(event: E, ...args: Parameters<TClientEvents[E]>): void;
+    /** Subscribe to connection up/down changes. Returns an unsubscribe. */
+    onConnectionChange(listener: (connected: boolean) => void): () => void;
+}
+export declare function createSocketIOClient<TServerEvents extends SocketEventMap, TClientEvents extends SocketEventMap>(config: SocketIOClientConfig): SocketIOClient<TServerEvents, TClientEvents>;
+//# sourceMappingURL=socket-io.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"socket-io.d.ts","sourceRoot":"","sources":["../../src/browser/socket-io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAM9D;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC;AAEvC,MAAM,WAAW,oBAAoB;IACnC,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,UAAU,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAC5C,iDAAiD;IACjD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc,CAC7B,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc;IAEpC,6DAA6D;IAC7D,OAAO,IAAI,IAAI,CAAC;IAChB,+CAA+C;IAC/C,UAAU,IAAI,IAAI,CAAC;IACnB,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,aAAa,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IAC5F,8DAA8D;IAC9D,IAAI,CAAC,CAAC,SAAS,MAAM,aAAa,GAAG,MAAM,EACzC,KAAK,EAAE,CAAC,EACR,GAAG,IAAI,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,GACpC,IAAI,CAAC;IACR,uEAAuE;IACvE,kBAAkB,CAAC,QAAQ,EAAE,CAAC,SAAS,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACxE;AAED,wBAAgB,oBAAoB,CAClC,aAAa,SAAS,cAAc,EACpC,aAAa,SAAS,cAAc,EACpC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAAC,aAAa,EAAE,aAAa,CAAC,CAoF5E"}

package/dist/browser/stream.d.ts

@@ -0,0 +1,2 @@
+export { type ParseSSEOptions, parseSSE } from '../server/stream';
+//# sourceMappingURL=stream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/browser/stream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC"}