@centrali-io/centrali-sdk 3.0.0 → 3.0.1

package/dist/index.js

@@ -1847,19 +1847,31 @@ class CentraliSDK {
      * @param queryParams - Query parameters including filter, sort, pagination, and expand
      *
      * @example
-     * // Basic query with filter and sort
+     * // Simple equality filter
+     * const activeProducts = await centrali.queryRecords('Product', {
+     *   filter: { status: 'active' },
+     *   sort: '-createdAt',
+     *   limit: 10
+     * });
+     *
+     * // Filter with operators
      * const products = await centrali.queryRecords('Product', {
-     *   filter: 'inStock = true AND price < 100',
+     *   filter: { inStock: true, price: { lte: 100 } },
      *   sort: '-createdAt',
      *   limit: 10
      * });
      *
-     * // Query with expanded references
+     * // Multiple values with 'in' operator
      * const orders = await centrali.queryRecords('Order', {
-     *   filter: 'status = "pending"',
+     *   filter: { status: { in: ['pending', 'processing'] } },
      *   expand: 'customer,items'
      * });
      * // Access expanded data: orders.data[0].data._expanded.customer
+     *
+     * // Range filters
+     * const customers = await centrali.queryRecords('Customer', {
+     *   filter: { age: { gte: 18, lte: 65 }, verified: true }
+     * });
      */
     queryRecords(recordSlug, queryParams) {
         const path = getRecordApiPath(this.options.workspaceId, recordSlug);
@@ -2170,7 +2182,7 @@ exports.CentraliSDK = CentraliSDK;
  *
  * // Subscribe to realtime events (Initial Sync Pattern):
  * // 1. First fetch initial data
- * const orders = await client.queryRecords('Order', { filter: 'status = "pending"' });
+ * const orders = await client.queryRecords('Order', { filter: { status: 'pending' } });
  * setOrders(orders.data);
  *
  * // 2. Then subscribe to realtime updates

package/index.ts

@@ -566,12 +566,69 @@ export interface ExpandOptions {
  */
 export interface GetRecordOptions extends ExpandOptions {}
 
+/**
+ * Filter operators for querying records.
+ * Use these within filter objects to apply comparison operations.
+ *
+ * @example
+ * // Filter with operators
+ * { age: { gte: 18, lte: 65 } }
+ * { status: { in: ['active', 'pending'] } }
+ * { email: { contains: '@gmail.com' } }
+ */
+export interface FilterOperators {
+    /** Equal to (default if just a value is provided) */
+    eq?: string | number | boolean;
+    /** Not equal to */
+    ne?: string | number | boolean;
+    /** Greater than */
+    gt?: number | string;
+    /** Greater than or equal to */
+    gte?: number | string;
+    /** Less than */
+    lt?: number | string;
+    /** Less than or equal to */
+    lte?: number | string;
+    /** Value is in the provided array */
+    in?: (string | number)[];
+    /** Value is not in the provided array */
+    nin?: (string | number)[];
+    /** String contains substring (case-insensitive) */
+    contains?: string;
+    /** String starts with (case-insensitive) */
+    startswith?: string;
+    /** String ends with (case-insensitive) */
+    endswith?: string;
+    /** Array field contains any of the provided values */
+    hasAny?: (string | number)[];
+    /** Array field contains all of the provided values */
+    hasAll?: (string | number)[];
+}
+
+/**
+ * Filter value can be a direct value or an object with operators.
+ */
+export type FilterValue = string | number | boolean | null | FilterOperators;
+
 /**
  * Options for querying records.
  */
 export interface QueryRecordOptions extends ExpandOptions {
-    /** CFL filter expression (e.g., 'status = "active" AND price > 100') */
-    filter?: string;
+    /**
+     * Filter object for querying records.
+     * Keys are field names, values are either direct values (for equality) or operator objects.
+     *
+     * @example
+     * // Simple equality filter
+     * { filter: { status: 'active' } }
+     *
+     * // Filter with operators
+     * { filter: { age: { gte: 18 }, status: { in: ['active', 'pending'] } } }
+     *
+     * // Multiple conditions (AND)
+     * { filter: { status: 'active', inStock: true, price: { lte: 100 } } }
+     */
+    filter?: Record<string, FilterValue>;
     /** Sort field with optional direction prefix (e.g., '-createdAt' for descending) */
     sort?: string;
     /** Maximum number of records to return */
@@ -3561,19 +3618,31 @@ export class CentraliSDK {
      * @param queryParams - Query parameters including filter, sort, pagination, and expand
      *
      * @example
-     * // Basic query with filter and sort
+     * // Simple equality filter
+     * const activeProducts = await centrali.queryRecords('Product', {
+     *   filter: { status: 'active' },
+     *   sort: '-createdAt',
+     *   limit: 10
+     * });
+     *
+     * // Filter with operators
      * const products = await centrali.queryRecords('Product', {
-     *   filter: 'inStock = true AND price < 100',
+     *   filter: { inStock: true, price: { lte: 100 } },
      *   sort: '-createdAt',
      *   limit: 10
      * });
      *
-     * // Query with expanded references
+     * // Multiple values with 'in' operator
      * const orders = await centrali.queryRecords('Order', {
-     *   filter: 'status = "pending"',
+     *   filter: { status: { in: ['pending', 'processing'] } },
      *   expand: 'customer,items'
      * });
      * // Access expanded data: orders.data[0].data._expanded.customer
+     *
+     * // Range filters
+     * const customers = await centrali.queryRecords('Customer', {
+     *   filter: { age: { gte: 18, lte: 65 }, verified: true }
+     * });
      */
     public queryRecords<T = any>(
         recordSlug: string,
@@ -3951,7 +4020,7 @@ export class CentraliSDK {
  *
  * // Subscribe to realtime events (Initial Sync Pattern):
  * // 1. First fetch initial data
- * const orders = await client.queryRecords('Order', { filter: 'status = "pending"' });
+ * const orders = await client.queryRecords('Order', { filter: { status: 'pending' } });
  * setOrders(orders.data);
  *
  * // 2. Then subscribe to realtime updates

package/package.json

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