@objectstack/client 4.0.2 → 4.0.3

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/client@4.0.2 build /home/runner/work/framework/framework/packages/client
+> @objectstack/client@4.0.3 build /home/runner/work/framework/framework/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     54.51 KB
-ESM dist/index.mjs.map 110.18 KB
-ESM ⚡️ Build success in 31ms
-CJS dist/index.js     55.68 KB
-CJS dist/index.js.map 110.24 KB
-CJS ⚡️ Build success in 31ms
+ESM dist/index.mjs     58.24 KB
+ESM dist/index.mjs.map 118.84 KB
+ESM ⚡️ Build success in 28ms
+CJS dist/index.js     59.44 KB
+CJS dist/index.js.map 118.90 KB
+CJS ⚡️ Build success in 28ms
 DTS Build start
-DTS ⚡️ Build success in 3191ms
-DTS dist/index.d.mts 33.94 KB
-DTS dist/index.d.ts  33.94 KB
+DTS ⚡️ Build success in 2598ms
+DTS dist/index.d.mts 36.26 KB
+DTS dist/index.d.ts  36.26 KB

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @objectstack/client
 
+## 4.0.3
+
+### Patch Changes
+
+- @objectstack/spec@4.0.3
+- @objectstack/core@4.0.3
+
 ## 4.0.2
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,7 +1,77 @@
 import { FilterCondition, QueryAST, SortNode, AggregationNode } from '@objectstack/spec/data';
-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, 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';
+import { MetadataEvent, DataEvent, 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, 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, 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';
+import { RealtimeEventPayload } from '@objectstack/spec/contracts';
+
+/**
+ * Realtime API Module for ObjectStackClient
+ *
+ * Provides real-time event subscription capabilities using long-polling.
+ * For production WebSocket/SSE support, extend with transport adapters.
+ */
+
+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;
+}
+type RealtimeEventHandler = (event: RealtimeEventPayload) => void;
+/**
+ * Realtime API for subscribing to server events
+ *
+ * Note: Currently uses in-memory adapter. WebSocket/SSE transport planned for future.
+ */
+declare class RealtimeAPI {
+    private _baseUrl;
+    private _token?;
+    private subscriptions;
+    private pollInterval?;
+    private eventBuffer;
+    constructor(baseUrl: string, token?: string);
+    /**
+     * Subscribe to metadata events
+     * Returns an unsubscribe function
+     */
+    subscribeMetadata(type: string, callback: (event: MetadataEvent) => void, options?: {
+        packageId?: string;
+    }): () => void;
+    /**
+     * Subscribe to data record events
+     * Returns an unsubscribe function
+     */
+    subscribeData(object: string, callback: (event: DataEvent) => void, options?: {
+        recordId?: string;
+    }): () => void;
+    /**
+     * Emit an event to all matching subscriptions (client-side only)
+     * This is used for in-process event delivery
+     */
+    private emitEvent;
+    /**
+     * Start polling for events (fallback mechanism)
+     * In production, this would be replaced with WebSocket/SSE
+     */
+    private startPolling;
+    /**
+     * Stop polling for events
+     */
+    private stopPolling;
+    /**
+     * Internal method to buffer events from server
+     * This would be called by WebSocket/SSE handlers in production
+     */
+    _bufferEvent(event: RealtimeEventPayload): void;
+    /**
+     * Disconnect and clean up all subscriptions
+     */
+    disconnect(): void;
+}
 
 /**
  * Type-Safe Query Builder
@@ -299,6 +369,7 @@ declare class ObjectStackClient {
     private fetchImpl;
     private discoveryInfo?;
     private logger;
+    private realtimeAPI;
     constructor(config: ClientConfig);
     /**
      * Initialize the client by discovering server capabilities.
@@ -614,6 +685,11 @@ declare class ObjectStackClient {
             get: (flowName: string, runId: string) => Promise<any>;
         };
     };
+    /**
+     * Event Subscription API
+     * Provides real-time event subscriptions for metadata and data changes
+     */
+    get events(): RealtimeAPI;
     /**
      * Permissions Services
      */
