@hypequery/serve 0.2.0 → 0.3.0

package/README.md

@@ -1,28 +1,23 @@
 # @hypequery/serve
 
-Code-first runtime for exposing hypequery analytics endpoints. Build typed query definitions, run them in-process, and add HTTP routes, docs, and adapters when needed.
+Code-first runtime for turning hypequery queries into reusable contracts, direct execution helpers, and HTTP routes.
 
-## Installation
+Use it when a local query should become something the rest of your app can call consistently.
+
+## Install
 
 ```bash
 npm install @hypequery/serve zod
 ```
 
-Peer dependency: `tsx@^4` (optional, for dev server)
+`tsx` is an optional peer dependency used by the local dev workflow.
 
 ## Quick Start
 
-Recommended path:
-
-1. Build a typed ClickHouse query
-2. Wrap it with `query({ ... })` when it becomes a reusable contract
-3. Add `serve({ queries })` when you need HTTP routes, docs, or adapters
-
 ```ts
-// analytics/queries.ts
 import { initServe } from '@hypequery/serve';
 import { z } from 'zod';
-import { db } from './client';
+import { db } from './client.js';
 
 const { query, serve } = initServe({
   context: () => ({ db }),
@@ -34,10 +29,9 @@ const weeklyRevenue = query({
   input: z.object({ startDate: z.string() }),
   query: ({ ctx, input }) =>
     ctx.db
-      .table('sales')
-      .select(['total_amount'])
-      .where('date', 'gte', input.startDate)
-      .sum('total_amount', 'total')
+      .table('orders')
+      .where('created_at', 'gte', input.startDate)
+      .sum('total', 'revenue')
       .execute(),
 });
 
@@ -45,948 +39,213 @@ export const api = serve({
   queries: { weeklyRevenue },
 });
 
-// Register an HTTP route
 api.route('/weeklyRevenue', api.queries.weeklyRevenue);
 ```
 
-```ts
-// analytics/server.ts
-import { api } from './queries';
-
-const server = await api.start({ port: 4000 });
-
-process.on('SIGTERM', async () => {
-  await server.stop();
-});
-```
-
-With the server running:
-- **Endpoint**: `POST http://localhost:4000/api/analytics/weeklyRevenue`
-- **Docs**: `http://localhost:4000/api/analytics/docs`
-- **OpenAPI**: `http://localhost:4000/api/analytics/openapi.json`
-
----
-
-## Core Concepts
-
-### 1. Create Queries And A Runtime
-
-#### `initServe<TContext, TAuth>(options)`
-
-Main entry point for creating typed query definitions and a serve runtime.
-
-**Parameters:**
-
-```ts
-interface ServeInitializerOptions<TContext, TAuth> {
-  // Context factory (runs per-request to inject dependencies)
-  context: TContext | ((opts: { request: ServeRequest; auth: TAuth | null }) => TContext | Promise<TContext>);
-
-  // Base path for all routes
-  basePath?: string;
-
-  // Authentication strategy
-  auth?: AuthStrategy<TAuth> | AuthStrategy<TAuth>[];
+Now you can:
 
-  // Global middlewares (run before every endpoint)
-  middlewares?: ServeMiddleware<any, any, TContext, TAuth>[];
+- call `api.execute('weeklyRevenue', { input: ... })` in process
+- expose the same query over HTTP
+- consume it from `@hypequery/react`
+- describe it for tools and agents
 
-  // Multi-tenancy configuration
-  tenant?: TenantConfig<TAuth>;
-
-  // Lifecycle hooks
-  hooks?: ServeLifecycleHooks<TAuth>;
-
-  // OpenAPI configuration
-  openapi?: OpenApiOptions;
-
-  // Docs UI configuration
-  docs?: DocsOptions;
-}
-```
-
-**Returns:**
+The same `api.execute(...)` call works for configured metrics and datasets:
 
 ```ts
-interface ServeInitializer<TContext, TAuth> {
-  query: QueryFactory<TContext, TAuth>;
-  serve<TQueries>(config: ServeConfig<TQueries, TContext, TAuth>): ServeBuilder<TQueries, TContext, TAuth>;
-}
-```
-
-Use `query({ ... })` to define a typed contract:
+import { initServe } from '@hypequery/serve';
+import { createQueryBuilder } from '@hypequery/clickhouse';
+import { dataset, dimension, measure } from '@hypequery/datasets';
 
