@bayoudhi/moose-lib-serverless 0.7.11 → 0.7.13

package/dist/index.d.ts

@@ -1,13 +1,17 @@
 export { JWT, Key } from './browserCompatible';
 import * as _clickhouse_client from '@clickhouse/client';
-import { aE as MooseUtils, aF as MooseClient } from './index-DdE-_e4q';
-export { A as Aggregated, h as Api, i as ApiConfig, aP as ApiHelpers, ao as ApiUtil, Y as ClickHouseByteSize, a7 as ClickHouseCodec, X as ClickHouseDecimal, a3 as ClickHouseDefault, C as ClickHouseEngines, Z as ClickHouseFixedStringSize, _ as ClickHouseFloat, $ as ClickHouseInt, a0 as ClickHouseJson, aI as ClickHouseLineString, a5 as ClickHouseMaterialized, aJ as ClickHouseMultiLineString, aL as ClickHouseMultiPolygon, a2 as ClickHouseNamedTuple, aG as ClickHousePoint, aK as ClickHousePolygon, U as ClickHousePrecision, aH as ClickHouseRing, a4 as ClickHouseTTL, j as ConsumptionApi, aQ as ConsumptionHelpers, ap as ConsumptionUtil, a8 as DateTime, a9 as DateTime64, ab as DateTime64String, aa as DateTimeString, e as DeadLetter, D as DeadLetterModel, f as DeadLetterQueue, an as Decimal, m as ETLPipeline, n as ETLPipelineConfig, E as EgressConfig, ac as FixedString, ad as Float32, ae as Float64, F as FrameworkApp, ar as IdentifierBrandedString, I as IngestApi, g as IngestConfig, k as IngestPipeline, ag as Int16, ah as Int32, ai as Int64, af as Int8, L as LifeCycle, a1 as LowCardinality, M as MaterializedView, as as NonIdentifierBrandedString, a as OlapConfig, O as OlapTable, aM as QueryClient, au as RawValue, b as S3QueueTableSettings, S as SimpleAggregated, ax as Sql, l as SqlResource, av as SqlTemplateTag, c as Stream, d as StreamConfig, T as Task, ak as UInt16, al as UInt32, am as UInt64, aj as UInt8, at as Value, V as View, o as WebApp, p as WebAppConfig, q as WebAppHandler, a6 as WithDefault, W as Workflow, aN as WorkflowClient, aC as createClickhouseParameter, y as getApi, x as getApis, w as getIngestApi, v as getIngestApis, Q as getMaterializedView, R as getMaterializedViews, B as getSqlResource, z as getSqlResources, u as getStream, t as getStreams, s as getTable, r as getTables, aO as getTemporalClient, aB as getValueFromParameter, N as getView, P as getViews, K as getWebApp, J as getWebApps, H as getWorkflow, G as getWorkflows, aR as joinQueries, aD as mapToClickHouseType, aq as quoteIdentifier, aw as sql, az as toQuery, aA as toQueryPreview, ay as toStaticQuery } from './index-DdE-_e4q';
+import { V as MooseUtils, X as MooseClient, M as MaterializedView } from './index-Cs6mRtl7';
+export { A as Aggregated, f as Api, g as ApiConfig, a3 as ApiHelpers, R as ApiUtil, C as ConsumptionApi, a4 as ConsumptionHelpers, U as ConsumptionUtil, c as DeadLetter, D as DeadLetterModel, d as DeadLetterQueue, l as ETLPipeline, m as ETLPipelineConfig, E as EgressConfig, F as FrameworkApp, I as IngestApi, e as IngestConfig, h as IngestPipeline, Y as MOOSE_RLS_ROLE, _ as MOOSE_RLS_SETTING_PREFIX, Z as MOOSE_RLS_USER, $ as RowPoliciesConfig, j as SelectRowPolicy, k as SelectRowPolicyConfig, S as SimpleAggregated, i as SqlResource, a as Stream, b as StreamConfig, T as Task, n as WebApp, o as WebAppConfig, p as WebAppHandler, W as Workflow, a1 as WorkflowClient, a0 as buildRowPolicyOptionsFromClaims, x as getApi, w as getApis, v as getIngestApi, u as getIngestApis, N as getMaterializedView, O as getMaterializedViews, P as getSelectRowPolicies, Q as getSelectRowPolicy, z as getSqlResource, y as getSqlResources, t as getStream, s as getStreams, r as getTable, q as getTables, a2 as getTemporalClient, K as getView, L as getViews, J as getWebApp, H as getWebApps, G as getWorkflow, B as getWorkflows, a5 as joinQueries } from './index-Cs6mRtl7';
 import http from 'http';
