@taruvi/sdk 1.4.9 → 1.5.0-beta.1

package/.claude/settings.local.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree:*)",
+      "Bash(npm run build:*)",
+      "Bash(npm ls:*)",
+      "Bash(npm link:*)",
+      "Bash(npx --yes markdownlint-cli:*)",
+      "Bash(cat:*)",
+      "Bash(test:*)",
+      "Bash(ls:*)",
+      "WebFetch(domain:www.markdownpaste.com)",
+      "WebSearch",
+      "WebFetch(domain:supabase.com)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/README.md

@@ -17,7 +17,7 @@ Recent updates to the SDK:
 - **App Service**: New service to retrieve app roles with `roles()` method.
 - **User Types**: Added `UserCreateRequest`, `UserResponse`, and `UserDataResponse` types for user management.
 - **Auth Service**: Web UI Flow with `login()`, `signup()`, `logout()` methods that redirect to backend pages. Token refresh with rotation support, `getCurrentUser()` for JWT decoding.
-- **Database Service**: Added `create()` method for creating records. Added `populate()` method for eager loading related records. Comprehensive filter support with Django-style operators (`__gte`, `__lte`, `__icontains`, etc.).
+- **Database Service**: Added `create()` method for creating records. Added `populate()` method for eager loading related records. Comprehensive filter support with Django-style operators (`__gte`, `__lte`, `__icontains`, etc.). Use **`orderBy()`** for sorting: one field (`orderBy('created_at', 'desc')`), multiple fields (`orderBy([{ field, order }])`), or a raw `ordering` string (`orderBy('-salary,hire_date')`). Hierarchy traversal uses **`.include('descendants' | 'ancestors' | 'both')`** — not `FilterOperator`. Import **`PgRangeValue`** for typed PG range columns in row data.
 - **Storage Service**: Added `download()` method. Enhanced filter support with size, date, MIME type, visibility filters. `delete()` now accepts array of paths for bulk deletion.
 - **Client**: Automatic token extraction from URL hash after OAuth callback - no manual token handling needed.
 - **Types**: Comprehensive `StorageFilters` and `DatabaseFilters` interfaces with full operator support.
@@ -363,43 +363,52 @@ const db = new Database(taruviClient)
 await db.from("accounts").delete("record-id").execute()
 ```
 
-### Filter Records
+### Filter records
+
+`Database` supports **DRF-style flat filters** (`filters(field, operator, value)`) and a **JSON filter tree** sent as the `filters` query param (`filters(tree)`).
 
 ```typescript
 const db = new Database(taruviClient)
 
-// Simple field filters
+// Flat: one condition per call (chain for AND)
 const filtered = await db
   .from("accounts")
-  .filter({
-    status: "active",
-    country: "USA"
-  })
+  .filters("status", "eq", "active")
+  .filters("country", "eq", "USA")
   .execute()
 
-// Advanced filters with operators
+// Flat: operators map to `field__suffix` query keys
 const advanced = await db
   .from("accounts")
-  .filter({
-    age__gte: 18,           // age >= 18
-    age__lt: 65,            // age < 65
-    name__icontains: "john", // case-insensitive contains
-    created_at__gte: "2024-01-01",
-    ordering: "-created_at"  // Sort by created_at descending
-  })
+  .filters("age", "gte", 18)
+  .filters("age", "lt", 65)
+  .filters("name", "icontains", "john")
+  .filters("created_at", "gte", "2024-01-01")
+  .orderBy("created_at", "desc")
   .execute()
 
-// Pagination
+// Pagination (separate methods)
 const paginated = await db
   .from("accounts")
-  .filter({
-    page: 1,
-    pageSize: 20
-  })
+  .page(1)
+  .pageSize(20)
   .execute()
+
+// JSON tree → `?filters=<url-encoded JSON>` (e.g. from Refine / your UI)
+import type { BackendFilterTreeRoot } from "@taruvi/sdk"
+const tree: BackendFilterTreeRoot = [
+  {
+    operator: "and",
+    value: [
+      { field: "is_active", operator: "eq", value: true },
+      { field: "hire_date", operator: "lt", value: "2021-01-01" },
+    ],
+  },
+]
+await db.from("employees").filters(tree).execute()
 ```
 
-### Populate Related Records
+### Populate related records
 
 Use `populate()` to eager load related records (foreign key relationships):
 
@@ -422,21 +431,20 @@ const invoices = await db
   .populate(["customer", "created_by", "items"])
   .execute()
 
-// Combine with filters
+// Combine with flat filters + populate
 const recentOrders = await db
   .from("orders")
-  .filter({
-    status: "completed",
-    created_at__gte: "2024-01-01",
-    ordering: "-created_at"
-  })
+  .filters("status", "eq", "completed")
+  .filters("created_at", "gte", "2024-01-01")
+  .orderBy("created_at", "desc")
   .populate(["customer", "product"])
   .execute()
 
-// Combine with pagination
+// Combine with pagination + populate
 const paginatedOrders = await db
   .from("orders")
-  .filter({ page: 1, pageSize: 10 })
+  .page(1)
+  .pageSize(10)
   .populate(["customer"])
   .execute()
 ```