-```ts
-const weeklyRevenue = query({
-  description: 'Calculate weekly revenue totals',
-  input: z.object({ startDate: z.string() }),
-  query: async ({ ctx, input }) => {
-    return ctx.db
-      .table('sales')
-      .where('date', 'gte', input.startDate)
-      .sum('amount', 'total')
-      .execute();
+const Orders = dataset('orders', {
+  source: 'orders',
+  dimensions: {
+    country: dimension.string(),
+  },
+  measures: {
+    revenue: measure.sum('amount'),
   },
 });
-```
 
-Use `serve({ queries })` to expose a typed runtime and optional HTTP surface:
-
-```ts
-interface ServeConfig<TQueries, TContext, TAuth> {
-  queries: TQueries;
-  basePath?: string;
-  auth?: AuthStrategy<TAuth> | AuthStrategy<TAuth>[];
-  middlewares?: ServeMiddleware<any, any, TContext, TAuth>[];
-  tenant?: TenantConfig<TAuth>;
-  hooks?: ServeLifecycleHooks<TAuth>;
-  openapi?: OpenApiOptions;
-  docs?: DocsOptions;
-}
-```
-
-**Example:**
-
-```ts
-const { query, serve } = initServe({
-  basePath: '/api',
-  context: async ({ auth }) => ({
-    db: createDatabase(),
-    userId: auth?.userId,
-  }),
-  auth: createBearerTokenStrategy({
-    validate: async (token) => {
-      const user = await verifyJWT(token);
-      return user ? { userId: user.id, role: user.role } : null;
-    },
-  }),
-});
+const revenue = Orders.metric('revenue', { measure: 'revenue' });
+const queryBuilder = createQueryBuilder({ url, username, password, database });
 
-const getUser = query({
-  input: z.object({ id: z.string() }),
-  query: async ({ ctx, input }) => {
-    return ctx.db.query.users.findFirst({
-      where: eq(users.id, input.id),
-    });
-  },
+const { serve } = initServe({
+  context: () => ({ db: queryBuilder }),  // ✅ Pass queryBuilder via context once
 });
 
-const weeklyRevenue = query({
-  description: 'Calculate weekly revenue totals',
-  input: z.object({ startDate: z.string() }),
-  query: async ({ ctx, input }) => {
-    return ctx.db
-      .table('sales')
-      .where('date', 'gte', input.startDate)
-      .sum('amount', 'total')
-      .execute();
-  },
+const api = serve({
+  metrics: { revenue },          // ✅ Auto-extracts queryBuilder from context
+  datasets: { orders: Orders },
 });
 
-export const api = serve({
-  queries: { getUser, weeklyRevenue },
+await api.execute('revenue', {
+  input: { dimensions: ['country'] },
 });
 
-api.route('/users/:id', api.queries.getUser, { method: 'GET' });
-api.route('/weeklyRevenue', api.queries.weeklyRevenue);
-```
-
----
-
-### 2. HTTP Adapters
-
-Adapters convert the framework-agnostic `ServeHandler` into platform-specific handlers.
-
-#### `createNodeHandler(handler)`
-
-Creates a Node.js HTTP handler for use with `http.createServer()` or Express.
-
-```ts
-import { createNodeHandler } from '@hypequery/serve';
-import { createServer } from 'http';
-
-const nodeHandler = createNodeHandler(api.handler);
-const server = createServer(nodeHandler);
-server.listen(3000);
-```
-
----
-
-#### `createFetchHandler(handler)`
-
-Creates a Web Fetch API handler for modern runtimes (Cloudflare Workers, Deno, Bun).
-
-```ts
-import { createFetchHandler } from '@hypequery/serve';
-
-const fetchHandler = createFetchHandler(api.handler);
-
-// Cloudflare Workers
-export default {
-  fetch: fetchHandler,
-};
-
-// Deno
-Deno.serve(fetchHandler);
-
-// Bun
-Bun.serve({
-  fetch: fetchHandler,
-  port: 3000,
+await api.execute('dataset:orders', {
+  input: { dimensions: ['country'], measures: ['revenue'] },
 });
 ```
 
