@hypequery/serve 0.2.1 → 0.3.0

package/dist/semantic/query-builder-context.d.ts

@@ -0,0 +1,20 @@
+import type { QueryBuilderFactoryLike, SemanticExecutionRuntime } from "@hypequery/datasets";
+export declare const INTERNAL_SEMANTIC_RUNTIME_KEY = "__hypequerySemanticRuntime";
+/**
+ * Type guard to check if a value is a QueryBuilderFactoryLike.
+ * Uses duck-typing to detect the required methods.
+ */
+export declare function isQueryBuilderFactoryLike(value: unknown): value is QueryBuilderFactoryLike;
+/**
+ * Extract queryBuilder from context.db if available.
+ * This allows users to pass queryBuilder via context instead of top-level config.
+ */
+export declare function extractQueryBuilderFromContext(context: Record<string, unknown>): QueryBuilderFactoryLike | undefined;
+export declare function attachSemanticQueryBuilder<TContext extends Record<string, unknown>>(context: TContext, builderFactory: QueryBuilderFactoryLike | undefined): TContext;
+export declare function attachSemanticRuntime<TContext extends Record<string, unknown>>(context: TContext, runtime: SemanticExecutionRuntime): TContext;
+export declare function resolveSemanticExecutionRuntime(context: Record<string, unknown>): SemanticExecutionRuntime | undefined;
+export declare function resolveSemanticQueryBuilder(context: Record<string, unknown>, fallback: QueryBuilderFactoryLike): QueryBuilderFactoryLike;
+export declare function attachSemanticTenantRuntime<TContext extends Record<string, unknown>>(context: TContext, options: {
+    tenantId: string;
+}): TContext;
+//# sourceMappingURL=query-builder-context.d.ts.map

package/dist/semantic/query-builder-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-builder-context.d.ts","sourceRoot":"","sources":["../../src/semantic/query-builder-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAE7F,eAAO,MAAM,6BAA6B,+BAA+B,CAAC;AAM1E;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,uBAAuB,CAS1F;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,uBAAuB,GAAG,SAAS,CAarC;AAED,wBAAgB,0BAA0B,CACxC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAExC,OAAO,EAAE,QAAQ,EACjB,cAAc,EAAE,uBAAuB,GAAG,SAAS,GAClD,QAAQ,CAMV;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5E,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,wBAAwB,GAChC,QAAQ,CAUV;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,wBAAwB,GAAG,SAAS,CAMtC;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE,uBAAuB,GAChC,uBAAuB,CAEzB;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClF,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE;IACP,QAAQ,EAAE,MAAM,CAAC;CAClB,GACA,QAAQ,CAMV"}

package/dist/semantic/query-builder-context.js

@@ -0,0 +1,66 @@
+export const INTERNAL_SEMANTIC_RUNTIME_KEY = "__hypequerySemanticRuntime";
+function isSemanticExecutionRuntime(value) {
+    return typeof value === 'object' && value !== null;
+}
+/**
+ * Type guard to check if a value is a QueryBuilderFactoryLike.
+ * Uses duck-typing to detect the required methods.
+ */
+export function isQueryBuilderFactoryLike(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'table' in value &&
+        typeof value.table === 'function' &&
+        'rawQuery' in value &&
+        typeof value.rawQuery === 'function');
+}
+/**
+ * Extract queryBuilder from context.db if available.
+ * This allows users to pass queryBuilder via context instead of top-level config.
+ */
+export function extractQueryBuilderFromContext(context) {
+    // Check if context.db is a queryBuilder
+    if ('db' in context && isQueryBuilderFactoryLike(context.db)) {
+        return context.db;
+    }
+    // Check if it's already in the semantic runtime
+    const runtime = resolveSemanticExecutionRuntime(context);
+    if (runtime?.builderFactory) {
+        return runtime.builderFactory;
+    }
+    return undefined;
+}
+export function attachSemanticQueryBuilder(context, builderFactory) {
+    if (!builderFactory) {
+        return context;
+    }
+    return attachSemanticRuntime(context, { builderFactory });
+}
+export function attachSemanticRuntime(context, runtime) {
+    const current = resolveSemanticExecutionRuntime(context);
+    return {
+        ...context,
+        [INTERNAL_SEMANTIC_RUNTIME_KEY]: {
+            ...(current ?? {}),
+            ...runtime,
+            tenant: runtime.tenant ?? current?.tenant,
+        },
+    };
+}
+export function resolveSemanticExecutionRuntime(context) {
+    const candidate = context[INTERNAL_SEMANTIC_RUNTIME_KEY];
+    if (!isSemanticExecutionRuntime(candidate)) {
+        return undefined;
+    }
+    return candidate;
+}
+export function resolveSemanticQueryBuilder(context, fallback) {
+    return resolveSemanticExecutionRuntime(context)?.builderFactory ?? fallback;
+}
+export function attachSemanticTenantRuntime(context, options) {
+    return attachSemanticRuntime(context, {
+        tenant: {
+            id: options.tenantId,
+        },
+    });
+}

