@centrali-io/centrali-sdk 5.3.0 → 5.5.0

package/README.md

@@ -98,7 +98,7 @@ const centrali = new CentraliSDK({
 - ✅ **Automatic authentication** and token management
 - ✅ **Records management** - Create, read, update, delete records
 - ✅ **Query operations** - Powerful data querying with filters and sorting
-- ✅ **Smart Queries** - Execute reusable, predefined queries
+- ✅ **Saved Queries** - Execute reusable, parameterized queries
 - ✅ **Full-text search** - Search records across structures with Meilisearch
 - ✅ **Realtime events** - Subscribe to record changes via SSE
 - ✅ **Compute functions** - Execute serverless functions
@@ -137,7 +137,66 @@ await centrali.deleteRecord('StructureName', 'record-id', { hard: true });
 
 // Restore a soft-deleted record
 await centrali.restoreRecord('StructureName', 'record-id');
+```
+
+### Querying records (canonical — recommended)
+
+The canonical query surface — `client.records.*` — is the **same query language used by every Centrali surface** (HTTP, SDK, compute, console, MCP, AI). One operator vocabulary, one result envelope. New code should start here.
+
+```typescript
+// Full canonical query — boolean trees, projection, sorting, paging
+const open = await centrali.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);
+
+// Full-text search — sugar over `query({ text: ... })`
+const matches = await centrali.records.search<Order>('orders', 'urgent shipping');
+
+// GET adapter for simple URL-param queries (bookmarkable, cacheable)
+const recent = await centrali.records.list<Order>('orders', {
+  'data.status': 'paid',
+  sort: '-createdAt',
+  pageSize: 25,
+});
+
+// Top-level convenience — same as `records.query` when called with a QueryDefinition
+const result = await centrali.queryRecords<Order>('orders', {
+  resource: 'orders',
+  where: { 'data.status': { eq: 'paid' } },
+  page: { limit: 100 }
+});
+```
 
+| Method | Endpoint | Use when |
+|---|---|---|
+| `centrali.records.query(resource, def)` | `POST /records/query` | Boolean trees, `select`, `text`, `include` |
+| `centrali.records.list(resource, urlOpts?)` | `GET /records/slug/:rs` | Flat AND of field conditions, bookmarkable URLs |
+| `centrali.records.search(resource, text, opts?)` | `POST /records/query` (text routes to search executor) | Full-text search with optional filters |
+| `centrali.records.test(resource, def)` | `POST /records/query/test` | Authoring-time dry-run; surfaces `unreadable_field` errors |
+| `centrali.queryRecords(resource, def)` | `POST /records/query` | Top-level convenience for the canonical form |
+
+**Operators** (no `$` prefix): `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains`, `startsWith`, `endsWith`, `hasAny`, `hasAll`, `exists`. **Boolean tree:** `and`, `or`, `not`. **Nested paths:** dotted strings (`'data.customer.email'`).
+
+**Result envelope:** every canonical method returns `QueryResult<T> = { data: T[]; meta: { limit, offset?, cursor?, nextCursor?, hasMore?, total?, processingTimeMs?, mode? } }`.
+
+> The legacy `queryRecords(slug, urlOptions)` form below (URL-param style with `'data.field[op]'` keys and `sort: '-createdAt'`) still works — server-side it already routes through the canonical engine — but is `@deprecated` since 5.5.0. New code should pass a canonical `QueryDefinition` instead.
+
+### Querying records (legacy URL-param form)
+
+```typescript
 // Query archived (soft-deleted) records
 const archived = await centrali.queryRecords('StructureName', {
   includeArchived: true
@@ -328,28 +387,28 @@ const post = await centrali.getRecord('Post', 'post-id', {
 const tagNames = post.data.data._expanded.tags.map(tag => tag.data.name);
 ```
 
-### Smart Queries
+### Saved Queries
 
-Smart queries are reusable, predefined queries that are created in the Centrali console and can be executed programmatically via the SDK. Pagination (limit/skip) is defined in the query definition itself.
+Saved queries are reusable, predefined queries created in the Centrali console and executed programmatically via the SDK. Pagination is defined in the query definition itself.
 
 ```typescript
-// List all smart queries in the workspace
-const allQueries = await centrali.smartQueries.listAll();
+// List all saved queries in the workspace
+const allQueries = await centrali.savedQueries.listAll();
 
-// List smart queries for a specific structure
-const employeeQueries = await centrali.smartQueries.list('employee');
+// List saved queries for a specific collection
+const employeeQueries = await centrali.savedQueries.list('employee');
 
-// Get a smart query by name
-const query = await centrali.smartQueries.getByName('employee', 'Active Employees');
+// Get a saved query by name
+const query = await centrali.savedQueries.getByName('employee', 'Active Employees');
 console.log('Query ID:', query.data.id);
 
-// Execute a smart query
-const results = await centrali.smartQueries.execute('employee', query.data.id);
+// Execute a saved query
+const results = await centrali.savedQueries.execute('employee', query.data.id);
 console.log('Found:', results.data.length, 'employees');
 
-// Execute with variables
-// Query definition uses {{variableName}} syntax: { where: { status: { $eq: "{{statusFilter}}" } } }
-const filteredResults = await centrali.smartQueries.execute('orders', query.data.id, {
+// Execute with variables (canonical operators — no `$` prefix)
+// Saved query body: { where: { 'data.status': { eq: '{{statusFilter}}' } } }
+const filteredResults = await centrali.savedQueries.execute('orders', query.data.id, {
   variables: {
     statusFilter: 'active',
     startDate: '2024-01-01'
@@ -357,6 +416,22 @@ const filteredResults = await centrali.smartQueries.execute('orders', query.data
 });
 ```
 
+`centrali.savedQueries.*` is the canonical namespace, routed through the `/saved-queries/*` HTTP endpoints (Phase 4 of the [query foundation](https://github.com/blueinit/centrali/blob/main/docs/maintainers/overview/query-foundation.md), CEN-1198). New code should always use it.
+
+#### Migration from `centrali.smartQueries.*` (deprecated alias)
+
+`centrali.smartQueries.*` is preserved as a deprecated alias of `centrali.savedQueries.*` during the deprecation window — it routes through the same canonical endpoints and emits a one-shot `console.warn` on first use. Migrate by:
+
+```typescript
+// Before
+const results = await centrali.smartQueries.execute('orders', queryId);
+
+// After
+const results = await centrali.savedQueries.execute('orders', queryId);
+```
+
+Saved-query bodies authored against the legacy operator vocabulary (`{ status: { $eq: 'open' } }`) keep working server-side via the legacy translator during the deprecation window. New saved-query definitions should use canonical operators (`{ 'data.status': { eq: 'open' } }`).
+
 ### Search
 
 Perform full-text search across workspace records using Meilisearch:

package/dist/index.d.ts

@@ -658,10 +658,18 @@ export interface ExpandOptions {
  */
 export interface GetRecordOptions extends ExpandOptions {
 }
+export * from './query-types';
+import type { QueryDefinition, QueryResult, WhereExpression, SortClause, PageClause, SelectClause } from './query-types';
 /**
- * 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
@@ -723,7 +731,7 @@ export interface DateWindowOption {
     to?: string;
 }
 /**
- * Options for querying records.
+ * Options for querying records via the GET adapter.
  *
  * Supports two filter styles:
  *
@@ -742,6 +750,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' }
@@ -2276,19 +2292,23 @@ export declare function getFunctionTriggerResumeApiPath(workspaceId: string, tri
  */
 export declare 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 declare function getSmartQueriesApiPath(workspaceId: string): string;
 /**
- * Generate Smart Queries API URL PATH for structure-level operations.
+ * Generate Saved Queries API URL PATH for structure-level operations.
  */
 export declare function getSmartQueriesStructureApiPath(workspaceId: string, structureSlug: string, queryId?: string): string;
 /**
- * Generate Smart Query by name API URL PATH.
+ * Generate Saved Query by name API URL PATH.
  */
 export declare function getSmartQueryByNameApiPath(workspaceId: string, structureSlug: string, name: string): string;
 /**
- * Generate Smart Query execute API URL PATH.
+ * Generate Saved Query execute API URL PATH.
  */
 export declare function getSmartQueryExecuteApiPath(workspaceId: string, structureSlug: string, queryId: string): string;
 /**
@@ -2376,7 +2396,7 @@ export declare function getFunctionRunsByFunctionApiPath(workspaceId: string, fu
  */
 export declare function getComputeJobStatusApiPath(workspaceId: string, jobId: string): string;
 /**
- * Generate Smart Query test execution API URL PATH.
+ * Generate Saved Query test execution API URL PATH.
  */
 export declare function getSmartQueryTestApiPath(workspaceId: string, structureSlug: string): string;
 /**
@@ -2963,21 +2983,133 @@ export declare class TriggersManager {
     invokeEndpoint<T = any>(endpointPath: string, options?: InvokeEndpointOptions): Promise<ApiResponse<T>>;
 }
 /**
- * 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`.
+ * 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 declare class RecordsManager {
+    private requestFn;
+    private workspaceId;
+    constructor(workspaceId: string, requestFn: <T>(method: Method, path: string, data?: any, queryParams?: Record<string, any>) => Promise<ApiResponse<T>>);
+    /**
+     * 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<T = any>(resource: string, definition: Omit<QueryDefinition, 'resource'> & {
+        resource?: string;
+    }): Promise<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.
+     */
+    test<T = any>(resource: string, definition: Omit<QueryDefinition, 'resource'> & {
+        resource?: string;
+    }): Promise<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.
+     */
+    list<T = any>(resource: string, urlOpts?: QueryRecordOptions): Promise<ApiResponse<T[]>>;
+    /**
+     * 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<T = any>(resource: string, text: string, opts?: {
+        fields?: string[];
+        typoTolerance?: boolean;
+        where?: WhereExpression;
+        sort?: SortClause[];
+        page?: PageClause;
+        select?: SelectClause;
+    }): Promise<QueryResult<T>>;
+}
+/**
+ * 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 declare class SmartQueriesManager {
@@ -4156,7 +4288,9 @@ export declare class CentraliSDK {
     private options;
     private _realtime;
     private _triggers;
+    private _records;
     private _smartQueries;
+    private _queryRecordsLegacyWarned;
     private _anomalyInsights;
     private _validation;
     private _orchestrations;
@@ -4216,24 +4350,72 @@ export declare class CentraliSDK {
      */
     get triggers(): TriggersManager;
     /**
-     * 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(): RecordsManager;
+    /**
+     * 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 savedQueries(): SmartQueriesManager;
+    /**
+     * @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(): SmartQueriesManager;
     /**
      * Anomaly Insights namespace for querying and managing AI-generated insights.
@@ -4525,6 +4707,31 @@ export declare 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);
+     */
+    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.
+     */
     queryRecords<T = any>(recordSlug: string, queryParams?: QueryRecordOptions): Promise<ApiResponse<T>>;
     /** Get records by Ids. */
     getRecordsByIds<T = any>(recordSlug: string, ids: string[]): Promise<ApiResponse<T[]>>;
@@ -4793,7 +5000,6 @@ export declare class CentraliSDK {
      */
     checkAuthorization(options: CheckAuthorizationOptions): Promise<ApiResponse<AuthorizationResult>>;
 }
-export {};
 /**
  * Usage Example:
  *