+import { M as Sql, O as OlapTable, a0 as Column, _ as QueryClient, a3 as DataType } from './view-CNYx8kUh';
+export { n as ClickHouseAlias, d as ClickHouseByteSize, o as ClickHouseCodec, c as ClickHouseDecimal, k as ClickHouseDefault, C as ClickHouseEngines, e as ClickHouseFixedStringSize, f as ClickHouseFloat, g as ClickHouseInt, h as ClickHouseJson, a6 as ClickHouseLineString, m as ClickHouseMaterialized, a7 as ClickHouseMultiLineString, a9 as ClickHouseMultiPolygon, j as ClickHouseNamedTuple, a4 as ClickHousePoint, a8 as ClickHousePolygon, b as ClickHousePrecision, a5 as ClickHouseRing, l as ClickHouseTTL, D as DateTime, p as DateTime64, r as DateTime64String, q as DateTimeString, A as Decimal, F as FixedString, s as Float32, t as Float64, G as IdentifierBrandedString, B as Insertable, u as Int16, v as Int32, w as Int64, I as Int8, L as LifeCycle, i as LowCardinality, N as NonIdentifierBrandedString, a as OlapConfig, R as RawValue, a1 as RowPolicyOptions, S as S3QueueTableSettings, J as SqlTemplateTag, x as UInt16, y as UInt32, z as UInt64, U as UInt8, H as Value, V as View, W as WithDefault, Y as createClickhouseParameter, X as getValueFromParameter, Z as mapToClickHouseType, E as quoteIdentifier, K as sql, Q as toQuery, T as toQueryPreview, P as toStaticQuery } from './view-CNYx8kUh';
 import { IsTuple } from 'typia/lib/typings/IsTuple';
 import { Readable } from 'node:stream';
-import 'typia';
-import 'typia/lib/tags';
+declare namespace z { type ZodType = any; }
+type McpServer = any;
+import { IValidation } from 'typia';
 import 'jose';
+import 'typia/lib/tags';
 
 declare const Kafka: any;
 type Kafka = any;
@@ -371,8 +375,14 @@ interface RuntimeClickHouseConfig {
     password: string;
     database: string;
     useSSL: boolean;
+    rlsUser?: string;
+    rlsPassword?: string;
 }
 
+interface GetMooseUtilsOptions {
+    /** Map of JWT claim names to their values for row policy scoping */
+    rlsContext?: Record<string, string>;
+}
 /**
  * Get Moose utilities for database access and SQL queries.
  * Works in both Moose runtime and standalone contexts.
@@ -383,21 +393,17 @@ interface RuntimeClickHouseConfig {
  * const moose = getMooseUtils(); // WRONG - returns Promise, not MooseUtils!
  * ```
  *
- * **Breaking Change from v1.x**: This function signature changed from sync to async.
- * If you were using the old sync API that extracted utils from a request object,
- * use `getMooseUtilsFromRequest(req)` for backward compatibility (deprecated).
- *
- * @param req - DEPRECATED: Request parameter is no longer needed and will be ignored.
- *              If you need to extract moose from a request, use getMooseUtilsFromRequest().
- * @returns Promise resolving to MooseUtils with client and sql utilities.
- *
- * @example
+ * Pass `{ rlsContext }` to get a scoped client that enforces ClickHouse row policies:
  * ```typescript
- * const { client, sql } = await getMooseUtils();
- * const result = await client.query.execute(sql`SELECT * FROM table`);
+ * const { client, sql } = await getMooseUtils({ rlsContext: { org_id: orgId } });
+ * // All queries through this client are filtered by org_id
  * ```
+ *
+ * @param options - Optional. Pass `{ rlsContext }` to scope queries via row policies.
+ *                  DEPRECATED: Passing a request object is no longer needed and will be ignored.
+ * @returns Promise resolving to MooseUtils with client and sql utilities.
  */
