@centrali-io/centrali-sdk 2.9.5 → 2.9.7

package/README.md

@@ -122,6 +122,69 @@ const products = await centrali.queryRecords('Product', {
 });
 ```
 
+### Expanding References
+
+When querying records with reference fields, use the `expand` parameter to include the full referenced record data:
+
+```typescript
+// Expand a single reference field
+const orders = await centrali.queryRecords('Order', {
+  expand: 'customer'
+});
+
+// Expand multiple reference fields
+const orders = await centrali.queryRecords('Order', {
+  expand: 'customer,product'
+});
+
+// Nested expansion (up to 3 levels deep)
+const orders = await centrali.queryRecords('Order', {
+  expand: 'customer,customer.address'
+});
+
+// Get a single record with expanded references
+const order = await centrali.getRecord('Order', 'order-id', {
+  expand: 'customer,items'
+});
+```
+
+Expanded data is placed in the `_expanded` object within the record's data:
+
+```typescript
+// Response structure
+{
+  "id": "order-123",
+  "data": {
+    "customerId": "cust-456",
+    "total": 99.99,
+    "_expanded": {
+      "customerId": {
+        "id": "cust-456",
+        "data": {
+          "name": "John Doe",
+          "email": "john@example.com"
+        }
+      }
+    }
+  }
+}
+
+// Access expanded data
+const customerName = order.data.data._expanded.customerId.data.name;
+```
+
+For many-to-many relationships, the expanded field contains an array:
+
+```typescript
+// Many-to-many expansion
+const post = await centrali.getRecord('Post', 'post-id', {
+  expand: 'tags'
+});
+
+// _expanded.tags will be an array of tag records
+const tagNames = post.data.data._expanded.tags.map(tag => tag.data.name);
+```
+
 ### Smart 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.
@@ -140,6 +203,15 @@ console.log('Query ID:', query.data.id);
 // Execute a smart query
 const results = await centrali.smartQueries.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, {
+  variables: {
+    statusFilter: 'active',
+    startDate: '2024-01-01'
+  }
+});
 ```
 
 ### Search

package/dist/index.js