----
-
-#### `createVercelEdgeHandler(handler)`
-
-Creates a Vercel Edge Runtime handler (uses Fetch API).
-
-```ts
-// pages/api/analytics.ts
-import { createVercelEdgeHandler } from '@hypequery/serve';
-import { api } from '@/analytics/server';
-
-export const config = { runtime: 'edge' };
-export default createVercelEdgeHandler(api.handler);
-```
-
----
-
-#### `createVercelNodeHandler(handler)`
-
-Creates a Vercel Node.js handler (uses Node HTTP).
-
-```ts
-// pages/api/analytics.ts
-import { createVercelNodeHandler } from '@hypequery/serve';
-import { api } from '@/analytics/server';
-
-export default createVercelNodeHandler(api.handler);
-```
-
----
-
-### 3. Authentication
-
-#### `createApiKeyStrategy<TAuth>(options)`
+## Main Ideas
 
-Creates an authentication strategy that validates API keys from headers or query parameters.
+### `query({ ... })`
 
-**Parameters:**
+Defines a typed contract:
 
-```ts
-interface ApiKeyStrategyOptions<TAuth> {
-  header?: string;        // Header name (default: "authorization")
-  queryParam?: string;    // Query param name (optional)
-  validate: (key: string, request: ServeRequest) => Promise<TAuth | null> | TAuth | null;
-}
-```
+- description
+- optional input schema
+- query implementation
 
-**Example:**
+Standalone queries can execute without creating a served API:
 
 ```ts
-import { createApiKeyStrategy, initServe } from '@hypequery/serve';
-
-const apiKeyAuth = createApiKeyStrategy({
-  header: 'x-api-key',
-  queryParam: 'apiKey',
-  validate: async (key) => {
-    const user = await db.query.apiKeys.findFirst({
-      where: eq(apiKeys.key, key),
-    });
-
-    if (!user || user.revoked) return null;
-
-    return {
-      userId: user.userId,
-      scopes: user.scopes,
-    };
-  },
-});
-
-const { query, serve } = initServe({
-  auth: apiKeyAuth,
-  context: () => ({ db }),
-});
-
-const revenue = query({
-  query: ({ ctx }) => ctx.db.table('sales').sum('amount', 'total').execute(),
+const topCustomers = query({
+  input: z.object({ limit: z.number().int().positive() }),
+  query: async ({ input }) =>
+    db
+      .table('orders')
+      .select(['customer_id'])
+      .sum('total', 'revenue')
+      .groupBy('customer_id')
+      .limit(input.limit)
+      .execute(),
 });
 
-const api = serve({
-  queries: { revenue },
+await topCustomers.execute({
+  input: { limit: 10 },
 });
 ```
 
-**Usage:**
+### `serve({ queries, metrics, datasets })`
 
-```bash
-# Header (preferred)
-curl -H "x-api-key: sk_live_abc123" http://localhost:3000/revenue
-
-# Query param (development only)
-curl http://localhost:3000/revenue?apiKey=sk_live_abc123
-```
-
----
-
-#### `createBearerTokenStrategy<TAuth>(options)`
+Builds a runtime around those contracts:
 
-Creates an authentication strategy that validates Bearer tokens (JWT, OAuth).
+- direct execution
+- route registration
+- docs and OpenAPI support
+- hooks, auth, and tenancy features when needed
 
