@centrali-io/centrali-sdk 5.4.0 → 5.5.0

package/index.ts

@@ -797,10 +797,74 @@ export interface ExpandOptions {
  */
 export interface GetRecordOptions extends ExpandOptions {}
 
+// =====================================================
+// 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`.
+export * from './query-types';
+import type {
+    QueryDefinition,
+    QueryResult,
+    WhereExpression,
+    SortClause,
+    PageClause,
+    SelectClause,
+    QueryVariableDefinition,
+    ScalarValue,
+    FieldConditionMap,
+    FieldCondition,
+} from './query-types';
+
+/**
+ * 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: any): arg is QueryDefinition {
+    return (
+        arg !== null &&
+        typeof arg === 'object' &&
+        typeof arg.resource === 'string'
+    );
+}
+
 /**
- * Filter operators for querying records.
+ * Filter operators for querying records via the legacy GET adapter.
+ *
  * Pass filters at the TOP LEVEL of query params (not nested under 'filter').
- * Use bracket notation for operators: 'data.field[operator]': value
+ * Use bracket notation for operators: `'data.field[operator]': value`
+ *
+ * @deprecated Since 5.5.0. Prefer canonical `FieldCondition` from
+ *   `@centrali-io/centrali-sdk` (re-exported above) and use `client.records.query()`
+ *   with a `QueryDefinition` body. This shape stays for back-compat with
+ *   `client.queryRecords(slug, options)` / `client.records.list()`.
  *
  * @example
  * // Simple equality - just use the field name
@@ -865,7 +929,7 @@ export interface DateWindowOption {
 }
 
 /**
- * Options for querying records.
+ * Options for querying records via the GET adapter.
  *
  * Supports two filter styles:
  *
@@ -884,6 +948,14 @@ export interface DateWindowOption {
  * Both styles are supported and can be mixed. Use `data.` prefix for custom fields.
  * System fields (`id`, `createdAt`, `updatedAt`, `status`) don't need the prefix.
  *
+ * @deprecated Since 5.5.0. This is the URL-param shape consumed by
+ *   `client.records.list()` and the legacy `client.queryRecords(slug, opts)`
+ *   form. New code should use a canonical `QueryDefinition` (`POST /records/query`)
+ *   via `client.records.query()` or the canonical `client.queryRecords(resource, definition)`
+ *   overload — same engine, but boolean trees, `select`, `text`, and `include`
+ *   become first-class. The GET adapter and this type stay supported during
+ *   the deprecation window per `docs/maintainers/overview/query-foundation.md`.
+ *
  * @example
  * // Top-level filters with bracket notation
  * { 'data.status': 'active', 'data.age[gte]': 18, sort: '-createdAt' }
@@ -1430,8 +1502,14 @@ export interface PaginatedResponse<T> {
 }
 
 // =====================================================
-// Smart Query Types
+// Smart Query Types (saved-query surface for `client.savedQueries`)
 // =====================================================
+//
+// These types describe the **stored** saved-query shape and the operator
+// vocabulary the `/saved-queries/*` routes accept. They back both
+// `client.savedQueries.*` (canonical) and the deprecated `client.smartQueries`
+// alias. The SDK still exports the type names with `SmartQuery` prefixes for
+// back-compat; canonical `SavedQuery*` aliases will be added in a follow-up.
 
 /**
  * Smart query definition stored in the database.
@@ -2882,32 +2960,36 @@ export function getEndpointApiPath(workspaceId: string, path: string): string {
 }
 
 /**
- * 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.
  */
 export function getSmartQueriesApiPath(workspaceId: string): string {
-    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.
  */
 export function getSmartQueriesStructureApiPath(workspaceId: string, structureSlug: string, queryId?: string): string {
-    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.
  */
 export function getSmartQueryByNameApiPath(workspaceId: string, structureSlug: string, name: string): string {
-    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.
  */
 export function getSmartQueryExecuteApiPath(workspaceId: string, structureSlug: string, queryId: string): string {
-    return `data/workspace/${workspaceId}/api/v1/smart-queries/slug/${structureSlug}/execute/${queryId}`;
+    return `data/workspace/${workspaceId}/api/v1/saved-queries/slug/${structureSlug}/execute/${queryId}`;
 }
 
 /**
@@ -3087,10 +3169,10 @@ export function getComputeJobStatusApiPath(workspaceId: string, jobId: string):
 // =====================================================
 
 /**
- * Generate Smart Query test execution API URL PATH.
+ * Generate Saved Query test execution API URL PATH.
  */
 export function getSmartQueryTestApiPath(workspaceId: string, structureSlug: string): string {
-    return `data/workspace/${workspaceId}/api/v1/smart-queries/slug/${structureSlug}/test`;
+    return `data/workspace/${workspaceId}/api/v1/saved-queries/slug/${structureSlug}/test`;
 }
 
 // =====================================================
@@ -3877,26 +3959,189 @@ export class 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');
+ * ```
+ */
+export class RecordsManager {
+    private requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>;
+    private workspaceId: string;
+
+    constructor(
+        workspaceId: string,
+        requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>
+    ) {
+        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 }
+     * });
+     */
+    public async query<T = any>(
+        resource: string,
+        definition: Omit<QueryDefinition, 'resource'> & { resource?: string }
+    ): Promise<QueryResult<T>> {
+        const path = `data/workspace/${this.workspaceId}/api/v1/records/query`;
+        const body: QueryDefinition = { ...definition, resource: definition.resource ?? resource };
+        const resp = await this.requestFn<T[]>('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 as unknown as QueryResult<T>;
+    }
+
+    /**
+     * 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.
+     */
+    public async test<T = any>(
+        resource: string,
+        definition: Omit<QueryDefinition, 'resource'> & { resource?: string }
+    ): Promise<QueryResult<T>> {
+        const path = `data/workspace/${this.workspaceId}/api/v1/records/query/test`;
+        const body: QueryDefinition = { ...definition, resource: definition.resource ?? resource };
+        const resp = await this.requestFn<T[]>('POST', path, body);
+        return resp as unknown as QueryResult<T>;
+    }
+
+    /**
+     * 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.
+     */
+    public list<T = any>(
+        resource: string,
+        urlOpts?: QueryRecordOptions
+    ): Promise<ApiResponse<T[]>> {
+        const path = getRecordApiPath(this.workspaceId, resource);
+        return this.requestFn<T[]>('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 }`).
+     */
+    public async search<T = any>(
+        resource: string,
+        text: string,
+        opts?: {
+            fields?: string[];
+            typoTolerance?: boolean;
+            where?: WhereExpression;
+            sort?: SortClause[];
+            page?: PageClause;
+            select?: SelectClause;
+        }
+    ): Promise<QueryResult<T>> {
+        return this.query<T>(resource, {
+            resource,
+            text: { query: text, fields: opts?.fields, typoTolerance: opts?.typoTolerance },
+            where: opts?.where,
+            sort: opts?.sort,
+            page: opts?.page,
+            select: opts?.select,
+        });
+    }
+}
+
 // =====================================================
 // 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');
  * ```
  */
 export class SmartQueriesManager {
@@ -5513,7 +5758,9 @@ export class CentraliSDK {
     private options: CentraliSDKOptions;
     private _realtime: RealtimeManager | null = null;
     private _triggers: TriggersManager | null = null;
+    private _records: RecordsManager | null = null;
     private _smartQueries: SmartQueriesManager | null = null;
+    private _queryRecordsLegacyWarned: boolean = false;
     private _anomalyInsights: AnomalyInsightsManager | null = null;
     private _validation: ValidationManager | null = null;
     private _orchestrations: OrchestrationsManager | null = null;
@@ -5737,25 +5984,75 @@ export class CentraliSDK {
     }
 
     /**
-     * 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');
+     * ```
+     */
+    public get records(): RecordsManager {
+        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');
      * ```
      */
-    public get smartQueries(): SmartQueriesManager {
+    public get savedQueries(): SmartQueriesManager {
         if (!this._smartQueries) {
             this._smartQueries = new SmartQueriesManager(
                 this.options.workspaceId,
@@ -5765,6 +6062,17 @@ export class CentraliSDK {
         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.
+     */
+    public get smartQueries(): SmartQueriesManager {
+        emitDeprecationWarning('client.smartQueries is deprecated. Use client.savedQueries instead.');
+        return this.savedQueries;
+    }
+
     /**
      * Anomaly Insights namespace for querying and managing AI-generated insights.
      *
@@ -6210,12 +6518,54 @@ export class CentraliSDK {
      *   pageSize: 100
      * });
      */
+    /**
+     * Canonical query (CEN-1194). When called with a `QueryDefinition` body,
+     * routes to `POST /records/query` and returns canonical `QueryResult<T>`.
+     *
+     * @example
+     * const result = await centrali.queryRecords<Order>('orders', {
+     *   resource: 'orders',
+     *   where: { 'data.status': { eq: 'paid' } },
+     *   page: { limit: 50 }
+     * });
+     * console.log(result.data, result.meta.hasMore);
+     */
+    public queryRecords<T = any>(
+        resource: string,
+        definition: QueryDefinition
+    ): Promise<QueryResult<T>>;
+    /**
+     * Legacy GET-adapter form. Pass `QueryRecordOptions` (URL-param style with
+     * `data.field[op]` keys, `sort: '-createdAt'`, `pageSize`, etc.) and the
+     * call routes to `GET /records/slug/:rs`.
+     *
+     * @deprecated Since 5.5.0. Prefer the canonical overload above (pass a
+     *   `QueryDefinition`) or {@link CentraliSDK.records | client.records.list()}
+     *   for the GET adapter explicitly. The legacy form keeps working — server-side
+     *   it already routes through the canonical engine (CEN-1181 WS3) — but the
+     *   client-side type story diverges from the canonical surface. Emits a
+     *   one-shot `console.warn` per client.
+     */
     public queryRecords<T = any>(
         recordSlug: string,
         queryParams?: QueryRecordOptions
-    ): Promise<ApiResponse<T>> {
-        const path = getRecordApiPath(this.options.workspaceId, recordSlug);
-        return this.request('GET', path, null, queryParams);
+    ): Promise<ApiResponse<T>>;
+    public queryRecords<T = any>(
+        resourceOrSlug: string,
+        arg2?: QueryDefinition | QueryRecordOptions
+    ): Promise<QueryResult<T>> | Promise<ApiResponse<T>> {
+        if (isCanonicalQueryDefinition(arg2)) {
+            return this.records.query<T>(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<T>('GET', path, null, arg2);
     }
 
     /** Get records by Ids. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-sdk",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "description": "Centrali Node SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,6 +10,8 @@
     "url": "git+https://github.com/blueinit/centrali-sdk.git"
   },
   "scripts": {
+    "sync:query-types": "node scripts/sync-query-types.mjs",
+    "prebuild": "npm run sync:query-types",
     "build": "tsc --project tsconfig.json",
     "prepublishOnly": "npm run build"
   },