@centrali-io/centrali-sdk 2.9.4 → 2.9.6

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.

package/dist/index.js

@@ -1801,15 +1801,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.
@@ -3429,24 +3476,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.4",
+  "version": "2.9.6",
   "description": "Centrali Node SDK",
   "main": "dist/index.js",
   "type": "commonjs",