-**Parameters:**
+## Common Example
 
 ```ts
-interface BearerTokenStrategyOptions<TAuth> {
-  header?: string;   // Header name (default: "authorization")
-  prefix?: string;   // Token prefix (default: "Bearer ")
-  validate: (token: string, request: ServeRequest) => Promise<TAuth | null> | TAuth | null;
-}
-```
-
-**Example:**
-
-```ts
-import { createBearerTokenStrategy, initServe } from '@hypequery/serve';
-import jwt from 'jsonwebtoken';
-
-const jwtAuth = createBearerTokenStrategy({
-  validate: async (token) => {
-    try {
-      const payload = jwt.verify(token, process.env.JWT_SECRET) as {
-        sub: string;
-        role: string;
-      };
-
-      return {
-        userId: payload.sub,
-        role: payload.role,
-      };
-    } catch {
-      return null;
-    }
-  },
-});
-
-const { query, serve } = initServe({
-  auth: jwtAuth,
-  context: () => ({ db: createDatabase() }),
-});
-
-const revenue = query({
-  query: ({ ctx }) => ctx.db.table('sales').sum('amount', 'total').execute(),
+const topCustomers = query({
+  description: 'Top customers by revenue',
+  input: z.object({ limit: z.number().int().positive().default(10) }),
+  query: ({ ctx, input }) =>
+    ctx.db
+      .table('orders')
+      .select(['customer_id'])
+      .sum('total', 'revenue')
+      .groupBy('customer_id')
+      .orderBy('revenue', 'DESC')
+      .limit(input.limit)
+      .execute(),
 });
 
-const api = serve({
-  queries: { revenue },
+export const api = serve({
+  queries: { topCustomers },
 });
-```
-
-**Usage:**
 
-```bash
-curl -H "Authorization: Bearer eyJhbGc..." http://localhost:3000/revenue
+api.route('/topCustomers', api.queries.topCustomers);
 ```
 
----
-
-### 4. Query Definition Options
+## Authentication
 
-`query({ ... })` accepts query logic plus optional metadata used for validation, docs, caching, and routing.
+Pass an auth strategy (or array of strategies) to `serve({ auth })` / `createAPI({ auth })`.
+When auth is configured, endpoints require authentication by default. Mark exceptions
+with `query.public()`.
 
