@objectstack/client 3.3.1 → 4.0.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/client@3.3.1 build /home/runner/work/spec/spec/packages/client
+> @objectstack/client@4.0.0 build /home/runner/work/spec/spec/packages/client
 > tsup --config ../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     52.12 KB
-ESM dist/index.mjs.map 104.44 KB
-ESM ⚡️ Build success in 56ms
-CJS dist/index.js     53.29 KB
-CJS dist/index.js.map 104.49 KB
-CJS ⚡️ Build success in 57ms
+ESM dist/index.mjs     53.98 KB
+ESM dist/index.mjs.map 109.49 KB
+ESM ⚡️ Build success in 41ms
+CJS dist/index.js     55.15 KB
+CJS dist/index.js.map 109.54 KB
+CJS ⚡️ Build success in 42ms
 DTS Build start
-DTS ⚡️ Build success in 5837ms
-DTS dist/index.d.mts 30.61 KB
-DTS dist/index.d.ts  30.61 KB
+DTS ⚡️ Build success in 5329ms
+DTS dist/index.d.mts 33.59 KB
+DTS dist/index.d.ts  33.59 KB

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @objectstack/client
 
+## 4.0.0
+
+### Minor Changes
+
+- f08ffc3: Fix discovery API endpoint routing and protocol consistency.
+
+  **Discovery route standardization:**
+
+  - All adapters (Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit) now mount the discovery endpoint at `{prefix}/discovery` instead of `{prefix}` root.
+  - `.well-known/objectstack` redirects now point to `{prefix}/discovery`.
+  - Client `connect()` fallback URL changed from `/api/v1` to `/api/v1/discovery`.
+  - Runtime dispatcher handles both `/discovery` (standard) and `/` (legacy) for backward compatibility.
+
+  **Schema & route alignment:**
+
+  - Added `storage` (service: `file-storage`) and `feed` (service: `data`) routes to `DEFAULT_DISPATCHER_ROUTES`.
+  - Added `feed` and `discovery` fields to `ApiRoutesSchema`.
+  - Unified `GetDiscoveryResponseSchema` with `DiscoverySchema` as single source of truth.
+  - Client `getRoute('feed')` fallback updated from `/api/v1/data` to `/api/v1/feed`.
+
+  **Type safety:**
+
+  - Extracted `ApiRouteType` from `ApiRoutes` keys for type-safe client route resolution.
+  - Removed `as any` type casting in client route access.
+
+- e0b0a78: Deprecate DataEngineQueryOptions in favor of QueryAST-aligned EngineQueryOptions.
+
+  Engine, Protocol, and Client now use standard QueryAST parameter names:
+
+  - `filter` → `where`
+  - `select` → `fields`
+  - `sort` → `orderBy`
+  - `skip` → `offset`
+  - `populate` → `expand`
+  - `top` → `limit`
+
+  The old DataEngine\* schemas and types are preserved with `@deprecated` markers for backward compatibility.
+
+### Patch Changes
+
+- Updated dependencies [f08ffc3]
+- Updated dependencies [e0b0a78]
+  - @objectstack/spec@4.0.0
+  - @objectstack/core@4.0.0
+
 ## 3.3.1
 
 ### Patch Changes

package/README.md

@@ -147,12 +147,15 @@ Initializes the client by fetching the system discovery manifest from `/api/v1`.
 - `setDefault(id, object)`: Set a view as default for an object.
 
 ### Query Options