-declare function getMooseUtils(req?: any): Promise<MooseUtils>;
+declare function getMooseUtils(options?: GetMooseUtilsOptions | any): Promise<MooseUtils>;
 /**
  * @deprecated Use getMooseUtils() instead.
  * Creates a Moose client for database access.
@@ -627,6 +633,754 @@ interface ExtractionResult<T = any> {
     metadata: Record<string, any>;
 }
 
+/**
+ * Query Layer Types
+ *
+ * Consolidated type definitions for the query layer.
+ *
+ * @module query-layer/types
+ */
+
+/** Valid SQL values that can be parameterized */
+type SqlValue = string | number | boolean | Date;
+/**
+ * Column reference — a Column object from OlapTable.columns.* or a raw Sql expression.
+ *
+ * @example
+ * const col = Events.columns.amount;   // Column
+ * const expr = sql`CASE WHEN ... END`; // Sql
+ */
+type ColRef = Column | Sql;
+/**
+ * Supported filter operators for building WHERE conditions.
+ *
+ * Each operator has specific value type requirements:
+ * - Scalar operators (eq, ne, gt, gte, lt, lte, like, ilike): single value
+ * - List operators (in, notIn): array of values
+ * - Range operators (between): tuple [low, high]
+ * - Null operators (isNull, isNotNull): boolean flag
+ */
+type FilterOperator = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "like" | "ilike" | "in" | "notIn" | "between" | "isNull" | "isNotNull";
+/** Sort direction for ORDER BY clauses */
+type SortDir = "ASC" | "DESC";
+/**
+ * Dimension definition — a column or expression used for grouping.
+ *
+ * @template TModel - The table's model type
+ * @template TKey - The column key (must be a key of TModel)
+ *
+ * @example
+ * dimensions: {
+ *   status: { column: "status" },
+ *   day: { expression: sql`toDate(timestamp)`, as: "day" },
+ * }
+ */
+interface DimensionDef<TModel = any, TKey extends keyof TModel = keyof TModel> {
+    column?: TKey;
+    expression?: Sql;
+    as?: string;
+    description?: string;
+}
+/**
+ * Metric definition — an aggregate or computed value.
+ *
+ * @example
+ * metrics: {
+ *   totalAmount: { agg: sql`sum(amount)` },
+ *   totalEvents: { agg: sql`count(*)` },
+ *   revenue: { agg: sql`sum(amount)`, as: "total_revenue" },
+ * }
+ */
+interface MetricDef {
+    agg: Sql;
+    as?: string;
+    description?: string;
+}
+/**
+ * Column definition for detail (non-aggregated) queries.
+ *
+ * @template TModel - The table's model type
+ * @template TKey - The column key (must be a key of TModel)
+ *
+ * @example
+ * columns: {
+ *   visitId: { column: "id" },
+ *   firstName: { join: "user", column: "first_name" },
+ * }
+ */
+interface ColumnDef<TModel = any, TKey extends keyof TModel = keyof TModel> {
+    column: TKey | string;
+    join?: string;
+    as?: string;
+}
+/**
+ * Join definition for lookup JOINs.
+ *
+ * @example
+ * joins: {
+ *   user: {
+ *     table: UsersTable,
+ *     leftKey: "user_id",
+ *     rightKey: "id",
+ *     type: "LEFT",
+ *   },
+ * }
+ */
+interface JoinDef {
+    table: OlapTable<any> | MaterializedView<any>;
+    on?: Sql;
+    leftKey?: string;
+    rightKey?: string;
+    type?: "LEFT" | "INNER";
+}
+/** Input type hint for filter UI rendering */
+type FilterInputTypeHint = "text" | "number" | "date" | "select" | "multiselect";
+/**
+ * Filter definition for use in defineQueryModel configuration.
+ *
+ * @template TModel - The table's model type
+ * @template TKey - The column key (must be a key of TModel)
+ *
+ * @example
+ * filters: {
+ *   status: { column: "status", operators: ["eq", "in"] as const },
+ *   amount: { column: "amount", operators: ["gte", "lte"] as const },
+ * }
+ */
+interface ModelFilterDef<TModel, TKey extends keyof TModel = keyof TModel> {
+    column?: TKey;
+    /** Metric name — filters referencing a metric are auto-routed to HAVING */
+    metric?: string;
+    operators: readonly FilterOperator[];
+    transform?: (value: TModel[TKey]) => SqlValue;
+    inputType?: FilterInputTypeHint;
+    /** When true, this filter's `eq` param is required in MCP tool schemas */
+    required?: true;
+    description?: string;
+}
+/** Extract string keys from a record type */
+type Names<T> = Extract<keyof T, string>;
+/**
+ * Infer the value type for a given operator and base value type.
+ *
+ * Maps filter operators to their required value types:
+ * - Scalar operators: single value
+ * - List operators (in, notIn): array of values
+ * - Range operators (between): tuple [low, high]
+ * - Null operators (isNull, isNotNull): boolean flag
+ */
+type OperatorValueType<Op extends FilterOperator, TValue = SqlValue> = Op extends "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "like" | "ilike" ? TValue : Op extends "in" | "notIn" ? TValue[] : Op extends "between" ? [TValue, TValue] : Op extends "isNull" | "isNotNull" ? boolean : never;
+/** Base constraint for filter definitions */
+type FilterDefBase = {
+    operators: readonly FilterOperator[];
+};
+/** Filter parameters structure derived from filter definitions */
+type FilterParams<TFilters extends Record<string, FilterDefBase>, TTable = any> = {
+    [K in keyof TFilters]?: {
+        [Op in TFilters[K]["operators"][number]]?: OperatorValueType<Op, TFilters[K] extends {
+            column: infer TKey extends keyof TTable;
+        } ? TTable[TKey] : SqlValue>;
+    };
+};
+/**
+ * User-facing query request specification.
+ *
+ * Users specify dimensions and metrics — semantic concepts, not SQL concepts.
+ * The query model handles the translation to actual SQL.
+ *
+ * @example
+ * const request: QueryRequest = {
+ *   dimensions: ["status", "day"],
+ *   metrics: ["totalEvents", "totalAmount"],
+ *   filters: { status: { eq: "active" } },
+ *   orderBy: [["totalAmount", "DESC"]],
+ *   limit: 10,
+ * };
+ */
+type QueryRequest<TMetrics extends string = string, TDimensions extends string = string, TFilters extends Record<string, FilterDefBase> = Record<string, FilterDefBase>, TSortable extends string = string, TColumns extends string = string, TTable = any> = {
+    filters?: FilterParams<TFilters, TTable>;
+    dimensions?: TDimensions[];
+    metrics?: TMetrics[];
+    /** Columns for detail mode (no aggregation). Mutually exclusive with dimensions/metrics. */
+    columns?: TColumns[];
+    orderBy?: Array<[TSortable, SortDir]>;
+    limit?: number;
+    /** Page number (0-indexed). Mutually exclusive with offset. */
+    page?: number;
+    /** Row offset. Mutually exclusive with page. */
+    offset?: number;
+};
+/** Individual SQL clauses for custom query assembly */
+interface QueryParts {
+    select: Sql;
+    dimensions: Sql;
+    metrics: Sql;
+    columns: Sql;
+    from: Sql;
+    conditions: Sql[];
+    where: Sql;
+    groupBy: Sql;
+    having: Sql;
+    orderBy: Sql;
+    /** Composed LIMIT + OFFSET clause */
+    pagination: Sql;
+}
+
+/**
+ * Query Model — Core query building interface and implementation.
+ *
+ * @module query-layer/query-model
+ */
+
+/**
+ * Configuration for defining a query model.
+ *
+ * @template TTable - The table's model type (row type)
+ * @template TMetrics - Record of metric definitions
+ * @template TDimensions - Record of dimension definitions
+ * @template TFilters - Record of filter definitions
+ * @template TSortable - Union type of sortable field names
+ */
+interface QueryModelConfig<TTable, TMetrics extends Record<string, MetricDef>, TDimensions extends Record<string, DimensionDef<TTable, keyof TTable>>, TFilters extends Record<string, ModelFilterDef<TTable, keyof TTable>>, TSortable extends string, TColumns extends Record<string, ColumnDef<TTable>> = Record<string, never>, TJoins extends Record<string, JoinDef> = Record<string, never>> {
+    /** Tool name used by registerModelTools (e.g. "query_visits") */
+    name?: string;
+    /** Tool description used by registerModelTools */
+    description?: string;
+    /** The OlapTable or MaterializedView to query. If a MaterializedView is passed, its targetTable is used. */
+    table: OlapTable<TTable> | MaterializedView<TTable>;
+    /**
+     * Dimension fields — columns used for grouping, filtering, and display.
+     *
+     * @example
+     * dimensions: {
+     *   status: { column: "status" },
+     *   day: { expression: sql`toDate(timestamp)`, as: "day" },
+     * }
+     */
+    dimensions?: TDimensions;
+    /**
+     * Metric fields — aggregate values computed over dimensions.
+     *
+     * @example
+     * metrics: {
+     *   totalAmount: { agg: sum(Events.columns.amount), as: "total_amount" },
+     *   totalEvents: { agg: count(), as: "total_events" },
+     * }
+     */
+    metrics?: TMetrics;
+    /**
+     * Column fields for detail (non-aggregated) queries.
+     *
+     * @example
+     * columns: {
+     *   visitId: { column: "id" },
+     *   firstName: { join: "user", column: "first_name" },
+     * }
+     */
+    columns?: TColumns;
+    /**
+     * Lookup JOIN definitions.
+     *
+     * @example
+     * joins: {
+     *   user: {
+     *     table: UsersTable,
+     *     leftKey: "user_id",
+     *     rightKey: "id",
+     *     type: "LEFT",
+     *   },
+     * }
+     */
+    joins?: TJoins;
+    /**
+     * Filterable fields with allowed operators.
+     *
+     * @example
+     * filters: {
+     *   status: { column: "status", operators: ["eq", "in"] as const },
+     *   amount: { column: "amount", operators: ["gte", "lte"] as const },
+     * }
+     */
+    filters: TFilters;
+    /**
+     * Which fields can be sorted.
+     *
+     * @example
+     * sortable: ["timestamp", "amount", "status"] as const
+     */
+    sortable: readonly TSortable[];
+    /** Default query behavior */
+    defaults?: {
+        orderBy?: Array<[TSortable, SortDir]>;
+        groupBy?: string[];
+        limit?: number;
+        maxLimit?: number;
+        dimensions?: string[];
+        metrics?: string[];
+        columns?: string[];
+    };
+}
+/**
+ * Query model interface providing type-safe query building and execution.
+ */
+interface QueryModel<TTable, TMetrics extends Record<string, MetricDef>, TDimensions extends Record<string, DimensionDef>, TFilters extends Record<string, FilterDefBase>, TSortable extends string, TResult, TColumns extends Record<string, ColumnDef> = Record<string, never>> {
+    readonly name?: string;
+    readonly description?: string;
+    readonly defaults: {
+        orderBy?: Array<[TSortable, SortDir]>;
+        groupBy?: string[];
+        limit?: number;
+        maxLimit?: number;
+        dimensions?: string[];
+        metrics?: string[];
+        columns?: string[];
+    };
+    readonly filters: TFilters;
+    readonly sortable: readonly TSortable[];
+    readonly dimensions?: TDimensions;
+    readonly metrics?: TMetrics;
+    readonly columns?: TColumns;
+    readonly columnNames: readonly string[];
+    /** Type inference helpers (similar to Drizzle's $inferSelect pattern). */
+    readonly $inferDimensions: Names<TDimensions>;
+    readonly $inferMetrics: Names<TMetrics>;
+    readonly $inferColumns: Names<TColumns>;
+    readonly $inferFilters: FilterParams<TFilters, TTable>;
+    readonly $inferRequest: QueryRequest<Names<TMetrics>, Names<TDimensions>, TFilters, TSortable, Names<TColumns>, TTable>;
+    readonly $inferResult: TResult;
+    /** Execute query with Moose QueryClient. */
+    query(request: QueryRequest<Names<TMetrics>, Names<TDimensions>, TFilters, TSortable, Names<TColumns>, TTable>, client: QueryClient): Promise<TResult[]>;
+    /** Build complete SQL query from request. */
+    toSql(request: QueryRequest<Names<TMetrics>, Names<TDimensions>, TFilters, TSortable, Names<TColumns>, TTable>): Sql;
+    /** Get individual SQL parts for custom assembly. */
+    toParts(request: QueryRequest<Names<TMetrics>, Names<TDimensions>, TFilters, TSortable, Names<TColumns>, TTable>): QueryParts;
+}
+/**
+ * Define a query model with controlled field selection, filtering, and sorting.
+ *
+ * @example
+ * const model = defineQueryModel({
+ *   table: Events,
+ *   dimensions: {
+ *     status: { column: "status" },
+ *     day: { expression: sql`toDate(timestamp)`, as: "day" },
+ *   },
+ *   metrics: {
+ *     totalEvents: { agg: count(), as: "total_events" },
+ *     totalAmount: { agg: sum(Events.columns.amount), as: "total_amount" },
+ *   },
+ *   filters: {
+ *     status: { column: "status", operators: ["eq", "in"] as const },
+ *   },
+ *   sortable: ["amount", "timestamp"] as const,
+ * });
+ */
+declare function defineQueryModel<TTable, TMetrics extends Record<string, MetricDef>, TDimensions extends Record<string, DimensionDef<TTable, keyof TTable>>, TFilters extends Record<string, ModelFilterDef<TTable, keyof TTable>>, TSortable extends string, TColumns extends Record<string, ColumnDef<TTable>> = Record<string, never>, TJoins extends Record<string, JoinDef> = Record<string, never>, TResult = TTable>(config: QueryModelConfig<TTable, TMetrics, TDimensions, TFilters, TSortable, TColumns, TJoins>): QueryModel<TTable, TMetrics, TDimensions, TFilters, TSortable, TResult, TColumns>;
+
+/**
+ * Composable helpers that leverage moose-lib table metadata to reduce
+ * boilerplate in QueryModel definitions.
+ *
+ * @module query-layer/helpers
+ */
+
+/**
+ * Derive FilterInputTypeHint from a ClickHouse column data_type.
+ */
+declare function deriveInputTypeFromDataType(dataType: DataType): FilterInputTypeHint;
+type DefaultTimePeriods = {
+    day: DimensionDef;
+    month: DimensionDef;
+    week: DimensionDef;
+};
+/**
+ * Generate day/month/week dimension definitions from a date column reference.
+ *
+ * @param dateColumn - A Column reference from `Table.columns.some_date`
+ * @returns `{ day, month, week }` dimension definitions
+ *
+ * @example
+ * dimensions: {
+ *   status: { column: "status" },
+ *   ...timeDimensions(VisitsTable.columns.start_date),
+ * }
+ */
+declare function timeDimensions(dateColumn: Column): DefaultTimePeriods;
+declare function timeDimensions(dateColumn: Column, options: {
+    periods: string[];
+}): Record<string, DimensionDef>;
+interface TableFieldOptions {
+    /** Only include these column names (snake_case as in the table) */
+    include?: string[];
+    /** Exclude these column names */
+    exclude?: string[];
+    /** Convert snake_case keys to camelCase (default: true) */
+    camelCase?: boolean;
+}
+/**
+ * Generate ColumnDef records from a table's columnArray metadata.
+ *
+ * @example
+ * columns: {
+ *   ...columnsFromTable(VisitsTable, { include: ["id", "name", "status"] }),
+ *   firstName: { join: "user", column: "first_name" },
+ * }
+ */
+declare function columnsFromTable<T>(table: OlapTable<T>, options?: TableFieldOptions): Record<string, ColumnDef<T>>;
+/**
+ * Generate ModelFilterDef records from a table's columnArray metadata.
+ *
+ * **Conservative defaults**: all filters get `["eq"]` operators only.
+ * Consumers widen operators explicitly via spread overrides.
+ *
+ * @example
+ * filters: {
+ *   ...filtersFromTable(VisitsTable, { include: ["studio_id", "start_date", "status"] }),
+ *   status: { column: "status", operators: ["eq", "ne", "in"] as const },
+ * }
+ */
+declare function filtersFromTable<T>(table: OlapTable<T>, options?: TableFieldOptions): Record<string, ModelFilterDef<T, keyof T>>;
+
+/**
+ * Fluent Query Builder API
+ *
+ * Provides a chainable API for building QueryRequest objects.
+ *
+ * @module query-layer/query-builder
+ */
+
+/**
+ * Fluent builder for constructing query requests.
+ *
+ * @example
+ * const results = await buildQuery(model)
+ *   .dimensions(["status"])
+ *   .metrics(["totalEvents", "totalAmount"])
+ *   .filter("status", "eq", "active")
+ *   .orderBy(["totalAmount", "DESC"])
+ *   .limit(10)
+ *   .execute(client.query);
+ */
+interface QueryBuilder<TMetrics extends string, TDimensions extends string, TFilters extends Record<string, FilterDefBase>, TSortable extends string, TResult, TTable = any, TColumns extends string = string> {
+    /** Add a filter condition. Automatically skips if value is undefined or null. */
+    filter<K extends keyof TFilters, Op extends TFilters[K]["operators"][number]>(filterName: K, op: Op, value: OperatorValueType<Op, SqlValue> | undefined): this;
+    /** Set dimensions to include in query (aggregate mode) */
+    dimensions(fields: TDimensions[]): this;
+    /** Set metrics to include in query (aggregate mode) */
+    metrics(fields: TMetrics[]): this;
+    /** Set columns for detail mode (no aggregation, no GROUP BY) */
+    columns(fields: TColumns[]): this;
+    /** Set multi-column sort */
+    orderBy(...orders: Array<[TSortable, SortDir]>): this;
+    /** Set maximum number of rows to return */
+    limit(n: number): this;
+    /** Set page number (0-indexed) for pagination */
+    page(n: number): this;
+    /** Set row offset for pagination */
+    offset(n: number): this;
+    /** Build the QueryRequest object */
+    build(): QueryRequest<TMetrics, TDimensions, TFilters, TSortable, TColumns, TTable>;
+    /** Build the SQL query */
+    toSql(): Sql;
+    /** Get query parts for custom assembly */
+    toParts(): QueryParts;
+    /** Build SQL with custom assembly function */
+    assemble(fn: (parts: QueryParts) => Sql): Sql;
+    /** Execute the query with Moose QueryClient. */
+    execute(client: QueryClient): Promise<TResult[]>;
+}
+/**
+ * Create a fluent query builder for a model.
+ *
+ * @param model - QueryModel instance to build queries for
+ * @returns QueryBuilder instance with chainable methods
+ *
+ * @example
+ * const results = await buildQuery(model)
+ *   .dimensions(["status"])
+ *   .metrics(["totalEvents", "totalAmount"])
+ *   .filter("status", "eq", "active")
+ *   .orderBy(["totalAmount", "DESC"])
+ *   .limit(10)
+ *   .execute(client.query);
+ */
+declare function buildQuery<TTable, TMetrics extends Record<string, MetricDef>, TDimensions extends Record<string, DimensionDef>, TFilters extends Record<string, FilterDefBase>, TSortable extends string, TResult, TColumns extends Record<string, ColumnDef> = Record<string, never>>(model: QueryModel<TTable, TMetrics, TDimensions, TFilters, TSortable, TResult, TColumns>): QueryBuilder<Names<TMetrics>, Names<TDimensions>, TFilters, TSortable, TResult, TTable, Names<TColumns>>;
+
+/**
+ * MCP Schema Generation from QueryModel
+ *
+ * Auto-generates Zod schemas and request builders for MCP tools
+ * directly from QueryModel metadata (filters, dimensions, metrics, columns).
+ *
+ * @module query-layer/model-tools
+ */
+
+/** Filter definition shape expected by MCP utilities. */
+interface QueryModelFilter {
+    operators: readonly string[];
+    inputType?: FilterInputTypeHint;
+    required?: true;
+    description?: string;
+}
+/**
+ * Minimal model interface consumed by createModelTool / registerModelTools.
+ *
+ * Any QueryModel from defineQueryModel() satisfies this structurally —
+ * no explicit `implements` needed. This avoids propagating generic
+ * type parameters into the MCP layer.
+ */
+interface QueryModelBase {
+    readonly name?: string;
+    readonly description?: string;
+    readonly defaults: {
+        orderBy?: Array<[string, SortDir]>;
+        groupBy?: string[];
+        limit?: number;
+        maxLimit?: number;
+        dimensions?: string[];
+        metrics?: string[];
+        columns?: string[];
+    };
+    readonly filters: Record<string, QueryModelFilter>;
+    readonly sortable: readonly string[];
+    readonly dimensions?: Record<string, {
+        description?: string;
+    }>;
+    readonly metrics?: Record<string, {
+        description?: string;
+    }>;
+    readonly columnNames: readonly string[];
+    toSql(request: Record<string, unknown>): Sql;
+}
+interface ModelToolOptions {
+    /** Filter names whose `eq` param is required (not optional). Merged with model-level `required` flags. */
+    requiredFilters?: string[];
+    /** Maximum limit for the tool. Falls back to model.defaults.maxLimit, then 1000. */
+    maxLimit?: number;
+    /** Default limit for the tool. Falls back to model.defaults.limit, then 100. */
+    defaultLimit?: number;
+    /** Default values applied when params are absent. Merged with model.defaults. */
+    defaults?: {
+        dimensions?: string[];
+        metrics?: string[];
+        columns?: string[];
+        limit?: number;
+    };
+}
+interface ModelToolResult {
+    /** Zod shape object to pass to server.tool() */
+    schema: Record<string, z.ZodType>;
+    /** Convert flat MCP params into a nested QueryRequest */
+    buildRequest: (params: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Generate a Zod schema and request builder from a QueryModel.
+ *
+ * Required filters, maxLimit, and default selections are first read from the
+ * model itself (via `required: true` on filter defs and `model.defaults`).
+ * The optional `options` param can override or extend any of these.
+ *
+ * @param model - A QueryModel instance (from defineQueryModel)
+ * @param options - Optional overrides for required filters, limits, defaults
+ * @returns `{ schema, buildRequest }` ready for `server.tool()`
+ */
+declare function createModelTool(model: QueryModelBase, options?: ModelToolOptions): ModelToolResult;
+/**
+ * Register MCP tools for all models that have a `name` defined.
+ *
+ * Each model with a `name` property becomes an MCP tool. The library handles
+ * everything: schema generation from model metadata, request building from
+ * flat MCP params, SQL generation via `model.toSql()`, parameterized
+ * execution with readonly enforcement, and MCP response formatting.
+ *
+ * Models without a `name` are silently skipped.
+ *
+ * @param server - McpServer instance
+ * @param models - Array of QueryModel instances (from `defineQueryModel`)
+ * @param queryClient - The QueryClient from `mooseUtils.client.query`.
+ *   Queries are executed in readonly mode with parameterized SQL.
+ *
+ * @example
+ * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+ * import { getMooseUtils, MooseUtils } from "@514labs/moose-lib";
+ * import { registerModelTools } from "@514labs/moose-lib";
+ * import { visitsModel, usersModel } from "./models";
+ *
+ * const serverFactory = (mooseUtils: MooseUtils) => {
+ *   const server = new McpServer({ name: "my-tools", version: "1.0.0" });
+ *
+ *   // One line registers all named models as MCP tools
+ *   registerModelTools(server, [visitsModel, usersModel], mooseUtils.client.query);
+ *
+ *   return server;
+ * };
+ */
+declare function registerModelTools(server: McpServer, models: QueryModelBase[], queryClient: QueryClient): void;
+
+/**
+ * SQL Utilities
+ *
+ * Low-level SQL building utilities for constructing type-safe queries.
+ * These are the building blocks used by QueryModel and can also be used
+ * directly for custom query construction.
+ *
+ * @module query-layer/sql-utils
+ */
+
+/**
+ * Create raw SQL (literal string, no parameterization).
+ * Delegates to sql.raw from sqlHelpers.
+ *
+ * Only for developer-defined constants (column names, expressions, sort
+ * directions) that originate from model config — never for HTTP/user input.
+ */
+declare const raw: (text: string) => Sql;
+/** Empty SQL fragment — useful as a no-op. */
+declare const empty: Sql;
+/**
+ * Join SQL fragments with a separator.
+ * Delegates to sql.join from sqlHelpers.
+ */
+declare const join: (fragments: Sql[], separator?: string) => Sql;
+/** Check if a Sql fragment is empty */
+declare function isEmpty(fragment: Sql): boolean;
+/**
+ * Create a filter condition. Automatically skips if value is undefined/null.
+ * This is the recommended way to build conditional WHERE clauses.
+ *
+ * @example
+ * where(
+ *   filter(Events.columns.amount, "gte", params.minAmount),
+ *   filter(Events.columns.amount, "lte", params.maxAmount),
+ *   filter(Events.columns.status, "eq", params.status),
+ * )
+ */
+declare function filter(col: ColRef, op: "between", value: [SqlValue, SqlValue] | undefined): Sql;
+declare function filter(col: ColRef, op: "in" | "notIn", value: SqlValue[] | undefined): Sql;
+declare function filter(col: ColRef, op: "isNull" | "isNotNull", value: boolean | undefined): Sql;
+declare function filter(col: ColRef, op: "like" | "ilike", value: string | undefined): Sql;
+declare function filter(col: ColRef, op: Exclude<FilterOperator, "between" | "in" | "notIn" | "isNull" | "isNotNull" | "like" | "ilike">, value: SqlValue | undefined): Sql;
+/** Equal: column = value */
+declare function eq(col: ColRef, value: SqlValue): Sql;
+/** Not equal: column != value */
+declare function ne(col: ColRef, value: SqlValue): Sql;
+/** Greater than: column > value */
+declare function gt(col: ColRef, value: SqlValue): Sql;
+/** Greater than or equal: column >= value */
+declare function gte(col: ColRef, value: SqlValue): Sql;
+/** Less than: column < value */
+declare function lt(col: ColRef, value: SqlValue): Sql;
+/** Less than or equal: column <= value */
+declare function lte(col: ColRef, value: SqlValue): Sql;
+/** LIKE pattern match (case-sensitive) */
+declare function like(col: ColRef, pattern: string): Sql;
+/** ILIKE pattern match (case-insensitive, ClickHouse) */
+declare function ilike(col: ColRef, pattern: string): Sql;
+/** IN list: column IN (a, b, c) */
+declare function inList(col: ColRef, values: SqlValue[]): Sql;
+/** NOT IN list */
+declare function notIn(col: ColRef, values: SqlValue[]): Sql;
+/** BETWEEN: column BETWEEN low AND high */
+declare function between(col: ColRef, low: SqlValue, high: SqlValue): Sql;
+/** IS NULL */
+declare function isNull(col: ColRef): Sql;
+/** IS NOT NULL */
+declare function isNotNull(col: ColRef): Sql;
+/** Combine conditions with AND, filtering out empty fragments */
+declare function and(...conditions: Sql[]): Sql;
+/** Combine conditions with OR, filtering out empty fragments */
+declare function or(...conditions: Sql[]): Sql;
+/** Negate a condition: NOT (condition) */
+declare function not(condition: Sql): Sql;
+/** Build WHERE clause — returns empty if no conditions */
+declare function where(...conditions: Sql[]): Sql;
+/** Build ORDER BY clause */
+declare function orderBy(...cols: Array<ColRef | [ColRef, "ASC" | "DESC"]>): Sql;
+/** Build LIMIT clause */
+declare function limit(n: number): Sql;
+/** Build OFFSET clause */
+declare function offset(n: number): Sql;
+/** Build LIMIT + OFFSET for pagination */
+declare function paginate(pageSize: number, page?: number): Sql;
+/** Build GROUP BY clause */
+declare function groupBy(...cols: ColRef[]): Sql;
+/** Build HAVING clause */
+declare function having(...conditions: Sql[]): Sql;
+/** SQL expression with fluent `.as()` method */
+interface Expr extends Sql {
+    as(alias: string): Sql;
+}
+/** COUNT(*) or COUNT(column) */
+declare function count(col?: ColRef): Expr;
+/** COUNT(DISTINCT column) */
+declare function countDistinct(col: ColRef): Expr;
+/** SUM(column) */
+declare function sum(col: ColRef): Expr;
+/** AVG(column) */
+declare function avg(col: ColRef): Expr;
+/** MIN(column) */
+declare function min(col: ColRef): Expr;
+/** MAX(column) */
+declare function max(col: ColRef): Expr;
+/** Build SELECT clause with columns */
+declare function select(...cols: Array<ColRef | [ColRef, string]>): Sql;
+/** Alias a column or expression */
+declare function as(expression: Sql, alias: string): Sql;
+
+/**
+ * Validation Utilities
+ *
+ * Request validation and error handling for API endpoints.
+ *
+ * @module query-layer/validation
+ */
+
+/** Frontend-friendly validation error structure */
+interface ValidationError {
+    path: string;
+    message: string;
+    expected: string;
+    received: string;
+}
+/** Error thrown when validation fails */
+declare class BadRequestError extends Error {
+    readonly errors: ValidationError[];
+    constructor(typiaErrors: IValidation.IError[]);
+    toJSON(): {
+        error: string;
+        details: ValidationError[];
+    };
+}
+/** Assert validation result, throw BadRequestError if invalid */
+declare function assertValid<T>(result: IValidation<T>): T;
+/**
+ * Query handler with three entry points for queries.
+ * Use this when writing raw SQL without a query model.
+ */
+interface QueryHandler<P, R> {
+    run: (params: P) => Promise<R>;
+    fromObject: (input: unknown) => Promise<R>;
+    fromUrl: (url: string | URL) => Promise<R>;
+}
+/**
+ * Create a simple query handler with validation.
+ *
+ * @example
+ * const handler = createQueryHandler({
+ *   fromUrl: typia.http.createValidateQuery<MyParams>(),
+ *   fromObject: typia.createValidate<MyParams>(),
+ *   queryFn: async (params) => {
+ *     const query = sql`SELECT * FROM ${Table} ${where(...)}`;
+ *     return executeQuery(query);
+ *   },
+ * });
+ */
+declare function createQueryHandler<P, R>(config: {
+    fromUrl: (input: string | URLSearchParams) => IValidation<P>;
+    fromObject: (input: unknown) => IValidation<P>;
+    queryFn: (params: P) => Promise<R>;
+}): QueryHandler<P, R>;
+
 type DataModelConfig<T> = Partial<{
     ingestion: true;
     storage: {
@@ -638,7 +1392,7 @@ type DataModelConfig<T> = Partial<{
     parallelism?: number;
 }>;
 
-export { ACKs, type CSVParsingConfig, CSV_DELIMITERS, type CliLogData, DEFAULT_CSV_CONFIG, DEFAULT_JSON_CONFIG, type DataModelConfig, DataSource, type DataSourceConfig, type ExpressRequestWithMoose, type ExtractionResult, type JSONParsingConfig, type KafkaClientConfig, type Logger, MAX_RETRIES, MAX_RETRIES_PRODUCER, MAX_RETRY_TIME_MS, MOOSE_RUNTIME_ENV_PREFIX, MooseCache, MooseClient, MooseUtils, type Producer, RETRY_FACTOR_PRODUCER, RETRY_INITIAL_TIME_MS, type StripDateIntersection, type TaskConfig, type TaskDefinition, type TaskFunction, antiCachePath, cliLog, compilerLog, createProducerConfig, expressMiddleware, getClickhouseClient, getFileName, getKafkaClient, getKafkaProducer, getLegacyMooseUtils, getMooseClients, getMooseUtils, getMooseUtilsFromRequest, isValidCSVDelimiter, logError, mapTstoJs, mooseEnvSecrets, mooseRuntimeEnv, parseCSV, parseJSON, parseJSONWithDates, rewriteImportExtensions };
+export { ACKs, BadRequestError, type CSVParsingConfig, CSV_DELIMITERS, type CliLogData, type ColRef, Column, type ColumnDef, DEFAULT_CSV_CONFIG, DEFAULT_JSON_CONFIG, type DataModelConfig, DataSource, type DataSourceConfig, type DimensionDef, type Expr, type ExpressRequestWithMoose, type ExtractionResult, type FilterDefBase, type FilterInputTypeHint, type FilterOperator, type FilterParams, type GetMooseUtilsOptions, type JSONParsingConfig, type JoinDef, type KafkaClientConfig, type Logger, MAX_RETRIES, MAX_RETRIES_PRODUCER, MAX_RETRY_TIME_MS, MOOSE_RUNTIME_ENV_PREFIX, MaterializedView, type MetricDef, type ModelFilterDef, type ModelToolOptions, type ModelToolResult, MooseCache, MooseClient, MooseUtils, type Names, OlapTable, type OperatorValueType, type Producer, type QueryBuilder, QueryClient, type QueryHandler, type QueryModel, type QueryModelBase, type QueryModelConfig, type QueryModelFilter, type QueryParts, type QueryRequest, RETRY_FACTOR_PRODUCER, RETRY_INITIAL_TIME_MS, type SortDir, Sql, type SqlValue, type StripDateIntersection, type TaskConfig, type TaskDefinition, type TaskFunction, type ValidationError, and, antiCachePath, as, assertValid, avg, between, buildQuery, cliLog, columnsFromTable, compilerLog, count, countDistinct, createModelTool, createProducerConfig, createQueryHandler, defineQueryModel, deriveInputTypeFromDataType, empty, eq, expressMiddleware, filter, filtersFromTable, getClickhouseClient, getFileName, getKafkaClient, getKafkaProducer, getLegacyMooseUtils, getMooseClients, getMooseUtils, getMooseUtilsFromRequest, groupBy, gt, gte, having, ilike, inList, isEmpty, isNotNull, isNull, isValidCSVDelimiter, join, like, limit, logError, lt, lte, mapTstoJs, max, min, mooseEnvSecrets, mooseRuntimeEnv, ne, not, notIn, offset, or, orderBy, paginate, parseCSV, parseJSON, parseJSONWithDates, raw, registerModelTools, rewriteImportExtensions, select, sum, timeDimensions, where };
 
 // ── @bayoudhi/moose-lib-serverless additions ──────────────────────────────