-```ts
-interface QueryConfig<TInput, TOutput, TContext, TAuth> {
-  query: (args: QueryResolverArgs<TInput, TContext, TAuth>) => Promise<TOutput> | TOutput;
-  input?: ZodTypeAny;
-  output?: ZodTypeAny;
-  description?: string;
-  summary?: string;
-  tags?: string[];
-  method?: HttpMethod;
-  cache?: number | null;
-  auth?: AuthStrategy<TAuth>;
-  tenant?: Partial<TenantConfig<TAuth>>;
-  middlewares?: ServeMiddleware<any, any, TContext, TAuth>[];
-  metadata?: Record<string, unknown>;
-}
-```
-
-**Example:**
+For same-app APIs, prefer reading the host app's authenticated request context:
 
 ```ts
-const getAnalytics = query({
-  description: 'Returns aggregated analytics for the selected metric and date range.',
-  summary: 'Analytics totals by date range',
-  input: z.object({
-    startDate: z.string(),
-    endDate: z.string(),
-    metric: z.enum(['revenue', 'users', 'sessions']),
-  }),
-  tags: ['Analytics'],
-  cache: 300000,
-  query: async ({ ctx, input }) => {
-    const result = await ctx.db
-      .table('analytics')
-      .where('date', 'gte', input.startDate)
-      .where('date', 'lte', input.endDate)
-      .sum(input.metric, 'total')
-      .execute();
-
-    return result[0];
-  },
-});
-```
-
----
-
-### 5. Multi-Tenancy
-
-Hypequery supports multi-tenant applications with automatic tenant isolation.
-
-**Configuration:**
-
-```ts
-interface TenantConfig<TAuth> {
-  // Extract tenant ID from auth context
-  extract: (auth: TAuth) => string | null;
-
-  // Tenant isolation mode
-  mode?: 'manual' | 'auto-inject';  // Default: 'manual'
+import { createAPI, fromContext } from '@hypequery/serve';
 
-  // Column name for tenant filtering (required for auto-inject mode)
-  column?: string;
-
-  // Is tenant required? (default: true)
-  required?: boolean;
-
-  // Custom error message when tenant is missing
-  errorMessage?: string;
-}
-```
-
-**Example (Manual Mode):**
-
-```ts
-const { query, serve } = initServe({
-  tenant: {
-    extract: (auth) => auth?.tenantId ?? null,
-    mode: 'manual',  // You manually filter by tenantId
-    required: true,
-  },
-  context: async ({ auth }) => ({
-    db: createDatabase(),
-    tenantId: auth?.tenantId,
+const api = createAPI({
+  queryBuilder: db,
+  datasets,
+  auth: fromContext(({ request }) => {
+    const user = getUserFromRequest(request.raw);
+    return user
+      ? { userId: user.id, tenantId: user.orgId, roles: user.roles }
+      : null;
   }),
-});
-
-const getUsers = query({
-  query: async ({ ctx }) => {
-    // Manually filter by tenant
-    return ctx.db
-      .table('users')
-      .where('tenant_id', 'eq', ctx.tenantId)
-      .execute();
-  },
-});
-
-export const api = serve({
-  queries: { getUsers },
-});
-```
-
-**Example (Auto-Inject Mode):**
-
-```ts
-const { query, serve } = initServe({
   tenant: {
-    extract: (auth) => auth?.organizationId ?? null,
+    extract: (auth) => auth.tenantId,
+    column: 'tenant_id',
     mode: 'auto-inject',
-    column: 'organization_id',  // Column to filter on
-  },
-  context: async () => ({
-    db: createDatabase(),
-  }),
-});
-
-const getUsers = query({
-  query: async ({ ctx }) => {
-    // Tenant filter is automatically injected
-    return ctx.db
-      .table('users')
-      .select(['id', 'name'])
-      .execute();
-    // Equivalent to: SELECT id, name FROM users WHERE organization_id = <tenant_id>
   },
 });
-
-export const api = serve({
-  queries: { getUsers },
-});
-```
-
-**Per-query override (optional tenant, no auto-inject):**
-
-```ts
-const adminStats = query
-  .tenantOptional({ mode: 'manual' })
-  .query(async ({ ctx }) => {
-    if (ctx.tenantId) {
-      return ctx.db.table('stats').where('tenant_id', 'eq', ctx.tenantId).execute();
-    }
-    return ctx.db.table('stats').execute();
-  });
-
-export const api = serve({
-  queries: { adminStats },
-});
-```
-
----
-
-### 6. Client Configuration
-
-#### `extractClientConfig(api)`
-
-Extracts serializable client configuration from a `ServeBuilder`. Returns HTTP method information for each query, used by `@hypequery/react` to configure hooks.
-
-**Example:**
-
-```ts
-// Server-side API route
-import { api } from '@/analytics/server';
-import { extractClientConfig } from '@hypequery/serve';
-
-export async function GET() {
-  return Response.json(extractClientConfig(api));
-}
-
-// Returns:
-// {
-//   "weeklyRevenue": { "method": "GET" },
-//   "createSale": { "method": "POST" }
-// }
-```
-
-**Client-side usage:**
-
-```ts
-// lib/analytics.ts
-import { createHooks } from '@hypequery/react';
-import type { Api } from '@/analytics/server';
-
-const config = await fetch('/api/config').then(r => r.json());
-
-export const { useQuery, useMutation } = createHooks<Api>({
-  baseUrl: '/api/analytics',
-  config,  // Auto-configures HTTP methods
-});
-```
-
----
-
-#### `defineClientConfig(config)`
-
-Type-safe helper to manually define client configuration when you can't access the API object.
-
-**Example:**
-
-```ts
-import { defineClientConfig } from '@hypequery/serve';
-
-const config = defineClientConfig({
-  weeklyRevenue: { method: 'GET' },
-  createSale: { method: 'POST' },
-  updateProduct: { method: 'PUT' },
-  deleteOrder: { method: 'DELETE' },
-});
-
-export const { useQuery, useMutation } = createHooks<Api>({
-  baseUrl: '/api',
-  config,
-});
-```
-
----
-
-### 7. Development Server
-
-#### `serveDev(api, options?)`
-
-Starts a development server with enhanced logging and automatic documentation.
-
-**Parameters:**
-
-```ts
-interface ServeDevOptions {
-  port?: number;          // Default: 4000 or process.env.PORT
-  hostname?: string;      // Default: 'localhost'
-  quiet?: boolean;        // Suppress logs (default: false)
-  signal?: AbortSignal;   // Graceful shutdown signal
-  logger?: (message: string) => void;  // Custom logger
-}
-```
-
-**Example:**
-
-```ts
-import { serveDev } from '@hypequery/serve';
-import { api } from './analytics/server';
-
-await serveDev(api, {
-  port: 4000,
-  logger: (msg) => console.log(`[API] ${msg}`),
-});
-
-// Output:
-// [API] hypequery dev server running at http://localhost:4000
-// [API] Docs available at http://localhost:4000/docs
-```
-
----
-
-## Advanced Features
-
-### Middleware
-
-Middlewares run before query handlers and can modify context, validate permissions, or log requests.
-
-**Signature:**
-
-```ts
-type ServeMiddleware<TInput, TOutput, TContext, TAuth> = (
-  ctx: EndpointContext<TInput, TContext, TAuth>,
-  next: () => Promise<TOutput>
-) => Promise<TOutput>;
 ```
 
