@centrali-io/centrali-sdk 4.4.9 → 4.5.1

package/README.md

@@ -143,12 +143,126 @@ const archived = await centrali.queryRecords('StructureName', {
   includeArchived: true
 });
 
-// Query records
+// Query records with top-level filters
 const products = await centrali.queryRecords('Product', {
-  filter: 'inStock = true AND price < 100',
+  'data.inStock': true,
+  'data.price[lte]': 100,
   sort: '-createdAt',
   limit: 10
 });
+
+// Same query using nested filter object (compute function style)
+const products2 = await centrali.queryRecords('Product', {
+  filter: { 'data.inStock': true, 'data.price': { lte: 100 } },
+  sort: '-createdAt',
+  limit: 10
+});
+```
+
+### Filter Syntax
+
+The SDK supports **two filter styles** — use whichever you prefer:
+
+**Style 1 — Top-level filters** (SDK-native):
+```typescript
+const results = await centrali.queryRecords('Order', {
+  'data.status': 'active',           // Exact match
+  'data.total[gte]': 100,            // Operator with bracket notation
+  'data.tags[hasAny]': 'vip,premium', // Comma-separated for array ops
+  sort: '-createdAt',
+  pageSize: 25
+});
+```
+
+**Style 2 — Nested `filter` object** (same syntax as compute functions):
+```typescript
+const results = await centrali.queryRecords('Order', {
+  filter: {
+    'data.status': 'active',
+    'data.total': { gte: 100 },
+    'data.tags': { hasAny: ['vip', 'premium'] }
+  },
+  sort: '-createdAt',
+  pageSize: 25
+});
+```
+
+Both styles work because the data service merges them. Use `data.` prefix for custom fields. System fields (`id`, `createdAt`, `updatedAt`, `status`) don't need the prefix.
+
+> **Compute functions** use `api.queryRecords()` which has a slightly different interface — sort is an array of objects `[{ field, direction }]` instead of a string, and `searchFields` is an array instead of comma-separated. See the [compute function docs](https://docs.centrali.io/platform/writing-functions) for details.
+
+### Filter Operators
+
+| Operator | SDK (top-level) | SDK (nested) / Compute |
+|----------|----------------|----------------------|
+| Equal | `'data.status': 'active'` | `'data.status': 'active'` or `{ eq: 'active' }` |
+| Not equal | `'data.status[ne]': 'deleted'` | `'data.status': { ne: 'deleted' }` |
+| Greater than | `'data.age[gt]': 18` | `'data.age': { gt: 18 }` |
+| Greater/equal | `'data.age[gte]': 18` | `'data.age': { gte: 18 }` |
+| Less than | `'data.age[lt]': 65` | `'data.age': { lt: 65 }` |
+| Less/equal | `'data.age[lte]': 65` | `'data.age': { lte: 65 }` |
+| In list | `'data.status[in]': 'a,b,c'` | `'data.status': { in: ['a', 'b', 'c'] }` |
+| Not in list | `'data.status[nin]': 'a,b'` | `'data.status': { nin: ['a', 'b'] }` |
+| Contains | `'data.email[contains]': '@gmail'` | `'data.email': { contains: '@gmail' }` |
+| Starts with | `'data.name[startswith]': 'John'` | `'data.name': { startswith: 'John' }` |
+| Ends with | `'data.email[endswith]': '.com'` | `'data.email': { endswith: '.com' }` |
+| Has any (array) | `'data.tags[hasAny]': 'a,b'` | `'data.tags': { hasAny: ['a', 'b'] }` |
+| Has all (array) | `'data.tags[hasAll]': 'a,b'` | `'data.tags': { hasAll: ['a', 'b'] }` |
+
+### Date Range Filtering
+
+Use `dateWindow` to filter records by a date field:
+
+```typescript
+// Records created in the last 30 days
+const recent = await centrali.queryRecords('Order', {
+  dateWindow: {
+    field: 'createdAt',
+    from: new Date(Date.now() - 30 * 86400000).toISOString()
+  }
+});
+
+// Records updated in a specific range
+const q1 = await centrali.queryRecords('Order', {
+  dateWindow: {
+    field: 'updatedAt',
+    from: '2024-01-01T00:00:00Z',
+    to: '2024-03-31T23:59:59Z'
+  }
+});
+```
+
+The `dateWindow` object has three properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `field` | string | Date field to filter on (e.g., `'createdAt'`, `'updatedAt'`, or a custom date field) |
+| `from` | string? | ISO 8601 lower bound (inclusive) |
+| `to` | string? | ISO 8601 upper bound (inclusive) |
+
+### Reserved Query Parameters
+
+When using `queryRecords`, the following parameter names are reserved and cannot be used as filter field names. Any other key you pass is treated as a record data filter.
+
+| Parameter | Purpose |
+|-----------|---------|
+| `page`, `pageSize`, `limit` | Pagination |
+| `sort` | Sorting (string with optional `-` prefix for descending) |
+| `search`, `searchField`, `searchFields` | Full-text search |
+| `filter` | Structured filter object (alternative to top-level filters) |
+| `fields`, `select` | Field selection |
+| `expand` | Reference expansion |
+| `includeDeleted`, `includeArchived`, `all` | Include soft-deleted records |
+| `includeTotal` | Include total count in response |
+| `dateWindow` | Date range filtering (see above) |
+
+To filter by a record field that shares a name with a reserved parameter, use the `data.` prefix:
+
+```typescript
+// Filter by a field called "sort" in your record data
+const results = await centrali.queryRecords('MyStructure', {
+  'data.sort': 'alphabetical'
+});
 ```
 
 ### Expanding References
@@ -541,6 +655,13 @@ const thumbnailUrl = centrali.getFileRenderUrl(renderId, {
 });
 ```
 