package/dist/semantic/utils/tenant-runtime.d.ts

@@ -0,0 +1,11 @@
+import type { EndpointMetadata } from '../../types.js';
+export declare function applySemanticTenantRuntime<TContext extends Record<string, unknown>>(context: TContext & {
+    tenantId?: string;
+}, options: {
+    queryKey: string;
+    metadata: EndpointMetadata;
+    tenantId: string;
+    mode: 'manual' | 'auto-inject';
+    column?: string;
+}): void;
+//# sourceMappingURL=tenant-runtime.d.ts.map

package/dist/semantic/utils/tenant-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-runtime.d.ts","sourceRoot":"","sources":["../../../src/semantic/utils/tenant-runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAyBvD,wBAAgB,0BAA0B,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjF,OAAO,EAAE,QAAQ,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EACzC,OAAO,EAAE;IACP,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,GAAG,aAAa,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,IAAI,CAyCN"}

package/dist/semantic/utils/tenant-runtime.js

@@ -0,0 +1,48 @@
+import { createTenantScope, warnTenantMisconfiguration } from '../../tenant.js';
+import { attachSemanticRuntime, attachSemanticTenantRuntime, resolveSemanticExecutionRuntime, } from '../query-builder-context.js';
+function usesServeTenantRuntimeMetadata(metadata) {
+    return Boolean(metadata.custom
+        && typeof metadata.custom === 'object'
+        && metadata.custom !== null
+        && 'usesServeTenantRuntime' in metadata.custom
+        && metadata.custom.usesServeTenantRuntime === true);
+}
+function hasTableFactory(value) {
+    return !!value && typeof value === 'object' && 'table' in value && typeof value.table === 'function';
+}
+export function applySemanticTenantRuntime(context, options) {
+    const mutableContext = context;
+    const usesServeTenantRuntime = usesServeTenantRuntimeMetadata(options.metadata);
+    const semanticRuntime = resolveSemanticExecutionRuntime(context);
+    if (options.mode === 'auto-inject' && options.column && semanticRuntime?.builderFactory) {
+        Object.assign(context, attachSemanticRuntime(context, {
+            tenant: {
+                id: options.tenantId,
+            },
+        }));
+    }
+    else {
+        Object.assign(context, attachSemanticTenantRuntime(context, {
+            tenantId: options.tenantId,
+        }));
+    }
+    if (options.mode === 'auto-inject' && options.column) {
+        for (const key of Object.keys(mutableContext)) {
+            const value = mutableContext[key];
+            if (hasTableFactory(value)) {
+                mutableContext[key] = createTenantScope(value, {
+                    tenantId: options.tenantId,
+                    column: options.column,
+                });
+            }
+        }
+    }
+    else if (options.mode === 'manual' && !usesServeTenantRuntime) {
+        warnTenantMisconfiguration({
+            queryKey: options.queryKey,
+            hasTenantConfig: true,
+            hasTenantId: true,
+            mode: 'manual',
+        });
+    }
+}