@@ -1095,17 +1095,27 @@ class SmartQueriesManager {
      *
      * @param structureSlug - The structure's record slug
      * @param queryId - The smart query UUID
+     * @param options - Optional execution options including variables
      * @returns Query results
      *
      * @example
      * ```ts
+     * // Simple execution without variables
      * const results = await client.smartQueries.execute('employee', 'query-uuid');
      * console.log('Found:', results.data.length, 'records');
+     *
+     * // Execution with variables
+     * // Query definition: { where: { status: { $eq: "{{statusFilter}}" } } }
+     * const filtered = await client.smartQueries.execute('orders', 'query-id', {
+     *   variables: { statusFilter: 'active' }
+     * });
      * ```
      */
-    execute(structureSlug, queryId) {
+    execute(structureSlug, queryId, options) {
         const path = getSmartQueryExecuteApiPath(this.workspaceId, structureSlug, queryId);
-        return this.requestFn('GET', path);
+        // Use POST to support variables, with empty body if no options
+        const body = (options === null || options === void 0 ? void 0 : options.variables) ? { variables: options.variables } : undefined;
+        return this.requestFn('POST', path, body);
     }
 }
 exports.SmartQueriesManager = SmartQueriesManager;
@@ -1801,15 +1811,51 @@ class CentraliSDK {
     getToken() {
         return this.token;
     }
-    /** Retrieve a record by ID. */
-    getRecord(recordSlug, id) {
+    /**
+     * Retrieve a record by ID.
+     *
+     * @param recordSlug - The structure's record slug
+     * @param id - The record ID
+     * @param options - Optional parameters including expand for reference fields
+     *
+     * @example
+     * // Basic fetch
+     * const order = await centrali.getRecord('Order', 'order-123');
+     *
+     * // With expanded references
+     * const order = await centrali.getRecord('Order', 'order-123', {
+     *   expand: 'customer,items'
+     * });
+     * // Access expanded data: order.data.data._expanded.customer
+     */
+    getRecord(recordSlug, id, options) {
         const path = getRecordApiPath(this.options.workspaceId, recordSlug, id);
-        return this.request('GET', path);
+        return this.request('GET', path, null, options);
     }
-    /** Query records with filters, pagination, etc. */
+    /**
+     * Query records with filters, pagination, sorting, and reference expansion.
+     *
+     * @param recordSlug - The structure's record slug
+     * @param queryParams - Query parameters including filter, sort, pagination, and expand
+     *
+     * @example
+     * // Basic query with filter and sort
+     * const products = await centrali.queryRecords('Product', {
+     *   filter: 'inStock = true AND price < 100',
+     *   sort: '-createdAt',
+     *   limit: 10
+     * });
+     *
+     * // Query with expanded references
+     * const orders = await centrali.queryRecords('Order', {
+     *   filter: 'status = "pending"',
+     *   expand: 'customer,items'
+     * });
+     * // Access expanded data: orders.data[0].data._expanded.customer
+     */
     queryRecords(recordSlug, queryParams) {
         const path = getRecordApiPath(this.options.workspaceId, recordSlug);
-        return this.request('GET', path, null, Object.assign({}, queryParams));
+        return this.request('GET', path, null, queryParams);
     }
     /** Get records by Ids. */
     getRecordsByIds(recordSlug, ids) {

package/index.ts

@@ -539,6 +539,53 @@ export interface DeleteRecordOptions {
     hard?: boolean;
 }
 
+/**
+ * Options for expanding reference fields when fetching records.
+ * Expanded data is placed in the `_expanded` object within the record's data.
+ */
+export interface ExpandOptions {
+    /**
+     * Comma-separated list of reference fields to expand.
+     * Supports nested expansion using dot notation (up to 3 levels deep).
+     *
+     * @example
+     * // Single field
+     * expand: 'customer'
+     *
+     * // Multiple fields
+     * expand: 'customer,product'
+     *
+     * // Nested expansion
+     * expand: 'customer,customer.address'
+     */
+    expand?: string;
+}
+
+/**
+ * Options for retrieving a single record.
+ */
+export interface GetRecordOptions extends ExpandOptions {}
+
+/**
+ * Options for querying records.
+ */
+export interface QueryRecordOptions extends ExpandOptions {
+    /** CFL filter expression (e.g., 'status = "active" AND price > 100') */
+    filter?: string;
+    /** Sort field with optional direction prefix (e.g., '-createdAt' for descending) */
+    sort?: string;
+    /** Maximum number of records to return */
+    limit?: number;
+    /** Number of records to skip (for pagination) */
+    skip?: number;
+    /** Page number (alternative to skip) */
+    page?: number;
+    /** Include archived (soft-deleted) records */
+    includeArchived?: boolean;
+    /** Additional query parameters */
+    [key: string]: any;
+}
+
 /**
  * Response from invoking a trigger.
  * Currently the API returns the queued job ID as a string.
@@ -1128,6 +1175,39 @@ export interface ListSmartQueryOptions {
     sortDirection?: 'asc' | 'desc';
 }
 
+/**
+ * Options for executing a smart query.
+ */
+export interface ExecuteSmartQueryOptions {
+    /**
+     * Variables to substitute in the query.
+     * Use mustache-style {{variableName}} syntax in query conditions,
+     * then provide values here at execution time.
+     *
+     * @example
+     * ```ts
+     * // Query definition with variable: { where: { userId: { $eq: "{{currentUserId}}" } } }
+     * const results = await client.smartQueries.execute('orders', 'query-id', {
+     *   variables: { currentUserId: 'user_123' }
+     * });
+     * ```
+     */
+    variables?: Record<string, string>;
+}
+
+/**
+ * Result from executing a smart query with metadata.
+ */
+export interface SmartQueryExecuteResult<T = any> {
+    /** Query results */
+    result: T[];
+    /** Metadata about the execution */
+    meta?: {
+        /** Variables that were used in the query */
+        variablesUsed?: string[];
+    };
+}
+
 // =====================================================
 // Search Types
 // =====================================================
@@ -2601,20 +2681,31 @@ export class SmartQueriesManager {
      *
      * @param structureSlug - The structure's record slug
      * @param queryId - The smart query UUID
+     * @param options - Optional execution options including variables
      * @returns Query results
      *
      * @example
      * ```ts
+     * // Simple execution without variables
      * const results = await client.smartQueries.execute('employee', 'query-uuid');
      * console.log('Found:', results.data.length, 'records');
+     *
+     * // Execution with variables
+     * // Query definition: { where: { status: { $eq: "{{statusFilter}}" } } }
+     * const filtered = await client.smartQueries.execute('orders', 'query-id', {
+     *   variables: { statusFilter: 'active' }
+     * });
      * ```
      */
     public execute<T = any>(
         structureSlug: string,
-        queryId: string
+        queryId: string,
+        options?: ExecuteSmartQueryOptions
     ): Promise<ApiResponse<T[]>> {
         const path = getSmartQueryExecuteApiPath(this.workspaceId, structureSlug, queryId);
-        return this.requestFn<T[]>('GET', path);
+        // Use POST to support variables, with empty body if no options
+        const body = options?.variables ? { variables: options.variables } : undefined;
+        return this.requestFn<T[]>('POST', path, body);
     }
 }
 
@@ -3429,24 +3520,59 @@ export class CentraliSDK {
     }
 
 
-    /** Retrieve a record by ID. */
+    /**
+     * Retrieve a record by ID.
+     *
+     * @param recordSlug - The structure's record slug
+     * @param id - The record ID
+     * @param options - Optional parameters including expand for reference fields
+     *
+     * @example
+     * // Basic fetch
+     * const order = await centrali.getRecord('Order', 'order-123');
+     *
+     * // With expanded references
+     * const order = await centrali.getRecord('Order', 'order-123', {
+     *   expand: 'customer,items'
+     * });
+     * // Access expanded data: order.data.data._expanded.customer
+     */
     public getRecord<T = any>(
         recordSlug: string,
-        id: string
+        id: string,
+        options?: GetRecordOptions
     ): Promise<ApiResponse<T>> {
         const path = getRecordApiPath(this.options.workspaceId, recordSlug, id);
-        return this.request('GET', path);
+        return this.request('GET', path, null, options);
     }
 
-    /** Query records with filters, pagination, etc. */
+    /**
+     * Query records with filters, pagination, sorting, and reference expansion.
+     *
+     * @param recordSlug - The structure's record slug
+     * @param queryParams - Query parameters including filter, sort, pagination, and expand
+     *
+     * @example
+     * // Basic query with filter and sort
+     * const products = await centrali.queryRecords('Product', {
+     *   filter: 'inStock = true AND price < 100',
+     *   sort: '-createdAt',
+     *   limit: 10
+     * });
+     *
+     * // Query with expanded references
+     * const orders = await centrali.queryRecords('Order', {
+     *   filter: 'status = "pending"',
+     *   expand: 'customer,items'
+     * });
+     * // Access expanded data: orders.data[0].data._expanded.customer
+     */
     public queryRecords<T = any>(
         recordSlug: string,
-        queryParams: Record<string, any>
+        queryParams?: QueryRecordOptions
     ): Promise<ApiResponse<T>> {
         const path = getRecordApiPath(this.options.workspaceId, recordSlug);
-        return this.request('GET', path, null, {
-            ...queryParams,
-        });
+        return this.request('GET', path, null, queryParams);
     }
 
     /** Get records by Ids. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-sdk",
-  "version": "2.9.5",
+  "version": "2.9.7",
   "description": "Centrali Node SDK",
   "main": "dist/index.js",
   "type": "commonjs",