-**Example:**
+For cross-origin embedding, verify JWT bearer tokens with a shared secret or a
+provider JWKS:
 
 ```ts
-// Logging middleware
-const logMiddleware: ServeMiddleware<any, any, any, any> = async (ctx, next) => {
-  console.log(`[${ctx.request.method}] ${ctx.request.path}`);
-  const start = Date.now();
-  const result = await next();
-  console.log(`Completed in ${Date.now() - start}ms`);
-  return result;
-};
-
-// Permission middleware
-const requireAdmin: ServeMiddleware<any, any, any, { role: string }> = async (ctx, next) => {
-  if (ctx.auth?.role !== 'admin') {
-    throw new Error('Admin access required');
-  }
-  return next();
-};
+import { createJwtStrategy } from '@hypequery/serve';
 
-const { query, serve } = initServe({
-  context: () => ({ db: createDatabase() }),
-  middlewares: [logMiddleware],
+const auth = createJwtStrategy({
+  // Use `secret` for HS256 tokens you mint yourself.
+  secret: process.env.HYPEQUERY_AUTH_SECRET!,
+  issuer: 'https://your-app.example.com',
+  audience: 'hypequery-analytics',
 });
 
-const deleteUser = query({
-  input: z.object({ id: z.string() }),
-  middlewares: [requireAdmin],
-  query: async ({ input, ctx }) => {
-    // Only admins can reach here
-    return ctx.db.table('users').where('id', 'eq', input.id).execute();
-  },
-});
-
-const api = serve({
-  queries: { deleteUser },
-});
-```
-
----
-
-### Lifecycle Hooks
-
-Hooks provide observability into the request lifecycle.
-
-**Available Hooks:**
-
-```ts
-interface ServeLifecycleHooks<TAuth> {
-  // Before request processing
-  onRequestStart?: (event: {
-    requestId: string;
-    queryKey: string;
-    metadata: EndpointMetadata;
-    request: ServeRequest;
-    auth: TAuth | null;
-  }) => void | Promise<void>;
-
-  // After successful request
-  onRequestEnd?: (event: {
-    requestId: string;
-    queryKey: string;
-    metadata: EndpointMetadata;
-    request: ServeRequest;
-    auth: TAuth | null;
-    durationMs: number;
-    result: unknown;
-  }) => void | Promise<void>;
-
-  // On authentication failure
-  onAuthFailure?: (event: {
-    requestId: string;
-    queryKey: string;
-    metadata: EndpointMetadata;
-    request: ServeRequest;
-    auth: TAuth | null;
-    reason: 'MISSING' | 'INVALID';
-  }) => void | Promise<void>;
-
-  // On any error
-  onError?: (event: {
-    requestId: string;
-    queryKey: string;
-    metadata: EndpointMetadata;
-    request: ServeRequest;
-    auth: TAuth | null;
-    durationMs: number;
-    error: unknown;
-  }) => void | Promise<void>;
-}
-```
-
-**Example:**
-
-```ts
-const api = serve({
-  hooks: {
-    onRequestStart: async (event) => {
-      await analytics.track({
-        event: 'api_request_start',
-        queryKey: event.queryKey,
-        userId: event.auth?.userId,
-      });
-    },
-
-    onError: async (event) => {
-      await errorReporting.captureException(event.error, {
-        queryKey: event.queryKey,
-        requestId: event.requestId,
-      });
-    },
-  },
-  queries: { /* ... */ },
+const providerAuth = createJwtStrategy({
+  // Use `jwksUri` for Auth0/Clerk/Cognito/etc.
+  jwksUri: 'https://example.auth0.com/.well-known/jwks.json',
+  issuer: 'https://example.auth0.com/',
+  audience: 'https://api.example.com',
 });
 ```
 
