@hypequery/serve 0.2.0 → 0.3.0

package/dist/semantic/datasets/metric-endpoint.js

@@ -0,0 +1,159 @@
+/**
+ * Converts a MetricRef into a standard ServeEndpoint.
+ *
+ * The generated endpoint is a POST handler that:
+ * - Validates dimensions/filters against the metric's contract
+ * - Calls DatasetClient.execute() with the parsed query + tenant context
+ * - Returns { data } or { data, meta } based on headers
+ */
+import { z } from 'zod';
+import { ServeHttpError } from '../../errors.js';
+import { resolveSemanticExecutionRuntime, resolveSemanticQueryBuilder, } from '../query-builder-context.js';
+import { buildMetricInputSchema } from './utils/semantic-input-schema.js';
+// ---------------------------------------------------------------------------
+// Zod schemas for metric query input / output
+// ---------------------------------------------------------------------------
+const metricResultMetaSchema = z.object({
+    timingMs: z.number().optional(),
+    sql: z.string().optional(),
+    tenant: z.string().optional(),
+    rowCount: z.number().optional(),
+    pagination: z.object({
+        limit: z.number(),
+        offset: z.number(),
+        hasMore: z.boolean(),
+    }).optional(),
+}).optional();
+const metricResultSchema = z.object({
+    data: z.array(z.record(z.unknown())),
+    meta: metricResultMetaSchema,
+});
+function isMetricHandleEntry(entry) {
+    return (!!entry &&
+        typeof entry === 'object' &&
+        '__type' in entry &&
+        (entry.__type === 'metric_ref' || entry.__type === 'grained_metric_ref'));
+}
+function isMetricEntryOptions(entry) {
+    return !!entry && typeof entry === 'object' && 'metric' in entry;
+}
+function resolveMetricEntry(entry) {
+    if (isMetricHandleEntry(entry)) {
+        return { metric: entry };
+    }
+    if (isMetricEntryOptions(entry)) {
+        return entry;
+    }
+    throw new Error('Invalid metric entry.');
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function createMetricEndpoint(name, entry, analytics, defaultBuilderFactory) {
+    const resolved = resolveMetricEntry(entry);
+    const metricRef = resolved.metric;
+    const contract = metricRef.contract();
+    // The metric's underlying dataset, used to enumerate valid query fields and
+    // page-size defaults.
+    const ds = (metricRef.__type === 'metric_ref' ? metricRef.dataset : metricRef.metric.dataset);
+    const metricQueryInputSchema = buildMetricInputSchema(ds, contract.name);
+    // Page-size cap, mirroring datasets: clamp (don't reject) and apply a default
+    // so a metric query is never unbounded.
+    const effectiveMaxLimit = resolved.maxLimit ?? ds.limits?.maxResultSize ?? 1000;
+    const metadata = {
+        path: '', // filled by router.register
+        method: 'POST',
+        name: contract.label ?? name,
+        summary: `Query the "${name}" metric`,
+        description: buildDescription(contract, effectiveMaxLimit),
+        tags: ['metrics'],
+        requiresAuth: resolved.auth !== null ? undefined : false,
+        requiredRoles: resolved.requiredRoles,
+        requiredScopes: resolved.requiredScopes,
+        cacheTtlMs: resolved.cache,
+        visibility: 'public',
+        custom: {
+            usesServeTenantRuntime: true,
+        },
+    };
+    const handler = async (ctx) => {
+        const semanticContext = ctx;
+        const input = ctx.input ?? {};
+        const runtime = resolveSemanticExecutionRuntime(semanticContext);
+        const runtimeBuilderFactory = resolveSemanticQueryBuilder(semanticContext, defaultBuilderFactory);
+        // Build the metric query
+        const query = {
+            dimensions: input.dimensions,
+            filters: input.filters,
+            orderBy: input.orderBy,
+            limit: Math.min(input.limit ?? effectiveMaxLimit, effectiveMaxLimit),
+            offset: input.offset,
+            by: input.by,
+        };
+        if (ctx.tenantId && !runtime?.tenant) {
+            throw new ServeHttpError(500, 'INTERNAL_SERVER_ERROR', `Metric endpoint "${name}" requires serve tenant runtime when tenant isolation is enabled.`);
+        }
+        const validationContext = ctx.tenantId && runtime?.tenant
+            ? {
+                runtime: {
+                    tenant: runtime.tenant,
+                },
+            }
+            : undefined;
+        const validation = analytics.validate(metricRef, query, validationContext);
+        if (!validation.valid) {
+            throw new ServeHttpError(400, 'VALIDATION_ERROR', validation.errors.join('; '));
+        }
+        // Execute with tenant context
+        const result = await analytics.execute(metricRef, query, {
+            runtime: {
+                ...runtime,
+                builderFactory: runtimeBuilderFactory,
+                tenant: runtime?.tenant,
+            },
+        });
+        // Decide whether to include meta — `includeMeta` input field or x-include-meta header.
+        const includeMeta = input.includeMeta === true
+            || ctx.request?.headers?.['x-include-meta'] === 'true';
+        return {
+            data: result.data,
+            meta: includeMeta ? result.meta : undefined,
+        };
+    };
+    return {
+        key: name,
+        method: 'POST',
+        inputSchema: metricQueryInputSchema,
+        outputSchema: metricResultSchema,
+        handler,
+        query: undefined,
+        middlewares: (resolved.middlewares ?? []),
+        auth: resolved.auth ?? null,
+        tenant: resolved.tenant,
+        metadata,
+        cacheTtlMs: resolved.cache ?? null,
+        defaultHeaders: undefined,
+        requiredRoles: resolved.requiredRoles,
+        requiredScopes: resolved.requiredScopes,
+    };
+}
+function buildDescription(contract, maxLimit) {
+    const lines = [
+        contract.description ?? `${contract.name} metric on the ${contract.dataset} dataset.`,
+        '',
+        `**Type:** ${contract.kind}`,
+        `**Dataset:** ${contract.dataset}`,
+        `**Dimensions:** ${contract.dimensions.join(', ') || 'none'}`,
+        `**Max limit:** ${maxLimit}`,
+    ];
+    if (contract.grains.length > 0) {
+        lines.push(`**Time grains:** ${contract.grains.join(', ')}`);
+    }
+    if (contract.requires && contract.requires.length > 0) {
+        lines.push(`**Requires:** ${contract.requires.join(', ')}`);
+    }
+    if (contract.tenantScoped) {
+        lines.push('**Tenant scoped:** yes');
+    }
+    return lines.join('\n');
+}

package/dist/semantic/datasets/utils/dataset-entry.d.ts

@@ -0,0 +1,24 @@
+import type { AuthContext, AuthStrategy, ServeMiddleware, TenantConfigOverride } from '../../../types.js';
+import type { AnyDatasetInstance } from '@hypequery/datasets';
+export type DatasetEntry<TAuth extends AuthContext = AuthContext> = AnyDatasetInstance | {
+    dataset: AnyDatasetInstance;
+    auth?: AuthStrategy<TAuth> | null;
+    tenant?: TenantConfigOverride<TAuth>;
+    cache?: number | null;
+    requiredRoles?: string[];
+    requiredScopes?: string[];
+    /** Middleware applied to this dataset endpoint. */
+    middlewares?: ServeMiddleware<any, any, any, TAuth>[];
+    maxLimit?: number;
+};
+export declare function resolveDatasetEntry<TAuth extends AuthContext>(entry: DatasetEntry<TAuth>): {
+    dataset: AnyDatasetInstance;
+    auth?: AuthStrategy<TAuth> | null;
+    tenant?: TenantConfigOverride<TAuth>;
+    cache?: number | null;
+    requiredRoles?: string[];
+    requiredScopes?: string[];
+    middlewares?: ServeMiddleware<any, any, any, TAuth>[];
+    maxLimit?: number;
+};
+//# sourceMappingURL=dataset-entry.d.ts.map

package/dist/semantic/datasets/utils/dataset-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-entry.d.ts","sourceRoot":"","sources":["../../../../src/semantic/datasets/utils/dataset-entry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,MAAM,MAAM,YAAY,CAAC,KAAK,SAAS,WAAW,GAAG,WAAW,IAC5D,kBAAkB,GAClB;IACE,OAAO,EAAE,kBAAkB,CAAC;IAC5B,IAAI,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAClC,MAAM,CAAC,EAAE,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,mDAAmD;IACnD,WAAW,CAAC,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAgBN,wBAAgB,mBAAmB,CAAC,KAAK,SAAS,WAAW,EAC3D,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC,GACzB;IACD,OAAO,EAAE,kBAAkB,CAAC;IAC5B,IAAI,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAClC,MAAM,CAAC,EAAE,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAUA"}

package/dist/semantic/datasets/utils/dataset-entry.js

@@ -0,0 +1,15 @@
+function isDatasetInstance(entry) {
+    return !!entry && typeof entry === 'object' && '__type' in entry && entry.__type === 'dataset';
+}
+function isDatasetEntryOptions(entry) {
+    return !!entry && typeof entry === 'object' && 'dataset' in entry;
+}
+export function resolveDatasetEntry(entry) {
+    if (isDatasetInstance(entry)) {
+        return { dataset: entry };
+    }
+    if (isDatasetEntryOptions(entry)) {
+        return entry;
+    }
+    throw new Error('Invalid dataset entry.');
+}

package/dist/semantic/datasets/utils/dataset-query-metadata.d.ts

@@ -0,0 +1,3 @@
+import type { AnyDatasetInstance } from '@hypequery/datasets';
+export declare function buildDatasetQueryDescription(ds: AnyDatasetInstance, maxLimit: number): string;
+//# sourceMappingURL=dataset-query-metadata.d.ts.map

package/dist/semantic/datasets/utils/dataset-query-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataset-query-metadata.d.ts","sourceRoot":"","sources":["../../../../src/semantic/datasets/utils/dataset-query-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,kBAAkB,EACtB,QAAQ,EAAE,MAAM,GACf,MAAM,CAYR"}

package/dist/semantic/datasets/utils/dataset-query-metadata.js

@@ -0,0 +1,12 @@
+export function buildDatasetQueryDescription(ds, maxLimit) {
+    const dimensionNames = Object.keys(ds.dimensions);
+    const measureNames = Object.keys(ds.measures);
+    const lines = [
+        `Query the ${ds.name} semantic dataset (source: ${ds.source}).`,
+        '',
+        `**Dimensions:** ${dimensionNames.join(', ') || 'none'}`,
+        `**Measures:** ${measureNames.join(', ') || 'none'}`,
+        `**Max limit:** ${maxLimit}`,
+    ];
+    return lines.join('\n');
+}

package/dist/semantic/datasets/utils/semantic-input-schema.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Builds per-dataset / per-metric Zod input schemas whose dimension, measure,
+ * filter, and orderBy fields are constrained to the names the semantic
+ * validators accept. This upgrades the generated OpenAPI/docs from "array of
+ * arbitrary strings" to enumerated fields and enables typed client codegen.
+ *
+ * The enums are deliberately a *superset-safe* mirror of the runtime validators
+ * (`validateDatasetQueryInput` / the metric `validateQuery`): they never reject
+ * a field the validator would accept. Where a list would be empty (e.g. a
+ * dataset with no declared filters) we fall back to `z.string()` and let the
+ * validator produce the precise error, rather than emitting an empty enum.
+ */
+import { z } from 'zod';
+import type { AnyDatasetInstance } from '@hypequery/datasets';
+/**
+ * Input schema for a dataset query endpoint, mirroring
+ * `validateDatasetQueryInput`.
+ */
+export declare function buildDatasetInputSchema(ds: AnyDatasetInstance): z.ZodObject<{
+    dimensions: z.ZodOptional<z.ZodArray<z.ZodTypeAny, "many">>;
+    measures: z.ZodOptional<z.ZodArray<z.ZodTypeAny, "many">>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodTypeAny, "many">>;
+    orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodTypeAny;
+        direction: z.ZodEnum<["asc", "desc"]>;
+    }, "strip", z.ZodTypeAny, {
+        direction: "asc" | "desc";
+        field?: any;
+    }, {
+        direction: "asc" | "desc";
+        field?: any;
+    }>, "many">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    by: z.ZodOptional<z.ZodEnum<["day", "week", "month", "quarter", "year"]>>;
+    includeMeta: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    dimensions?: any[] | undefined;
+    measures?: any[] | undefined;
+    filters?: any[] | undefined;
+    orderBy?: {
+        direction: "asc" | "desc";
+        field?: any;
+    }[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    by?: "day" | "week" | "month" | "quarter" | "year" | undefined;
+    includeMeta?: boolean | undefined;
+}, {
+    dimensions?: any[] | undefined;
+    measures?: any[] | undefined;
+    filters?: any[] | undefined;
+    orderBy?: {
+        direction: "asc" | "desc";
+        field?: any;
+    }[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    by?: "day" | "week" | "month" | "quarter" | "year" | undefined;
+    includeMeta?: boolean | undefined;
+}>;
+/**
+ * Input schema for a metric query endpoint, mirroring the metric `validateQuery`.
+ * Metrics select a single value, so there is no `measures` field; `orderBy` may
+ * reference the metric's own output column (`metricName`).
+ */
+export declare function buildMetricInputSchema(ds: AnyDatasetInstance, metricName: string): z.ZodObject<{
+    dimensions: z.ZodOptional<z.ZodArray<z.ZodTypeAny, "many">>;
+    filters: z.ZodOptional<z.ZodArray<z.ZodTypeAny, "many">>;
+    orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodTypeAny;
+        direction: z.ZodEnum<["asc", "desc"]>;
+    }, "strip", z.ZodTypeAny, {
+        direction: "asc" | "desc";
+        field?: any;
+    }, {
+        direction: "asc" | "desc";
+        field?: any;
+    }>, "many">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    by: z.ZodOptional<z.ZodEnum<["day", "week", "month", "quarter", "year"]>>;
+    includeMeta: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    dimensions?: any[] | undefined;
+    filters?: any[] | undefined;
+    orderBy?: {
+        direction: "asc" | "desc";
+        field?: any;
+    }[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    by?: "day" | "week" | "month" | "quarter" | "year" | undefined;
+    includeMeta?: boolean | undefined;
+}, {
+    dimensions?: any[] | undefined;
+    filters?: any[] | undefined;
+    orderBy?: {
+        direction: "asc" | "desc";
+        field?: any;
+    }[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    by?: "day" | "week" | "month" | "quarter" | "year" | undefined;
+    includeMeta?: boolean | undefined;
+}>;
+//# sourceMappingURL=semantic-input-schema.d.ts.map

package/dist/semantic/datasets/utils/semantic-input-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-input-schema.d.ts","sourceRoot":"","sources":["../../../../src/semantic/datasets/utils/semantic-input-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAqC9D;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmB7D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiBhF"}

package/dist/semantic/datasets/utils/semantic-input-schema.js

@@ -0,0 +1,87 @@
+/**
+ * Builds per-dataset / per-metric Zod input schemas whose dimension, measure,
+ * filter, and orderBy fields are constrained to the names the semantic
+ * validators accept. This upgrades the generated OpenAPI/docs from "array of
+ * arbitrary strings" to enumerated fields and enables typed client codegen.
+ *
+ * The enums are deliberately a *superset-safe* mirror of the runtime validators
+ * (`validateDatasetQueryInput` / the metric `validateQuery`): they never reject
+ * a field the validator would accept. Where a list would be empty (e.g. a
+ * dataset with no declared filters) we fall back to `z.string()` and let the
+ * validator produce the precise error, rather than emitting an empty enum.
+ */
+import { z } from 'zod';
+const OPERATORS = [
+    'eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'in', 'notIn', 'between', 'like',
+];
+const GRAINS = ['day', 'week', 'month', 'quarter', 'year'];
+/** An enum over the given field names, or a plain string when none are known. */
+function fieldEnum(values) {
+    const unique = Array.from(new Set(values));
+    return unique.length > 0
+        ? z.enum(unique)
+        : z.string();
+}
+function filterSchema(fieldNames) {
+    return z.object({
+        field: fieldEnum(fieldNames),
+        operator: z.enum(OPERATORS),
+        value: z.unknown(),
+    });
+}
+function orderBySchema(fieldNames) {
+    return z.object({
+        field: fieldEnum(fieldNames),
+        direction: z.enum(['asc', 'desc']),
+    });
+}
+/** Apply a `.max()` bound only when the dataset declares one. */
+function boundedArray(item, max) {
+    const arr = z.array(item);
+    return (max != null ? arr.max(max) : arr).optional();
+}
+/**
+ * Input schema for a dataset query endpoint, mirroring
+ * `validateDatasetQueryInput`.
+ */
+export function buildDatasetInputSchema(ds) {
+    const dimensionNames = Object.keys(ds.dimensions);
+    const measureNames = Object.keys(ds.measures);
+    // Dataset filters are keyed by filter-definition name (no dimension fallback).
+    const filterNames = Object.keys(ds.filters);
+    // orderBy is query-dependent at runtime; the static superset is every
+    // dimension/measure plus the synthetic `period` column when grained.
+    const orderableNames = [...dimensionNames, ...measureNames, 'period'];
+    return z.object({
+        dimensions: boundedArray(fieldEnum(dimensionNames), ds.limits?.maxDimensions),
+        measures: boundedArray(fieldEnum(measureNames), ds.limits?.maxMeasures),
+        filters: boundedArray(filterSchema(filterNames), ds.limits?.maxFilters),
+        orderBy: z.array(orderBySchema(orderableNames)).optional(),
+        limit: z.number().int().positive().optional(),
+        offset: z.number().int().nonnegative().optional(),
+        by: z.enum(GRAINS).optional(),
+        includeMeta: z.boolean().optional(),
+    }).strict();
+}
+/**
+ * Input schema for a metric query endpoint, mirroring the metric `validateQuery`.
+ * Metrics select a single value, so there is no `measures` field; `orderBy` may
+ * reference the metric's own output column (`metricName`).
+ */
+export function buildMetricInputSchema(ds, metricName) {
+    const dimensionNames = Object.keys(ds.dimensions);
+    // Metric validator falls back to dimension names when no filters are declared.
+    const filterNames = Object.keys(ds.filters).length > 0
+        ? Object.keys(ds.filters)
+        : dimensionNames;
+    const orderableNames = [...dimensionNames, metricName, 'period'];
+    return z.object({
+        dimensions: boundedArray(fieldEnum(dimensionNames), ds.limits?.maxDimensions),
+        filters: boundedArray(filterSchema(filterNames), ds.limits?.maxFilters),
+        orderBy: z.array(orderBySchema(orderableNames)).optional(),
+        limit: z.number().int().positive().optional(),
+        offset: z.number().int().nonnegative().optional(),
+        by: z.enum(GRAINS).optional(),
+        includeMeta: z.boolean().optional(),
+    });
+}

package/dist/semantic/index.d.ts

@@ -0,0 +1,2 @@
+export * from './datasets/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/semantic/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC"}

package/dist/semantic/index.js

@@ -0,0 +1 @@
+export * from './datasets/index.js';

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"}