+**Audio & video files** are supported up to 500 MB. The storage service supports HTTP range requests (`Accept-Ranges: bytes`), so render URLs work with standard `<audio>` and `<video>` elements — seeking and progressive playback work out of the box:
+
+```html
+<video src={centrali.getFileRenderUrl(renderId)} controls />
+<audio src={centrali.getFileRenderUrl(renderId)} controls />
+```
+
 ### Data Validation
 
 AI-powered data quality validation to detect typos, format issues, duplicates, and semantic errors:

package/index.ts

@@ -845,29 +845,64 @@ export interface FilterOperators {
  */
 export type FilterValue = string | number | boolean | null | FilterOperators;
 
+/**
+ * Date range filter for restricting results to a time window.
+ *
+ * @example
+ * // Records created in the last 30 days
+ * { field: 'createdAt', from: '2024-01-01T00:00:00Z' }
+ *
+ * // Records updated in a specific range
+ * { field: 'updatedAt', from: '2024-01-01T00:00:00Z', to: '2024-03-31T23:59:59Z' }
+ */
+export interface DateWindowOption {
+    /** The date field to filter on (e.g., 'createdAt', 'updatedAt', or a custom date field) */
+    field: string;
+    /** ISO 8601 date string — lower bound (inclusive, gte) */
+    from?: string;
+    /** ISO 8601 date string — upper bound (inclusive, lte) */
+    to?: string;
+}
+
 /**
  * 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.
+ * Supports two filter styles:
  *
- * @example
- * // Simple equality filter
- * { 'data.status': 'active', pageSize: 10 }
+ * **Style 1 — Top-level filters (recommended for SDK):**
+ * Pass filter fields directly as top-level keys with `data.` prefix and bracket notation.
+ * ```ts
+ * { 'data.status': 'active', 'data.price[lte]': 100, pageSize: 10 }
+ * ```
  *
- * // Filter with operators (bracket notation)
- * { 'data.price[lte]': 100, 'data.status[ne]': 'discontinued' }
+ * **Style 2 — Nested filter object (same syntax as compute functions):**
+ * Wrap filters in a `filter` object. Useful if you prefer the same syntax as `api.queryRecords` in compute functions.
+ * ```ts
+ * { filter: { 'data.status': 'active', 'data.price': { lte: 100 } }, pageSize: 10 }
+ * ```
  *
- * // Multiple values with 'in' operator (comma-separated string)
- * { 'data.status[in]': 'pending,processing', pageSize: 50 }
+ * 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.
  *
- * // Range filters
- * { 'data.age[gte]': 18, 'data.age[lte]': 65 }
+ * @example
+ * // Top-level filters with bracket notation
+ * { 'data.status': 'active', 'data.age[gte]': 18, sort: '-createdAt' }
+ *
+ * // Nested filter object
+ * { filter: { 'data.status': 'active', 'data.age': { gte: 18 } }, sort: '-createdAt' }
  *
- * // Filter on top-level record fields (no 'data.' prefix)
- * { 'createdAt[gte]': '2024-01-01', sort: '-createdAt' }
+ * // Date window
+ * { dateWindow: { field: 'createdAt', from: '2024-01-01T00:00:00Z' }, sort: '-createdAt' }
  */
 export interface QueryRecordOptions extends ExpandOptions {
+    /**
+     * Structured filter object. Wrap your field filters here as an alternative to top-level keys.
+     * Uses the same syntax as compute function `api.queryRecords`.
+     *
+     * @example
+     * { filter: { 'data.status': 'active', 'data.age': { gte: 18 } } }
+     */
+    filter?: Record<string, any>;
     /** Sort field with optional direction prefix (e.g., '-createdAt' for descending) */
     sort?: string;
     /** Page number (1-indexed, default: 1) */
@@ -876,16 +911,34 @@ export interface QueryRecordOptions extends ExpandOptions {
     pageSize?: number;
     /** Alias for pageSize */
     limit?: number;
-    /** Include archived (soft-deleted) records */
+    /** Include soft-deleted records */
+    includeDeleted?: boolean;
+    /** Include archived (soft-deleted) records. Alias for includeDeleted. */
     includeArchived?: boolean;
-    /** Include total count in response */
+    /** Shorthand for includeDeleted (from HTTP query params) */
+    all?: boolean;
+    /** Include total count in response metadata */
     includeTotal?: boolean;
     /** Search query string */
     search?: string;
     /** Field(s) to search in (comma-separated or single field) */
     searchField?: string;
+    /** Fields to search in (array format) */
+    searchFields?: string[];
+    /**
+     * Date range filter. Restricts results to records where the specified date field
+     * falls within the given range.
+     *
+     * @example
+     * { dateWindow: { field: 'createdAt', from: '2024-01-01T00:00:00Z', to: '2024-12-31T23:59:59Z' } }
+     */
+    dateWindow?: DateWindowOption;
+    /** Comma-separated fields to return (field selection) */
+    fields?: string;
+    /** Field selection (alias for fields) */
+    select?: string[];
     /**
-     * Filter fields - pass at TOP LEVEL with 'data.' prefix for custom fields.
+     * Additional 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

package/package.json

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