package/dist/serve.d.ts

@@ -1,4 +1,4 @@
-import type { AuthContext, QueryObjectConfig, SchemaOutput, ServeBuilder, ServeConfig, ServeContextFactory, ServeEndpointMap, ServeQueriesMap, StandaloneQueryDefinition } from "./types.js";
+import type { AuthContext, QueryObjectConfig, SchemaOutput, ServeBuilder, ServeConfig, ServeContextFactory, ServeEndpointMap, ServeSemanticEndpointMap, ServeQueriesMap, StandaloneQueryDefinition, MetricsConfig, DatasetsConfig } from "./types.js";
 import type { ZodTypeAny } from "zod";
 export declare const createQueryFactory: <TContext extends Record<string, unknown> = Record<string, unknown>, TAuth extends AuthContext = AuthContext>(contextFactory?: ServeContextFactory<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>;
 /**
@@ -12,5 +12,5 @@ export declare const query: <TInputSchema extends ZodTypeAny | undefined = undef
  *
  * This is the unbound version. Use `initServe().serve(...)` when you want shared context and config.
  */
-export declare function serve<TContext extends Record<string, unknown> = Record<string, unknown>, TAuth extends AuthContext = AuthContext, TQueries extends ServeQueriesMap<TContext, TAuth> = ServeQueriesMap<TContext, TAuth>>(config: ServeConfig<TContext, TAuth, TQueries>): ServeBuilder<ServeEndpointMap<TQueries, TContext, TAuth>, TContext, TAuth>;
+export declare function serve<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>>(config: ServeConfig<TContext, TAuth, TQueries, TMetrics, TDatasets>): ServeBuilder<ServeEndpointMap<TQueries, TContext, TAuth> & ServeSemanticEndpointMap<TMetrics, TDatasets, TContext, TAuth>, TContext, TAuth>;
 //# sourceMappingURL=serve.d.ts.map

package/dist/serve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAEX,iBAAiB,EAGjB,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EAEf,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAgGtC,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,EAEvC,iBAAiB,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,MAGnD,YAAY,SAAS,UAAU,GAAG,SAAS,GAAG,SAAS,EACvD,aAAa,SAAS,UAAU,GAAG,SAAS,GAAG,SAAS,EACxD,OAAO,GAAG,aAAa,SAAS,UAAU,GAAG,YAAY,CAAC,aAAa,CAAC,GAAG,OAAO,EAElF,QAAQ,iBAAiB,CAAC,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,KAC/E,yBAAyB,CAC1B,YAAY,EACZ,aAAa,SAAS,UAAU,GAAG,aAAa,GAAG,UAAU,EAC7D,QAAQ,EACR,KAAK,EACL,OAAO,CAIV,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,KAAK,GArBd,YAAY,SAAS,UAAU,GAAG,SAAS,cAC3C,aAAa,SAAS,UAAU,GAAG,SAAS,cAC5C,OAAO,4UAmB8B,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,KAAK,CACnB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,EACvC,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,EACpF,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAG,YAAY,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAE5H"}
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAEX,iBAAiB,EAGjB,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,EACxB,eAAe,EAEf,yBAAyB,EACzB,aAAa,EACb,cAAc,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAgGtC,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,EAEvC,iBAAiB,mBAAmB,CAAC,QAAQ,EAAE,KAAK,CAAC,MAGnD,YAAY,SAAS,UAAU,GAAG,SAAS,GAAG,SAAS,EACvD,aAAa,SAAS,UAAU,GAAG,SAAS,GAAG,SAAS,EACxD,OAAO,GAAG,aAAa,SAAS,UAAU,GAAG,YAAY,CAAC,aAAa,CAAC,GAAG,OAAO,EAElF,QAAQ,iBAAiB,CAAC,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,KAC/E,yBAAyB,CAC1B,YAAY,EACZ,aAAa,SAAS,UAAU,GAAG,aAAa,GAAG,UAAU,EAC7D,QAAQ,EACR,KAAK,EACL,OAAO,CAIV,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,KAAK,GArBd,YAAY,SAAS,UAAU,GAAG,SAAS,cAC3C,aAAa,SAAS,UAAU,GAAG,SAAS,cAC5C,OAAO,4UAmB8B,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,KAAK,CACnB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,EACvC,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACxE,QAAQ,SAAS,aAAa,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC5D,SAAS,SAAS,cAAc,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAE9D,MAAM,EAAE,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,GAClE,YAAY,CACb,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,GACvC,wBAAwB,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,EAClE,QAAQ,EACR,KAAK,CACN,CAEA"}

package/dist/server/api-builder.d.ts

@@ -0,0 +1,5 @@
+import type { AuthContext, AuthStrategy, HypeQueryAPI, ServeEndpointMap, ServeMiddleware, ServeQueriesMap, ServeHandler, ExecuteQueryFunction } from "../types.js";
+import type { ServeRouter } from "../router.js";
+import { ServeQueryLogger } from "../query-logger.js";
+export declare const createAPImethods: <TQueries extends ServeQueriesMap<TContext, TAuth>, TContext extends Record<string, unknown>, TAuth extends AuthContext>(queryEntries: ServeEndpointMap<TQueries, TContext, TAuth>, queryLogger: ServeQueryLogger, router: ServeRouter, authStrategies: AuthStrategy<TAuth>[], globalMiddlewares: ServeMiddleware<any, any, TContext, TAuth>[], executeQuery: ExecuteQueryFunction<ServeEndpointMap<TQueries, TContext, TAuth>, TContext>, handler: ServeHandler, basePath: string) => HypeQueryAPI<ServeEndpointMap<TQueries, TContext, TAuth>, TContext, TAuth>;
+//# sourceMappingURL=api-builder.d.ts.map

package/dist/server/api-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-builder.d.ts","sourceRoot":"","sources":["../../src/server/api-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EAIZ,gBAAgB,EAChB,eAAe,EAEf,eAAe,EACf,YAAY,EACZ,oBAAoB,EAErB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAKtD,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,EACjD,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW,EAEzB,cAAc,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EACzD,aAAa,gBAAgB,EAC7B,QAAQ,WAAW,EACnB,gBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,EACrC,mBAAmB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,EAC/D,cAAc,oBAAoB,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,EACzF,SAAS,YAAY,EACrB,UAAU,MAAM,KACf,YAAY,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,CA0F3E,CAAC"}

package/dist/server/api-builder.js

@@ -0,0 +1,76 @@
+import { mergeTags } from "../utils.js";
+import { applyBasePath, normalizeRoutePath } from "../router.js";
+import { mapEndpointToToolkit } from "./mapper.js";
+export const createAPImethods = (queryEntries, queryLogger, router, authStrategies, globalMiddlewares, executeQuery, handler, basePath) => {
+    const api = {
+        queries: queryEntries,
+        queryLogger,
+        manifest: () => {
+            const manifest = {};
+            for (const [key, endpoint] of Object.entries(queryEntries)) {
+                manifest[key] = {
+                    method: endpoint.method,
+                    // queryEntries store the pre-basePath route; re-apply so the manifest
+                    // carries the full request path clients should call.
+                    path: applyBasePath(basePath, endpoint.metadata.path),
+                };
+            }
+            return manifest;
+        },
+        route: (path, endpoint, options = {}) => {
+            if (!endpoint) {
+                throw new Error("Endpoint definition is required when registering a route");
+            }
+            const method = options?.method ?? endpoint.method;
+            const normalizedPath = normalizeRoutePath(path);
+            const fallbackRequiresAuth = endpoint.auth
+                ? true
+                : authStrategies.length > 0
+                    ? true
+                    : undefined;
+            const requiresAuth = options?.requiresAuth ?? endpoint.metadata.requiresAuth ?? fallbackRequiresAuth;
+            const visibility = options?.visibility ?? endpoint.metadata.visibility ?? "public";
+            const metadata = {
+                ...endpoint.metadata,
+                path: normalizedPath,
+                method,
+                name: options?.name ?? endpoint.metadata.name ?? endpoint.key,
+                summary: options?.summary ?? endpoint.metadata.summary,
+                description: options?.description ?? endpoint.metadata.description,
+                tags: mergeTags(endpoint.metadata.tags, options?.tags),
+                requiresAuth,
+                visibility,
+            };
+            const middlewares = [...endpoint.middlewares, ...(options?.middlewares ?? [])];
+            const registeredEndpoint = {
+                ...endpoint,
+                method,
+                metadata,
+                middlewares,
+            };
+            router.register(registeredEndpoint);
+            return api;
+        },
+        use: (middleware) => {
+            globalMiddlewares.push(middleware);
+            return api;
+        },
+        useAuth: (strategy) => {
+            authStrategies.push(strategy);
+            router.markRoutesRequireAuth();
+            return api;
+        },
+        execute: executeQuery,
+        client: executeQuery,
+        run: executeQuery,
+        describe: () => {
+            const description = {
+                basePath: basePath || undefined,
+                queries: router.list().map(mapEndpointToToolkit),
+            };
+            return description;
+        },
+        handler,
+    };
+    return api;
+};

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

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/server/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EACV,YAAY,EAEZ,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,oBAAoB,EAGrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAYtD,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,EACjD,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW,EAEzB,cAAc,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EACzD,aAAa,gBAAgB,EAC7B,aAAa,MAAM,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC,EACnD,QAAQ,WAAW,EACnB,gBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,EACrC,mBAAmB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,EAC/D,cAAc,oBAAoB,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,EACzF,SAAS,YAAY,EACrB,UAAU,MAAM,KACf,YAAY,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,CAsF3E,CAAC"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/server/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,UAAU,EAEV,YAAY,EAEZ,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,oBAAoB,EAGrB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAYtD,eAAO,MAAM,oBAAoB,GAC/B,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,EACjD,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,SAAS,WAAW,EAEzB,cAAc,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EACzD,aAAa,gBAAgB,EAC7B,aAAa,MAAM,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC,EACnD,QAAQ,WAAW,EACnB,gBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,EACrC,mBAAmB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,EAC/D,cAAc,oBAAoB,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,EACzF,SAAS,YAAY,EACrB,UAAU,MAAM,KACf,YAAY,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,CAoG3E,CAAC"}

