@centrali-io/centrali-sdk 3.0.0 → 3.0.2

package/README.md

@@ -704,7 +704,7 @@ try {
 - [Complete SDK Guide](https://docs.centrali.io/guides/centrali-sdk)
 - [API Reference](https://docs.centrali.io/api-reference/overview)
 - [Quick Start Tutorial](https://docs.centrali.io/getting-started/02-quickstart)
-- [Compute Functions Guide](https://docs.centrali.io/guides/compute-functions-guide)
+- [Compute Functions Guide](https://docs.centrali.io/guides/FUNCTION_CODE_GUIDE)
 
 ## Examples
 

package/dist/index.js

@@ -1558,6 +1558,8 @@ class CentraliSDK {
         this._anomalyInsights = null;
         this._validation = null;
         this._orchestrations = null;
+        this.isRefreshingToken = false;
+        this.tokenRefreshPromise = null;
         this.options = options;
         this.token = options.token || null;
         const apiUrl = getApiUrl(options.baseUrl);
@@ -1572,6 +1574,44 @@ class CentraliSDK {
             }
             return config;
         }), (error) => Promise.reject(error));
+        // Response interceptor for automatic token refresh on 401/403
+        this.axios.interceptors.response.use((response) => response, (error) => __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const originalRequest = error.config;
+            // Only attempt refresh for 401/403 errors when using client credentials
+            const isAuthError = ((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 401 || ((_b = error.response) === null || _b === void 0 ? void 0 : _b.status) === 403;
+            const hasClientCredentials = this.options.clientId && this.options.clientSecret;
+            const hasNotRetried = !originalRequest._hasRetried;
+            if (isAuthError && hasClientCredentials && hasNotRetried) {
+                // Mark request as retried to prevent infinite loops
+                originalRequest._hasRetried = true;
+                try {
+                    // If already refreshing, wait for the existing refresh to complete
+                    if (this.isRefreshingToken && this.tokenRefreshPromise) {
+                        yield this.tokenRefreshPromise;
+                    }
+                    else {
+                        // Start a new token refresh
+                        this.isRefreshingToken = true;
+                        this.tokenRefreshPromise = fetchClientToken(this.options.clientId, this.options.clientSecret, this.options.baseUrl);
+                        this.token = yield this.tokenRefreshPromise;
+                        this.isRefreshingToken = false;
+                        this.tokenRefreshPromise = null;
+                    }
+                    // Retry the original request with the new token
+                    originalRequest.headers.Authorization = `Bearer ${this.token}`;
+                    return this.axios(originalRequest);
+                }
+                catch (refreshError) {
+                    // Token refresh failed, clear state and reject
+                    this.isRefreshingToken = false;
+                    this.tokenRefreshPromise = null;
+                    this.token = null;
+                    return Promise.reject(refreshError);
+                }
+            }
+            return Promise.reject(error);
+        }));
     }
     /**
      * Realtime namespace for subscribing to SSE events.
@@ -1843,23 +1883,48 @@ class CentraliSDK {
     /**
      * Query records with filters, pagination, sorting, and reference expansion.
      *
+     * IMPORTANT: Filters are passed at the TOP LEVEL, not nested under 'filter'.
+     * Use 'data.' prefix for custom fields and bracket notation for operators.
+     *
      * @param recordSlug - The structure's record slug
-     * @param queryParams - Query parameters including filter, sort, pagination, and expand
+     * @param queryParams - Query parameters (filters at top level, plus sort, pagination, expand)
      *
      * @example
-     * // Basic query with filter and sort
+     * // Simple equality filter
+     * const activeProducts = await centrali.queryRecords('Product', {
+     *   'data.status': 'active',
+     *   sort: '-createdAt',
+     *   page: 1,
+     *   pageSize: 10
+     * });
+     *
+     * // Filter with operators (bracket notation)
      * const products = await centrali.queryRecords('Product', {
-     *   filter: 'inStock = true AND price < 100',
+     *   'data.inStock': true,
+     *   'data.price[lte]': 100,
      *   sort: '-createdAt',
-     *   limit: 10
+     *   pageSize: 10
      * });
      *
-     * // Query with expanded references
+     * // Multiple values with 'in' operator (comma-separated string)
      * const orders = await centrali.queryRecords('Order', {
-     *   filter: 'status = "pending"',
+     *   'data.status[in]': 'pending,processing',
      *   expand: 'customer,items'
      * });
      * // Access expanded data: orders.data[0].data._expanded.customer
+     *
+     * // Range filters
+     * const customers = await centrali.queryRecords('Customer', {
+     *   'data.age[gte]': 18,
+     *   'data.age[lte]': 65,
+     *   'data.verified': true
+     * });
+     *
+     * // Filter with 'ne' (not equal)
+     * const availableItems = await centrali.queryRecords('Product', {
+     *   'data.status[ne]': 'discontinued',
+     *   pageSize: 100
+     * });
      */
     queryRecords(recordSlug, queryParams) {
         const path = getRecordApiPath(this.options.workspaceId, recordSlug);
@@ -2166,11 +2231,11 @@ exports.CentraliSDK = CentraliSDK;
  *
  * // Or set a user token:
  * client.setToken('<JWT_TOKEN>');
- * await client.queryRecords('Product', { limit: 10 });
+ * await client.queryRecords('Product', { pageSize: 10 });
  *
  * // Subscribe to realtime events (Initial Sync Pattern):
- * // 1. First fetch initial data
- * const orders = await client.queryRecords('Order', { filter: 'status = "pending"' });
+ * // 1. First fetch initial data (filters at TOP LEVEL, not nested)
+ * const orders = await client.queryRecords('Order', { 'data.status': 'pending' });
  * setOrders(orders.data);
  *
  * // 2. Then subscribe to realtime updates

package/index.ts

@@ -566,23 +566,99 @@ export interface ExpandOptions {
  */
 export interface GetRecordOptions extends ExpandOptions {}
 
+/**
+ * Filter operators for querying records.
+ * Pass filters at the TOP LEVEL of query params (not nested under 'filter').
+ * Use bracket notation for operators: 'data.field[operator]': value
+ *
+ * @example
+ * // Simple equality - just use the field name
+ * { 'data.status': 'active' }
+ *
+ * // With operators - use bracket notation
+ * { 'data.age[gte]': 18, 'data.age[lte]': 65 }
+ * { 'data.status[in]': 'pending,processing' }  // comma-separated for 'in'
+ * { 'data.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.
+ *
+ * IMPORTANT: Filters are passed at the TOP LEVEL, not nested under a 'filter' key.
+ * Use 'data.' prefix for custom fields, and bracket notation for operators.
+ *
+ * @example
+ * // Simple equality filter
+ * { 'data.status': 'active', pageSize: 10 }
+ *
+ * // Filter with operators (bracket notation)
+ * { 'data.price[lte]': 100, 'data.status[ne]': 'discontinued' }
+ *
+ * // Multiple values with 'in' operator (comma-separated string)
+ * { 'data.status[in]': 'pending,processing', pageSize: 50 }
+ *
+ * // Range filters
+ * { 'data.age[gte]': 18, 'data.age[lte]': 65 }
+ *
+ * // Filter on top-level record fields (no 'data.' prefix)
+ * { 'createdAt[gte]': '2024-01-01', sort: '-createdAt' }
  */
 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 (1-indexed, default: 1) */
     page?: number;
+    /** Number of records per page (default: 50, max: 500) */
+    pageSize?: number;
+    /** Alias for pageSize */
+    limit?: number;
     /** Include archived (soft-deleted) records */
     includeArchived?: boolean;
-    /** Additional query parameters */
+    /** Include total count in response */
+    includeTotal?: boolean;
+    /** Search query string */
+    search?: string;
+    /** Field(s) to search in (comma-separated or single field) */
+    searchField?: string;
+    /**
+     * Filter fields - pass at TOP LEVEL with 'data.' prefix for custom fields.
+     * Use bracket notation for operators: 'data.field[operator]': value
+     *
+     * Supported operators: eq, ne, gt, gte, lt, lte, in, nin, contains, startswith, endswith, hasAny, hasAll
+     */
     [key: string]: any;
 }
 
@@ -3199,6 +3275,8 @@ export class CentraliSDK {
     private _anomalyInsights: AnomalyInsightsManager | null = null;
     private _validation: ValidationManager | null = null;
     private _orchestrations: OrchestrationsManager | null = null;
+    private isRefreshingToken: boolean = false;
+    private tokenRefreshPromise: Promise<string> | null = null;
 
     constructor(options: CentraliSDKOptions) {
         this.options = options;
@@ -3229,6 +3307,54 @@ export class CentraliSDK {
             },
             (error) => Promise.reject(error)
         );
+
+        // Response interceptor for automatic token refresh on 401/403
+        this.axios.interceptors.response.use(
+            (response) => response,
+            async (error) => {
+                const originalRequest = error.config;
+
+                // Only attempt refresh for 401/403 errors when using client credentials
+                const isAuthError = error.response?.status === 401 || error.response?.status === 403;
+                const hasClientCredentials = this.options.clientId && this.options.clientSecret;
+                const hasNotRetried = !originalRequest._hasRetried;
+
+                if (isAuthError && hasClientCredentials && hasNotRetried) {
+                    // Mark request as retried to prevent infinite loops
+                    originalRequest._hasRetried = true;
+
+                    try {
+                        // If already refreshing, wait for the existing refresh to complete
+                        if (this.isRefreshingToken && this.tokenRefreshPromise) {
+                            await this.tokenRefreshPromise;
+                        } else {
+                            // Start a new token refresh
+                            this.isRefreshingToken = true;
+                            this.tokenRefreshPromise = fetchClientToken(
+                                this.options.clientId!,
+                                this.options.clientSecret!,
+                                this.options.baseUrl
+                            );
+                            this.token = await this.tokenRefreshPromise;
+                            this.isRefreshingToken = false;
+                            this.tokenRefreshPromise = null;
+                        }
+
+                        // Retry the original request with the new token
+                        originalRequest.headers.Authorization = `Bearer ${this.token}`;
+                        return this.axios(originalRequest);
+                    } catch (refreshError) {
+                        // Token refresh failed, clear state and reject
+                        this.isRefreshingToken = false;
+                        this.tokenRefreshPromise = null;
+                        this.token = null;
+                        return Promise.reject(refreshError);
+                    }
+                }
+
+                return Promise.reject(error);
+            }
+        );
     }
 
     /**
@@ -3557,23 +3683,48 @@ export class CentraliSDK {
     /**
      * Query records with filters, pagination, sorting, and reference expansion.
      *
+     * IMPORTANT: Filters are passed at the TOP LEVEL, not nested under 'filter'.
+     * Use 'data.' prefix for custom fields and bracket notation for operators.
+     *
      * @param recordSlug - The structure's record slug
-     * @param queryParams - Query parameters including filter, sort, pagination, and expand
+     * @param queryParams - Query parameters (filters at top level, plus sort, pagination, expand)
      *
      * @example
-     * // Basic query with filter and sort
+     * // Simple equality filter
+     * const activeProducts = await centrali.queryRecords('Product', {
+     *   'data.status': 'active',
+     *   sort: '-createdAt',
+     *   page: 1,
+     *   pageSize: 10
+     * });
+     *
+     * // Filter with operators (bracket notation)
      * const products = await centrali.queryRecords('Product', {
-     *   filter: 'inStock = true AND price < 100',
+     *   'data.inStock': true,
+     *   'data.price[lte]': 100,
      *   sort: '-createdAt',
-     *   limit: 10
+     *   pageSize: 10
      * });
      *
-     * // Query with expanded references
+     * // Multiple values with 'in' operator (comma-separated string)
      * const orders = await centrali.queryRecords('Order', {
-     *   filter: 'status = "pending"',
+     *   'data.status[in]': 'pending,processing',
      *   expand: 'customer,items'
      * });
      * // Access expanded data: orders.data[0].data._expanded.customer
+     *
+     * // Range filters
+     * const customers = await centrali.queryRecords('Customer', {
+     *   'data.age[gte]': 18,
+     *   'data.age[lte]': 65,
+     *   'data.verified': true
+     * });
+     *
+     * // Filter with 'ne' (not equal)
+     * const availableItems = await centrali.queryRecords('Product', {
+     *   'data.status[ne]': 'discontinued',
+     *   pageSize: 100
+     * });
      */
     public queryRecords<T = any>(
         recordSlug: string,
@@ -3947,11 +4098,11 @@ export class CentraliSDK {
  *
  * // Or set a user token:
  * client.setToken('<JWT_TOKEN>');
- * await client.queryRecords('Product', { limit: 10 });
+ * await client.queryRecords('Product', { pageSize: 10 });
  *
  * // Subscribe to realtime events (Initial Sync Pattern):
- * // 1. First fetch initial data
- * const orders = await client.queryRecords('Order', { filter: 'status = "pending"' });
+ * // 1. First fetch initial data (filters at TOP LEVEL, not nested)
+ * const orders = await client.queryRecords('Order', { 'data.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.2",
   "description": "Centrali Node SDK",
   "main": "dist/index.js",
   "type": "commonjs",