----
-
-### OpenAPI Configuration
-
-**Options:**
+For signed embedding, mint short-lived analytics tokens server-side:
 
 ```ts
-interface OpenApiOptions {
-  enabled?: boolean;       // Enable OpenAPI endpoint (default: true)
-  path?: string;           // OpenAPI JSON path (default: '/openapi.json')
-  info?: {
-    title?: string;        // API title (default: 'Hypequery API')
-    version?: string;      // API version (default: '1.0.0')
-    description?: string;  // API description
-  };
-  servers?: Array<{
-    url: string;
-    description?: string;
-  }>;
-}
-```
-
-**Example:**
+import { createAnalyticsTokenIssuer } from '@hypequery/serve';
 
-```ts
-const api = serve({
-  openapi: {
-    path: '/api-schema.json',
-    info: {
-      title: 'Analytics API',
-      version: '2.0.0',
-      description: 'Real-time analytics and reporting API',
-    },
-    servers: [
-      { url: 'https://api.example.com', description: 'Production' },
-      { url: 'http://localhost:4000', description: 'Development' },
-    ],
-  },
-  queries: { /* ... */ },
+const issueAnalyticsToken = createAnalyticsTokenIssuer({
+  secret: process.env.HYPEQUERY_AUTH_SECRET!,
+  expiresIn: '15m',
+  issuer: 'https://your-app.example.com',
+  audience: 'hypequery-analytics',
 });
-```
-
----
-
-### Documentation UI
 
-**Options:**
-
-```ts
-interface DocsOptions {
-  enabled?: boolean;  // Enable docs UI (default: true)
-  path?: string;      // Docs UI path (default: '/docs')
-  title?: string;     // Page title (default: 'API Documentation')
-}
-```
-
-**Example:**
-
-```ts
-const api = serve({
-  docs: {
-    path: '/api-docs',
-    title: 'Analytics API Reference',
-  },
-  queries: { /* ... */ },
+app.get('/api/analytics/token', requireUser, async (req, res) => {
+  res.json({
+    token: await issueAnalyticsToken({
+      userId: req.user.id,
+      tenantId: req.user.orgId,
+      roles: req.user.roles,
+    }),
+  });
 });
 ```
 