package/dist/server/builder.js

@@ -1,5 +1,5 @@
 import { mergeTags } from "../utils.js";
-import { normalizeRoutePath } from "../router.js";
+import { applyBasePath, normalizeRoutePath } from "../router.js";
 import { mapEndpointToToolkit } from "./mapper.js";
 const loadNodeAdapter = async () => {
     if (typeof require !== "undefined") {
@@ -13,6 +13,16 @@ export const createBuilderMethods = (queryEntries, queryLogger, routeConfig, rou
         basePath: basePath || undefined,
         queryLogger,
         _routeConfig: routeConfig,
+        manifest: () => {
+            const manifest = {};
+            for (const [key, endpoint] of Object.entries(queryEntries)) {
+                manifest[key] = {
+                    method: routeConfig[key]?.method ?? endpoint.method,
+                    path: applyBasePath(basePath, endpoint.metadata.path),
+                };
+            }
+            return manifest;
+        },
         route: (path, endpoint, options = {}) => {
             if (!endpoint) {
                 throw new Error("Endpoint definition is required when registering a route");

package/dist/server/create-api.d.ts

@@ -0,0 +1,32 @@
+import type { AuthContext, HypeQueryAPI, ServeEndpointMap, ServeQueriesMap, ServeConfig, MetricsConfig, DatasetsConfig, ServeSemanticEndpointMap } from "../types.js";
+/**
+ * Create a transport-agnostic API definition.
+ *
+ * `createAPI` sets up queries, auth, tenancy, caching, and middleware —
+ * without binding to any HTTP server or runtime. Use standalone transport
+ * functions to serve the API:
+ *
+ * @example
+ * ```ts
+ * import { createAPI } from '@hypequery/serve';
+ * import { startServer, toFetchHandler, toNodeHandler } from '@hypequery/serve';
+ *
+ * const api = createAPI({
+ *   auth: jwtStrategy,
+ *   queries: {
+ *     revenue: { query: async () => db.table('orders').sum('amount').execute() },
+ *   },
+ * });
+ *
+ * // Standalone server
+ * startServer(api, { port: 3000 });
+ *
+ * // Express / Node.js middleware
+ * app.use('/analytics', toNodeHandler(api));
+ *
+ * // Serverless (Vercel, Cloudflare, etc.)
+ * export default toFetchHandler(api);
+ * ```
+ */
+export declare const createAPI: <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>>(config: ServeConfig<TContext, TAuth, TQueries, TMetrics, TDatasets>) => HypeQueryAPI<ServeEndpointMap<TQueries, TContext, TAuth> & ServeSemanticEndpointMap<TMetrics, TDatasets, TContext, TAuth>, TContext, TAuth>;
+//# sourceMappingURL=create-api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-api.d.ts","sourceRoot":"","sources":["../../src/server/create-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAEX,YAAY,EAGZ,gBAAgB,EAIhB,eAAe,EACf,WAAW,EACX,aAAa,EACb,cAAc,EACd,wBAAwB,EACzB,MAAM,aAAa,CAAC;AA2BrB;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,SAAS,GACpB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,EACvC,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACxE,QAAQ,SAAS,aAAa,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC5D,SAAS,SAAS,cAAc,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAE9D,QAAQ,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,KAClE,YAAY,CACb,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,GACvC,wBAAwB,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,EAClE,QAAQ,EACR,KAAK,CA8ON,CAAC"}

package/dist/server/create-api.js

@@ -0,0 +1,211 @@
+import { createEndpoint } from "../endpoint.js";
+import { ServeRouter, applyBasePath, normalizeRoutePath } 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 { createAPImethods } from "./api-builder.js";
+import { createDatasetClient } from "@hypequery/datasets";
+import { createMetricEndpoint, createDatasetEndpoint } from "../semantic/datasets/index.js";
+import { attachSemanticQueryBuilder, extractQueryBuilderFromContext } from "../semantic/query-builder-context.js";
+const assertSemanticKeyAvailable = (queryEntries, key, kind) => {
+    if (key in queryEntries) {
+        throw new Error(`createAPI: ${kind} "${key}" collides with an existing query key. ` +
+            `Rename the ${kind} or the query to keep api.queries and api.execute() unambiguous.`);
+    }
+};
+/**
+ * Create a transport-agnostic API definition.
+ *
+ * `createAPI` sets up queries, auth, tenancy, caching, and middleware —
+ * without binding to any HTTP server or runtime. Use standalone transport
+ * functions to serve the API:
+ *
+ * @example
+ * ```ts
+ * import { createAPI } from '@hypequery/serve';
+ * import { startServer, toFetchHandler, toNodeHandler } from '@hypequery/serve';
+ *
+ * const api = createAPI({
+ *   auth: jwtStrategy,
+ *   queries: {
+ *     revenue: { query: async () => db.table('orders').sum('amount').execute() },
+ *   },
+ * });
+ *
+ * // Standalone server
+ * startServer(api, { port: 3000 });
+ *
+ * // Express / Node.js middleware
+ * app.use('/analytics', toNodeHandler(api));
+ *
+ * // Serverless (Vercel, Cloudflare, etc.)
+ * export default toFetchHandler(api);
+ * ```
+ */
+export const createAPI = (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 baseContextFactory = config.context;
+    // Extract queryBuilder from context.db if not provided in config
+    let resolvedQueryBuilder = config.queryBuilder;
+    let extractedFromContext = false;
+    if (!resolvedQueryBuilder && baseContextFactory && (config.metrics || config.datasets)) {
+        // If context is a static object (not a function), we can extract queryBuilder synchronously
+        if (typeof baseContextFactory !== "function") {
+            resolvedQueryBuilder = extractQueryBuilderFromContext(baseContextFactory);
+            if (resolvedQueryBuilder) {
+                extractedFromContext = true;
+            }
+        }
+    }
+    const contextFactory = baseContextFactory || resolvedQueryBuilder
+        ? async ({ request, auth }) => {
+            const baseContext = baseContextFactory
+                ? typeof baseContextFactory === "function"
+                    ? await baseContextFactory({ request, auth })
+                    : baseContextFactory
+                : {};
+            // If queryBuilder was explicitly passed in config (not extracted from context),
+            // attach it to context for backward compatibility
+            if (config.queryBuilder) {
+                return attachSemanticQueryBuilder({ ...baseContext }, config.queryBuilder);
+            }
+            // If context.db is a queryBuilder but we haven't extracted it yet,
+            // also check and attach it to the semantic runtime for consistency
+            if (!extractedFromContext && typeof baseContextFactory === "function") {
+                const maybeQueryBuilder = extractQueryBuilderFromContext(baseContext);
+                if (maybeQueryBuilder) {
+                    return attachSemanticQueryBuilder({ ...baseContext }, maybeQueryBuilder);
+                }
+            }
+            return baseContext;
+        }
+        : undefined;
+    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);
+        }
+        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",
+    };
+    const docsConfig = {
+        enabled: config.docs?.enabled ?? true,
+        path: config.docs?.path ?? "/docs",
+    };
+    const openapiPublicPath = applyBasePath(basePath, openapiConfig.path);
+    const configuredQueries = config.queries ?? {};
+    const queryEntries = {};
+    for (const key of Object.keys(configuredQueries)) {
+        const endpoint = createEndpoint(String(key), configuredQueries[key]);
+        const routePath = normalizeRoutePath(`/queries/${String(key)}`);
+        const registeredEndpoint = {
+            ...endpoint,
+            metadata: { ...endpoint.metadata, path: routePath },
+        };
+        queryEntries[key] = registeredEndpoint;
+        router.register(registeredEndpoint);
+    }
+    // Process metrics — auto-generate POST endpoints
+    if (config.metrics) {
+        const metricsEntries = config.metrics;
+        const builderFactory = resolvedQueryBuilder;
+        if (!builderFactory) {
+            throw new Error('createAPI: `queryBuilder` is required when `metrics` is provided. ' +
+                'Pass the createQueryBuilder(config) return value as `queryBuilder`, ' +
+                'or provide it via context as `context: () => ({ db: queryBuilder })`.');
+        }
+        const analytics = createDatasetClient({ queryBuilder: builderFactory });
+        for (const [name, entry] of Object.entries(metricsEntries)) {
+            assertSemanticKeyAvailable(queryEntries, name, "metric");
+            const metricEndpoint = createMetricEndpoint(name, entry, analytics, builderFactory);
+            const metricsPath = config.semanticPaths?.metrics ?? '/metrics';
+            const routePath = normalizeRoutePath(`${metricsPath}/${name}`);
+            const registeredEndpoint = {
+                ...metricEndpoint,
+                metadata: { ...metricEndpoint.metadata, path: routePath },
+            };
+            queryEntries[name] = registeredEndpoint;
+            router.register(registeredEndpoint);
+        }
+    }
+    // Process datasets — auto-generate POST endpoints for semantic dataset queries
+    if (config.datasets) {
+        const datasetEntries = config.datasets;
+        const builderFactory = resolvedQueryBuilder;
+        if (!builderFactory) {
+            throw new Error('createAPI: `queryBuilder` is required when `datasets` is provided. ' +
+                'Pass the createQueryBuilder(config) return value as `queryBuilder`, ' +
+                'or provide it via context as `context: () => ({ db: queryBuilder })`.');
+        }
+        for (const [name, entry] of Object.entries(datasetEntries)) {
+            assertSemanticKeyAvailable(queryEntries, `dataset:${name}`, "dataset");
+            const datasetEndpoint = createDatasetEndpoint(name, entry, builderFactory);
+            const datasetsPath = config.semanticPaths?.datasets ?? '/datasets';
+            const routePath = normalizeRoutePath(`${datasetsPath}/${name}/query`);
+            const registeredEndpoint = {
+                ...datasetEndpoint,
+                metadata: { ...datasetEndpoint.metadata, path: routePath },
+            };
+            queryEntries[`dataset:${name}`] = registeredEndpoint;
+            router.register(registeredEndpoint);
+        }
+    }
+    const corsConfig = resolveCorsConfig(config.cors);
+    const handler = createServeHandler({
+        router,
+        globalMiddlewares,
+        authStrategies,
+        tenantConfig: globalTenantConfig,
+        contextFactory,
+        hooks,
+        queryLogger,
+        verboseAuthErrors: config.security?.verboseAuthErrors ?? false,
+        corsConfig,
+    });
+    const executeQuery = createExecuteQuery(queryEntries, authStrategies, contextFactory, globalMiddlewares, globalTenantConfig, hooks, queryLogger, config.security?.verboseAuthErrors ?? false);
+    const api = createAPImethods(queryEntries, queryLogger, 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);
+    }
+    return api;
+};

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

@@ -1,3 +1,22 @@
-import type { AuthContext, ServeBuilder, ServeConfig, ServeEndpointMap, ServeQueriesMap } from "../types.js";
-export declare const defineServe: <TContext extends Record<string, unknown> = Record<string, unknown>, TAuth extends AuthContext = AuthContext, TQueries extends ServeQueriesMap<TContext, TAuth> = ServeQueriesMap<TContext, TAuth>>(config: ServeConfig<TContext, TAuth, TQueries>) => ServeBuilder<ServeEndpointMap<TQueries, TContext, TAuth>, TContext, TAuth>;
+import type { AuthContext, ServeBuilder, ServeConfig, ServeEndpointMap, ServeSemanticEndpointMap, ServeQueriesMap, MetricsConfig, DatasetsConfig } from "../types.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 declare const defineServe: <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>>(config: ServeConfig<TContext, TAuth, TQueries, TMetrics, TDatasets>) => ServeBuilder<ServeEndpointMap<TQueries, TContext, TAuth> & ServeSemanticEndpointMap<TMetrics, TDatasets, TContext, TAuth>, TContext, TAuth>;
 //# sourceMappingURL=define-serve.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"define-serve.d.ts","sourceRoot":"","sources":["../../src/server/define-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EAGX,YAAY,EACZ,WAAW,EAEX,gBAAgB,EAIhB,eAAe,EAEhB,MAAM,aAAa,CAAC;AAWrB,eAAO,MAAM,WAAW,GACtB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,EACvC,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,EAEpF,QAAQ,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,KAC7C,YAAY,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,QAAQ,EAAE,KAAK,CAoH3E,CAAC"}
+{"version":3,"file":"define-serve.d.ts","sourceRoot":"","sources":["../../src/server/define-serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,wBAAwB,EACxB,eAAe,EAEf,aAAa,EACb,cAAc,EACf,MAAM,aAAa,CAAC;AAGrB;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClE,KAAK,SAAS,WAAW,GAAG,WAAW,EACvC,QAAQ,SAAS,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EACxE,QAAQ,SAAS,aAAa,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC5D,SAAS,SAAS,cAAc,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAE9D,QAAQ,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,KAClE,YAAY,CACb,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,GACvC,wBAAwB,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,EAClE,QAAQ,EACR,KAAK,CAqDN,CAAC"}