@@ -938,4 +1014,4 @@ declare class ObjectStackClient {
     private getRoute;
 }
 
-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 };
+export { type ApiRouteType, type ClientConfig, type CreateDataResult, type DeleteDataResult, type DiscoveryResult, FilterBuilder, type GetDataResult, ObjectStackClient, type PaginatedResult, QueryBuilder, type QueryOptions, type QueryOptionsV2, RealtimeAPI, type RealtimeEventHandler, type RealtimeSubscriptionFilter, type StandardError, type UpdateDataResult, createFilter, createQuery };

package/dist/index.d.ts

@@ -1,7 +1,77 @@
 import { FilterCondition, QueryAST, SortNode, AggregationNode } from '@objectstack/spec/data';
-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, 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';
+import { MetadataEvent, DataEvent, 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, 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, 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';
+import { RealtimeEventPayload } from '@objectstack/spec/contracts';
+
+/**
+ * Realtime API Module for ObjectStackClient
+ *
+ * Provides real-time event subscription capabilities using long-polling.
+ * For production WebSocket/SSE support, extend with transport adapters.
+ */
+
+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;
+}
+type RealtimeEventHandler = (event: RealtimeEventPayload) => void;
+/**
+ * Realtime API for subscribing to server events
+ *
+ * Note: Currently uses in-memory adapter. WebSocket/SSE transport planned for future.
+ */
+declare class RealtimeAPI {
+    private _baseUrl;
+    private _token?;
+    private subscriptions;
+    private pollInterval?;
+    private eventBuffer;
+    constructor(baseUrl: string, token?: string);
+    /**
+     * Subscribe to metadata events
+     * Returns an unsubscribe function
+     */
+    subscribeMetadata(type: string, callback: (event: MetadataEvent) => void, options?: {
+        packageId?: string;
+    }): () => void;
+    /**
+     * Subscribe to data record events
+     * Returns an unsubscribe function
+     */
+    subscribeData(object: string, callback: (event: DataEvent) => void, options?: {
+        recordId?: string;
+    }): () => void;
+    /**
+     * Emit an event to all matching subscriptions (client-side only)
+     * This is used for in-process event delivery
+     */
+    private emitEvent;
+    /**
+     * Start polling for events (fallback mechanism)
+     * In production, this would be replaced with WebSocket/SSE
+     */
+    private startPolling;
+    /**
+     * Stop polling for events
+     */
+    private stopPolling;
+    /**
+     * Internal method to buffer events from server
+     * This would be called by WebSocket/SSE handlers in production
+     */
+    _bufferEvent(event: RealtimeEventPayload): void;
+    /**
+     * Disconnect and clean up all subscriptions
+     */
+    disconnect(): void;
+}
 
 /**
  * Type-Safe Query Builder
@@ -299,6 +369,7 @@ declare class ObjectStackClient {
     private fetchImpl;
     private discoveryInfo?;
     private logger;
+    private realtimeAPI;
     constructor(config: ClientConfig);
     /**
      * Initialize the client by discovering server capabilities.
@@ -614,6 +685,11 @@ declare class ObjectStackClient {
             get: (flowName: string, runId: string) => Promise<any>;
         };
     };
+    /**
+     * Event Subscription API
+     * Provides real-time event subscriptions for metadata and data changes
+     */
+    get events(): RealtimeAPI;
     /**
      * Permissions Services
      */
@@ -938,4 +1014,4 @@ declare class ObjectStackClient {
     private getRoute;
 }
 
-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 };
+export { type ApiRouteType, type ClientConfig, type CreateDataResult, type DeleteDataResult, type DiscoveryResult, FilterBuilder, type GetDataResult, ObjectStackClient, type PaginatedResult, QueryBuilder, type QueryOptions, type QueryOptionsV2, RealtimeAPI, type RealtimeEventHandler, type RealtimeSubscriptionFilter, type StandardError, type UpdateDataResult, createFilter, createQuery };

