@objectstack/client 4.0.2 → 4.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/client",
-  "version": "4.0.2",
+  "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.2",
-    "@objectstack/spec": "4.0.2"
+    "@objectstack/core": "4.0.3",
+    "@objectstack/spec": "4.0.3"
   },
   "devDependencies": {
-    "@hono/node-server": "^1.19.12",
-    "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.2",
-    "@objectstack/hono": "4.0.2",
-    "@objectstack/objectql": "4.0.2",
-    "@objectstack/plugin-hono-server": "4.0.2",
-    "@objectstack/plugin-msw": "4.0.2",
-    "@objectstack/runtime": "4.0.2"
+    "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/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,
@@ -88,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.
@@ -228,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 });
   }
 
@@ -887,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
    */
@@ -1789,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,

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 = [];
+  }
+}