@hypequery/serve 0.15.1 → 0.15.3

package/README.md

@@ -1,8 +1,8 @@
 # @hypequery/serve
 
-Code-first runtime for turning hypequery queries into reusable contracts, direct execution helpers, and HTTP routes.
+Turn TypeScript ClickHouse queries into trusted analytics APIs.
 
-Use it when a local query should become something the rest of your app can call consistently.
+`@hypequery/serve` lets one query contract run inside your app, over HTTP, through OpenAPI, in typed React hooks, or as an agent tool. Inputs are validated, outputs stay typed, and authentication and tenant context live at the server boundary.
 
 ## Install
 
@@ -10,9 +10,7 @@ Use it when a local query should become something the rest of your app can call
 npm install @hypequery/serve zod
 ```
 
-`tsx` is an optional peer dependency used by the local dev workflow.
-
-## Quick Start
+## Define once
 
 ```ts
 import { initServe } from '@hypequery/serve';
@@ -25,245 +23,59 @@ const { query, serve } = initServe({
 });
 
 const weeklyRevenue = query({
-  description: 'Calculate weekly revenue',
+  description: 'Weekly revenue since a given date',
   input: z.object({ startDate: z.string() }),
   query: ({ ctx, input }) =>
     ctx.db
       .table('orders')
       .where('created_at', 'gte', input.startDate)
-      .sum('total', 'revenue')
+      .sum('amount', 'revenue')
       .execute(),
 });
 
-export const api = serve({
-  queries: { weeklyRevenue },
-});
-
-api.route('/weeklyRevenue', api.queries.weeklyRevenue);
+export const api = serve({ queries: { weeklyRevenue } });
+api.route('/weekly-revenue', api.queries.weeklyRevenue);
 ```
 
-Now you can:
-
-- call `api.execute('weeklyRevenue', { input: ... })` in process
-- expose the same query over HTTP
-- consume it from `@hypequery/react`
-- describe it for tools and agents
-
-The same `api.execute(...)` call works for configured metrics and datasets:
+## Run anywhere
 
 ```ts
-import { initServe } from '@hypequery/serve';
-import { createQueryBuilder } from '@hypequery/clickhouse';
-import { dataset, dimension, measure } from '@hypequery/datasets';
-
-const Orders = dataset('orders', {
-  source: 'orders',
-  dimensions: {
-    country: dimension.string(),
-  },
-  measures: {
-    revenue: measure.sum('amount'),
-  },
-});
-
-const revenue = Orders.metric('revenue', { measure: 'revenue' });
-const queryBuilder = createQueryBuilder({ url, username, password, database });
-
-const { serve } = initServe({
-  context: () => ({ db: queryBuilder }),  // ✅ Pass queryBuilder via context once
-});
-
-const api = serve({
-  metrics: { revenue },          // ✅ Auto-extracts queryBuilder from context
-  datasets: { orders: Orders },
-});
-
-await api.execute('revenue', {
-  input: { dimensions: ['country'] },
-});
-
-await api.execute('dataset:orders', {
-  input: { dimensions: ['country'], measures: ['revenue'] },
+await api.execute('weeklyRevenue', {
+  input: { startDate: '2026-01-01' },
 });
 ```
 
-### Semantic endpoint auth
+The same contract can power a REST endpoint, generated OpenAPI, a typed `@hypequery/react` hook, or a tool description for an AI agent.
 
-Dataset and metric entries follow the same auth rules as named queries. An
-entry with no local strategy, including `auth: null`, still inherits the global
-`auth` configuration. Use `requiresAuth: false` for an explicitly public
-endpoint; `requiredRoles` or `requiredScopes` always require authentication.
+Serve also accepts semantic metrics and datasets directly:
 
 ```ts
-const api = serve({
-  auth: globalAuth,
-  metrics: {
-    revenue: { metric: revenue, auth: null }, // inherits globalAuth
-  },
-  datasets: {
-    publicOrders: { dataset: Orders, requiresAuth: false },
-  },
-});
-```
-
-## Main Ideas
-
-### `query({ ... })`
-
-Defines a typed contract:
-
-- description
-- optional input schema
-- query implementation
-
-Standalone queries can execute without creating a served API:
-
-```ts
-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(),
-});
-
-await topCustomers.execute({
-  input: { limit: 10 },
-});
-```
-
-### `serve({ queries, metrics, datasets })`
-
-Builds a runtime around those contracts:
-
-- direct execution
-- route registration
-- docs and OpenAPI support
-- hooks, auth, and tenancy features when needed
-
-## Common Example
-
-```ts
-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(),
-});
-
 export const api = serve({
-  queries: { topCustomers },
-});
-
-api.route('/topCustomers', api.queries.topCustomers);
-```
-
-## Authentication
-
-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()`.
-
-For same-app APIs, prefer reading the host app's authenticated request context:
-
-```ts
-import { createAPI, fromContext } from '@hypequery/serve';
-
-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;
-  }),
-  tenant: {
-    extract: (auth) => auth.tenantId,
-    column: 'tenant_id',
-    mode: 'auto-inject',
-  },
-});
-```
-
-For cross-origin embedding, verify JWT bearer tokens with a shared secret or a
-provider JWKS:
-
-```ts
-import { createJwtStrategy } from '@hypequery/serve';
-
-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 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',
-});
-```
-
-For signed embedding, mint short-lived analytics tokens server-side:
-
-```ts
-import { createAnalyticsTokenIssuer } from '@hypequery/serve';
-
-const issueAnalyticsToken = createAnalyticsTokenIssuer({
-  secret: process.env.HYPEQUERY_AUTH_SECRET!,
-  expiresIn: '15m',
-  issuer: 'https://your-app.example.com',
-  audience: 'hypequery-analytics',
-});
-
-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,
-    }),
-  });
+  metrics: { revenue },
+  datasets: { orders: Orders },
 });
 ```
 