package/dist/index.js

@@ -23,6 +23,7 @@ __export(index_exports, {
   FilterBuilder: () => FilterBuilder,
   ObjectStackClient: () => ObjectStackClient,
   QueryBuilder: () => QueryBuilder,
+  RealtimeAPI: () => RealtimeAPI,
   createFilter: () => createFilter,
   createQuery: () => createQuery
 });
@@ -30,6 +31,135 @@ module.exports = __toCommonJS(index_exports);
 var import_data = require("@objectstack/spec/data");
 var import_core = require("@objectstack/core");
 
+// src/realtime-api.ts
+var RealtimeAPI = class {
+  constructor(baseUrl, token) {
+    this.subscriptions = /* @__PURE__ */ new Map();
+    this.eventBuffer = [];
+    this._baseUrl = baseUrl;
+    this._token = token;
+  }
+  /**
+   * Subscribe to metadata events
+   * Returns an unsubscribe function
+   */
+  subscribeMetadata(type, callback, options) {
+    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) => {
+        if (event.type.startsWith("metadata.")) {
+          callback(event);
+        }
+      }
+    });
+    this.startPolling();
+    return () => {
+      this.subscriptions.delete(subscriptionId);
+      if (this.subscriptions.size === 0) {
+        this.stopPolling();
+      }
+    };
+  }
+  /**
+   * Subscribe to data record events
+   * Returns an unsubscribe function
+   */
+  subscribeData(object, callback, options) {
+    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) => {
+        if (event.type.startsWith("data.") && event.object === object) {
+          if (!options?.recordId || event.payload?.recordId === options.recordId) {
+            callback(event);
+          }
+        }
+      }
+    });
+    this.startPolling();
+    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
+   */
+  emitEvent(event) {
+    for (const sub of this.subscriptions.values()) {
+      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?.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
+   */
+  startPolling() {
+    if (this.pollInterval) return;
+    this.pollInterval = setInterval(() => {
+      while (this.eventBuffer.length > 0) {
+        const event = this.eventBuffer.shift();
+        if (event) {
+          this.emitEvent(event);
+        }
+      }
+    }, 2e3);
+  }
+  /**
+   * Stop polling for events
+   */
+  stopPolling() {
+    if (this.pollInterval) {
+      clearInterval(this.pollInterval);
+      this.pollInterval = void 0;
+    }
+  }
+  /**
+   * Internal method to buffer events from server
+   * This would be called by WebSocket/SSE handlers in production
+   */
+  _bufferEvent(event) {
+    this.eventBuffer.push(event);
+  }
+  /**
+   * Disconnect and clean up all subscriptions
+   */
+  disconnect() {
+    this.stopPolling();
+    this.subscriptions.clear();
+    this.eventBuffer = [];
+  }
+};
+
 // src/query-builder.ts
 var FilterBuilder = class {
   constructor() {
@@ -1500,6 +1630,7 @@ var ObjectStackClient = class {
       level: config.debug ? "debug" : "info",
       format: "pretty"
     });
+    this.realtimeAPI = new RealtimeAPI(this.baseUrl, this.token);
     this.logger.debug("ObjectStack client created", { baseUrl: this.baseUrl });
   }
   /**
@@ -1570,6 +1701,13 @@ var ObjectStackClient = class {
     }
     return result;
   }
+  /**
+   * Event Subscription API
+   * Provides real-time event subscriptions for metadata and data changes
+   */
+  get events() {
+    return this.realtimeAPI;
+  }
   /**
    * Private Helpers
    */
@@ -1674,6 +1812,7 @@ var ObjectStackClient = class {
   FilterBuilder,
   ObjectStackClient,
   QueryBuilder,
+  RealtimeAPI,
   createFilter,
   createQuery
 });