@@ -1285,8 +1293,8 @@ All query-building services use method chaining:
 // Database
 const db = new Database(taruviClient)
 await db.from("table").get("id").update(data).execute()
-await db.from("table").filter({ status: "active" }).execute()
-await db.from("table").filter({ page: 1 }).populate(["related_field"]).execute()
+await db.from("table").filters("status", "eq", "active").execute()
+await db.from("table").page(1).populate(["related_field"]).execute()
 await db.from("table").create({ name: "New" }).execute()
 
 // Storage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taruvi/sdk",
-  "version": "1.4.9",
+  "version": "1.5.0-beta.1",
   "description": "Taruvi SDK",
   "main": "src/index.ts",
   "type": "module",

package/src/client.ts

@@ -1,5 +1,5 @@
 import { HttpClient } from "./lib-internal/http/HttpClient.js";
-import { TokenClient, type AuthTokens } from "./lib-internal/token/TokenClient.js";
+import { TokenClient } from "./lib-internal/token/TokenClient.js";
 import type { TaruviConfig } from "./types.js";
 import packageJson from "../package.json" with { type: "json" };
 

package/src/index.ts

@@ -35,7 +35,8 @@ export type { RoleData, AppSettingsData, RoleResponse, RolesListResponse, AppSet
 export type { FunctionRequest, FunctionResponse, FunctionInvocation } from "./lib/functions/types.js"
 
 // Database types
-export type { DatabaseRequest, DatabaseResponse, DatabaseSingleResponse, FilterOperator, SortOrder, GraphInclude, GraphFormat, EdgeRequest, EdgeResponse, EdgeDeleteRequest } from "./lib/database/types.js"
+export type { DatabaseRequest, DatabaseResponse, DatabaseSingleResponse, FilterOperator, SortOrder, GraphInclude, GraphFormat, EdgeRequest, EdgeResponse, EdgeDeleteRequest, PgRangeValue, BackendFilterLeafNode, BackendFilterLogicalNode, BackendFilterNode, BackendFilterTreeRoot } from "./lib/database/types.js"
+export { isBackendFilterTreeRoot } from "./lib/database/types.js"
 
 // Storage types
 export type { StorageRequest, StorageUpdateRequest, StorageObject, StorageResponse, StorageListResponse, StorageUploadBatchResponse, StorageDeleteBatchResponse } from "./lib/storage/types.js"

package/src/lib/auth/AuthClient.ts

@@ -1,7 +1,6 @@
 import type { Client } from "../../client.js";
 import type { TaruviResponse } from "../../types.js";
 import type { UserData } from "../users/types.js";
-import { AuthRoutes } from "../../lib-internal/routes/AuthRoutes.js";
 import { UserRoutes } from "../../lib-internal/routes/UserRoutes.js";
 
 /**
@@ -95,33 +94,12 @@ export class Auth {
     }
 
     /**
-     * Check if a session token exists locally (does not validate with server)
+     * Check if user is authenticated (has session token)
      */
-    hasToken(): boolean {
+    isUserAuthenticated(): boolean {
         return this.client.tokenClient.isAuthenticated()
     }
 
-    /**
-     * Check if user is authenticated by validating session with the server
-     */
-    async isUserAuthenticated(): Promise<boolean> {
-        if (!this.hasToken()) return false
-        try {
-            await this.validateSession()
-            return true
-        } catch {
-            return false
-        }
-    }
-
-    /**
-     * Validate current session token with auth session endpoint.
-     * HttpClient injects X-Session-Token automatically.
-     */
-    async validateSession(): Promise<void> {
-        await this.client.httpClient.get(AuthRoutes.session())
-    }
-
     /**
      * Get the current session token
      */
@@ -134,7 +112,7 @@ export class Auth {
      * @returns Promise with user data or null if not authenticated
      */
     async getCurrentUser(): Promise<TaruviResponse<UserData> | null> {
-        if (!this.hasToken()) {
+        if (!this.isUserAuthenticated()) {
             return null
         }
 

package/src/lib/database/DatabaseClient.ts

@@ -2,7 +2,8 @@ import type { Client } from "../../client.js";
 import { DatabaseRoutes } from "../../lib-internal/routes/DatabaseRoutes.js";
 import { HttpMethod } from "../../lib-internal/http/types.js";
 import type { TaruviConfig, DatabaseFilters, TaruviResponse } from "../../types.js";
-import type { UrlParams, FilterOperator, SortOrder, GraphInclude, GraphFormat, EdgeRequest, EdgeDeleteRequest } from "./types.js";
+import type { UrlParams, FilterOperator, SortOrder, GraphInclude, GraphFormat, EdgeRequest, EdgeDeleteRequest, BackendFilterTreeRoot } from "./types.js";
+import { isBackendFilterTreeRoot } from "./types.js";
 import { buildQueryString } from "../../utils/utils.js";
 
 interface GraphQueryParams {
@@ -62,17 +63,65 @@ export class Database<T = Record<string, unknown>> {
     }
 
     // Filter & query methods
-    filter(field: string, operator: FilterOperator, value: string | number | boolean | (string | number)[]): Database<T> {
-        const filterKey = operator === 'eq' ? field : `${field}__${operator}`
-        const filterValue = Array.isArray(value) ? value.join(',') : value
-        return new Database<T>(this.client, { ...this.urlParams }, undefined, undefined, {
-            ...this.queryParams,
-            [filterKey]: filterValue
-        }, { ...this.graphParams }, this.isEdges)
+    /**
+     * JSON filter tree for the `filters` query param. Must match the platform contract:
+     * root is an array of logical nodes `{ operator: "and" | "or", value: [...] }`; leaves are
+     * `{ field, operator, value }` where `operator` is a **backend** token (`contains` = case-insensitive
+     * substring, `containss` = case-sensitive, `eq`, `in`, …). The SDK only JSON-stringifies this value.
+     */
+    filters(tree: BackendFilterTreeRoot): Database<T>
+    /**
+     * DRF-style flat filter: `field` or `field__operator` query keys.
+     */
+    filters(field: string, operator: FilterOperator, value: string | number | boolean | (string | number | boolean)[]): Database<T>
+    filters(
+        arg0: string | BackendFilterTreeRoot,
+        arg1?: FilterOperator,
+        arg2?: string | number | boolean | (string | number | boolean)[]
+    ): Database<T> {
+        if (typeof arg0 === 'string' && arg1 !== undefined && arg2 !== undefined) {
+            const field = arg0
+            const operator = arg1
+            const value = arg2
+            const filterKey = operator === 'eq' ? field : `${field}__${operator}`
+            const filterValue = Array.isArray(value) ? value.join(',') : value
+            return new Database<T>(this.client, { ...this.urlParams }, undefined, undefined, {
+                ...this.queryParams,
+                [filterKey]: filterValue
+            }, { ...this.graphParams }, this.isEdges)
+        }
+
+        if (arg1 === undefined && arg2 === undefined && isBackendFilterTreeRoot(arg0)) {
+            return new Database<T>(this.client, { ...this.urlParams }, undefined, undefined, {
+                ...this.queryParams,
+                filters: JSON.stringify(arg0)
+            }, { ...this.graphParams }, this.isEdges)
+        }
+
+        throw new TypeError(
+            'Database.filters: use filters(tree) with a root array of { operator: "and"|"or", value: [...] }, or filters(field, operator, value).'
+        )
     }
 
-    sort(field: string, order: SortOrder = 'asc'): Database<T> {
-        const ordering = order === 'desc' ? `-${field}` : field
+    /**
+     * Sets the `ordering` query param (DRF-style: `-field` for desc, comma-separated for multiple).
+     * - `orderBy('created_at', 'desc')` — one column (optional second arg defaults to `'asc'`)
+     * - `orderBy([{ field: 'salary', order: 'desc' }, { field: 'hire_date' }])` — multiple columns
+     * - `orderBy('-salary,hire_date')` — raw string (e.g. from `convertRefineSorters`); omit the second arg
+     */
+    orderBy(
+        fieldOrFields: string | Array<{ field: string; order?: SortOrder }>,
+        order?: SortOrder
+    ): Database<T> {
+        let ordering: string
+        if (typeof fieldOrFields === 'string') {
+            const o = order ?? 'asc'
+            ordering = o === 'desc' ? `-${fieldOrFields}` : fieldOrFields
+        } else {
+            ordering = fieldOrFields
+                .map(({ field, order: o = 'asc' }) => (o === 'desc' ? `-${field}` : field))
+                .join(',')
+        }
         return new Database<T>(this.client, { ...this.urlParams }, undefined, undefined, {
             ...this.queryParams,
             ordering
@@ -100,6 +149,11 @@ export class Database<T = Record<string, unknown>> {
         }, { ...this.graphParams }, this.isEdges)
     }
 
+    /** Populate all first-level relations (`?populate=*`). */
+    populateAll(): Database<T> {
+        return this.populate(['*'])
+    }
+
     search(query: string): Database<T> {
         return new Database<T>(this.client, { ...this.urlParams }, undefined, undefined, {
             ...this.queryParams,
@@ -107,6 +161,14 @@ export class Database<T = Record<string, unknown>> {
         }, { ...this.graphParams }, this.isEdges)
     }
 
+    /** Restrict SELECT to named columns (`?fields=a,b,c`). */
+    fields(columns: string): Database<T> {
+        return new Database<T>(this.client, { ...this.urlParams }, undefined, undefined, {
+            ...this.queryParams,
+            fields: columns
+        }, { ...this.graphParams }, this.isEdges)
+    }
+
     allowedActions(actions: string[]): Database<T> {
         return new Database<T>(this.client, { ...this.urlParams }, undefined, undefined, {
             ...this.queryParams,

package/src/lib/database/types.ts

@@ -4,7 +4,7 @@ import type { TaruviResponse } from "../../types.js"
 
 export type DatabaseOperation = HttpMethod
 
-// Filter operators matching backend FilterParams.OPERATORS (32 operators)
+// Filter operators matching backend FilterParams.OPERATORS
 export type FilterOperator =
     // Comparison
     | 'eq'           // Equal
@@ -18,29 +18,49 @@ export type FilterOperator =
     | 'nin'          // Not in array
     | 'ina'          // In array (case-insensitive)
     | 'nina'         // Not in array (case-insensitive)
-    // String contains
-    | 'contains'     // Contains (case-sensitive)
-    | 'ncontains'    // Not contains (case-sensitive)
-    | 'containss'    // Contains (case-sensitive, strict)
-    | 'ncontainss'   // Not contains (case-sensitive, strict)
-    | 'icontains'    // Contains (case-insensitive)
-    | 'nicontains'   // Not contains (case-insensitive)
+    // String contains (backend: plain contains uses ILIKE; *s suffix = case-sensitive LIKE)
+    | 'contains'     // Contains (case-insensitive, ILIKE)
+    | 'ncontains'    // Not contains (case-insensitive)
+    | 'containss'    // Contains (case-sensitive LIKE)
+    | 'ncontainss'   // Not contains (case-sensitive LIKE)
+    | 'icontains'    // Alias → contains (case-insensitive)
+    | 'nicontains'   // Alias → ncontains
     // Starts with
-    | 'startswith'   // Starts with (case-sensitive)
-    | 'nstartswith'  // Not starts with (case-sensitive)
-    | 'startswiths'  // Starts with (case-sensitive, strict)
-    | 'nstartswiths' // Not starts with (case-sensitive, strict)
+    | 'startswith'   // Starts with (case-insensitive)
+    | 'nstartswith'  // Not starts with (case-insensitive)
+    | 'startswiths'  // Starts with (case-sensitive LIKE)
+    | 'nstartswiths' // Not starts with (case-sensitive LIKE)
     // Ends with
-    | 'endswith'     // Ends with (case-sensitive)
-    | 'nendswith'    // Not ends with (case-sensitive)
-    | 'endswiths'    // Ends with (case-sensitive, strict)
-    | 'nendswiths'   // Not ends with (case-sensitive, strict)
+    | 'endswith'     // Ends with (case-insensitive)
+    | 'nendswith'    // Not ends with (case-insensitive)
+    | 'endswiths'    // Ends with (case-sensitive LIKE)
+    | 'nendswiths'   // Not ends with (case-sensitive LIKE)
     // Range
     | 'between'      // Between two values
     | 'nbetween'     // Not between two values
     // Null checks
     | 'null'         // Is null
     | 'nnull'        // Is not null
+    // Search / pattern
+    | 'search'       // Full-text search
+    | 'like'         // SQL LIKE pattern
+    | 'ilike'        // Case-insensitive LIKE
+    // Array containment (PostgreSQL)
+    | 'acontains'      // Array contains all items (column @> ARRAY[values])
+    | 'nacontains'     // NOT array contains
+    | 'acontainedby'   // Array contained by (column <@ ARRAY[values])
+    | 'nacontainedby'  // NOT array contained by
+    | 'aoverlap'       // Arrays have overlap (column && ARRAY[values])
+    | 'naoverlap'      // No overlap
+    | 'aelement'       // Value exists in array (value = ANY(column))
+    | 'naelement'      // Value not in array (value != ALL(column))
+    // PostgreSQL range type operators
+    | 'rcontains'      // Range column @> value or [lower, upper]
+    | 'rcontainedby'   // Range column <@ [lower, upper]
+    | 'roverlaps'      // Range column && [lower, upper]
+    | 'radjacent'      // Range column -|- [lower, upper]
+    | 'rstrictleft'    // Range column << [lower, upper]
+    | 'rstrictright'   // Range column >> [lower, upper]
 
 export type SortOrder = 'asc' | 'desc'
 
@@ -87,4 +107,50 @@ export interface EdgeResponse {
 
 export interface EdgeDeleteRequest {
     edge_ids: number[]
+}
+
+export interface PgRangeValue {
+    lower: string | number | null
+    upper: string | number | null
+    bounds: '()' | '(]' | '[)' | '[]'
+    empty: boolean
+}
+
+/**
+ * Leaf node for the backend `filters` JSON query param.
+ * Leaf `operator` strings are platform tokens (see taruvi-platform `FIELD_OPERATORS` /
+ * `filter_translator`). `contains` = case-insensitive substring; `containss` = case-sensitive.
+ */
+export interface BackendFilterLeafNode {
+    field: string
+    operator: string
+    value: unknown
+}
+
+/** Logical `and` / `or` group for the backend `filters` JSON query param. */
+export interface BackendFilterLogicalNode {
+    operator: 'and' | 'or'
+    value: BackendFilterNode[]
+}
+
+export type BackendFilterNode = BackendFilterLogicalNode | BackendFilterLeafNode
+
+/** Top level of the `filters` JSON payload: an array of logical nodes. */
+export type BackendFilterTreeRoot = BackendFilterLogicalNode[]
+
+function isPlainObject(x: unknown): x is Record<string, unknown> {
+    return typeof x === 'object' && x !== null && !Array.isArray(x)
+}
+
+function isBackendFilterLogicalNode(x: unknown): x is BackendFilterLogicalNode {
+    if (!isPlainObject(x)) return false
+    if (x.operator !== 'and' && x.operator !== 'or') return false
+    if (!Array.isArray(x.value)) return false
+    if ('field' in x) return false
+    return true
+}
+
+/** Runtime check for the single-arg `filters(tree)` overload. */
+export function isBackendFilterTreeRoot(x: unknown): x is BackendFilterTreeRoot {
+    return Array.isArray(x) && x.every(isBackendFilterLogicalNode)
 }

package/src/lib-internal/http/HttpClient.ts

@@ -12,12 +12,10 @@ import type { ErrorResponseBody } from "../errors/index.js";
  * @internal
  */
 export class HttpClient {
-    private config: TaruviConfig
     private tokenClient: TokenClient
     private axiosInstance: AxiosInstance
 
     constructor(config: TaruviConfig, tokenClient: TokenClient) {
-        this.config = config
         this.tokenClient = tokenClient
         this.axiosInstance = axios.create({ baseURL: config.apiUrl, withCredentials: true })
         this.setupInterceptors()
@@ -25,6 +23,7 @@ export class HttpClient {
 
     private setupInterceptors(): void {
         // Request interceptor: attach session token
+        console.log("test")
         this.axiosInstance.interceptors.request.use((config: InternalAxiosRequestConfig) => {
             const isFormData = config.data instanceof FormData
             if (!isFormData) {

package/src/lib-internal/routes/AuthRoutes.ts

@@ -1,3 +0,0 @@
-export const AuthRoutes = {
-    session: () => "_allauth/app/v1/auth/session"
-} as const

package/src/types.ts

@@ -93,6 +93,12 @@ export interface DatabaseFilters {
     _group_by?: string
     _having?: string
 
+    /**
+     * JSON filter tree for the `filters` query param (set via `Database.filters(tree)`).
+     * Do not use the flat `filters(field, …)` triple overload with `field === 'filters'`.
+     */
+    filters?: string
+
     // Dynamic filters - allows any field with operators
     [key: string]: string | number | boolean | undefined
 }

package/src/utils/utils.ts

@@ -18,6 +18,7 @@ export const getRuntimeEnvironment = (): string => {
     return 'Server'
 }
 
+/** Builds a query string. Keys may include pre-flattened bracket names (e.g. CrudFilters `filters[0][field]=...`). */
 export function buildQueryString(queryParams: Record<string, unknown> | undefined): string {
     if (!queryParams || Object.keys(queryParams).length === 0) {
         return ''

package/tests/unit/database/DatabaseClient.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
 import { Database } from '../../../src/lib/database/DatabaseClient.js'
 import { Client } from '../../../src/client.js'
-import type { DatabaseResponse, DatabaseSingleResponse, EdgeResponse } from '../../../src/lib/database/types.js'
+import type { BackendFilterTreeRoot, DatabaseResponse, DatabaseSingleResponse, EdgeResponse } from '../../../src/lib/database/types.js'
 import type { TaruviResponse } from '../../../src/types.js'
 
 // Mock the Client
@@ -30,61 +30,61 @@ describe('Database', () => {
         })
     })
 
-    describe('filter()', () => {
+    describe('filters() flat (triple-arg)', () => {
         it('eq operator uses field name without suffix', async () => {
             mockHttpClient.get.mockResolvedValue([])
-            await new Database(mockClient).from('accounts').filter('status', 'eq', 'active').execute()
+            await new Database(mockClient).from('accounts').filters('status', 'eq', 'active').execute()
             expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('status=active'))
         })
 
         it('gt operator appends __gt suffix', async () => {
             mockHttpClient.get.mockResolvedValue([])
-            await new Database(mockClient).from('accounts').filter('age', 'gt', 18).execute()
+            await new Database(mockClient).from('accounts').filters('age', 'gt', 18).execute()
             expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('age__gt=18'))
         })
 
         it('gte operator appends __gte suffix', async () => {
             mockHttpClient.get.mockResolvedValue([])
-            await new Database(mockClient).from('accounts').filter('age', 'gte', 18).execute()
+            await new Database(mockClient).from('accounts').filters('age', 'gte', 18).execute()
             expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('age__gte=18'))
         })
 
         it('lt operator appends __lt suffix', async () => {
             mockHttpClient.get.mockResolvedValue([])
-            await new Database(mockClient).from('accounts').filter('age', 'lt', 65).execute()
+            await new Database(mockClient).from('accounts').filters('age', 'lt', 65).execute()
             expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('age__lt=65'))
         })
 
         it('lte operator appends __lte suffix', async () => {
             mockHttpClient.get.mockResolvedValue([])
-            await new Database(mockClient).from('accounts').filter('age', 'lte', 65).execute()
+            await new Database(mockClient).from('accounts').filters('age', 'lte', 65).execute()
             expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('age__lte=65'))
         })
 
         it('icontains operator appends __icontains suffix', async () => {
             mockHttpClient.get.mockResolvedValue([])
-            await new Database(mockClient).from('accounts').filter('name', 'icontains', 'john').execute()
+            await new Database(mockClient).from('accounts').filters('name', 'icontains', 'john').execute()
             expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('name__icontains=john'))
         })
 
         it('in operator joins array values with comma', async () => {
             mockHttpClient.get.mockResolvedValue([])
-            await new Database(mockClient).from('accounts').filter('status', 'in', ['active', 'pending']).execute()
+            await new Database(mockClient).from('accounts').filters('status', 'in', ['active', 'pending']).execute()
             expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('status__in=active%2Cpending'))
         })
 
-        it('isnull operator appends __isnull suffix', async () => {
+        it('null operator appends __null suffix', async () => {
             mockHttpClient.get.mockResolvedValue([])
-            await new Database(mockClient).from('accounts').filter('deleted_at', 'isnull', true).execute()
-            expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('deleted_at__isnull=true'))
+            await new Database(mockClient).from('accounts').filters('deleted_at', 'null', true).execute()
+            expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('deleted_at__null=true'))
         })
 
         it('multiple filters chain correctly', async () => {
             mockHttpClient.get.mockResolvedValue([])
             await new Database(mockClient)
                 .from('accounts')
-                .filter('status', 'eq', 'active')
-                .filter('age', 'gte', 18)
+                .filters('status', 'eq', 'active')
+                .filters('age', 'gte', 18)
                 .execute()
             const url = mockHttpClient.get.mock.calls[0][0]
             expect(url).toContain('status=active')
@@ -92,24 +92,105 @@ describe('Database', () => {
         })
     })
 
-    describe('sort()', () => {
+    describe('filters() JSON tree', () => {
+        const normativeTree: BackendFilterTreeRoot = [
+            {
+                operator: 'and',
+                value: [
+                    { field: 'is_active', operator: 'eq', value: true },
+                    { field: 'hire_date', operator: 'lt', value: '2021-01-01' },
+                    {
+                        operator: 'or',
+                        value: [
+                            { field: 'salary', operator: 'gte', value: 200000 },
+                            {
+                                operator: 'and',
+                                value: [
+                                    { field: 'title', operator: 'containss', value: 'VP' },
+                                    { field: 'bonus', operator: 'gte', value: 50000 },
+                                ],
+                            },
+                        ],
+                    },
+                ],
+            },
+        ]
+
+        it('serializes tree into filters query param (round-trip)', async () => {
+            mockHttpClient.get.mockResolvedValue([])
+            await new Database(mockClient).from('accounts').filters(normativeTree).execute()
+            const url = mockHttpClient.get.mock.calls[0][0] as string
+            const q = url.includes('?') ? url.split('?')[1] : ''
+            const params = new URLSearchParams(q)
+            const raw = params.get('filters')
+            expect(raw).toBeTruthy()
+            expect(JSON.parse(decodeURIComponent(raw!))).toEqual(normativeTree)
+        })
+
+        it('chains JSON filters with populate', async () => {
+            mockHttpClient.get.mockResolvedValue([])
+            await new Database(mockClient)
+                .from('accounts')
+                .filters(normativeTree)
+                .populate(['customer'])
+                .execute()
+            const url = mockHttpClient.get.mock.calls[0][0] as string
+            expect(url).toContain('populate=customer')
+            const q = url.split('?')[1]
+            expect(new URLSearchParams(q).get('filters')).toBeTruthy()
+        })
+    })
+
+    describe('orderBy()', () => {
         it('asc order uses field name without prefix', async () => {
             mockHttpClient.get.mockResolvedValue([])
-            await new Database(mockClient).from('accounts').sort('created_at', 'asc').execute()
+            await new Database(mockClient).from('accounts').orderBy('created_at', 'asc').execute()
             expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('ordering=created_at'))
         })
 
         it('desc order adds - prefix', async () => {
             mockHttpClient.get.mockResolvedValue([])
-            await new Database(mockClient).from('accounts').sort('created_at', 'desc').execute()
+            await new Database(mockClient).from('accounts').orderBy('created_at', 'desc').execute()
             expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('ordering=-created_at'))
         })
 
         it('defaults to asc when order not specified', async () => {
             mockHttpClient.get.mockResolvedValue([])
-            await new Database(mockClient).from('accounts').sort('name').execute()
+            await new Database(mockClient).from('accounts').orderBy('name').execute()
             expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringMatching(/ordering=name(?!-)/))
         })
+
+        it('comma-joins multiple fields from array (mixed asc/desc)', async () => {
+            mockHttpClient.get.mockResolvedValue([])
+            await new Database(mockClient)
+                .from('accounts')
+                .orderBy([
+                    { field: 'salary', order: 'desc' },
+                    { field: 'hire_date', order: 'asc' },
+                ])
+                .execute()
+            expect(mockHttpClient.get).toHaveBeenCalledWith(
+                expect.stringContaining('ordering=-salary%2Chire_date')
+            )
+        })
+
+        it('accepts pre-built ordering string', async () => {
+            mockHttpClient.get.mockResolvedValue([])
+            await new Database(mockClient).from('accounts').orderBy('-a,b').execute()
+            expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('ordering=-a%2Cb'))
+        })
+
+        it('chains with filters without dropping ordering', async () => {
+            mockHttpClient.get.mockResolvedValue([])
+            await new Database(mockClient)
+                .from('accounts')
+                .filters('status', 'eq', 'active')
+                .orderBy([{ field: 'name', order: 'asc' }])
+                .execute()
+            const url = mockHttpClient.get.mock.calls[0][0] as string
+            expect(url).toContain('status=active')
+            expect(url).toContain('ordering=name')
+        })
     })
 
     describe('pagination', () => {
@@ -132,6 +213,12 @@ describe('Database', () => {
             await new Database(mockClient).from('orders').populate(['customer', 'items']).execute()
             expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('populate=customer%2Citems'))
         })
+
+        it('populateAll sets wildcard populate', async () => {
+            mockHttpClient.get.mockResolvedValue([])
+            await new Database(mockClient).from('orders').populateAll().execute()
+            expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('populate=*'))
+        })
     })
 
     describe('CRUD operations', () => {
@@ -232,7 +319,7 @@ describe('Database', () => {
             mockHttpClient.get.mockResolvedValue([])
             await new Database(mockClient)
                 .from('accounts')
-                .filter('status', 'eq', 'active')
+                .filters('status', 'eq', 'active')
                 .page(1)
                 .pageSize(10)
                 .execute()
@@ -486,7 +573,7 @@ describe('Database', () => {
     describe('deleteFiltered()', () => {
         it('calls httpClient.delete with filter params in query string', async () => {
             mockHttpClient.delete.mockResolvedValue({ status: 'success' })
-            await new Database(mockClient).from('accounts').filter('status', 'eq', 'inactive').deleteFiltered().execute()
+            await new Database(mockClient).from('accounts').filters('status', 'eq', 'inactive').deleteFiltered().execute()
             const url = mockHttpClient.delete.mock.calls[0][0]
             expect(url).toContain('status=inactive')
             expect(url).not.toContain('/undefined/')
@@ -494,7 +581,7 @@ describe('Database', () => {
 
         it('hits collection endpoint without recordId', async () => {
             mockHttpClient.delete.mockResolvedValue({ status: 'success' })
-            await new Database(mockClient).from('accounts').filter('age', 'lt', 18).deleteFiltered().execute()
+            await new Database(mockClient).from('accounts').filters('age', 'lt', 18).deleteFiltered().execute()
             expect(mockHttpClient.delete).toHaveBeenCalledWith(
                 expect.stringContaining('api/apps/test-app/datatables/accounts/data/?')
             )

package/tests/unit/edge-cases/robustness.test.ts

@@ -100,26 +100,26 @@ describe('Encoding edge cases', () => {
 
     it('encodes filter value with spaces', async () => {
         mockHttpClient.get.mockResolvedValue([])
-        await new Database(mockClient).from('accounts').filter('name', 'eq', 'John Doe').execute()
+        await new Database(mockClient).from('accounts').filters('name', 'eq', 'John Doe').execute()
         expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('name=John+Doe'))
     })
 
     it('encodes filter value with special characters', async () => {
         mockHttpClient.get.mockResolvedValue([])
-        await new Database(mockClient).from('accounts').filter('email', 'eq', 'user@example.com').execute()
+        await new Database(mockClient).from('accounts').filters('email', 'eq', 'user@example.com').execute()
         expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('email=user%40example.com'))
     })
 
     it('encodes filter value with ampersand', async () => {
         mockHttpClient.get.mockResolvedValue([])
-        await new Database(mockClient).from('accounts').filter('company', 'eq', 'A&B Corp').execute()
+        await new Database(mockClient).from('accounts').filters('company', 'eq', 'A&B Corp').execute()
         const url = mockHttpClient.get.mock.calls[0][0]
         expect(url).toContain('company=A%26B')
     })
 
     it('handles unicode in filter values', async () => {
         mockHttpClient.get.mockResolvedValue([])
-        await new Database(mockClient).from('accounts').filter('name', 'icontains', '日本語').execute()
+        await new Database(mockClient).from('accounts').filters('name', 'icontains', '日本語').execute()
         expect(mockHttpClient.get).toHaveBeenCalledWith(expect.stringContaining('name__icontains='))
     })
 
@@ -137,7 +137,7 @@ describe('Encoding edge cases', () => {
 
     it('handles empty string filter value', async () => {
         mockHttpClient.get.mockResolvedValue([])
-        await new Database(mockClient).from('accounts').filter('status', 'eq', '').execute()
+        await new Database(mockClient).from('accounts').filters('status', 'eq', '').execute()
         const url = mockHttpClient.get.mock.calls[0][0]
         expect(url).toContain('status=')
     })
@@ -149,8 +149,8 @@ describe('Builder immutability', () => {
     it('Database: chaining does not mutate original instance', async () => {
         mockHttpClient.get.mockResolvedValue([])
         const base = new Database(mockClient).from('accounts')
-        const filtered = base.filter('status', 'eq', 'active')
-        const sorted = base.sort('name', 'asc')
+        const filtered = base.filters('status', 'eq', 'active')
+        const sorted = base.orderBy('name', 'asc')
 
         await filtered.execute()
         const filteredUrl = mockHttpClient.get.mock.calls[0][0]