-The `find` method accepts an options object:
-- `select`: Array of field names to retrieve.
-- `filters`: Simple key-value map OR Filter AST `['field', 'op', 'value']`.
-- `sort`: Sort string (`'name'`) or array `['-created_at', 'name']`.
-- `top`: Limit number of records.
-- `skip`: Offset for pagination.
+The `find` method accepts an options object with canonical field names:
+- `where`: Filter conditions (WHERE clause). Accepts object or FilterCondition AST.
+- `fields`: Array of field names to retrieve (SELECT clause).
+- `orderBy`: Sort definition — `'name'`, `['-created_at', 'name']`, or `SortNode[]`.
+- `limit`: Maximum number of records to return (LIMIT).
+- `offset`: Number of records to skip (OFFSET).
+- `expand`: Relations to expand (JOIN / eager-load).
+
+> **Deprecated aliases** (accepted for backward compatibility): `select` → `fields`, `filter`/`filters` → `where`, `sort` → `orderBy`, `top` → `limit`, `skip` → `offset`.
 
 ### Batch Options
 Batch operations support the following options:

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { FilterCondition, QueryAST, SortNode, AggregationNode } from '@objectstack/spec/data';
-import { GetDiscoveryResponse, StandardErrorCode, ErrorCategory, WellKnownCapabilities, GetMetaTypesResponse, GetMetaItemsResponse, MetadataCacheRequest, MetadataCacheResponse, LoginRequest, SessionResponse, RegisterRequest, FileUploadResponse, GetPresignedUrlRequest, PresignedUrlResponse, InitiateChunkedUploadRequest, InitiateChunkedUploadResponse, UploadChunkResponse, CompleteChunkedUploadRequest, CompleteChunkedUploadResponse, CheckPermissionRequest, CheckPermissionResponse, GetObjectPermissionsResponse, GetEffectivePermissionsResponse, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, SetPresenceRequest, GetPresenceResponse, GetWorkflowConfigResponse, GetWorkflowStateResponse, WorkflowTransitionRequest, WorkflowTransitionResponse, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, ListViewsResponse, GetViewResponse, CreateViewRequest, CreateViewResponse, UpdateViewRequest, UpdateViewResponse, DeleteViewResponse, RegisterDeviceRequest, RegisterDeviceResponse, UnregisterDeviceResponse, GetNotificationPreferencesResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, ListNotificationsResponse, MarkNotificationsReadResponse, MarkAllNotificationsReadResponse, AiNlqRequest, AiNlqResponse, AiChatRequest, AiChatResponse, AiSuggestRequest, AiSuggestResponse, AiInsightsRequest, AiInsightsResponse, GetLocalesResponse, GetTranslationsResponse, GetFieldLabelsResponse, GetFeedResponse, CreateFeedItemResponse, UpdateFeedItemResponse, DeleteFeedItemResponse, AddReactionResponse, RemoveReactionResponse, PinFeedItemResponse, UnpinFeedItemResponse, StarFeedItemResponse, UnstarFeedItemResponse, SearchFeedResponse, GetChangelogResponse, SubscribeResponse, UnsubscribeResponse, BatchUpdateRequest, BatchUpdateResponse, BatchOptions } from '@objectstack/spec/api';
+import { ApiRoutes, GetDiscoveryResponse, WellKnownCapabilities, GetMetaTypesResponse, GetMetaItemsResponse, MetadataCacheRequest, MetadataCacheResponse, LoginRequest, SessionResponse, RegisterRequest, FileUploadResponse, GetPresignedUrlRequest, PresignedUrlResponse, InitiateChunkedUploadRequest, InitiateChunkedUploadResponse, UploadChunkResponse, CompleteChunkedUploadRequest, CompleteChunkedUploadResponse, CheckPermissionRequest, CheckPermissionResponse, GetObjectPermissionsResponse, GetEffectivePermissionsResponse, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, SetPresenceRequest, GetPresenceResponse, GetWorkflowConfigResponse, GetWorkflowStateResponse, WorkflowTransitionRequest, WorkflowTransitionResponse, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, ListViewsResponse, GetViewResponse, CreateViewRequest, CreateViewResponse, UpdateViewRequest, UpdateViewResponse, DeleteViewResponse, RegisterDeviceRequest, RegisterDeviceResponse, UnregisterDeviceResponse, GetNotificationPreferencesResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, ListNotificationsResponse, MarkNotificationsReadResponse, MarkAllNotificationsReadResponse, AiNlqRequest, AiNlqResponse, AiChatRequest, AiChatResponse, AiSuggestRequest, AiSuggestResponse, AiInsightsRequest, AiInsightsResponse, GetLocalesResponse, GetTranslationsResponse, GetFieldLabelsResponse, GetFeedResponse, CreateFeedItemResponse, UpdateFeedItemResponse, DeleteFeedItemResponse, AddReactionResponse, RemoveReactionResponse, PinFeedItemResponse, UnpinFeedItemResponse, StarFeedItemResponse, UnstarFeedItemResponse, SearchFeedResponse, GetChangelogResponse, SubscribeResponse, UnsubscribeResponse, BatchUpdateRequest, BatchUpdateResponse, BatchOptions, StandardErrorCode, ErrorCategory } from '@objectstack/spec/api';
 export { AddReactionResponse, AiChatRequest, AiChatResponse, AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, BatchOperationResult, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, CheckPermissionRequest, CheckPermissionResponse, CreateFeedItemResponse, CreateViewResponse, DeleteFeedItemResponse, DeleteManyRequest, DeleteViewResponse, ErrorCategory, GetChangelogResponse, GetDiscoveryResponse, GetEffectivePermissionsResponse, GetFeedResponse, GetFieldLabelsResponse, GetLocalesResponse, GetMetaItemsResponse, GetMetaTypesResponse, GetObjectPermissionsResponse, GetPresenceResponse, GetTranslationsResponse, GetViewResponse, GetWorkflowConfigResponse, GetWorkflowStateResponse, ListNotificationsResponse, ListViewsResponse, MetadataCacheRequest, MetadataCacheResponse, PinFeedItemResponse, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RefreshTokenRequest, RegisterDeviceRequest, RegisterDeviceResponse, RegisterRequest, RemoveReactionResponse, SearchFeedResponse, StandardErrorCode, StarFeedItemResponse, SubscribeResponse, UnpinFeedItemResponse, UnstarFeedItemResponse, UnsubscribeResponse, UpdateFeedItemResponse, UpdateManyRequest, UpdateViewResponse, WellKnownCapabilities, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api';
 import { Logger } from '@objectstack/core';
 
@@ -119,9 +119,14 @@ declare class QueryBuilder<T = any> {
      */
     limit(count: number): this;
     /**
-     * Skip records (for pagination)
+     * Skip records (for pagination).
+     * @deprecated Prefer `.offset()` for alignment with Spec canonical field names.
      */
     skip(count: number): this;
+    /**
+     * Offset records (for pagination) — canonical alias for `.skip()`
+     */
+    offset(count: number): this;
     /**
      * Paginate results
      */
@@ -167,6 +172,12 @@ declare function createQuery<T = any>(object: string): QueryBuilder<T>;
  */
 declare function createFilter<T = any>(): FilterBuilder<T>;
 
+/**
+ * Route types that the client can resolve.
+ * Covers all keys from `ApiRoutes` (the discovery schema) plus
+ * client-specific virtual routes (`views`, `permissions`).
+ */
+type ApiRouteType = keyof ApiRoutes | 'views' | 'permissions';
 interface ClientConfig {
     baseUrl: string;
     token?: string;
@@ -188,6 +199,16 @@ interface ClientConfig {
  * Re-export from @objectstack/spec/api for convenience
  */
 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
+ */
 interface QueryOptions {
     select?: string[];
     /** @canonical Preferred filter parameter (singular). */
@@ -200,6 +221,36 @@ interface QueryOptions {
     aggregations?: AggregationNode[];
     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`)
+ */
+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[];
+}
 interface PaginatedResult<T = any> {
     /** Spec-compliant: array of matching records */
     records: T[];
@@ -254,10 +305,12 @@ declare class ObjectStackClient {
      */
     connect(): Promise<{
         version: string;
-        apiName: string;
+        name?: string | undefined;
+        environment?: "development" | "production" | "sandbox" | undefined;
         routes?: {
             data: string;
             metadata: string;
+            discovery?: string | undefined;
             ui?: string | undefined;
             auth?: string | undefined;
             automation?: string | undefined;
@@ -270,6 +323,12 @@ declare class ObjectStackClient {
             notifications?: string | undefined;
             ai?: string | undefined;
             i18n?: string | undefined;
+            feed?: string | undefined;
+        } | undefined;
+        locale?: {
+            default: string;
+            supported: string[];
+            timezone: string;
         } | undefined;
         services?: Record<string, {
             enabled: boolean;
@@ -285,20 +344,27 @@ declare class ObjectStackClient {
                 retryAfterMs?: number | undefined;
             } | undefined;
         }> | undefined;
-        capabilities?: {
-            feed: boolean;
-            comments: boolean;
-            automation: boolean;
-            cron: boolean;
-            search: boolean;
-            export: boolean;
-            chunkedUpload: boolean;
+        capabilities?: Record<string, {
+            enabled: boolean;
+            features?: Record<string, boolean> | undefined;
+            description?: string | undefined;
+        }> | undefined;
+        schemaDiscovery?: {
+            openapi?: string | undefined;
+            graphql?: string | undefined;
+            jsonSchema?: string | undefined;
         } | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        apiName?: string | undefined;
     }>;
     /**
      * 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;
     /**
@@ -814,7 +880,11 @@ declare class ObjectStackClient {
          * Supports both simplified options and full AST
          */
         query: <T = any>(object: string, query: Partial<QueryAST>) => Promise<PaginatedResult<T>>;
-        find: <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: <T = any>(object: string, options?: QueryOptions | QueryOptionsV2) => Promise<PaginatedResult<T>>;
         get: <T = any>(object: string, id: string) => Promise<GetDataResult<T>>;
         create: <T = any>(object: string, data: Partial<T>) => Promise<CreateDataResult<T>>;
         createMany: <T = any>(object: string, data: Partial<T>[]) => Promise<T[]>;
@@ -858,4 +928,4 @@ declare class ObjectStackClient {
     private getRoute;
 }
 
-export { type ClientConfig, type CreateDataResult, type DeleteDataResult, type DiscoveryResult, FilterBuilder, type GetDataResult, ObjectStackClient, type PaginatedResult, QueryBuilder, type QueryOptions, type StandardError, type UpdateDataResult, createFilter, createQuery };
+export { type ApiRouteType, type ClientConfig, type CreateDataResult, type DeleteDataResult, type DiscoveryResult, FilterBuilder, type GetDataResult, ObjectStackClient, type PaginatedResult, QueryBuilder, type QueryOptions, type QueryOptionsV2, type StandardError, type UpdateDataResult, createFilter, createQuery };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { FilterCondition, QueryAST, SortNode, AggregationNode } from '@objectstack/spec/data';
-import { GetDiscoveryResponse, StandardErrorCode, ErrorCategory, WellKnownCapabilities, GetMetaTypesResponse, GetMetaItemsResponse, MetadataCacheRequest, MetadataCacheResponse, LoginRequest, SessionResponse, RegisterRequest, FileUploadResponse, GetPresignedUrlRequest, PresignedUrlResponse, InitiateChunkedUploadRequest, InitiateChunkedUploadResponse, UploadChunkResponse, CompleteChunkedUploadRequest, CompleteChunkedUploadResponse, CheckPermissionRequest, CheckPermissionResponse, GetObjectPermissionsResponse, GetEffectivePermissionsResponse, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, SetPresenceRequest, GetPresenceResponse, GetWorkflowConfigResponse, GetWorkflowStateResponse, WorkflowTransitionRequest, WorkflowTransitionResponse, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, ListViewsResponse, GetViewResponse, CreateViewRequest, CreateViewResponse, UpdateViewRequest, UpdateViewResponse, DeleteViewResponse, RegisterDeviceRequest, RegisterDeviceResponse, UnregisterDeviceResponse, GetNotificationPreferencesResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, ListNotificationsResponse, MarkNotificationsReadResponse, MarkAllNotificationsReadResponse, AiNlqRequest, AiNlqResponse, AiChatRequest, AiChatResponse, AiSuggestRequest, AiSuggestResponse, AiInsightsRequest, AiInsightsResponse, GetLocalesResponse, GetTranslationsResponse, GetFieldLabelsResponse, GetFeedResponse, CreateFeedItemResponse, UpdateFeedItemResponse, DeleteFeedItemResponse, AddReactionResponse, RemoveReactionResponse, PinFeedItemResponse, UnpinFeedItemResponse, StarFeedItemResponse, UnstarFeedItemResponse, SearchFeedResponse, GetChangelogResponse, SubscribeResponse, UnsubscribeResponse, BatchUpdateRequest, BatchUpdateResponse, BatchOptions } from '@objectstack/spec/api';
+import { ApiRoutes, GetDiscoveryResponse, WellKnownCapabilities, GetMetaTypesResponse, GetMetaItemsResponse, MetadataCacheRequest, MetadataCacheResponse, LoginRequest, SessionResponse, RegisterRequest, FileUploadResponse, GetPresignedUrlRequest, PresignedUrlResponse, InitiateChunkedUploadRequest, InitiateChunkedUploadResponse, UploadChunkResponse, CompleteChunkedUploadRequest, CompleteChunkedUploadResponse, CheckPermissionRequest, CheckPermissionResponse, GetObjectPermissionsResponse, GetEffectivePermissionsResponse, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, SetPresenceRequest, GetPresenceResponse, GetWorkflowConfigResponse, GetWorkflowStateResponse, WorkflowTransitionRequest, WorkflowTransitionResponse, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, ListViewsResponse, GetViewResponse, CreateViewRequest, CreateViewResponse, UpdateViewRequest, UpdateViewResponse, DeleteViewResponse, RegisterDeviceRequest, RegisterDeviceResponse, UnregisterDeviceResponse, GetNotificationPreferencesResponse, UpdateNotificationPreferencesRequest, UpdateNotificationPreferencesResponse, ListNotificationsResponse, MarkNotificationsReadResponse, MarkAllNotificationsReadResponse, AiNlqRequest, AiNlqResponse, AiChatRequest, AiChatResponse, AiSuggestRequest, AiSuggestResponse, AiInsightsRequest, AiInsightsResponse, GetLocalesResponse, GetTranslationsResponse, GetFieldLabelsResponse, GetFeedResponse, CreateFeedItemResponse, UpdateFeedItemResponse, DeleteFeedItemResponse, AddReactionResponse, RemoveReactionResponse, PinFeedItemResponse, UnpinFeedItemResponse, StarFeedItemResponse, UnstarFeedItemResponse, SearchFeedResponse, GetChangelogResponse, SubscribeResponse, UnsubscribeResponse, BatchUpdateRequest, BatchUpdateResponse, BatchOptions, StandardErrorCode, ErrorCategory } from '@objectstack/spec/api';
 export { AddReactionResponse, AiChatRequest, AiChatResponse, AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, BatchOperationResult, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, CheckPermissionRequest, CheckPermissionResponse, CreateFeedItemResponse, CreateViewResponse, DeleteFeedItemResponse, DeleteManyRequest, DeleteViewResponse, ErrorCategory, GetChangelogResponse, GetDiscoveryResponse, GetEffectivePermissionsResponse, GetFeedResponse, GetFieldLabelsResponse, GetLocalesResponse, GetMetaItemsResponse, GetMetaTypesResponse, GetObjectPermissionsResponse, GetPresenceResponse, GetTranslationsResponse, GetViewResponse, GetWorkflowConfigResponse, GetWorkflowStateResponse, ListNotificationsResponse, ListViewsResponse, MetadataCacheRequest, MetadataCacheResponse, PinFeedItemResponse, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RefreshTokenRequest, RegisterDeviceRequest, RegisterDeviceResponse, RegisterRequest, RemoveReactionResponse, SearchFeedResponse, StandardErrorCode, StarFeedItemResponse, SubscribeResponse, UnpinFeedItemResponse, UnstarFeedItemResponse, UnsubscribeResponse, UpdateFeedItemResponse, UpdateManyRequest, UpdateViewResponse, WellKnownCapabilities, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api';
 import { Logger } from '@objectstack/core';
 
@@ -119,9 +119,14 @@ declare class QueryBuilder<T = any> {
      */
     limit(count: number): this;
     /**
-     * Skip records (for pagination)
+     * Skip records (for pagination).
+     * @deprecated Prefer `.offset()` for alignment with Spec canonical field names.
      */
     skip(count: number): this;
+    /**
+     * Offset records (for pagination) — canonical alias for `.skip()`
+     */
+    offset(count: number): this;
     /**
      * Paginate results
      */
@@ -167,6 +172,12 @@ declare function createQuery<T = any>(object: string): QueryBuilder<T>;
  */
 declare function createFilter<T = any>(): FilterBuilder<T>;
 
+/**
+ * Route types that the client can resolve.
+ * Covers all keys from `ApiRoutes` (the discovery schema) plus
+ * client-specific virtual routes (`views`, `permissions`).
+ */
+type ApiRouteType = keyof ApiRoutes | 'views' | 'permissions';
 interface ClientConfig {
     baseUrl: string;
     token?: string;
@@ -188,6 +199,16 @@ interface ClientConfig {
  * Re-export from @objectstack/spec/api for convenience
  */
 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
+ */
 interface QueryOptions {
     select?: string[];
     /** @canonical Preferred filter parameter (singular). */
@@ -200,6 +221,36 @@ interface QueryOptions {
     aggregations?: AggregationNode[];
     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`)
+ */
+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[];
+}
 interface PaginatedResult<T = any> {
     /** Spec-compliant: array of matching records */
     records: T[];
@@ -254,10 +305,12 @@ declare class ObjectStackClient {
      */
     connect(): Promise<{
         version: string;
-        apiName: string;
+        name?: string | undefined;
+        environment?: "development" | "production" | "sandbox" | undefined;
         routes?: {
             data: string;
             metadata: string;
+            discovery?: string | undefined;
             ui?: string | undefined;
             auth?: string | undefined;
             automation?: string | undefined;
@@ -270,6 +323,12 @@ declare class ObjectStackClient {
             notifications?: string | undefined;
             ai?: string | undefined;
             i18n?: string | undefined;
+            feed?: string | undefined;
+        } | undefined;
+        locale?: {
+            default: string;
+            supported: string[];
+            timezone: string;
         } | undefined;
         services?: Record<string, {
             enabled: boolean;
@@ -285,20 +344,27 @@ declare class ObjectStackClient {
                 retryAfterMs?: number | undefined;
             } | undefined;
         }> | undefined;
-        capabilities?: {
-            feed: boolean;
-            comments: boolean;
-            automation: boolean;
-            cron: boolean;
-            search: boolean;
-            export: boolean;
-            chunkedUpload: boolean;
+        capabilities?: Record<string, {
+            enabled: boolean;
+            features?: Record<string, boolean> | undefined;
+            description?: string | undefined;
+        }> | undefined;
+        schemaDiscovery?: {
+            openapi?: string | undefined;
+            graphql?: string | undefined;
+            jsonSchema?: string | undefined;
         } | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        apiName?: string | undefined;
     }>;
     /**
      * 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;
     /**
@@ -814,7 +880,11 @@ declare class ObjectStackClient {
          * Supports both simplified options and full AST
          */
         query: <T = any>(object: string, query: Partial<QueryAST>) => Promise<PaginatedResult<T>>;
-        find: <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: <T = any>(object: string, options?: QueryOptions | QueryOptionsV2) => Promise<PaginatedResult<T>>;
         get: <T = any>(object: string, id: string) => Promise<GetDataResult<T>>;
         create: <T = any>(object: string, data: Partial<T>) => Promise<CreateDataResult<T>>;
         createMany: <T = any>(object: string, data: Partial<T>[]) => Promise<T[]>;
@@ -858,4 +928,4 @@ declare class ObjectStackClient {
     private getRoute;
 }
 
-export { type ClientConfig, type CreateDataResult, type DeleteDataResult, type DiscoveryResult, FilterBuilder, type GetDataResult, ObjectStackClient, type PaginatedResult, QueryBuilder, type QueryOptions, type StandardError, type UpdateDataResult, createFilter, createQuery };
+export { type ApiRouteType, type ClientConfig, type CreateDataResult, type DeleteDataResult, type DiscoveryResult, FilterBuilder, type GetDataResult, ObjectStackClient, type PaginatedResult, QueryBuilder, type QueryOptions, type QueryOptionsV2, type StandardError, type UpdateDataResult, createFilter, createQuery };