@hypequery/serve 0.2.1 → 0.3.0

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

@@ -0,0 +1,121 @@
+/**
+ * Converts a DatasetInstance into a standard ServeEndpoint for semantic queries.
+ *
+ * The generated endpoint is a POST handler that:
+ * - Accepts dimensions, measures, filters, orderBy, limit, offset, by
+ * - Validates requested dimensions/measures/filters against the dataset contract
+ * - Executes via QueryBuilderFactoryLike
+ * - Applies Serve-managed tenant filtering when configured
+ * - Returns { data } or { data, meta } based on headers
+ */
+import { z } from 'zod';
+import { runDatasetQuery, validateDatasetQuery, } from '@hypequery/datasets/internal';
+import { ServeHttpError } from '../../errors.js';
+import { resolveSemanticExecutionRuntime, resolveSemanticQueryBuilder, } from '../query-builder-context.js';
+import { buildDatasetQueryDescription } from './utils/dataset-query-metadata.js';
+import { resolveDatasetEntry } from './utils/dataset-entry.js';
+import { buildDatasetInputSchema } from './utils/semantic-input-schema.js';
+// ---------------------------------------------------------------------------
+// Zod schemas for dataset query input / output
+// ---------------------------------------------------------------------------
+const datasetResultMetaSchema = 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 datasetResultSchema = z.object({
+    data: z.array(z.record(z.unknown())),
+    meta: datasetResultMetaSchema,
+});
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+export function createDatasetEndpoint(name, entry, builderFactory) {
+    const resolved = resolveDatasetEntry(entry);
+    const ds = resolved.dataset;
+    const effectiveMaxLimit = resolved.maxLimit ?? ds.limits?.maxResultSize ?? 1000;
+    // Build a schema whose dimension/measure/filter fields are enumerated from
+    // this dataset's contract, so OpenAPI/docs and clients see the valid fields.
+    const datasetQueryInputSchema = buildDatasetInputSchema(ds);
+    const metadata = {
+        path: '', // filled by router.register
+        method: 'POST',
+        name: name,
+        summary: `Query the "${name}" semantic dataset`,
+        description: buildDatasetQueryDescription(ds, effectiveMaxLimit),
+        tags: ['datasets'],
+        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 start = Date.now();
+        const runtime = resolveSemanticExecutionRuntime(semanticContext);
+        // Validate
+        const query = {
+            dimensions: input.dimensions,
+            measures: input.measures,
+            filters: input.filters,
+            orderBy: input.orderBy,
+            limit: Math.min(input.limit ?? effectiveMaxLimit, effectiveMaxLimit),
+            offset: input.offset,
+            by: input.by,
+        };
+        const executionContext = runtime ? { runtime } : undefined;
+        const validation = validateDatasetQuery(ds, query, executionContext);
+        if (!validation.valid) {
+            throw new ServeHttpError(400, 'VALIDATION_ERROR', validation.errors.join('; '));
+        }
+        // Build query
+        const runtimeBuilderFactory = resolveSemanticQueryBuilder(semanticContext, builderFactory);
+        if (ctx.tenantId) {
+            if (!runtime?.tenant || !ds.tenantKey) {
+                throw new ServeHttpError(500, 'INTERNAL_SERVER_ERROR', `Dataset endpoint "${name}" requires dataset tenantKey and serve tenant runtime when tenant isolation is enabled.`);
+            }
+        }
+        const result = await runDatasetQuery(ds, query, {
+            builderFactory: runtimeBuilderFactory,
+            context: executionContext,
+        });
+        const timingMs = Date.now() - start;
+        // Meta — opt in via the `includeMeta` input field or the x-include-meta header.
+        const includeMeta = input.includeMeta === true
+            || ctx.request?.headers?.['x-include-meta'] === 'true';
+        return {
+            data: result.data,
+            meta: includeMeta ? {
+                ...(result.meta ?? {}),
+                timingMs,
+            } : undefined,
+        };
+    };
+    return {
+        key: name,
+        method: 'POST',
+        inputSchema: datasetQueryInputSchema,
+        outputSchema: datasetResultSchema,
+        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,
+    };
+}

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

