@centrali-io/centrali-sdk 5.3.0 → 5.5.0

package/dist/index.js

@@ -38,6 +38,9 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -51,7 +54,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CentraliSDK = exports.WebhookSubscriptionsManager = exports.FunctionRunsManager = exports.ComputeFunctionsManager = exports.CollectionsManager = exports.StructuresManager = exports.AllowedDomainsManager = exports.ValidationManager = exports.AnomalyInsightsManager = exports.SmartQueriesManager = exports.TriggersManager = exports.OrchestrationsManager = exports.RealtimeManager = exports.RecordEvents = exports.CentraliError = void 0;
+exports.CentraliSDK = exports.WebhookSubscriptionsManager = exports.FunctionRunsManager = exports.ComputeFunctionsManager = exports.CollectionsManager = exports.StructuresManager = exports.AllowedDomainsManager = exports.ValidationManager = exports.AnomalyInsightsManager = exports.SmartQueriesManager = exports.RecordsManager = exports.TriggersManager = exports.OrchestrationsManager = exports.RealtimeManager = exports.RecordEvents = exports.CentraliError = void 0;
 exports.isCentraliError = isCentraliError;
 exports.getApiUrl = getApiUrl;
 exports.getAuthUrl = getAuthUrl;
@@ -199,6 +202,48 @@ function encodeFormData(data) {
     return new URLSearchParams(data).toString();
 }
 // =====================================================
