@objectstack/client 3.3.0 → 4.0.0

package/src/client.hono.test.ts

@@ -52,14 +52,14 @@ describe('ObjectStackClient (with Hono Server)', () => {
                         if (protocol) {
                             return await protocol.findData({ object: params.object, query: params.query || params.filters });
                         }
-                        const records = await ql.find(params.object, { filter: params.filters });
+                        const records = await ql.find(params.object, { where: params.filters });
                         return { object: params.object, records, total: records.length };
                     }
                     if (method === 'find') {
                         if (protocol) {
                             return await protocol.findData({ object: params.object, query: params.query || params.filters });
                         }
-                        const records = await ql.find(params.object, { filter: params.filters });
+                        const records = await ql.find(params.object, { where: params.filters });
                         return { object: params.object, records, total: records.length };
                     }
                 }

package/src/client.msw.test.ts

@@ -57,7 +57,7 @@ describe('ObjectStackClient (with MSW Plugin)', () => {
                             return await protocol.findData({ object: params.object, query: params.query });
                         }
                         const queryOpts = params.query || {};
-                        const records = await ql.find(params.object, { filter: queryOpts.filters || queryOpts.filter });
+                        const records = await ql.find(params.object, { where: queryOpts.filters || queryOpts.filter || queryOpts.where });
                         return { object: params.object, records, total: records.length };
                     }
                     if (method === 'find') {
@@ -65,7 +65,7 @@ describe('ObjectStackClient (with MSW Plugin)', () => {
                             return await protocol.findData({ object: params.object, query: params.query });
                         }
                         const queryOpts = params.query || {};
-                        const records = await ql.find(params.object, { filter: queryOpts.filters || queryOpts.filter });
+                        const records = await ql.find(params.object, { where: queryOpts.filters || queryOpts.filter || queryOpts.where });
                         return { object: params.object, records, total: records.length };
                     }
                 }

package/src/client.test.ts

@@ -827,3 +827,73 @@ describe('ObjectStackClient.automation', () => {
         expect(client.capabilities!.search).toBe(true);
     });
 });
+
+// ==========================================
+// QueryOptionsV2 (Canonical Query Syntax) Tests
+// ==========================================
+
+describe('QueryOptionsV2 — canonical find()', () => {
+    it('should accept canonical field names (where, fields, orderBy, limit, offset)', async () => {
+        const { client, fetchMock } = createMockClient({
+            success: true,
+            data: { object: 'account', records: [], total: 0 }
+        });
+
+        await client.data.find('account', {
+            where: { status: 'active' },
+            fields: ['name', 'email'],
+            orderBy: ['-created_at'],
+            limit: 10,
+            offset: 5,
+        });
+
+        const url = fetchMock.mock.calls[0][0] as string;
+        // V2 canonical options are normalized to HTTP transport params
+        expect(url).toContain('top=10');
+        expect(url).toContain('skip=5');
+        expect(url).toContain('select=name%2Cemail');
+        expect(url).toContain('sort=-created_at');
+        // where → filter as JSON
+        expect(url).toContain('status=active');
+    });
+
+    it('should still accept legacy field names (filter, select, sort, top, skip)', async () => {
+        const { client, fetchMock } = createMockClient({
+            success: true,
+            data: { object: 'account', records: [], total: 0 }
+        });
+
+        await client.data.find('account', {
+            filter: { industry: 'Tech' },
+            select: ['name'],
+            sort: ['-revenue'],
+            top: 20,
+            skip: 0,
+        });
+
+        const url = fetchMock.mock.calls[0][0] as string;
+        expect(url).toContain('top=20');
+        expect(url).toContain('select=name');
+        expect(url).toContain('sort=-revenue');
+        expect(url).toContain('industry=Tech');
+    });
+});
+
+describe('QueryBuilder — offset() alias', () => {
+    it('should set offset via .offset() method', () => {
+        const q = createQuery('task')
+            .limit(10)
+            .offset(20)
+            .build();
+        expect(q.limit).toBe(10);
+        expect(q.offset).toBe(20);
+    });
+
+    it('should set offset via deprecated .skip() method', () => {
+        const q = createQuery('task')
+            .limit(10)
+            .skip(30)
+            .build();
+        expect(q.offset).toBe(30);
+    });
+});