-`createApiKeyStrategy` and `createBearerTokenStrategy` remain available for custom
-authentication systems.
-
-> **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.
-
-## Adapters And Runtimes
+## Built for real analytics APIs
 
-`@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.
+- zod input and output validation;
+- authentication, roles, scopes, and explicit public routes;
+- trusted multi-tenant context and automatic tenant predicates;
+- OpenAPI and static React route manifests;
+- CORS, rate limiting, request IDs, logging, and cache observability;
+- Node and Fetch adapters for existing application stacks.
 
-If you need framework-specific integration, see the docs for:
+## Why it matters
 
-- Node handlers
-- Fetch handlers
-- OpenAPI generation
-- auth and middleware
+Analytics endpoints usually drift across three copies: the SQL, the API type, and the frontend client. Serve keeps them on one TypeScript contract while leaving deployment and framework choices with your application.
 
-## Docs
+## Learn more
 
 - [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)
+- [HTTP and OpenAPI](https://hypequery.com/docs/http-openapi)
+- [Authentication](https://hypequery.com/docs/authentication)
+- [Multi-tenancy](https://hypequery.com/docs/multi-tenancy)
+- [Current capabilities](https://hypequery.com/docs/capabilities)
 
 ## License
 

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "@hypequery/serve",
-  "version": "0.15.1",
-  "description": "Declarative HTTP server for exposing hypequery analytics endpoints",
+  "version": "0.15.3",
+  "description": "Code-first TypeScript runtime for validated ClickHouse analytics APIs, OpenAPI, auth, and tenancy",
+  "keywords": [
+    "clickhouse",
+    "typescript",
+    "analytics-api",
+    "semantic-layer",
+    "query-builder",
+    "orm",
+    "openapi",
+    "multi-tenant",
+    "http",
+    "zod"
+  ],
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -22,12 +34,12 @@
     "dist"
   ],
   "dependencies": {
-    "@hypequery/protocol": "^0.10.0",
+    "@hypequery/protocol": "^0.11.0",
     "jose": "^5.9.6",
     "openapi-typescript": "^7.13.0",
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.23.5",
-    "@hypequery/datasets": "^0.13.2"
+    "@hypequery/datasets": "^0.13.4"
   },
   "peerDependencies": {
     "tsx": "^4.0.0"
@@ -46,7 +58,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/hypequery/hypequery.git"
+    "url": "git+https://github.com/hypequery/hypequery.git",
+    "directory": "packages/serve"
   },
   "homepage": "https://hypequery.com",
   "bugs": {