@hypequery/serve 0.2.1 → 0.3.0

package/dist/server/define-serve.js

@@ -1,91 +1,60 @@
-import { createEndpoint } from "../endpoint.js";
-import { ServeRouter, applyBasePath } from "../router.js";
-import { ensureArray } from "../utils.js";
-import { ServeQueryLogger, formatQueryEvent, formatQueryEventJSON } from "../query-logger.js";
-import { createServeHandler } from "../pipeline.js";
-import { createDocsEndpoint, createOpenApiEndpoint } from "../pipeline.js";
-import { resolveCorsConfig } from "../cors.js";
-import { createExecuteQuery } from "./execute-query.js";
-import { createBuilderMethods } from "./builder.js";
+import { createAPI } from "./create-api.js";
+/**
+ * Define and configure a serve API with embedded transport.
+ *
+ * @deprecated Prefer `createAPI()` with standalone transport functions for
+ * better separation of concerns. `defineServe()` couples API definition
+ * with the Node.js HTTP server via `.start()`.
+ *
+ * @example
+ * ```ts
+ * // Before (defineServe)
+ * const api = defineServe({ queries: { ... } });
+ * api.start({ port: 3000 });
+ *
+ * // After (createAPI + serve)
+ * import { createAPI, startServer } from '@hypequery/serve';
+ * const api = createAPI({ queries: { ... } });
+ * startServer(api, { port: 3000 });
+ * ```
+ */
 export const defineServe = (config) => {
-    const basePath = config.basePath ?? "/api/analytics";
-    const router = new ServeRouter(basePath);
-    const globalMiddlewares = [
-        ...(config.middlewares ?? []),
-    ];
-    const authStrategies = ensureArray(config.auth);
-    const globalTenantConfig = config.tenant;
-    const contextFactory = config.context;
-    const hooks = (config.hooks ?? {});
-    const queryLogger = new ServeQueryLogger();
-    // Wire up production query logging if configured
-    if (config.queryLogging) {
-        if (typeof config.queryLogging === 'function') {
-            queryLogger.on(config.queryLogging);
+    const api = createAPI(config);
+    const loadNodeAdapter = async () => {
+        if (typeof require !== "undefined") {
+            return require("../adapters/node.js");
         }
-        else if (config.queryLogging === 'json') {
-            queryLogger.on((event) => {
-                const line = formatQueryEventJSON(event);
-                if (line)
-                    console.log(line);
-            });
-        }
-        else {
-            queryLogger.on((event) => {
-                const line = formatQueryEvent(event);
-                if (line)
-                    console.log(line);
-            });
-        }
-    }
-    // Slow query warning
-    if (config.slowQueryThreshold != null) {
-        queryLogger.on((event) => {
-            if (event.status === 'completed' && event.durationMs && event.durationMs > config.slowQueryThreshold) {
-                console.warn(`[hypequery/slow-query] ${event.method} ${event.path} took ${event.durationMs}ms (threshold: ${config.slowQueryThreshold}ms)`);
-            }
-        });
-    }
-    const openapiConfig = {
-        enabled: config.openapi?.enabled ?? true,
-        path: config.openapi?.path ?? "/openapi.json",
+        return import("../adapters/node.js");
     };
-    const docsConfig = {
-        enabled: config.docs?.enabled ?? true,
-        path: config.docs?.path ?? "/docs",
-    };
-    const openapiPublicPath = applyBasePath(basePath, openapiConfig.path);
-    const configuredQueries = config.queries ?? {};
-    const queryEntries = {};
-    const registerQuery = (key, definition) => {
-        queryEntries[key] = createEndpoint(String(key), definition);
-    };
-    for (const key of Object.keys(configuredQueries)) {
-        registerQuery(key, configuredQueries[key]);
-    }
-    const corsConfig = resolveCorsConfig(config.cors);
-    const handler = createServeHandler({
-        router,
-        globalMiddlewares,
-        authStrategies,
-        tenantConfig: globalTenantConfig,
-        contextFactory,
-        hooks,
-        queryLogger,
-        verboseAuthErrors: config.security?.verboseAuthErrors ?? false,
-        corsConfig,
-    });
-    // Track route configuration for client config extraction
+    // Extend the API with backwards-compatible ServeBuilder methods
+    const builder = api;
     const routeConfig = {};
-    const executeQuery = createExecuteQuery(queryEntries, authStrategies, contextFactory, globalMiddlewares, globalTenantConfig, hooks, queryLogger, config.security?.verboseAuthErrors ?? false);
-    const builder = createBuilderMethods(queryEntries, queryLogger, routeConfig, router, authStrategies, globalMiddlewares, executeQuery, handler, basePath);
-    if (openapiConfig.enabled) {
-        const openapiEndpoint = createOpenApiEndpoint(openapiConfig.path, () => router.list(), config.openapi);
-        router.register(openapiEndpoint);
-    }
-    if (docsConfig.enabled) {
-        const docsEndpoint = createDocsEndpoint(docsConfig.path, openapiPublicPath, config.docs);
-        router.register(docsEndpoint);
+    for (const [key, endpoint] of Object.entries(api.queries)) {
+        routeConfig[key] = { method: endpoint.method };
     }
+    Object.defineProperty(builder, "basePath", {
+        value: config.basePath ?? "/api/analytics",
+        enumerable: true,
+        configurable: true,
+    });
+    Object.defineProperty(builder, "_routeConfig", {
+        value: routeConfig,
+        enumerable: true,
+        configurable: true,
+    });
+    const originalRoute = builder.route.bind(builder);
+    builder.route = (path, endpoint, options = {}) => {
+        const result = originalRoute(path, endpoint, options);
+        const queryKey = Object.entries(api.queries).find(([_, entry]) => entry === endpoint)?.[0];
+        if (queryKey) {
+            routeConfig[queryKey] = { method: options?.method ?? endpoint.method };
+        }
+        return result;
+    };
+    // Add transport method that ServeBuilder expects
+    builder.start = async (options = {}) => {
+        const { startNodeServer } = await loadNodeAdapter();
+        return startNodeServer(api.handler, options);
+    };
     return builder;
 };

package/dist/server/index.d.ts

@@ -1,6 +1,8 @@
+export { createAPI } from "./create-api.js";
 export { defineServe } from "./define-serve.js";
 export { initServe } from "./init-serve.js";
 export { createExecuteQuery } from "./execute-query.js";
 export { createBuilderMethods } from "./builder.js";
+export { createAPImethods } from "./api-builder.js";
 export { mapEndpointToToolkit } from "./mapper.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}

package/dist/server/index.js

@@ -1,5 +1,7 @@
+export { createAPI } from "./create-api.js";
 export { defineServe } from "./define-serve.js";
 export { initServe } from "./init-serve.js";
 export { createExecuteQuery } from "./execute-query.js";
 export { createBuilderMethods } from "./builder.js";
+export { createAPImethods } from "./api-builder.js";
 export { mapEndpointToToolkit } from "./mapper.js";

package/dist/server/init-serve.d.ts

@@ -1,6 +1,6 @@
 import type { AuthContext, ServeContextFactory, ServeInitializer, ServeQueriesMap, ServeConfig } from "../types.js";
 type InferInitializerContext<TFactory, TAuth extends AuthContext> = TFactory extends ServeContextFactory<infer TContext, TAuth> ? TContext : never;
-type ServeInitializerOptions<TFactory extends ServeContextFactory<any, TAuth>, TAuth extends AuthContext> = Omit<ServeConfig<InferInitializerContext<TFactory, TAuth>, TAuth, ServeQueriesMap<InferInitializerContext<TFactory, TAuth>, TAuth>>, "queries" | "context"> & {
+type ServeInitializerOptions<TFactory extends ServeContextFactory<any, TAuth>, TAuth extends AuthContext> = Omit<ServeConfig<InferInitializerContext<TFactory, TAuth>, TAuth, ServeQueriesMap<InferInitializerContext<TFactory, TAuth>, TAuth>, Record<never, never>, Record<never, never>>, "queries" | "context"> & {
     context: TFactory;
 };
 export declare const initServe: <TFactory extends ServeContextFactory<any, TAuth>, TAuth extends AuthContext = AuthContext>(options: ServeInitializerOptions<TFactory, TAuth>) => ServeInitializer<InferInitializerContext<TFactory, TAuth>, TAuth>;

package/dist/server/init-serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-serve.d.ts","sourceRoot":"","sources":["../../src/server/init-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAEX,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,WAAW,EACZ,MAAM,aAAa,CAAC;AAKrB,KAAK,uBAAuB,CAC1B,QAAQ,EACR,KAAK,SAAS,WAAW,IACvB,QAAQ,SAAS,mBAAmB,CAAC,MAAM,QAAQ,EAAE,KAAK,CAAC,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEnF,KAAK,uBAAuB,CAC1B,QAAQ,SAAS,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,EAChD,KAAK,SAAS,WAAW,IACvB,IAAI,CACN,WAAW,CACT,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,EACxC,KAAK,EACL,eAAe,CAAC,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CACjE,EACD,SAAS,GAAG,SAAS,CACtB,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;AAQ1B,eAAO,MAAM,SAAS,GACpB,QAAQ,SAAS,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,EAChD,KAAK,SAAS,WAAW,GAAG,WAAW,EACvC,SAAS,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAG,gBAAgB,CACpE,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,EACxC,KAAK,CAqCN,CAAC"}
+{"version":3,"file":"init-serve.d.ts","sourceRoot":"","sources":["../../src/server/init-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAEX,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,WAAW,EAGZ,MAAM,aAAa,CAAC;AAKrB,KAAK,uBAAuB,CAC1B,QAAQ,EACR,KAAK,SAAS,WAAW,IACvB,QAAQ,SAAS,mBAAmB,CAAC,MAAM,QAAQ,EAAE,KAAK,CAAC,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEnF,KAAK,uBAAuB,CAC1B,QAAQ,SAAS,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,EAChD,KAAK,SAAS,WAAW,IACvB,IAAI,CACN,WAAW,CACT,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,EACxC,KAAK,EACL,eAAe,CAAC,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,EAChE,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACpB,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CACrB,EACD,SAAS,GAAG,SAAS,CACtB,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;AAU1B,eAAO,MAAM,SAAS,GACpB,QAAQ,SAAS,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,EAChD,KAAK,SAAS,WAAW,GAAG,WAAW,EACvC,SAAS,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,KAAG,gBAAgB,CACpE,uBAAuB,CAAC,QAAQ,EAAE,KAAK,CAAC,EACxC,KAAK,CAkDN,CAAC"}

package/dist/server/init-serve.js

@@ -5,11 +5,16 @@ export const initServe = (options) => {
     const { context, ...staticOptions } = options;
     const procedure = createProcedureBuilder();
     const define = (config) => {
-        return defineServe({
+        // Auto-extract queryBuilder from context.db if metrics/datasets are used
+        // This is handled in createAPI since it needs to support both sync and async contexts
+        const finalConfig = {
             ...staticOptions,
             ...config,
             context: (context ?? {}),
-        });
+        };
+        // Note: defineServe is deprecated for public use, but initServe uses it internally
+        // to provide the .start() method on the returned builder. This is intentional.
+        return defineServe(finalConfig);
     };
     const queryFactory = createQueryFactory((context ?? {}));
     const query = new Proxy(queryFactory, {

package/dist/type-tests/builder.test-d.d.ts

@@ -13,6 +13,10 @@ export declare const api: import("../types.js").ServeBuilder<import("../types.js
     }[]>;
 }, {
     db: {};
+}, import("../types.js").AuthContext> & import("../types.js").SemanticMetricEndpointMap<Record<never, never>, {
+    db: {};
+}, import("../types.js").AuthContext> & import("../types.js").SemanticDatasetEndpointMap<Record<never, never>, {
+    db: {};
 }, import("../types.js").AuthContext>, {
     db: {};
 }, import("../types.js").AuthContext>;

package/dist/type-tests/builder.test-d.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builder.test-d.d.ts","sourceRoot":"","sources":["../../src/type-tests/builder.test-d.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;qCAUd,CAAC"}
+{"version":3,"file":"builder.test-d.d.ts","sourceRoot":"","sources":["../../src/type-tests/builder.test-d.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;qCAUd,CAAC"}

package/dist/type-tests/builder.test-d.js

@@ -1,4 +1,4 @@
-import { initServe } from '../index.js';
+import { createAnalyticsTokenIssuer, createJwtStrategy, initServe } from '../index.js';
 import { z } from 'zod';
 const serve = initServe({
     context: () => ({
@@ -34,3 +34,18 @@ const executableResultPromise = executableQuery.execute({
 const _executableResultIsTyped = { total: 10 };
 // @ts-expect-error total must be number
 const _executableResultRejectsString = { total: '10' };
+createJwtStrategy({ secret: 'secret' });
+createJwtStrategy({ jwksUri: 'https://issuer.example.com/.well-known/jwks.json' });
+// @ts-expect-error exactly one key source is allowed
+createJwtStrategy({ secret: 'secret', jwksUri: 'https://issuer.example.com/.well-known/jwks.json' });
+// @ts-expect-error custom auth types require a mapper that proves required fields exist
+createJwtStrategy({ secret: 'secret' });
+createJwtStrategy({
+    secret: 'secret',
+    mapClaims: (payload) => ({
+        userId: String(payload.sub),
+        tenantId: String(payload.org_id),
+    }),
+});
+// @ts-expect-error token issuer supports symmetric HMAC JWT algorithms only
+createAnalyticsTokenIssuer({ secret: 'secret', algorithm: 'RS256' });

package/dist/type-tests/semantic.test-d.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=semantic.test-d.d.ts.map

package/dist/type-tests/semantic.test-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic.test-d.d.ts","sourceRoot":"","sources":["../../src/type-tests/semantic.test-d.ts"],"names":[],"mappings":""}

package/dist/type-tests/semantic.test-d.js

@@ -0,0 +1,59 @@
+import { dataset, dimension, measure, divide, nullIfZero, belongsTo } from '../semantic/index.js';
+import { createAPI } from '../index.js';
+const Customers = dataset('customers', {
+    source: 'customers',
+    dimensions: {
+        id: dimension.string(),
+        name: dimension.string(),
+        country: dimension.string(),
+    },
+    measures: {
+        customerCount: measure.count('id'),
+    },
+});
+const Orders = dataset('orders', {
+    source: 'orders',
+    tenantKey: 'tenant_id',
+    timeKey: 'created_at',
+    dimensions: {
+        id: dimension.string(),
+        customerId: dimension.string({ column: 'customer_id' }),
+        status: dimension.string(),
+        createdAt: dimension.timestamp({ column: 'created_at' }),
+    },
+    measures: {
+        revenue: measure.sum('amount'),
+        orderCount: measure.count('id'),
+    },
+    relationships: {
+        customer: belongsTo(() => Customers, { from: 'customerId', to: 'id' }),
+    },
+});
+const totalRevenue = Orders.metric('totalRevenue', { measure: 'revenue' });
+const orderCountMetric = Orders.metric('orderCountMetric', { measure: 'orderCount' });
+const avgOrderValue = Orders.metric('avgOrderValue', {
+    uses: { revenue: totalRevenue, orders: orderCountMetric },
+    formula: ({ revenue, orders }) => divide(revenue, nullIfZero(orders)),
+});
+const monthlyRevenue = totalRevenue.by('month');
+monthlyRevenue.contract();
+avgOrderValue.contract();
+const queryBuilder = {
+    table: (() => {
+        throw new Error('type-only query builder');
+    }),
+    rawQuery: async () => [],
+};
+const semanticApi = createAPI({
+    metrics: { totalRevenue },
+    datasets: { orders: Orders },
+    queryBuilder,
+});
+void semanticApi.execute('totalRevenue', {
+    input: { dimensions: ['status'] },
+});
+void semanticApi.execute('dataset:orders', {
+    input: { dimensions: ['status'], measures: ['revenue'] },
+});
+// @ts-expect-error only configured semantic keys are executable
+void semanticApi.execute('dataset:customers', { input: {} });

package/dist/types.d.ts

@@ -1,5 +1,6 @@
-import type { ZodTypeAny } from "zod";
+import type { ZodType, ZodTypeAny } from "zod";
 import type { ServeQueryLogger, ServeQueryEventCallback } from "./query-logger.js";
+import type { QueryBuilderFactoryLike } from "@hypequery/datasets";
 /** Supported HTTP verbs for serve-managed endpoints. */
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS";
 export type HeaderMap = Record<string, string | undefined>;
@@ -328,8 +329,118 @@ export interface OpenApiDocument {
         securitySchemes?: Record<string, unknown>;
     };
 }
-export interface ServeConfig<TContext extends Record<string, unknown> = Record<string, unknown>, TAuth extends AuthContext = AuthContext, TQueries extends ServeQueriesMap<TContext, TAuth> = ServeQueriesMap<TContext, TAuth>> {
-    queries: TQueries;
+/** Per-metric entry: shorthand (just the ref) or with overrides. */
+export type MetricEntry<TAuth extends AuthContext = AuthContext> = MetricHandle<any, any> | {
+    metric: MetricHandle<any, any>;
+    auth?: AuthStrategy<TAuth> | null;
+    tenant?: TenantConfigOverride<TAuth>;
+    cache?: number | null;
+    requiredRoles?: string[];
+    requiredScopes?: string[];
+    /** Middleware applied to this metric endpoint. */
+    middlewares?: ServeMiddleware<any, any, any, TAuth>[];
+    /**
+     * Caps the page size for this metric. Requests above it are clamped (not
+     * rejected). Defaults to the dataset's `limits.maxResultSize`, else 1000.
+     */
+    maxLimit?: number;
+};
+/** Map of metric names to entries. */
+export type MetricsConfig<TAuth extends AuthContext = AuthContext> = Record<string, MetricEntry<TAuth>>;
+import type { DatasetInstance, DatasetQueryFor, DatasetQueryResultFor, MetricHandle, MetricQueryFor, MetricResultFor } from "@hypequery/datasets";
+import type { DatasetEntry } from "./semantic/datasets/dataset-endpoint.js";
+export type { DatasetEntry } from "./semantic/datasets/dataset-endpoint.js";
+/** Map of dataset names to entries. */
+export type DatasetsConfig<TAuth extends AuthContext = AuthContext> = Record<string, DatasetEntry<TAuth>>;
+/** The dataset instance behind a `DatasetEntry` (bare instance or `{ dataset }`). */
+type DatasetInstanceOfEntry<TEntry> = TEntry extends {
+    __type: 'dataset';
+} ? TEntry : TEntry extends {
+    dataset: infer TDataset;
+} ? (TDataset extends DatasetInstance<any, any, any, any> ? TDataset : never) : never;
+/** The `MetricHandle` behind a `MetricEntry` (bare handle or `{ metric }`). */
+type MetricHandleOfEntry<TEntry> = TEntry extends {
+    __type: 'metric_ref' | 'grained_metric_ref';
+} ? TEntry : TEntry extends {
+    metric: infer THandle;
+} ? THandle : never;
+/** Unwrap a grained metric ref to its underlying base ref. */
+type BaseMetricRefOf<THandle> = THandle extends {
+    __type: 'grained_metric_ref';
+    metric: infer TRef;
+} ? TRef : THandle;
+/** The concrete dataset instance a metric is defined on. */
+type MetricDatasetOfEntry<TEntry> = BaseMetricRefOf<MetricHandleOfEntry<TEntry>> extends {
+    dataset: infer TDataset;
+} ? (TDataset extends DatasetInstance<any, any, any, any> ? TDataset : never) : never;
+/** The metric's output column name (used for typed rows and orderBy). */
+type MetricNameOfEntry<TEntry> = BaseMetricRefOf<MetricHandleOfEntry<TEntry>> extends {
+    name: infer TName;
+} ? (TName extends string ? TName : string) : string;
+export type SemanticMetricEndpointMap<TMetrics extends MetricsConfig<TAuth>, TContext extends Record<string, unknown>, TAuth extends AuthContext> = {
+    [TKey in keyof TMetrics & string]: ServeEndpoint<ZodType<MetricQueryFor<MetricDatasetOfEntry<TMetrics[TKey]>, MetricNameOfEntry<TMetrics[TKey]>>>, ZodType<MetricResultFor<MetricDatasetOfEntry<TMetrics[TKey]>, MetricNameOfEntry<TMetrics[TKey]>>>, TContext, TAuth, MetricResultFor<MetricDatasetOfEntry<TMetrics[TKey]>, MetricNameOfEntry<TMetrics[TKey]>>>;
+};
+export type SemanticDatasetEndpointMap<TDatasets extends DatasetsConfig<TAuth>, TContext extends Record<string, unknown>, TAuth extends AuthContext> = {
+    [TKey in keyof TDatasets & string as `dataset:${TKey}`]: ServeEndpoint<ZodType<DatasetQueryFor<DatasetInstanceOfEntry<TDatasets[TKey]>>>, ZodType<DatasetQueryResultFor<DatasetInstanceOfEntry<TDatasets[TKey]>>>, TContext, TAuth, DatasetQueryResultFor<DatasetInstanceOfEntry<TDatasets[TKey]>>>;
+};
+export type ServeSemanticEndpointMap<TMetrics extends MetricsConfig<TAuth>, TDatasets extends DatasetsConfig<TAuth>, TContext extends Record<string, unknown>, TAuth extends AuthContext> = SemanticMetricEndpointMap<TMetrics, TContext, TAuth> & SemanticDatasetEndpointMap<TDatasets, TContext, TAuth>;
+export interface ServeConfig<TContext extends Record<string, unknown> = Record<string, unknown>, TAuth extends AuthContext = AuthContext, TQueries extends ServeQueriesMap<TContext, TAuth> = Record<never, never>, TMetrics extends MetricsConfig<TAuth> = Record<never, never>, TDatasets extends DatasetsConfig<TAuth> = Record<never, never>> {
+    queries?: TQueries;
+    /**
+     * Metrics: auto-generated POST endpoints for each metric.
+     * Each metric gets a `POST /api/analytics/metrics/:name` endpoint
+     * that validates dimensions/filters against the metric's contract.
+     *
+     * @example
+     * ```ts
+     * const api = createAPI({
+     *   metrics: {
+     *     totalRevenue,           // shorthand
+     *     profitMargin: {         // with overrides
+     *       metric: profitMargin,
+     *       auth: requireRole('finance'),
+     *       cache: 300_000,
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    metrics?: TMetrics;
+    /**
+     * Semantic dataset endpoints — auto-generated POST endpoints for each dataset.
+     * Each dataset gets a `POST /api/analytics/datasets/:name/query` endpoint
+     * that validates dimensions/measures/filters against the dataset definition.
+     *
+     * When Serve tenant isolation is enabled for semantic endpoints, set
+     * `tenant.column` in the Serve config or per-entry override so the runtime
+     * knows which column to enforce.
+     *
+     * Accepts an inline map of dataset instances.
+     *
+     * @example
+     * ```ts
+     * const api = createAPI({
+     *   datasets: { orders, customers },
+     *   queryBuilder: qb,
+     * });
+     * ```
+     */
+    datasets?: TDatasets;
+    /**
+     * Query builder instance for metric/dataset execution.
+     * Required when `metrics` or `datasets` are provided.
+     * Pass the return value of `createQueryBuilder(config)` directly.
+     *
+     * @example
+     * ```ts
+     * const qb = createQueryBuilder<Schema>(config);
+     * const api = createAPI({
+     *   metrics: { totalRevenue },
+     *   queryBuilder: qb,
+     * });
+     * ```
+     */
+    queryBuilder?: QueryBuilderFactoryLike;
     basePath?: string;
     middlewares?: ServeMiddleware<any, any, TContext, TAuth>[];
     auth?: AuthStrategy<TAuth> | AuthStrategy<TAuth>[];
@@ -383,6 +494,31 @@ export interface ServeConfig<TContext extends Record<string, unknown> = Record<s
     security?: {
         verboseAuthErrors?: boolean;
     };
+    /**
+     * Customize path prefixes for auto-generated semantic layer endpoints.
+     * Useful for avoiding route collisions or organizing API structure.
+     *
+     * @default { metrics: '/metrics', datasets: '/datasets' }
+     *
+     * @example
+     * ```ts
+     * const api = createAPI({
+     *   metrics: { totalRevenue },
+     *   datasets: { orders: Orders },
+     *   semanticPaths: {
+     *     metrics: '/api/metrics',
+     *     datasets: '/api/data',
+     *   },
+     * });
+     * // Generates:
+     * // POST /api/metrics/totalRevenue
+     * // POST /api/data/orders/query
+     * ```
+     */
+    semanticPaths?: {
+        metrics?: string;
+        datasets?: string;
+    };
 }
 export interface RouteRegistrationOptions<TContext extends Record<string, unknown> = Record<string, unknown>, TAuth extends AuthContext = AuthContext> {
     method?: HttpMethod;
@@ -471,6 +607,87 @@ export type ExecuteQueryFunction<TQueries extends Record<string, ServeEndpoint<a
     context?: Partial<TContext>;
     request?: Partial<ServeRequest>;
 }) => Promise<ServeEndpointResult<TQueries[TKey]>>;
+/**
+ * A transport-agnostic API definition. Contains queries, auth, tenancy,
+ * and a handler — but no HTTP server. Pass to standalone transport functions:
+ *
+ * @example
+ * ```ts
+ * const api = createAPI({ queries: { ... }, auth: jwtStrategy });
+ *
+ * // Use with any transport:
+ * startServer(api, { port: 3000 });
+ * app.use('/analytics', toNodeHandler(api));
+ * export default toFetchHandler(api);
+ * ```
+ */
+/** A single route in a {@link RouteManifest}. */
+export interface RouteManifestEntry {
+    method: HttpMethod;
+    /** Full request path including the API base path. */
+    path: string;
+}
+/**
+ * Serializable map of query/metric/dataset keys to their HTTP method and full
+ * path. Keys match {@link HypeQueryAPI.queries} (including `dataset:<name>`
+ * keys for datasets), so it can be paired with `InferAPIType` and handed to
+ * `@hypequery/react`'s `createHooks({ manifest })` to resolve client routes
+ * without importing server code into the browser bundle.
+ */
+export type RouteManifest = Record<string, RouteManifestEntry>;
+export interface HypeQueryAPI<TQueries extends Record<string, ServeEndpoint<any, any, any, any>> = Record<string, ServeEndpoint<any, any, any, any>>, TContext extends Record<string, unknown> = Record<string, unknown>, TAuth extends AuthContext = AuthContext> {
+    readonly queries: TQueries;
+    /** Serve-layer query logger for subscribing to endpoint execution events */
+    readonly queryLogger: ServeQueryLogger;
+    /** The underlying request handler. Can be passed directly to transport adapters. */
+    readonly handler: ServeHandler;
+    /**
+     * Build a serializable {@link RouteManifest} of every query/metric/dataset
+     * route (method + full path). Safe to JSON-serialize and ship to the client.
+     */
+    manifest(): RouteManifest;
+    route<Path extends string, TKey extends keyof TQueries>(path: Path, endpoint: TQueries[TKey], options?: Partial<RouteRegistrationOptions<TContext, TAuth>>): this;
+    use(middleware: ServeMiddleware<any, any, TContext, TAuth>): this;
+    useAuth(strategy: AuthStrategy<TAuth>): this;
+    execute<TKey extends keyof TQueries>(key: TKey, options?: {
+        input?: SchemaInput<TQueries[TKey]["inputSchema"]>;
+        context?: Partial<TContext>;
+        request?: Partial<ServeRequest>;
+    }): Promise<ServeEndpointResult<TQueries[TKey]>>;
+    /** Alias of execute() for in-process execution. */
+    client<TKey extends keyof TQueries>(key: TKey, options?: {
+        input?: SchemaInput<TQueries[TKey]["inputSchema"]>;
+        context?: Partial<TContext>;
+        request?: Partial<ServeRequest>;
+    }): Promise<ServeEndpointResult<TQueries[TKey]>>;
+    /** Alias of execute() for in-process execution. */
+    run<TKey extends keyof TQueries>(key: TKey, options?: {
+        input?: SchemaInput<TQueries[TKey]["inputSchema"]>;
+        context?: Partial<TContext>;
+        request?: Partial<ServeRequest>;
+    }): Promise<ServeEndpointResult<TQueries[TKey]>>;
+    describe(): ToolkitDescription;
+}
+/**
+ * Infer the API type from a HypeQueryAPI for use with @hypequery/react.
+ *
+ * @example
+ * ```ts
+ * const api = createAPI({ queries: { hello: ... } });
+ * type Api = InferAPIType<typeof api>;
+ * createHooks<Api>({ baseUrl: '/api' });
+ * ```
+ */
+export type InferAPIType<TTarget> = TTarget extends HypeQueryAPI<infer TQueries, any, any> ? {
+    [K in keyof TQueries]: TQueries[K] extends ServeEndpoint<infer TInputSchema, infer TOutputSchema, any, any, any> ? {
+        input: SchemaInput<TInputSchema>;
+        output: SchemaOutput<TOutputSchema>;
+    } : never;
+} : never;
+/**
+ * @deprecated Use `HypeQueryAPI` and `createAPI()` instead. `ServeBuilder` adds
+ * transport concerns (`start()`) that should be handled separately.
+ */
 export interface ServeBuilder<TQueries extends Record<string, ServeEndpoint<any, any, any, any>> = Record<string, ServeEndpoint<any, any, any, any>>, TContext extends Record<string, unknown> = Record<string, unknown>, TAuth extends AuthContext = AuthContext> {
     readonly queries: TQueries;
     /** Base path applied to all registered routes, docs, and OpenAPI endpoints */
@@ -481,6 +698,11 @@ export interface ServeBuilder<TQueries extends Record<string, ServeEndpoint<any,
     readonly _routeConfig?: Record<string, {
         method: HttpMethod;
     }>;
+    /**
+     * Build a serializable {@link RouteManifest} of every query/metric/dataset
+     * route (method + full path). Safe to JSON-serialize and ship to the client.
+     */
+    manifest(): RouteManifest;
     route<Path extends string, TKey extends keyof TQueries>(path: Path, endpoint: TQueries[TKey], options?: Partial<RouteRegistrationOptions<TContext, TAuth>>): this;
     use(middleware: ServeMiddleware<any, any, TContext, TAuth>): this;
     useAuth(strategy: AuthStrategy<TAuth>): this;
@@ -508,8 +730,8 @@ export interface ServeInitializer<TContext extends Record<string, unknown> = Rec
     readonly procedure: QueryProcedureBuilder<TContext, TAuth>;
     readonly query: QueryFactory<TContext, TAuth>;
     queries<TQueries extends ServeQueriesMap<TContext, TAuth>>(queries: TQueries): TQueries;
-    serve<TQueries extends ServeQueriesMap<TContext, TAuth>>(config: Omit<ServeConfig<TContext, TAuth, TQueries>, "context">): ServeBuilder<ServeEndpointMap<TQueries, TContext, TAuth>, TContext, TAuth>;
-    define<TQueries extends ServeQueriesMap<TContext, TAuth>>(config: Omit<ServeConfig<TContext, TAuth, TQueries>, "context">): ServeBuilder<ServeEndpointMap<TQueries, TContext, TAuth>, TContext, TAuth>;
+    serve<TQueries extends ServeQueriesMap<TContext, TAuth>, TMetrics extends MetricsConfig<TAuth> = Record<never, never>, TDatasets extends DatasetsConfig<TAuth> = Record<never, never>>(config: Omit<ServeConfig<TContext, TAuth, TQueries, TMetrics, TDatasets>, "context">): ServeBuilder<ServeEndpointMap<TQueries, TContext, TAuth> & ServeSemanticEndpointMap<TMetrics, TDatasets, TContext, TAuth>, TContext, TAuth>;
+    define<TQueries extends ServeQueriesMap<TContext, TAuth>, TMetrics extends MetricsConfig<TAuth> = Record<never, never>, TDatasets extends DatasetsConfig<TAuth> = Record<never, never>>(config: Omit<ServeConfig<TContext, TAuth, TQueries, TMetrics, TDatasets>, "context">): ServeBuilder<ServeEndpointMap<TQueries, TContext, TAuth> & ServeSemanticEndpointMap<TMetrics, TDatasets, TContext, TAuth>, TContext, TAuth>;
 }
 export type QueryFactory<TContext extends Record<string, unknown>, TAuth extends AuthContext> = QueryProcedureBuilder<TContext, TAuth> & {
     <TInputSchema extends ZodTypeAny | undefined = undefined, TOutputSchema extends ZodTypeAny | undefined = undefined, TResult = TOutputSchema extends ZodTypeAny ? SchemaOutput<TOutputSchema> : unknown>(config: QueryObjectConfig<TInputSchema, TOutputSchema, TContext, TAuth, TResult>): StandaloneQueryDefinition<TInputSchema, TOutputSchema extends ZodTypeAny ? TOutputSchema : ZodTypeAny, TContext, TAuth, TResult>;
@@ -628,5 +850,4 @@ export type ServeContextFactory<TContext extends Record<string, unknown>, TAuth
     request: ServeRequest;
     auth: TAuth | null;
 }) => MaybePromise<TContext>);
-export {};
 //# sourceMappingURL=types.d.ts.map