+// Canonical query types (CEN-1194 — Phase 1 query foundation)
+// =====================================================
+// Re-exports the canonical `QueryDefinition` surface from @centrali/query.
+// `query-types.ts` is generated from `services/backend/shared/query/src/types.ts`
+// by `scripts/sync-query-types.mjs` (runs on prebuild). Do not edit it by hand.
+//
+// Use these for new code:
+//   - `client.records.query(resource, definition)`        — POST /records/query
+//   - `client.records.list(resource, urlOpts?)`           — GET adapter
+//   - `client.records.search(resource, text, opts?)`      — sugar over `{ text }`
+//   - `client.records.test(resource, definition)`         — authoring dry-run
+//   - `client.queryRecords<T>(resource, definition)`      — top-level convenience
+//
+// Saved queries: `client.savedQueries.*` is the canonical namespace, routing
+// through the `/saved-queries/*` HTTP endpoints (Phase 4 — CEN-1198).
+// `client.smartQueries.*` is preserved as a deprecated alias during the
+// deprecation window.
+//
+// The legacy `FilterOperators` / `QueryRecordOptions` block below is preserved
+// for the GET adapter (`client.records.list()` and the legacy
+// `client.queryRecords(slug, urlOpts)` form). Migration guidance for the
+// canonical operator vocabulary lives in
+// `docs/maintainers/overview/query-foundation.md`.
+__exportStar(require("./query-types"), exports);
+/**
+ * Discriminator for the dual-shape `client.queryRecords(...)` overload.
+ *
+ * Returns `true` if the argument is a canonical `QueryDefinition`. The
+ * marker is **the presence of `resource`** — that field is required by the
+ * canonical contract (`docs/superpowers/specs/2026-04-25-query-foundation-contract.md` §3)
+ * and isn't a legal key in the legacy `QueryRecordOptions` URL-param shape.
+ *
+ * Callers who want to omit `resource` (relying on the first argument to fill
+ * it in) should use `client.records.query(resource, definition)` directly,
+ * which has its own backfill behavior.
+ */
+function isCanonicalQueryDefinition(arg) {
+    return (arg !== null &&
+        typeof arg === 'object' &&
+        typeof arg.resource === 'string');
+}
+// =====================================================
 // Webhook Subscription Types
 // =====================================================
 /**
@@ -554,29 +599,33 @@ function getEndpointApiPath(workspaceId, path) {
     return `data/workspace/${workspaceId}/api/v1/endpoints/${path}`;
 }
 /**
- * Generate Smart Queries base API URL PATH for workspace-level operations.
+ * Generate Saved Queries base API URL PATH for workspace-level operations.
+ *
+ * Phase 4 (CEN-1198) of the query foundation moved the canonical mount from
+ * `/smart-queries` to `/saved-queries`. The data service dual-mounts both for
+ * the deprecation window; this helper emits the canonical path.
  */
 function getSmartQueriesApiPath(workspaceId) {
-    return `data/workspace/${workspaceId}/api/v1/smart-queries`;
+    return `data/workspace/${workspaceId}/api/v1/saved-queries`;
 }
 /**
- * Generate Smart Queries API URL PATH for structure-level operations.
+ * Generate Saved Queries API URL PATH for structure-level operations.
  */
 function getSmartQueriesStructureApiPath(workspaceId, structureSlug, queryId) {
-    const basePath = `data/workspace/${workspaceId}/api/v1/smart-queries/slug/${structureSlug}`;
+    const basePath = `data/workspace/${workspaceId}/api/v1/saved-queries/slug/${structureSlug}`;
     return queryId ? `${basePath}/${queryId}` : basePath;
 }
 /**
- * Generate Smart Query by name API URL PATH.
+ * Generate Saved Query by name API URL PATH.
  */
 function getSmartQueryByNameApiPath(workspaceId, structureSlug, name) {
-    return `data/workspace/${workspaceId}/api/v1/smart-queries/slug/${structureSlug}/name/${encodeURIComponent(name)}`;
+    return `data/workspace/${workspaceId}/api/v1/saved-queries/slug/${structureSlug}/name/${encodeURIComponent(name)}`;
 }
 /**
- * Generate Smart Query execute API URL PATH.
+ * Generate Saved Query execute API URL PATH.
  */
 function getSmartQueryExecuteApiPath(workspaceId, structureSlug, queryId) {
-    return `data/workspace/${workspaceId}/api/v1/smart-queries/slug/${structureSlug}/execute/${queryId}`;
+    return `data/workspace/${workspaceId}/api/v1/saved-queries/slug/${structureSlug}/execute/${queryId}`;
 }
 /**
  * Generate Search API URL PATH.
@@ -728,10 +777,10 @@ function getComputeJobStatusApiPath(workspaceId, jobId) {
 // Smart Query Test API Path Helper (Configuration-as-Code)
 // =====================================================
 /**
- * Generate Smart Query test execution API URL PATH.
+ * Generate Saved Query test execution API URL PATH.
  */
 function getSmartQueryTestApiPath(workspaceId, structureSlug) {
-    return `data/workspace/${workspaceId}/api/v1/smart-queries/slug/${structureSlug}/test`;
+    return `data/workspace/${workspaceId}/api/v1/saved-queries/slug/${structureSlug}/test`;
 }
 // =====================================================
 // Validation API Path Helpers
@@ -1454,24 +1503,164 @@ class TriggersManager {
 }
 exports.TriggersManager = TriggersManager;
 // =====================================================
