@objectstack/client 2.0.0 → 2.0.2

package/README.md

@@ -11,6 +11,8 @@ The official TypeScript client for ObjectStack.
 - **Batch Operations**: Efficient bulk create/update/delete with transaction support.
 - **View Storage**: Save, load, and share custom UI view configurations.
 - **Standardized Errors**: Machine-readable error codes with retry guidance.
+- **Full Protocol Coverage**: Implements all 13 API namespaces defined in `@objectstack/spec`
+- **95+ Methods**: Complete implementation of discovery, metadata, data, auth, workflow, realtime, AI, and more.
 
 ## 🤖 AI Development Context
 
@@ -219,3 +221,130 @@ const data = await retryableRequest(() =>
 );
 ```
 
+## Protocol Compliance
+
+The `@objectstack/client` SDK implements all 13 API namespaces defined in the `@objectstack/spec` protocol specification:
+
+| Namespace | Purpose | Status |
+|-----------|---------|:------:|
+| `discovery` | API version & capabilities detection | ✅ |
+| `meta` | Metadata operations (objects, plugins, etc.) | ✅ |
+| `data` | CRUD & query operations | ✅ |
+| `auth` | Authentication & user management | ✅ |
+| `packages` | Plugin/package lifecycle management | ✅ |
+| `views` | UI view definitions | ✅ |
+| `workflow` | Workflow state transitions | ✅ |
+| `analytics` | Analytics queries | ✅ |
+| `automation` | Automation triggers | ✅ |
+| `i18n` | Internationalization | ✅ |
+| `notifications` | Push notifications | ✅ |
+| `realtime` | WebSocket subscriptions | ✅ |
+| `ai` | AI services (NLQ, chat, insights) | ✅ |
+
+For detailed compliance verification, see [CLIENT_SPEC_COMPLIANCE.md](./CLIENT_SPEC_COMPLIANCE.md).
+
+## Available Namespaces
+
+### Complete API Coverage
+
+```typescript
+const client = new ObjectStackClient({ baseUrl: 'http://localhost:3000' });
+await client.connect();
+
+// Discovery & Metadata
+await client.meta.getTypes();                    // List metadata types
+await client.meta.getItems('object');            // List all objects
+await client.meta.getItem('object', 'contact');  // Get specific object
+
+// Data Operations
+await client.data.find('contact', { filters: { status: 'active' } });
+await client.data.create('contact', { name: 'John' });
+await client.data.update('contact', id, { status: 'inactive' });
+await client.data.delete('contact', id);
+await client.data.batch('contact', batchRequest);
+
+// Authentication
+await client.auth.login({ email: 'user@example.com', password: 'pass' });
+await client.auth.register({ email: 'new@example.com', password: 'pass' });
+await client.auth.me();
+await client.auth.logout();
+await client.auth.refreshToken('refresh-token-string');
+
+// Package Management
+await client.packages.list();
+await client.packages.install({
+  name: 'vendor_plugin',
+  label: 'Vendor Plugin',
+  version: '1.0.0',
+});
+await client.packages.enable('plugin-id');
+
+// Permissions
+await client.permissions.check({ object: 'contact', action: 'create' });
+await client.permissions.getObjectPermissions('contact');
+await client.permissions.getEffectivePermissions();
+
+// Workflow
+await client.workflow.getConfig('approval');
+await client.workflow.getState('approval', recordId);
+await client.workflow.transition({ object: 'approval', recordId, transition: 'submit' });
+await client.workflow.approve({ object: 'approval', recordId });
+await client.workflow.reject({ object: 'approval', recordId, reason: 'Incomplete' });
+
+// Realtime
+await client.realtime.connect({ protocol: 'websocket' });
+await client.realtime.subscribe({ channel: 'contact', event: 'update' });
+await client.realtime.setPresence({ status: 'online' });
+
+// Notifications
+await client.notifications.registerDevice({ token: 'device-token', platform: 'ios' });
+await client.notifications.list({ unreadOnly: true });
+await client.notifications.markRead(['notif-1', 'notif-2']);
+
+// AI Services
+await client.ai.nlq({ query: 'Show me all active contacts' });
+await client.ai.chat({ message: 'Summarize this project', context: projectId });
+await client.ai.suggest({ object: 'contact', field: 'industry' });
+await client.ai.insights({ object: 'sales', recordId: dealId });
+
+// Internationalization
+await client.i18n.getLocales();
+await client.i18n.getTranslations('zh-CN');
+await client.i18n.getFieldLabels('contact', 'zh-CN');
+
+// Analytics
+await client.analytics.query({ object: 'sales', aggregations: ['sum:amount'] });
+await client.analytics.meta('sales');
+
+// Automation
+await client.automation.trigger('send_welcome_email', { userId });
+
+// File Storage
+await client.storage.upload(fileData, 'user');
+await client.storage.getDownloadUrl('file-123');
+```
+
+## Testing
+
+### Unit Tests
+
+```bash
+pnpm test
+```
+
+### Integration Tests
+
+**Note:** Integration tests require a running ObjectStack server. The server is provided by a separate repository and must be set up independently.
+
+```bash
+# Start test server (in the ObjectStack server repository)
+# Follow that project's documentation for test server setup
+# Example: cd /path/to/objectstack-server && pnpm dev:test
+
+# Run integration tests (in this repository)
+cd packages/client
+pnpm test:integration
+```
+
+See [CLIENT_SERVER_INTEGRATION_TESTS.md](./CLIENT_SERVER_INTEGRATION_TESTS.md) for detailed test specifications.
+

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { FilterCondition, QueryAST, SortNode, AggregationNode } from '@objectstack/spec/data';
-import { GetDiscoveryResponse, StandardErrorCode, ErrorCategory, GetMetaTypesResponse, GetMetaItemsResponse, MetadataCacheRequest, MetadataCacheResponse, LoginRequest, SessionResponse, FileUploadResponse, BatchUpdateRequest, BatchUpdateResponse, BatchOptions } from '@objectstack/spec/api';
-export { BatchOperationResult, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, DeleteManyRequest, ErrorCategory, GetDiscoveryResponse, GetMetaItemsResponse, GetMetaTypesResponse, MetadataCacheRequest, MetadataCacheResponse, StandardErrorCode, UpdateManyRequest } from '@objectstack/spec/api';
+import { GetDiscoveryResponse, StandardErrorCode, ErrorCategory, GetMetaTypesResponse, GetMetaItemsResponse, MetadataCacheRequest, MetadataCacheResponse, LoginRequest, SessionResponse, RegisterRequest, FileUploadResponse, 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, BatchUpdateRequest, BatchUpdateResponse, BatchOptions } from '@objectstack/spec/api';
+export { AiChatRequest, AiChatResponse, AiInsightsRequest, AiInsightsResponse, AiNlqRequest, AiNlqResponse, AiSuggestRequest, AiSuggestResponse, BatchOperationResult, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, CheckPermissionRequest, CheckPermissionResponse, CreateViewResponse, DeleteManyRequest, DeleteViewResponse, ErrorCategory, GetDiscoveryResponse, GetEffectivePermissionsResponse, GetFieldLabelsResponse, GetLocalesResponse, GetMetaItemsResponse, GetMetaTypesResponse, GetObjectPermissionsResponse, GetPresenceResponse, GetTranslationsResponse, GetViewResponse, GetWorkflowConfigResponse, GetWorkflowStateResponse, ListNotificationsResponse, ListViewsResponse, MetadataCacheRequest, MetadataCacheResponse, RealtimeConnectRequest, RealtimeConnectResponse, RealtimeSubscribeRequest, RealtimeSubscribeResponse, RefreshTokenRequest, RegisterDeviceRequest, RegisterDeviceResponse, RegisterRequest, StandardErrorCode, UpdateManyRequest, UpdateViewResponse, WorkflowApproveRequest, WorkflowApproveResponse, WorkflowRejectRequest, WorkflowRejectResponse, WorkflowTransitionRequest, WorkflowTransitionResponse } from '@objectstack/spec/api';
 import { Logger } from '@objectstack/core';
 
 /**
@@ -62,6 +62,26 @@ declare class FilterBuilder<T = any> {
      * IS NOT NULL filter: field IS NOT NULL
      */
     isNotNull<K extends keyof T>(field: K): this;
+    /**
+     * BETWEEN filter: field BETWEEN min AND max
+     */
+    between<K extends keyof T>(field: K, min: T[K], max: T[K]): this;
+    /**
+     * CONTAINS filter: field contains value (case-insensitive LIKE %value%)
+     */
+    contains<K extends keyof T>(field: K, value: string): this;
+    /**
+     * STARTS WITH filter: field starts with value (LIKE value%)
+     */
+    startsWith<K extends keyof T>(field: K, value: string): this;
+    /**
+     * ENDS WITH filter: field ends with value (LIKE %value)
+     */
+    endsWith<K extends keyof T>(field: K, value: string): this;
+    /**
+     * EXISTS filter: field is not null (alias for isNotNull)
+     */
+    exists<K extends keyof T>(field: K): this;
     /**
      * Build the filter condition
      */
@@ -110,6 +130,25 @@ declare class QueryBuilder<T = any> {
      * Group by fields
      */
     groupBy<K extends keyof T>(...fields: K[]): this;
+    /**
+     * Expand (eager-load) a related object with an optional sub-query
+     */
+    expand(relation: string, subQuery?: Partial<QueryAST>): this;
+    /**
+     * Add full-text search
+     */
+    search(query: string, options?: {
+        fields?: string[];
+        fuzzy?: boolean;
+    }): this;
+    /**
+     * Set cursor for keyset pagination
+     */
+    cursor(cursor: Record<string, any>): this;
+    /**
+     * Enable SELECT DISTINCT
+     */
+    distinct(): this;
     /**
      * Build the final query AST
      */
@@ -218,33 +257,31 @@ declare class ObjectStackClient {
         version: string;
         apiName: string;
         capabilities?: {
+            graphql: boolean;
             search: boolean;
+            websockets: boolean;
             files: boolean;
-            graphql: boolean;
-            notifications: boolean;
             analytics: boolean;
-            hub: boolean;
             ai: boolean;
-            i18n: boolean;
             workflow: boolean;
-            websockets: boolean;
+            notifications: boolean;
+            i18n: boolean;
         } | undefined;
         endpoints?: {
             data: string;
             metadata: string;
-            auth: string;
-            graphql?: string | undefined;
-            notifications?: string | undefined;
-            storage?: string | undefined;
+            ui?: string | undefined;
+            auth?: string | undefined;
             automation?: string | undefined;
+            storage?: string | undefined;
             analytics?: string | undefined;
-            hub?: string | undefined;
+            graphql?: string | undefined;
+            packages?: string | undefined;
+            workflow?: string | undefined;
             realtime?: string | undefined;
+            notifications?: string | undefined;
             ai?: string | undefined;
             i18n?: string | undefined;
-            ui?: string | undefined;
-            workflow?: string | undefined;
-            packages?: string | undefined;
         } | undefined;
     }>;
     /**
@@ -298,18 +335,6 @@ declare class ObjectStackClient {
         meta: (cube: string) => Promise<any>;
         explain: (payload: any) => Promise<any>;
     };
-    /**
-     * Hub Management Services
-     */
-    hub: {
-        spaces: {
-            list: () => Promise<any>;
-            create: (payload: any) => Promise<any>;
-        };
-        plugins: {
-            install: (pkg: string, version?: string) => Promise<any>;
-        };
-    };
     /**
      * Package Management Services
      *
@@ -384,6 +409,14 @@ declare class ObjectStackClient {
         login: (request: LoginRequest) => Promise<SessionResponse>;
         logout: () => Promise<void>;
         me: () => Promise<SessionResponse>;
+        /**
+         * Register a new user account
+         */
+        register: (request: RegisterRequest) => Promise<SessionResponse>;
+        /**
+         * Refresh an authentication token
+         */
+        refreshToken: (refreshToken: string) => Promise<SessionResponse>;
     };
     /**
      * Storage Services
@@ -398,6 +431,181 @@ declare class ObjectStackClient {
     automation: {
         trigger: (triggerName: string, payload: any) => Promise<any>;
     };
+    /**
+     * Permissions Services
+     */
+    permissions: {
+        /**
+         * Check if current user has permission for an action on an object
+         */
+        check: (request: CheckPermissionRequest) => Promise<CheckPermissionResponse>;
+        /**
+         * Get all permissions for a specific object
+         */
+        getObjectPermissions: (object: string) => Promise<GetObjectPermissionsResponse>;
+        /**
+         * Get effective permissions for the current user
+         */
+        getEffectivePermissions: () => Promise<GetEffectivePermissionsResponse>;
+    };
+    /**
+     * Realtime Services
+     */
+    realtime: {
+        /**
+         * Establish a realtime connection
+         */
+        connect: (request?: RealtimeConnectRequest) => Promise<RealtimeConnectResponse>;
+        /**
+         * Disconnect from realtime services
+         */
+        disconnect: () => Promise<void>;
+        /**
+         * Subscribe to a channel
+         */
+        subscribe: (request: RealtimeSubscribeRequest) => Promise<RealtimeSubscribeResponse>;
+        /**
+         * Unsubscribe from a channel
+         */
+        unsubscribe: (subscriptionId: string) => Promise<void>;
+        /**
+         * Set presence state on a channel
+         */
+        setPresence: (channel: string, state: SetPresenceRequest["state"]) => Promise<void>;
+        /**
+         * Get presence information for a channel
+         */
+        getPresence: (channel: string) => Promise<GetPresenceResponse>;
+    };
+    /**
+     * Workflow Services
+     */
+    workflow: {
+        /**
+         * Get workflow configuration for an object
+         */
+        getConfig: (object: string) => Promise<GetWorkflowConfigResponse>;
+        /**
+         * Get current workflow state for a record
+         */
+        getState: (object: string, recordId: string) => Promise<GetWorkflowStateResponse>;
+        /**
+         * Execute a workflow state transition
+         */
+        transition: (request: WorkflowTransitionRequest) => Promise<WorkflowTransitionResponse>;
+        /**
+         * Approve a workflow step
+         */
+        approve: (request: WorkflowApproveRequest) => Promise<WorkflowApproveResponse>;
+        /**
+         * Reject a workflow step
+         */
+        reject: (request: WorkflowRejectRequest) => Promise<WorkflowRejectResponse>;
+    };
+    /**
+     * Views CRUD Services
+     */
+    views: {
+        /**
+         * List views for an object
+         */
+        list: (object: string, type?: "list" | "form") => Promise<ListViewsResponse>;
+        /**
+         * Get a specific view
+         */
+        get: (object: string, viewId: string) => Promise<GetViewResponse>;
+        /**
+         * Create a new view
+         */
+        create: (object: string, data: CreateViewRequest["data"]) => Promise<CreateViewResponse>;
+        /**
+         * Update an existing view
+         */
+        update: (object: string, viewId: string, data: UpdateViewRequest["data"]) => Promise<UpdateViewResponse>;
+        /**
+         * Delete a view
+         */
+        delete: (object: string, viewId: string) => Promise<DeleteViewResponse>;
+    };
+    /**
+     * Notification Services
+     */
+    notifications: {
+        /**
+         * Register a device for push notifications
+         */
+        registerDevice: (request: RegisterDeviceRequest) => Promise<RegisterDeviceResponse>;
+        /**
+         * Unregister a device from push notifications
+         */
+        unregisterDevice: (deviceId: string) => Promise<UnregisterDeviceResponse>;
+        /**
+         * Get notification preferences for the current user
+         */
+        getPreferences: () => Promise<GetNotificationPreferencesResponse>;
+        /**
+         * Update notification preferences
+         */
+        updatePreferences: (preferences: UpdateNotificationPreferencesRequest["preferences"]) => Promise<UpdateNotificationPreferencesResponse>;
+        /**
+         * List notifications for the current user
+         */
+        list: (options?: {
+            read?: boolean;
+            type?: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<ListNotificationsResponse>;
+        /**
+         * Mark specific notifications as read
+         */
+        markRead: (ids: string[]) => Promise<MarkNotificationsReadResponse>;
+        /**
+         * Mark all notifications as read
+         */
+        markAllRead: () => Promise<MarkAllNotificationsReadResponse>;
+    };
+    /**
+     * AI Services
+     */
+    ai: {
+        /**
+         * Natural language query — converts natural language to structured query
+         */
+        nlq: (request: AiNlqRequest) => Promise<AiNlqResponse>;
+        /**
+         * Multi-turn AI chat
+         */
+        chat: (request: AiChatRequest) => Promise<AiChatResponse>;
+        /**
+         * AI-powered field value suggestions
+         */
+        suggest: (request: AiSuggestRequest) => Promise<AiSuggestResponse>;
+        /**
+         * AI-powered data insights
+         */
+        insights: (request: AiInsightsRequest) => Promise<AiInsightsResponse>;
+    };
+    /**
+     * Internationalization Services
+     */
+    i18n: {
+        /**
+         * Get available locales
+         */
+        getLocales: () => Promise<GetLocalesResponse>;
+        /**
+         * Get translations for a locale
+         */
+        getTranslations: (locale: string, options?: {
+            namespace?: string;
+            keys?: string[];
+        }) => Promise<GetTranslationsResponse>;
+        /**
+         * Get translated field labels for an object
+         */
+        getFieldLabels: (object: string, locale: string) => Promise<GetFieldLabelsResponse>;
+    };
     /**
      * Data Operations
      */