@objectstack/client 4.0.1 → 4.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/client",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "license": "Apache-2.0",
   "description": "Official Client SDK for ObjectStack Protocol",
   "main": "dist/index.js",
@@ -13,20 +13,20 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "4.0.1",
-    "@objectstack/spec": "4.0.1"
+    "@objectstack/core": "4.0.3",
+    "@objectstack/spec": "4.0.3"
   },
   "devDependencies": {
-    "@hono/node-server": "^1.19.11",
-    "msw": "^2.12.14",
+    "@hono/node-server": "^1.19.14",
+    "msw": "^2.13.2",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.2",
-    "@objectstack/driver-memory": "4.0.1",
-    "@objectstack/hono": "4.0.1",
-    "@objectstack/objectql": "4.0.1",
-    "@objectstack/plugin-hono-server": "4.0.1",
-    "@objectstack/plugin-msw": "4.0.1",
-    "@objectstack/runtime": "4.0.1"
+    "vitest": "^4.1.4",
+    "@objectstack/driver-memory": "4.0.3",
+    "@objectstack/hono": "4.0.3",
+    "@objectstack/objectql": "4.0.3",
+    "@objectstack/plugin-hono-server": "4.0.3",
+    "@objectstack/plugin-msw": "4.0.3",
+    "@objectstack/runtime": "4.0.3"
   },
   "scripts": {
     "build": "tsup --config ../../tsup.config.ts",

package/src/client.test.ts

@@ -486,18 +486,10 @@ describe('AI namespace', () => {
         expect(opts.method).toBe('POST');
     });
 
-    it('should chat with AI', async () => {
-        const { client, fetchMock } = createMockClient({
-            success: true,
-            data: { message: 'Here are the results...', conversationId: 'conv-1' }
-        });
-        const result = await client.ai.chat({
-            message: 'Show me customer stats',
-            conversationId: 'conv-1'
-        });
-        expect(result.conversationId).toBe('conv-1');
-        const body = JSON.parse(fetchMock.mock.calls[0][1].body);
-        expect(body.message).toBe('Show me customer stats');
+    it('should not expose chat method (use Vercel AI SDK useChat directly)', () => {
+        const { client } = createMockClient({ success: true, data: {} });
+        // ai.chat was removed — consumers should use @ai-sdk/react useChat() directly
+        expect(client.ai).not.toHaveProperty('chat');
     });
 
     it('should get AI suggestions', async () => {

package/src/index.ts

@@ -1,9 +1,9 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { QueryAST, SortNode, AggregationNode, isFilterAST } from '@objectstack/spec/data';
-import { 
-  BatchUpdateRequest, 
-  BatchUpdateResponse, 
+import {
+  BatchUpdateRequest,
+  BatchUpdateResponse,
   UpdateManyRequest,
   DeleteManyRequest,
   BatchOptions,
@@ -62,8 +62,6 @@ import {
   MarkAllNotificationsReadResponse,
   AiNlqRequest,
   AiNlqResponse,
-  AiChatRequest,
-  AiChatResponse,
   AiSuggestRequest,
   AiSuggestResponse,
   AiInsightsRequest,
@@ -90,6 +88,7 @@ import {
   ApiRoutes,
 } from '@objectstack/spec/api';
 import { Logger, createLogger } from '@objectstack/core';
+import { RealtimeAPI } from './realtime-api';
 
 /**
  * Route types that the client can resolve.
@@ -230,18 +229,22 @@ export class ObjectStackClient {
   private fetchImpl: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
   private discoveryInfo?: DiscoveryResult;
   private logger: Logger;
+  private realtimeAPI: RealtimeAPI;
 
   constructor(config: ClientConfig) {
     this.baseUrl = config.baseUrl.replace(/\/$/, ''); // Remove trailing slash
     this.token = config.token;
     this.fetchImpl = config.fetch || globalThis.fetch.bind(globalThis);
-    
+
     // Initialize logger
-    this.logger = config.logger || createLogger({ 
+    this.logger = config.logger || createLogger({
       level: config.debug ? 'debug' : 'info',
       format: 'pretty'
     });
-    
+
+    // Initialize realtime API
+    this.realtimeAPI = new RealtimeAPI(this.baseUrl, this.token);
+
     this.logger.debug('ObjectStack client created', { baseUrl: this.baseUrl });
   }
 
@@ -361,10 +364,15 @@ export class ObjectStackClient {
      * Get a specific metadata item by type and name
      * @param type - Metadata type (e.g., 'object', 'plugin')
      * @param name - Item name (snake_case identifier)
+     * @param options - Optional filters (e.g., packageId to scope by package)
      */
-    getItem: async (type: string, name: string) => {
+    getItem: async (type: string, name: string, options?: { packageId?: string }) => {
         const route = this.getRoute('metadata');
-        const res = await this.fetch(`${this.baseUrl}${route}/${type}/${name}`);
+        const params = new URLSearchParams();
+        if (options?.packageId) params.set('package', options.packageId);
+        const qs = params.toString();
+        const url = `${this.baseUrl}${route}/${type}/${name}${qs ? `?${qs}` : ''}`;
+        const res = await this.fetch(url);
         return this.unwrapResponse(res);
     },
 
@@ -382,6 +390,19 @@ export class ObjectStackClient {
         });
         return this.unwrapResponse(res);
     },
+
+    /**
+     * Delete a metadata item
+     * @param type - Metadata type (e.g., 'object', 'plugin')
+     * @param name - Item name (snake_case identifier)
+     */
+    deleteItem: async (type: string, name: string): Promise<{ type: string; name: string; deleted: boolean }> => {
+        const route = this.getRoute('metadata');
+        const res = await this.fetch(`${this.baseUrl}${route}/${encodeURIComponent(type)}/${encodeURIComponent(name)}`, {
+            method: 'DELETE',
+        });
+        return this.unwrapResponse(res);
+    },
     
     /**
      * Get object metadata with cache support
@@ -871,6 +892,14 @@ export class ObjectStackClient {
       },
   };
 
+  /**
+   * Event Subscription API
+   * Provides real-time event subscriptions for metadata and data changes
+   */
+  get events() {
+    return this.realtimeAPI;
+  }
+
   /**
    * Permissions Services
    */
@@ -1209,17 +1238,7 @@ export class ObjectStackClient {
       return this.unwrapResponse<AiNlqResponse>(res);
     },
 
-    /**
-     * Multi-turn AI chat
-     */
-    chat: async (request: AiChatRequest): Promise<AiChatResponse> => {
-      const route = this.getRoute('ai');
-      const res = await this.fetch(`${this.baseUrl}${route}/chat`, {
-        method: 'POST',
-        body: JSON.stringify(request)
-      });
-      return this.unwrapResponse<AiChatResponse>(res);
-    },
+    // AI chat method removed — use Vercel AI SDK `useChat()` / `@ai-sdk/react` directly.
 
     /**
      * AI-powered field value suggestions
@@ -1783,6 +1802,9 @@ export class ObjectStackClient {
 // Re-export type-safe query builder
 export { QueryBuilder, FilterBuilder, createQuery, createFilter } from './query-builder';
 
+// Re-export realtime API types
+export { RealtimeAPI, RealtimeSubscriptionFilter, RealtimeEventHandler } from './realtime-api';
+
 // Re-export commonly used types from @objectstack/spec/api for convenience
 export type {
   BatchUpdateRequest,
@@ -1826,8 +1848,6 @@ export type {
   ListNotificationsResponse,
   AiNlqRequest,
   AiNlqResponse,
-  AiChatRequest,
-  AiChatResponse,
   AiSuggestRequest,
   AiSuggestResponse,
   AiInsightsRequest,

package/src/realtime-api.ts

@@ -0,0 +1,208 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Realtime API Module for ObjectStackClient
+ *
+ * Provides real-time event subscription capabilities using long-polling.
+ * For production WebSocket/SSE support, extend with transport adapters.
+ */
+
+import type { RealtimeEventPayload } from '@objectstack/spec/contracts';
+import type { MetadataEvent, DataEvent } from '@objectstack/spec/api';
+
+export interface RealtimeSubscriptionFilter {
+  /** Metadata/object type filter */
+  type?: string;
+  /** Package ID filter */
+  packageId?: string;
+  /** Event types to listen for */
+  eventTypes?: string[];
+  /** Record ID filter (for data events) */
+  recordId?: string;
+}
+
+export type RealtimeEventHandler = (event: RealtimeEventPayload) => void;
+
+/**
+ * Realtime API for subscribing to server events
+ *
+ * Note: Currently uses in-memory adapter. WebSocket/SSE transport planned for future.
+ */
+export class RealtimeAPI {
+  // @ts-expect-error - Reserved for future WebSocket/SSE implementation
+  private _baseUrl: string;
+  // @ts-expect-error - Reserved for future WebSocket/SSE implementation
+  private _token?: string;
+  private subscriptions = new Map<string, {
+    filter: RealtimeSubscriptionFilter;
+    handler: RealtimeEventHandler;
+  }>();
+  private pollInterval?: ReturnType<typeof setInterval>;
+  private eventBuffer: RealtimeEventPayload[] = [];
+
+  constructor(baseUrl: string, token?: string) {
+    this._baseUrl = baseUrl;
+    this._token = token;
+  }
+
+  /**
+   * Subscribe to metadata events
+   * Returns an unsubscribe function
+   */
+  subscribeMetadata(
+    type: string,
+    callback: (event: MetadataEvent) => void,
+    options?: { packageId?: string }
+  ): () => void {
+    const subscriptionId = `metadata-${type}-${Date.now()}`;
+
+    this.subscriptions.set(subscriptionId, {
+      filter: {
+        type,
+        packageId: options?.packageId,
+        eventTypes: [
+          `metadata.${type}.created`,
+          `metadata.${type}.updated`,
+          `metadata.${type}.deleted`
+        ]
+      },
+      handler: (event) => {
+        // Type guard and filter
+        if (event.type.startsWith('metadata.')) {
+          callback(event as any as MetadataEvent);
+        }
+      }
+    });
+
+    // Start polling if not already started
+    this.startPolling();
+
+    // Return unsubscribe function
+    return () => {
+      this.subscriptions.delete(subscriptionId);
+      if (this.subscriptions.size === 0) {
+        this.stopPolling();
+      }
+    };
+  }
+
+  /**
+   * Subscribe to data record events
+   * Returns an unsubscribe function
+   */
+  subscribeData(
+    object: string,
+    callback: (event: DataEvent) => void,
+    options?: { recordId?: string }
+  ): () => void {
+    const subscriptionId = `data-${object}-${Date.now()}`;
+
+    this.subscriptions.set(subscriptionId, {
+      filter: {
+        type: object,
+        recordId: options?.recordId,
+        eventTypes: [
+          'data.record.created',
+          'data.record.updated',
+          'data.record.deleted'
+        ]
+      },
+      handler: (event) => {
+        // Type guard and filter
+        if (event.type.startsWith('data.') && event.object === object) {
+          if (!options?.recordId || (event.payload as any)?.recordId === options.recordId) {
+            callback(event as any as DataEvent);
+          }
+        }
+      }
+    });
+
+    // Start polling if not already started
+    this.startPolling();
+
+    // Return unsubscribe function
+    return () => {
+      this.subscriptions.delete(subscriptionId);
+      if (this.subscriptions.size === 0) {
+        this.stopPolling();
+      }
+    };
+  }
+
+  /**
+   * Emit an event to all matching subscriptions (client-side only)
+   * This is used for in-process event delivery
+   */
+  private emitEvent(event: RealtimeEventPayload): void {
+    for (const sub of this.subscriptions.values()) {
+      // Check if event matches subscription filters
+      const matchesType = !sub.filter.type ||
+        event.type.includes(sub.filter.type) ||
+        event.object === sub.filter.type;
+
+      const matchesEventType = !sub.filter.eventTypes?.length ||
+        sub.filter.eventTypes.includes(event.type);
+
+      const matchesPackage = !sub.filter.packageId ||
+        (event.payload as any)?.packageId === sub.filter.packageId;
+
+      if (matchesType && matchesEventType && matchesPackage) {
+        try {
+          sub.handler(event);
+        } catch (error) {
+          console.error('Error in realtime event handler:', error);
+        }
+      }
+    }
+  }
+
+  /**
+   * Start polling for events (fallback mechanism)
+   * In production, this would be replaced with WebSocket/SSE
+   */
+  private startPolling(): void {
+    if (this.pollInterval) return;
+
+    // For now, we rely on the in-memory adapter within the same process
+    // Events are delivered synchronously via the IRealtimeService
+    // This polling is a placeholder for future WebSocket/SSE implementation
+
+    // Poll every 2 seconds for buffered events
+    this.pollInterval = setInterval(() => {
+      // Process any buffered events
+      while (this.eventBuffer.length > 0) {
+        const event = this.eventBuffer.shift();
+        if (event) {
+          this.emitEvent(event);
+        }
+      }
+    }, 2000);
+  }
+
+  /**
+   * Stop polling for events
+   */
+  private stopPolling(): void {
+    if (this.pollInterval) {
+      clearInterval(this.pollInterval);
+      this.pollInterval = undefined;
+    }
+  }
+
+  /**
+   * Internal method to buffer events from server
+   * This would be called by WebSocket/SSE handlers in production
+   */
+  _bufferEvent(event: RealtimeEventPayload): void {
+    this.eventBuffer.push(event);
+  }
+
+  /**
+   * Disconnect and clean up all subscriptions
+   */
+  disconnect(): void {
+    this.stopPolling();
+    this.subscriptions.clear();
+    this.eventBuffer = [];
+  }
+}