+// Records Manager (canonical query surface — CEN-1194)
+// =====================================================
+/**
+ * RecordsManager exposes the canonical query surface for records.
+ *
+ * All three methods compile to a single canonical `QueryDefinition` server-side
+ * and return the canonical `{ data, meta }` envelope (`QueryResult<T>`).
+ *
+ * - {@link RecordsManager.query | query} — full POST `/records/query`. Use for
+ *   nested boolean trees, `select`, `text`, `include`.
+ * - {@link RecordsManager.list | list} — GET adapter for simple URL-param
+ *   queries. Bookmarkable, cacheable, but cannot express nested `or`/`not`.
+ * - {@link RecordsManager.search | search} — sugar over `query({ text: ... })`.
+ *
+ * Access via `client.records`.
+ *
+ * @example
+ * ```ts
+ * // Canonical query — boolean tree, select, paging
+ * const open = await client.records.query<Order>('orders', {
+ *   resource: 'orders',
+ *   where: {
+ *     and: [
+ *       { 'data.status': { eq: 'open' } },
+ *       { or: [
+ *         { 'data.amount': { gte: 100 } },
+ *         { 'data.priority': { eq: 'high' } }
+ *       ]}
+ *     ]
+ *   },
+ *   sort: [{ field: 'createdAt', direction: 'desc' }],
+ *   page: { limit: 50 },
+ *   select: { fields: ['id', 'data.status', 'data.amount'] }
+ * });
+ * console.log(open.data, open.meta.hasMore);
+ *
+ * // GET adapter — simple cases
+ * const recent = await client.records.list<Order>('orders', {
+ *   'data.status': 'paid',
+ *   sort: '-createdAt',
+ *   pageSize: 25,
+ * });
+ *
+ * // Text search — sugar over { text }
+ * const matches = await client.records.search<Order>('orders', 'urgent shipping');
+ * ```
+ */
+class RecordsManager {
+    constructor(workspaceId, requestFn) {
+        this.workspaceId = workspaceId;
+        this.requestFn = requestFn;
+    }
+    /**
+     * Run a canonical query against `POST /records/query`.
+     *
+     * The body **is** a `QueryDefinition`. Returns the canonical `{ data, meta }`
+     * envelope. If `definition.resource` is omitted, `resource` is filled in
+     * from the first argument so the wire shape always matches the contract.
+     *
+     * @example
+     * const open = await client.records.query<Order>('orders', {
+     *   resource: 'orders',
+     *   where: { 'data.status': { eq: 'open' } },
+     *   page: { limit: 100 }
+     * });
+     */
+    query(resource, definition) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const path = `data/workspace/${this.workspaceId}/api/v1/records/query`;
+            const body = Object.assign(Object.assign({}, definition), { resource: (_a = definition.resource) !== null && _a !== void 0 ? _a : resource });
+            const resp = yield this.requestFn('POST', path, body);
+            // POST /records/query returns canonical `{ data, meta }`. The SDK's
+            // `request()` normalizer leaves objects with a `data` key untouched, so
+            // the runtime shape already matches `QueryResult<T>` — we only need to
+            // re-type the response. `meta` is server-guaranteed for this route.
+            return resp;
+        });
+    }
+    /**
+     * Authoring-time dry-run of a canonical query against `POST /records/query/test`.
+     *
+     * Same input shape as {@link RecordsManager.query | query}. Returns
+     * `422 unreadable_field` on fields the caller can't see (instead of the
+     * runtime privacy-preserving empty-result behavior). Use from query
+     * builders to surface precise errors to the author.
+     */
+    test(resource, definition) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const path = `data/workspace/${this.workspaceId}/api/v1/records/query/test`;
+            const body = Object.assign(Object.assign({}, definition), { resource: (_a = definition.resource) !== null && _a !== void 0 ? _a : resource });
+            const resp = yield this.requestFn('POST', path, body);
+            return resp;
+        });
+    }
+    /**
+     * GET adapter for simple, URL-encodable queries (`?status=paid&sort=-createdAt`).
+     *
+     * Server-side this routes through the same canonical engine as
+     * {@link RecordsManager.query | query} (per CEN-1181 WS3) — the URL
+     * params compile into a `QueryDefinition` before execution. Use this when
+     * a flat AND of field conditions is enough; reach for `query()` when you
+     * need nested booleans, `select`, `text`, or `include`.
+     *
+     * Returns the records-list `ApiResponse<T[]>` envelope unchanged so
+     * callers that read `meta.page` / `meta.pageSize` keep working during
+     * the deprecation window.
+     */
+    list(resource, urlOpts) {
+        const path = getRecordApiPath(this.workspaceId, resource);
+        return this.requestFn('GET', path, null, urlOpts);
+    }
+    /**
+     * Full-text search sugar — equivalent to `query(resource, { text: ... })`.
+     *
+     * Routes through `RecordsSearchExecutor` (Meilisearch) when only `text` is
+     * provided, or through the hybrid Meili-first path when `where` is also
+     * set. Result envelope is identical across pure-filter, pure-text, and
+     * hybrid (`{ data, meta }`).
+     */
+    search(resource, text, opts) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.query(resource, {
+                resource,
+                text: { query: text, fields: opts === null || opts === void 0 ? void 0 : opts.fields, typoTolerance: opts === null || opts === void 0 ? void 0 : opts.typoTolerance },
+                where: opts === null || opts === void 0 ? void 0 : opts.where,
+                sort: opts === null || opts === void 0 ? void 0 : opts.sort,
+                page: opts === null || opts === void 0 ? void 0 : opts.page,
+                select: opts === null || opts === void 0 ? void 0 : opts.select,
+            });
+        });
+    }
+}
+exports.RecordsManager = RecordsManager;
+// =====================================================
 // Smart Queries Manager
 // =====================================================
 /**
- * SmartQueriesManager provides methods for listing and executing smart queries.
- * Smart queries are reusable, parameterized queries defined in the console
- * that can be executed programmatically via the SDK.
- * Access via `client.smartQueries`.
+ * SmartQueriesManager — reusable, parameterized saved queries. Access via
+ * `client.savedQueries` (canonical) or `client.smartQueries` (deprecated alias).
+ *
+ * Phase 4 of the query foundation (CEN-1198) shipped the canonical
+ * `/saved-queries/*` HTTP routes; this manager now routes through them. The
+ * data service dual-mounts the deprecated `/smart-queries/*` alias for the
+ * deprecation window. New code that doesn't need saved queries should still
+ * prefer `client.records.query()` for ad-hoc queries.
  *
  * Usage:
  * ```ts
- * // List smart queries for a structure
- * const queries = await client.smartQueries.list('employee');
+ * // List saved queries for a structure
+ * const queries = await client.savedQueries.list('employee');
  *
- * // Execute a smart query by ID
- * const results = await client.smartQueries.execute('employee', 'query-uuid');
+ * // Execute a saved query by ID
+ * const results = await client.savedQueries.execute('employee', 'query-uuid');
  *
- * // Get a smart query by name
- * const query = await client.smartQueries.getByName('employee', 'Active Employees');
+ * // Get a saved query by name
+ * const query = await client.savedQueries.getByName('employee', 'Active Employees');
  * ```
  */
 class SmartQueriesManager {
@@ -2921,7 +3110,9 @@ class CentraliSDK {
         this.token = null;
         this._realtime = null;
         this._triggers = null;
+        this._records = null;
         this._smartQueries = null;
+        this._queryRecordsLegacyWarned = false;
         this._anomalyInsights = null;
         this._validation = null;
         this._orchestrations = null;
@@ -3099,30 +3290,86 @@ class CentraliSDK {
         return this._triggers;
     }
     /**
-     * Smart Queries namespace for listing and executing smart queries.
+     * Records namespace — canonical query surface for records (CEN-1194).
+     *
+     * Three methods, one engine, one envelope:
+     * - `records.query(resource, definition)` — POST `/records/query` with a
+     *   full `QueryDefinition` (boolean trees, `select`, `text`, `include`).
+     * - `records.list(resource, urlOpts?)` — GET adapter for simple URL-param
+     *   queries. Bookmarkable; cannot express nested booleans.
+     * - `records.search(resource, text, opts?)` — sugar over `query({ text })`.
+     *
+     * @example
+     * ```ts
+     * // Boolean tree with sort + projection
+     * const orders = await client.records.query<Order>('orders', {
+     *   resource: 'orders',
+     *   where: {
+     *     and: [
+     *       { 'data.status': { eq: 'paid' } },
+     *       { 'data.amount': { gte: 100 } }
+     *     ]
+     *   },
+     *   sort: [{ field: 'createdAt', direction: 'desc' }],
+     *   page: { limit: 50 },
+     *   select: { fields: ['id', 'data.amount', 'data.customer'] }
+     * });
+     *
+     * // Simple GET
+     * const recent = await client.records.list<Order>('orders', {
+     *   'data.status': 'paid',
+     *   sort: '-createdAt',
+     * });
+     *
+     * // Text search
+     * const matches = await client.records.search<Order>('orders', 'urgent');
+     * ```
+     */
+    get records() {
+        if (!this._records) {
+            this._records = new RecordsManager(this.options.workspaceId, this.request.bind(this));
+        }
+        return this._records;
+    }
+    /**
+     * Saved Queries namespace — list, execute, create, update, and delete
+     * saved (formerly "smart") queries. Routes through the canonical
+     * `/saved-queries/*` endpoints (Phase 4 of the query foundation,
+     * CEN-1198). The data service dual-mounts the deprecated `/smart-queries`
+     * alias for the deprecation window.
      *
      * Usage:
      * ```ts
-     * // List all smart queries in workspace
-     * const allQueries = await client.smartQueries.listAll();
+     * // List all saved queries in workspace
+     * const allQueries = await client.savedQueries.listAll();
      *
-     * // List smart queries for a structure
-     * const queries = await client.smartQueries.list('employee');
+     * // List saved queries for a structure
+     * const queries = await client.savedQueries.list('employee');
      *
-     * // Get a smart query by name
-     * const query = await client.smartQueries.getByName('employee', 'Active Employees');
+     * // Get a saved query by name
+     * const query = await client.savedQueries.getByName('employee', 'Active Employees');
      *
-     * // Execute a smart query
-     * const results = await client.smartQueries.execute('employee', query.data.id);
+     * // Execute a saved query
+     * const results = await client.savedQueries.execute('employee', query.data.id);
      * console.log('Found:', results.data.length, 'records');
      * ```
      */
-    get smartQueries() {
+    get savedQueries() {
         if (!this._smartQueries) {
             this._smartQueries = new SmartQueriesManager(this.options.workspaceId, this.request.bind(this));
         }
         return this._smartQueries;
     }
+    /**
+     * @deprecated Use `client.savedQueries` instead. The "smart queries"
+     * surface was renamed to "saved queries" in Phase 4 of the query
+     * foundation (CEN-1198). This getter is a deprecated alias and will be
+     * removed in a future major SDK release.
+     */
+    get smartQueries() {
+        emitDeprecationWarning('client.smartQueries is deprecated. Use client.savedQueries instead.');
+        return this.savedQueries;
+    }
     /**
      * Anomaly Insights namespace for querying and managing AI-generated insights.
      *
@@ -3459,55 +3706,17 @@ class CentraliSDK {
         const path = getRecordApiPath(this.options.workspaceId, recordSlug, id);
         return this.request('GET', path, null, options);
     }
-    /**
-     * Query records with filters, pagination, sorting, and reference expansion.
-     *
-     * IMPORTANT: Filters are passed at the TOP LEVEL, not nested under 'filter'.
-     * Use 'data.' prefix for custom fields and bracket notation for operators.
-     *
-     * @param recordSlug - The structure's record slug
-     * @param queryParams - Query parameters (filters at top level, plus sort, pagination, expand)
-     *
-     * @example
-     * // Simple equality filter
-     * const activeProducts = await centrali.queryRecords('Product', {
-     *   'data.status': 'active',
-     *   sort: '-createdAt',
-     *   page: 1,
-     *   pageSize: 10
-     * });
-     *
-     * // Filter with operators (bracket notation)
-     * const products = await centrali.queryRecords('Product', {
-     *   'data.inStock': true,
-     *   'data.price[lte]': 100,
-     *   sort: '-createdAt',
-     *   pageSize: 10
-     * });
-     *
-     * // Multiple values with 'in' operator (comma-separated string)
-     * const orders = await centrali.queryRecords('Order', {
-     *   'data.status[in]': 'pending,processing',
-     *   expand: 'customer,items'
-     * });
-     * // Access expanded data: orders.data[0].data._expanded.customer
-     *
-     * // Range filters
-     * const customers = await centrali.queryRecords('Customer', {
-     *   'data.age[gte]': 18,
-     *   'data.age[lte]': 65,
-     *   'data.verified': true
-     * });
-     *
-     * // Filter with 'ne' (not equal)
-     * const availableItems = await centrali.queryRecords('Product', {
-     *   'data.status[ne]': 'discontinued',
-     *   pageSize: 100
-     * });
-     */
-    queryRecords(recordSlug, queryParams) {
-        const path = getRecordApiPath(this.options.workspaceId, recordSlug);
-        return this.request('GET', path, null, queryParams);
+    queryRecords(resourceOrSlug, arg2) {
+        if (isCanonicalQueryDefinition(arg2)) {
+            return this.records.query(resourceOrSlug, arg2);
+        }
+        if (!this._queryRecordsLegacyWarned) {
+            this._queryRecordsLegacyWarned = true;
+            // eslint-disable-next-line no-console
+            console.warn('[centrali-sdk] `client.queryRecords(slug, urlOpts)` (legacy URL-param form) is deprecated — pass a canonical `QueryDefinition` (`{ resource, where, sort, page, … }`) for `POST /records/query`, or use `client.records.list(resource, urlOpts)` for the GET adapter explicitly.');
+        }
+        const path = getRecordApiPath(this.options.workspaceId, resourceOrSlug);
+        return this.request('GET', path, null, arg2);
     }
     /** Get records by Ids. */
     getRecordsByIds(recordSlug, ids) {

package/dist/query-types.d.ts

@@ -0,0 +1,187 @@
+export type QueryDefinition = {
+    /**
+     * Logical resource being queried.
+     *
+     * - For records: the collection (a.k.a. structure) slug — e.g. `"orders"`,
+     *   `"customers"`. The records executor treats this as the collection slug.
+     * - For other queryable resources: the resource type identifier — e.g.
+     *   `"audit-log"`, `"function-runs"`, `"files"`, `"webhook-deliveries"`.
+     *
+     * Named `resource` (not `collection`) because "collection" is overloaded in
+     * Centrali — it's the renamed records-bucket entity, so `collection: "audit-log"`
+     * would read as a category error. `resource` is REST-canonical and reads
+     * truthfully across every executor.
+     */
+    resource: string;
+    where?: WhereExpression;
+    text?: TextSearchClause;
+    sort?: SortClause[];
+    page?: PageClause;
+    select?: SelectClause;
+    include?: IncludeClause[];
+};
+export type SavedQueryDefinition = {
+    name: string;
+    description?: string;
+    query: QueryDefinition;
+    variables?: Record<string, QueryVariableDefinition>;
+};
+export type WhereExpression = FieldConditionMap | {
+    and: WhereExpression[];
+} | {
+    or: WhereExpression[];
+} | {
+    not: WhereExpression;
+};
+export type FieldConditionMap = {
+    [field: string]: FieldCondition;
+};
+/**
+ * Exactly-one helper: for a record of operator → value-type, produces a union
+ * where each variant has exactly one of the keys present and all the others
+ * forbidden via `?: never`. This enforces the contract's "exactly one operator
+ * per FieldCondition" rule at the type level — `{ eq: 1, ne: 2 }` fails to
+ * type-check.
+ */
+type ExactlyOneOperator<T> = {
+    [K in keyof T]: {
+        [P in K]: T[P];
+    } & {
+        [P in Exclude<keyof T, K>]?: never;
+    };
+}[keyof T];
+type FieldOperatorMap = {
+    eq: ScalarValue;
+    ne: ScalarValue;
+    gt: number | string;
+    gte: number | string;
+    lt: number | string;
+    lte: number | string;
+    in: ScalarValue[];
+    nin: ScalarValue[];
+    contains: string;
+    startsWith: string;
+    endsWith: string;
+    hasAny: ScalarValue[];
+    hasAll: ScalarValue[];
+    exists: boolean;
+};
+export type FieldCondition = ExactlyOneOperator<FieldOperatorMap>;
+export type ScalarValue = string | number | boolean | null;
+export type CanonicalOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'contains' | 'startsWith' | 'endsWith' | 'hasAny' | 'hasAll' | 'exists';
+export declare const CANONICAL_OPERATORS: readonly CanonicalOperator[];
+/** Argument shape an operator expects in a `FieldCondition`. */
+export type OperatorValueShape = 
+/** Single scalar input (string/number/boolean/null). */
+'scalar'
+/** Array of scalars — UI typically renders a chip / comma input. */
+ | 'array'
+/** Boolean toggle — `exists`. */
+ | 'boolean';
+/**
+ * Logical type families an operator applies to. The visual builder narrows
+ * the dropdown to the operators valid for the selected field's type.
+ *
+ * `any` means the operator is type-agnostic (`eq`, `ne`, `exists`).
+ */
+export type OperatorTypeApplicability = 'string' | 'number' | 'boolean' | 'datetime' | 'array' | 'any';
+export type OperatorMeta = {
+    /** Canonical bare operator name. */
+    operator: CanonicalOperator;
+    /** Human-readable label for dropdowns. */
+    label: string;
+    /** Short, symbol-style label suitable for compact number/datetime UIs. */
+    shortLabel?: string;
+    /** Argument shape — drives the value input affordance. */
+    valueShape: OperatorValueShape;
+    /** Field types this operator applies to. */
+    applicableTypes: OperatorTypeApplicability[];
+};
+export declare const OPERATOR_METADATA: Readonly<Record<CanonicalOperator, OperatorMeta>>;
+/**
+ * Operators applicable to a given field-type. Used by builder UIs to narrow
+ * the dropdown when the user selects a field; falls back to `any`-applicable
+ * operators when the type is unknown.
+ */
+export declare function operatorsForFieldType(type: OperatorTypeApplicability | string): readonly OperatorMeta[];
+export type TextSearchClause = {
+    query: string;
+    fields?: string[];
+    typoTolerance?: boolean;
+};
+export type SortClause = {
+    field: string;
+    direction: 'asc' | 'desc';
+};
+/**
+ * Two pagination modes. Per contract §6 they are mutually exclusive — `cursor`
+ * is forbidden in offset mode and `offset` is forbidden in cursor mode so a
+ * caller cannot construct an ambiguous request.
+ */
+export type PageClause = {
+    limit: number;
+    offset?: number;
+    cursor?: never;
+} | {
+    limit: number;
+    cursor?: string;
+    offset?: never;
+};
+/**
+ * Records Phase 1 page defaults (contract §6).
+ * Same default and cap for GET adapter and POST query body.
+ */
+export declare const RECORDS_PAGE_DEFAULT_LIMIT = 50;
+export declare const RECORDS_PAGE_MAX_LIMIT = 500;
+export type SelectClause = {
+    fields: string[];
+};
+/**
+ * Phase 1 reserves the shape but rejects execution with `unsupported_clause`.
+ */
+export type IncludeClause = {
+    relation: string;
+};
+export type VariableType = 'string' | 'number' | 'boolean' | 'datetime' | 'id' | {
+    array: VariableType;
+} | {
+    reference: string;
+};
+export type QueryVariableDefinition = {
+    type: VariableType;
+    required?: boolean;
+    default?: ScalarValue;
+    description?: string;
+};
+export type QueryExecutionMode = 'filter' | 'search' | 'hybrid';
+export type QueryResultMeta = {
+    total?: number;
+    limit: number;
+    offset?: number;
+    cursor?: string;
+    nextCursor?: string;
+    hasMore?: boolean;
+    processingTimeMs?: number;
+    mode?: QueryExecutionMode;
+};
+export type QueryResult<T> = {
+    data: T[];
+    meta: QueryResultMeta;
+};
+export type QueryErrorCode = 'unsupported_clause' | 'unsupported_operator' | 'unsupported_legacy_operator' | 'unreadable_field' | 'invalid_query' | 'legacy_write_unsupported';
+export type QueryError = {
+    code: QueryErrorCode;
+    message: string;
+    /** Dotted path inside the QueryDefinition where the error was detected, e.g. "where.data.status.eq". */
+    path?: string;
+    /** For `unsupported_clause` / `unsupported_operator`, the offending name. */
+    clause?: string;
+};
+export type ValidationResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    errors: QueryError[];
+};
+export {};