@@ -0,0 +1,6 @@
+export { dataset, dimension, measure, belongsTo, hasMany, hasOne, sum, count, countDistinct, avg, min, max, divide, multiply, subtract, add, nullIfZero, coalesce, round, floor, ceil, eq, neq, gt, gte, lt, lte, inList, notInList, between, like, asc, desc, filter, order, createDatasetRegistry, } from '@hypequery/datasets';
+export type { FieldType, DimensionType, DimensionOptions, DimensionDefinition, MeasureOptions, MeasureDefinition, InferDimensionType, RelationshipKind, RelationshipDefinition, AggregationType, MeasureAggregation, AggregationSpec, FormulaExpr, DerivedMetricSpec, TimeGrain, MetricRef, BaseMetricRef, DerivedMetricRef, GrainedMetricRef, MetricContract, MetricFilter, MetricOrderBy, MetricQuery, DatasetQuery, MetricResultMeta, MetricResult, DatasetQueryResult, MetricHandle, ExecutionContext, SemanticExecutionRuntime, SemanticTenantRuntime, SemanticFilterDefinition, SemanticFiltersDefinition, DatasetConfig, DatasetLimits, DatasetInstance, BaseMetricConfig, DerivedMetricConfig, DatasetRegistryInstance, DatasetFieldNames, } from '@hypequery/datasets';
+export { createMetricEndpoint } from './metric-endpoint.js';
+export { createDatasetEndpoint } from './dataset-endpoint.js';
+export type { DatasetEntry } from './dataset-endpoint.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/semantic/datasets/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,OAAO,EACP,SAAS,EACT,OAAO,EACP,SAAS,EACT,OAAO,EACP,MAAM,EACN,GAAG,EACH,KAAK,EACL,aAAa,EACb,GAAG,EACH,GAAG,EACH,GAAG,EACH,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,GAAG,EACH,UAAU,EACV,QAAQ,EACR,KAAK,EACL,KAAK,EACL,IAAI,EACJ,EAAE,EACF,GAAG,EACH,EAAE,EACF,GAAG,EACH,EAAE,EACF,GAAG,EACH,MAAM,EACN,SAAS,EACT,OAAO,EACP,IAAI,EACJ,GAAG,EACH,IAAI,EACJ,MAAM,EACN,KAAK,EACL,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACxB,yBAAyB,EACzB,aAAa,EACb,aAAa,EACb,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/semantic/datasets/index.js

@@ -0,0 +1,5 @@
+// Re-export public datasets APIs for convenience
+export { dataset, dimension, measure, belongsTo, hasMany, hasOne, sum, count, countDistinct, avg, min, max, divide, multiply, subtract, add, nullIfZero, coalesce, round, floor, ceil, eq, neq, gt, gte, lt, lte, inList, notInList, between, like, asc, desc, filter, order, createDatasetRegistry, } from '@hypequery/datasets';
+// Serve-specific endpoint integration
+export { createMetricEndpoint } from './metric-endpoint.js';
+export { createDatasetEndpoint } from './dataset-endpoint.js';

package/dist/semantic/datasets/metric-endpoint.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 type { AuthContext, MetricEntry, ServeEndpoint } from '../../types.js';
+import type { DatasetClient, QueryBuilderFactoryLike } from '@hypequery/datasets';
+declare const metricResultSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">;
+    meta: z.ZodOptional<z.ZodObject<{
+        timingMs: z.ZodOptional<z.ZodNumber>;
+        sql: z.ZodOptional<z.ZodString>;
+        tenant: z.ZodOptional<z.ZodString>;
+        rowCount: z.ZodOptional<z.ZodNumber>;
+        pagination: z.ZodOptional<z.ZodObject<{
+            limit: z.ZodNumber;
+            offset: z.ZodNumber;
+            hasMore: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            limit: number;
+            offset: number;
+            hasMore: boolean;
+        }, {
+            limit: number;
+            offset: number;
+            hasMore: boolean;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        tenant?: string | undefined;
+        timingMs?: number | undefined;
+        sql?: string | undefined;
+        rowCount?: number | undefined;
+        pagination?: {
+            limit: number;
+            offset: number;
+            hasMore: boolean;
+        } | undefined;
+    }, {
+        tenant?: string | undefined;
+        timingMs?: number | undefined;
+        sql?: string | undefined;
+        rowCount?: number | undefined;
+        pagination?: {
+            limit: number;
+            offset: number;
+            hasMore: boolean;
+        } | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    data: Record<string, unknown>[];
+    meta?: {
+        tenant?: string | undefined;
+        timingMs?: number | undefined;
+        sql?: string | undefined;
+        rowCount?: number | undefined;
+        pagination?: {
+            limit: number;
+            offset: number;
+            hasMore: boolean;
+        } | undefined;
+    } | undefined;
+}, {
+    data: Record<string, unknown>[];
+    meta?: {
+        tenant?: string | undefined;
+        timingMs?: number | undefined;
+        sql?: string | undefined;
+        rowCount?: number | undefined;
+        pagination?: {
+            limit: number;
+            offset: number;
+            hasMore: boolean;
+        } | undefined;
+    } | undefined;
+}>;
+export declare function createMetricEndpoint<TAuth extends AuthContext>(name: string, entry: MetricEntry<TAuth>, analytics: DatasetClient, defaultBuilderFactory: QueryBuilderFactoryLike): ServeEndpoint<z.ZodTypeAny, typeof metricResultSchema, any, TAuth, any>;
+export {};
+//# sourceMappingURL=metric-endpoint.d.ts.map

package/dist/semantic/datasets/metric-endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-endpoint.d.ts","sourceRoot":"","sources":["../../../src/semantic/datasets/metric-endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,WAAW,EAIX,WAAW,EACX,aAAa,EAGd,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAsB,aAAa,EAAgC,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAwBpI,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGtB,CAAC;AAoDH,wBAAgB,oBAAoB,CAAC,KAAK,SAAS,WAAW,EAC5D,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,EACzB,SAAS,EAAE,aAAa,EACxB,qBAAqB,EAAE,uBAAuB,GAC7C,aAAa,CAAC,CAAC,CAAC,UAAU,EAAE,OAAO,kBAAkB,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CA4GzE"}

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';