----
-
-## Deployment Examples
-
-### Vercel (Edge Runtime)
-
-```ts
-// pages/api/analytics/[...path].ts
-import { createVercelEdgeHandler } from '@hypequery/serve';
-import { api } from '@/analytics/server';
-
-export const config = { runtime: 'edge' };
-export default createVercelEdgeHandler(api.handler);
-```
-
----
-
-### Cloudflare Workers
-
-```ts
-// src/index.ts
-import { createFetchHandler } from '@hypequery/serve';
-import { api } from './analytics/server';
-
-const handler = createFetchHandler(api.handler);
-
-export default {
-  fetch: handler,
-};
-```
-
----
-
-### Express.js
-
-```ts
-// server.ts
-import express from 'express';
-import { createNodeHandler } from '@hypequery/serve';
-import { api } from './analytics/server';
-
-const app = express();
-const analyticsHandler = createNodeHandler(api.handler);
-
-app.use('/api/analytics', analyticsHandler);
-app.listen(3000);
-```
-
----
-
-### Next.js App Router
-
-```ts
-// app/api/analytics/[...path]/route.ts
-import { createFetchHandler } from '@hypequery/serve';
-import { api } from '@/analytics/server';
-
-const handler = createFetchHandler(api.handler);
-
-export { handler as GET, handler as POST, handler as PUT, handler as DELETE };
-```
-
----
-
-## TypeScript
+`createApiKeyStrategy` and `createBearerTokenStrategy` remain available for custom
+authentication systems.
 
-All functions are fully typed with automatic inference:
+> **Rate limiting:** the default `RateLimitStore` is in-memory and therefore
+> per-instance. Behind multiple instances, supply a shared store (e.g. Redis) by
+> implementing the `RateLimitStore` interface.
 
-```ts
-import { initServe } from '@hypequery/serve';
-import { z } from 'zod';
+## Adapters And Runtimes
 
-const { query, serve } = initServe({
-  context: async ({ auth }) => ({
-    db: createDatabase(),
-    userId: auth?.userId,
-  }),
-});
+`@hypequery/serve` can be used behind different runtimes and adapters, but most users should start with the standard `initServe(...).serve(...)` path and the CLI dev server.
 
-const getUser = query({
-  input: z.object({ id: z.string() }),
-  query: async ({ ctx, input }) => {
-    // input: { id: string }
-    // ctx: { db: Database; userId: string | undefined }
-    return ctx.db
-      .table('users')
-      .where('id', 'eq', input.id)
-      .select(['name', 'email'])
-      .limit(1)
-      .execute();
-  },
-});
+If you need framework-specific integration, see the docs for:
 
-export const api = serve({
-  queries: { getUser },
-});
+- Node handlers
+- Fetch handlers
+- OpenAPI generation
+- auth and middleware
 
-// Execute with type safety (aliases: api.execute, api.client)
-const result = await api.run('getUser', { input: { id: '123' } });
-const user = result[0];
-// user: { name: string; email: string }
-```
-
----
-
-## Error Handling
-
-All errors follow a consistent format:
-
-```ts
-interface ErrorEnvelope {
-  error: {
-    type: 'VALIDATION_ERROR' | 'UNAUTHORIZED' | 'NOT_FOUND' | 'INTERNAL_SERVER_ERROR';
-    message: string;
-    details?: Record<string, unknown>;
-  };
-}
-```
-
-**Example Error Response:**
-
-```json
-{
-  "error": {
-    "type": "VALIDATION_ERROR",
-    "message": "Request validation failed",
-    "details": {
-      "issues": [
-        {
-          "code": "invalid_type",
-          "expected": "string",
-          "received": "number",
-          "path": ["startDate"],
-          "message": "Expected string, received number"
-        }
-      ]
-    }
-  }
-}
-```
+## Docs
 
----
+- [Core concepts](https://hypequery.com/docs/core-concepts)
+- [Serve runtime reference](https://hypequery.com/docs/reference/runtime)
+- [CLI reference](https://hypequery.com/docs/reference/api/cli)
 
 ## License
 
-Apache-2.0
+Apache-2.0.