package/src/index.ts

@@ -87,9 +87,17 @@ import {
   SubscribeResponse,
   UnsubscribeResponse,
   WellKnownCapabilities,
+  ApiRoutes,
 } from '@objectstack/spec/api';
 import { Logger, createLogger } from '@objectstack/core';
 
+/**
+ * Route types that the client can resolve.
+ * Covers all keys from `ApiRoutes` (the discovery schema) plus
+ * client-specific virtual routes (`views`, `permissions`).
+ */
+export type ApiRouteType = keyof ApiRoutes | 'views' | 'permissions';
+
 export interface ClientConfig {
   baseUrl: string;
   token?: string;
@@ -113,6 +121,16 @@ export interface ClientConfig {
  */
 export type DiscoveryResult = GetDiscoveryResponse;
 
+/**
+ * @deprecated Use `data.query()` with standard QueryAST parameters instead.
+ * This interface uses legacy parameter names (filter/sort/top/skip) that
+ * require translation to QueryAST. Prefer QueryAST fields directly:
+ *   - filter → where
+ *   - select → fields
+ *   - sort → orderBy
+ *   - skip → offset
+ *   - top → limit
+ */
 export interface QueryOptions {
   select?: string[]; // Simplified Selection
   /** @canonical Preferred filter parameter (singular). */
@@ -127,6 +145,37 @@ export interface QueryOptions {
   groupBy?: string[];
 }
 
+/**
+ * Canonical query options using Spec protocol field names.
+ * This is the recommended interface for `data.find()` queries.
+ *
+ *  Canonical field mapping (QueryAST-aligned):
+ *   - `where`   — filter conditions (replaces legacy `filter`/`filters`)
+ *   - `fields`  — field selection  (replaces legacy `select`)
+ *   - `orderBy` — sort definition  (replaces legacy `sort`)
+ *   - `limit`   — max records      (replaces legacy `top`)
+ *   - `offset`  — skip records     (replaces legacy `skip`)
+ *   - `expand`  — relation loading (replaces legacy `populate`)
+ */
+export interface QueryOptionsV2 {
+  /** Filter conditions (WHERE clause). Accepts MongoDB-style $op object or FilterCondition AST. */
+  where?: Record<string, any> | unknown[];
+  /** Fields to retrieve (SELECT clause). */
+  fields?: string[];
+  /** Sort definition (ORDER BY clause). */
+  orderBy?: string | string[] | SortNode[];
+  /** Maximum number of records to return (LIMIT). */
+  limit?: number;
+  /** Number of records to skip (OFFSET). */
+  offset?: number;
+  /** Relations to expand (JOIN / eager-load). */
+  expand?: Record<string, any> | string[];
+  /** Aggregation functions. */
+  aggregations?: AggregationNode[];
+  /** Group by fields. */
+  groupBy?: string[];
+}
+
 export interface PaginatedResult<T = any> {
   /** Spec-compliant: array of matching records */
   records: T[];
@@ -228,10 +277,10 @@ export class ObjectStackClient {
         this.logger.debug('Standard discovery probe failed', { error: (e as Error).message });
       }
 
-      // 2. Fallback to Legacy/Direct Path /api/v1
+      // 2. Fallback to Protocol-standard Discovery Path /api/v1/discovery
       if (!data) {
-        const fallbackUrl = `${this.baseUrl}/api/v1`;
-        this.logger.debug('Falling back to legacy discovery', { url: fallbackUrl });
+        const fallbackUrl = `${this.baseUrl}/api/v1/discovery`;
+        this.logger.debug('Falling back to standard discovery endpoint', { url: fallbackUrl });
         const res = await this.fetchImpl(fallbackUrl);
         if (!res.ok) {
            throw new Error(`Failed to connect to ${fallbackUrl}: ${res.statusText}`);
@@ -263,9 +312,20 @@ export class ObjectStackClient {
    * Well-known capability flags discovered from the server.
    * Returns undefined if the client has not yet connected or the server
    * did not include capabilities in its discovery response.
+   *
+   * The server may return capabilities in hierarchical format
+   * `{ key: { enabled: boolean } }` or flat boolean format `{ key: boolean }`.
+   * This getter normalizes both to flat `WellKnownCapabilities`.
    */
   get capabilities(): WellKnownCapabilities | undefined {
-    return this.discoveryInfo?.capabilities;
+    const raw = this.discoveryInfo?.capabilities;
+    if (!raw) return undefined;
+    // Normalize: hierarchical { enabled: boolean } → flat boolean
+    const result: Record<string, boolean> = {};
+    for (const [key, value] of Object.entries(raw)) {
+      result[key] = typeof value === 'object' && value !== null ? !!(value as any).enabled : !!value;
+    }
+    return result as unknown as WellKnownCapabilities;
   }
 
   /**
@@ -1234,7 +1294,7 @@ export class ObjectStackClient {
      * List feed items for a record
      */
     list: async (object: string, recordId: string, options?: { type?: string; limit?: number; cursor?: string }): Promise<GetFeedResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const params = new URLSearchParams();
       if (options?.type) params.set('type', options.type);
       if (options?.limit) params.set('limit', String(options.limit));
@@ -1248,7 +1308,7 @@ export class ObjectStackClient {
      * Create a new feed item (comment, note, task, etc.)
      */
     create: async (object: string, recordId: string, data: { type: string; body?: string; mentions?: any[]; parentId?: string; visibility?: string }): Promise<CreateFeedItemResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed`, {
         method: 'POST',
         body: JSON.stringify(data)
@@ -1260,7 +1320,7 @@ export class ObjectStackClient {
      * Update an existing feed item
      */
     update: async (object: string, recordId: string, feedId: string, data: { body?: string; mentions?: any[]; visibility?: string }): Promise<UpdateFeedItemResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}`, {
         method: 'PUT',
         body: JSON.stringify(data)
@@ -1272,7 +1332,7 @@ export class ObjectStackClient {
      * Delete a feed item
      */
     delete: async (object: string, recordId: string, feedId: string): Promise<DeleteFeedItemResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}`, {
         method: 'DELETE'
       });
@@ -1283,7 +1343,7 @@ export class ObjectStackClient {
      * Add an emoji reaction to a feed item
      */
     addReaction: async (object: string, recordId: string, feedId: string, emoji: string): Promise<AddReactionResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}/reactions`, {
         method: 'POST',
         body: JSON.stringify({ emoji })
@@ -1295,7 +1355,7 @@ export class ObjectStackClient {
      * Remove an emoji reaction from a feed item
      */
     removeReaction: async (object: string, recordId: string, feedId: string, emoji: string): Promise<RemoveReactionResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}/reactions/${encodeURIComponent(emoji)}`, {
         method: 'DELETE'
       });
@@ -1306,7 +1366,7 @@ export class ObjectStackClient {
      * Pin a feed item to the top of the timeline
      */
     pin: async (object: string, recordId: string, feedId: string): Promise<PinFeedItemResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}/pin`, {
         method: 'POST'
       });
@@ -1317,7 +1377,7 @@ export class ObjectStackClient {
      * Unpin a feed item
      */
     unpin: async (object: string, recordId: string, feedId: string): Promise<UnpinFeedItemResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}/pin`, {
         method: 'DELETE'
       });
@@ -1328,7 +1388,7 @@ export class ObjectStackClient {
      * Star (bookmark) a feed item
      */
     star: async (object: string, recordId: string, feedId: string): Promise<StarFeedItemResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}/star`, {
         method: 'POST'
       });
@@ -1339,7 +1399,7 @@ export class ObjectStackClient {
      * Unstar a feed item
      */
     unstar: async (object: string, recordId: string, feedId: string): Promise<UnstarFeedItemResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/feed/${encodeURIComponent(feedId)}/star`, {
         method: 'DELETE'
       });
@@ -1350,7 +1410,7 @@ export class ObjectStackClient {
      * Search feed items
      */
     search: async (object: string, recordId: string, query: string, options?: { type?: string; actorId?: string; dateFrom?: string; dateTo?: string; limit?: number; cursor?: string }): Promise<SearchFeedResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const params = new URLSearchParams();
       params.set('query', query);
       if (options?.type) params.set('type', options.type);
@@ -1367,7 +1427,7 @@ export class ObjectStackClient {
      * Get field-level changelog for a record
      */
     getChangelog: async (object: string, recordId: string, options?: { field?: string; actorId?: string; dateFrom?: string; dateTo?: string; limit?: number; cursor?: string }): Promise<GetChangelogResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const params = new URLSearchParams();
       if (options?.field) params.set('field', options.field);
       if (options?.actorId) params.set('actorId', options.actorId);
@@ -1384,7 +1444,7 @@ export class ObjectStackClient {
      * Subscribe to record notifications
      */
     subscribe: async (object: string, recordId: string, options?: { events?: string[]; channels?: string[] }): Promise<SubscribeResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/subscribe`, {
         method: 'POST',
         body: JSON.stringify(options || {})
@@ -1396,7 +1456,7 @@ export class ObjectStackClient {
      * Unsubscribe from record notifications
      */
     unsubscribe: async (object: string, recordId: string): Promise<UnsubscribeResponse> => {
-      const route = this.getRoute('feed');
+      const route = this.getRoute('data');
       const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}/subscribe`, {
         method: 'DELETE'
       });
@@ -1423,34 +1483,56 @@ export class ObjectStackClient {
       return this.unwrapResponse<PaginatedResult<T>>(res);
     },
 
-    find: async <T = any>(object: string, options: QueryOptions = {}): Promise<PaginatedResult<T>> => {
+    /**
+     * @deprecated Use `data.query()` with standard QueryAST parameters instead.
+     * This method uses legacy parameter names. Internally adapts to HTTP GET params.
+     */
+    find: async <T = any>(object: string, options: QueryOptions | QueryOptionsV2 = {}): Promise<PaginatedResult<T>> => {
         const route = this.getRoute('data');
         const queryParams = new URLSearchParams();
-        
+
+        // ── Normalize V2 canonical options → HTTP transport params ───
+        // Detect V2 options by presence of canonical-only keys.
+        const v2 = options as QueryOptionsV2;
+        const normalizedOptions: QueryOptions = {} as QueryOptions;
+        if ('where' in options || 'fields' in options || 'orderBy' in options || 'offset' in options) {
+            // V2 canonical options detected — map to legacy HTTP transport keys
+            if (v2.where) normalizedOptions.filter = v2.where as any;
+            if (v2.fields) normalizedOptions.select = v2.fields;
+            if (v2.orderBy) normalizedOptions.sort = v2.orderBy as any;
+            if (v2.limit != null) normalizedOptions.top = v2.limit;
+            if (v2.offset != null) normalizedOptions.skip = v2.offset;
+            if (v2.aggregations) normalizedOptions.aggregations = v2.aggregations;
+            if (v2.groupBy) normalizedOptions.groupBy = v2.groupBy;
+        } else {
+            // Legacy QueryOptions — pass through as-is
+            Object.assign(normalizedOptions, options);
+        }
+
         // 1. Handle Pagination
-        if (options.top) queryParams.set('top', options.top.toString());
-        if (options.skip) queryParams.set('skip', options.skip.toString());
+        if (normalizedOptions.top) queryParams.set('top', normalizedOptions.top.toString());
+        if (normalizedOptions.skip) queryParams.set('skip', normalizedOptions.skip.toString());
 
         // 2. Handle Sort
-        if (options.sort) {
+        if (normalizedOptions.sort) {
             // Check if it's AST 
-            if (Array.isArray(options.sort) && typeof options.sort[0] === 'object') {
-                 queryParams.set('sort', JSON.stringify(options.sort));
+            if (Array.isArray(normalizedOptions.sort) && typeof normalizedOptions.sort[0] === 'object') {
+                 queryParams.set('sort', JSON.stringify(normalizedOptions.sort));
             } else {
-                 const sortVal = Array.isArray(options.sort) ? options.sort.join(',') : options.sort;
+                 const sortVal = Array.isArray(normalizedOptions.sort) ? normalizedOptions.sort.join(',') : normalizedOptions.sort;
                  queryParams.set('sort', sortVal as string);
             }
         }
         
         // 3. Handle Select
-        if (options.select) {
-            queryParams.set('select', options.select.join(','));
+        if (normalizedOptions.select) {
+            queryParams.set('select', normalizedOptions.select.join(','));
         }
 
         // 4. Handle Filters (Simple vs AST)
         // Canonical HTTP param name: `filter` (singular). `filters` (plural) is accepted
         // for backward compatibility but `filter` is the standard going forward.
-        const filterValue = options.filter ?? options.filters;
+        const filterValue = normalizedOptions.filter ?? normalizedOptions.filters;
         if (filterValue) {
              // Detect AST filter format vs simple key-value map. AST filters use an array structure
              // with [field, operator, value] or [logicOp, ...nodes] shape (see isFilterAST from spec).
@@ -1469,11 +1551,11 @@ export class ObjectStackClient {
         }
         
         // 5. Handle Aggregations & GroupBy (Pass through as JSON if present)
-        if (options.aggregations) {
-            queryParams.set('aggregations', JSON.stringify(options.aggregations));
+        if (normalizedOptions.aggregations) {
+            queryParams.set('aggregations', JSON.stringify(normalizedOptions.aggregations));
         }
-        if (options.groupBy) {
-             queryParams.set('groupBy', options.groupBy.join(','));
+        if (normalizedOptions.groupBy) {
+             queryParams.set('groupBy', normalizedOptions.groupBy.join(','));
         }
 
         const res = await this.fetch(`${this.baseUrl}${route}/${object}?${queryParams.toString()}`);
@@ -1663,16 +1745,20 @@ export class ObjectStackClient {
    * Get the conventional route path for a given API endpoint type
    * ObjectStack uses standard conventions: /api/v1/data, /api/v1/meta, /api/v1/ui
    */
-  private getRoute(type: 'data' | 'metadata' | 'ui' | 'auth' | 'analytics' | 'storage' | 'automation' | 'packages' | 'permissions' | 'realtime' | 'workflow' | 'views' | 'notifications' | 'ai' | 'i18n' | 'feed'): string {
-    // 1. Use discovered routes if available
-    if (this.discoveryInfo?.routes && (this.discoveryInfo.routes as any)[type]) {
-        return (this.discoveryInfo.routes as any)[type];
+  private getRoute(type: ApiRouteType): string {
+    // 1. Use discovered routes if available (only for ApiRoutes keys, not client-specific keys)
+    const routes = this.discoveryInfo?.routes;
+    if (routes) {
+        const key = type as keyof ApiRoutes;
+        const discovered = routes[key];
+        if (discovered) return discovered;
     }
 
-    // 2. Fallback to conventions
-    const routeMap: Record<string, string> = {
+    // 2. Fallback to conventions (covers all ApiRoutes keys + client-specific virtual routes)
+    const routeMap: Record<ApiRouteType, string> = {
       data: '/api/v1/data',
       metadata: '/api/v1/meta',
+      discovery: '/api/v1/discovery',
       ui: '/api/v1/ui',
       auth: '/api/v1/auth',
       analytics: '/api/v1/analytics',
@@ -1686,7 +1772,8 @@ export class ObjectStackClient {
       notifications: '/api/v1/notifications',
       ai: '/api/v1/ai',
       i18n: '/api/v1/i18n',
-      feed: '/api/v1/data',
+      feed: '/api/v1/feed',
+      graphql: '/graphql',
     };
     
     return routeMap[type] || `/api/v1/${type}`;

package/src/query-builder.ts

@@ -236,13 +236,22 @@ export class QueryBuilder<T = any> {
   }
 
   /**
-   * Skip records (for pagination)
+   * Skip records (for pagination).
+   * @deprecated Prefer `.offset()` for alignment with Spec canonical field names.
    */
   skip(count: number): this {
     this.query.offset = count;
     return this;
   }
 
+  /**
+   * Offset records (for pagination) — canonical alias for `.skip()`
+   */
+  offset(count: number): this {
+    this.query.offset = count;
+    return this;
+  }
+
   /**
    * Paginate results
    */

package/tsconfig.json

@@ -3,7 +3,8 @@
   "compilerOptions": {
     "outDir": "./dist",
     "rootDir": "./src",
-    "lib": ["ES2020", "DOM", "DOM.Iterable"]
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "types": ["node"]
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist", "**/*.test.ts"]