@objectstack/client 4.0.2 → 4.0.4

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.4 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.57 KB
+ESM dist/index.mjs.map 119.43 KB
+ESM ⚡️ Build success in 33ms
+CJS dist/index.js     59.78 KB
+CJS dist/index.js.map 119.48 KB
+CJS ⚡️ Build success in 33ms
 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 3330ms
+DTS dist/index.d.mts 36.51 KB
+DTS dist/index.d.ts  36.51 KB

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @objectstack/client
 
+## 4.0.4
+
+### Patch Changes
+
+- Updated dependencies [326b66b]
+  - @objectstack/spec@4.0.4
+  - @objectstack/core@4.0.4
+
+## 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';
-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 { 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, AuthFeaturesConfig, AuthProviderInfo, BatchOperationResult, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, CheckPermissionRequest, CheckPermissionResponse, CreateFeedItemResponse, CreateViewResponse, DeleteFeedItemResponse, DeleteManyRequest, DeleteViewResponse, EmailPasswordConfigPublic, ErrorCategory, GetAuthConfigResponse, 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.
@@ -497,6 +568,11 @@ declare class ObjectStackClient {
      * Authentication Services
      */
     auth: {
+        /**
+         * Get authentication configuration
+         * Returns available auth providers and features
+         */
+        getConfig: () => Promise<unknown>;
         /**
          * Login with email and password
          * Uses better-auth endpoint: POST /sign-in/email
@@ -614,6 +690,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 +1019,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';
-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 { 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, AuthFeaturesConfig, AuthProviderInfo, BatchOperationResult, BatchOptions, BatchRecord, BatchUpdateRequest, BatchUpdateResponse, CheckPermissionRequest, CheckPermissionResponse, CreateFeedItemResponse, CreateViewResponse, DeleteFeedItemResponse, DeleteManyRequest, DeleteViewResponse, EmailPasswordConfigPublic, ErrorCategory, GetAuthConfigResponse, 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.
@@ -497,6 +568,11 @@ declare class ObjectStackClient {
      * Authentication Services
      */
     auth: {
+        /**
+         * Get authentication configuration
+         * Returns available auth providers and features
+         */
+        getConfig: () => Promise<unknown>;
         /**
          * Login with email and password
          * Uses better-auth endpoint: POST /sign-in/email
@@ -614,6 +690,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 +1019,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() {
@@ -534,6 +664,15 @@ var ObjectStackClient = class {
      * Authentication Services
      */
     this.auth = {
+      /**
+       * Get authentication configuration
+       * Returns available auth providers and features
+       */
+      getConfig: async () => {
+        const route = this.getRoute("auth");
+        const res = await this.fetch(`${this.baseUrl}${route}/config`);
+        return this.unwrapResponse(res);
+      },
       /**
        * Login with email and password
        * Uses better-auth endpoint: POST /sign-in/email
@@ -1500,6 +1639,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 });
   }
   /**
@@ -1510,6 +1650,18 @@ var ObjectStackClient = class {
     try {
       let data;
       try {
+        const discoveryUrl = `${this.baseUrl}/api/v1/discovery`;
+        this.logger.debug("Probing protocol-standard discovery endpoint", { url: discoveryUrl });
+        const res = await this.fetchImpl(discoveryUrl);
+        if (res.ok) {
+          const body = await res.json();
+          data = body.data || body;
+          this.logger.debug("Discovered via /api/v1/discovery");
+        }
+      } catch (e) {
+        this.logger.debug("Protocol-standard discovery probe failed", { error: e.message });
+      }
+      if (!data) {
         let wellKnownUrl;
         try {
           const url = new URL(this.baseUrl);
@@ -1517,22 +1669,10 @@ var ObjectStackClient = class {
         } catch {
           wellKnownUrl = "/.well-known/objectstack";
         }
-        this.logger.debug("Probing .well-known discovery", { url: wellKnownUrl });
+        this.logger.debug("Falling back to .well-known discovery", { url: wellKnownUrl });
         const res = await this.fetchImpl(wellKnownUrl);
-        if (res.ok) {
-          const body = await res.json();
-          data = body.data || body;
-          this.logger.debug("Discovered via .well-known");
-        }
-      } catch (e) {
-        this.logger.debug("Standard discovery probe failed", { error: e.message });
-      }
-      if (!data) {
-        const fallbackUrl = `${this.baseUrl}/api/v1/discovery`;
-        this.logger.debug("Falling back to standard discovery endpoint", { url: fallbackUrl });
-        const res = await this.fetchImpl(fallbackUrl);
         if (!res.ok) {
-          throw new Error(`Failed to connect to ${fallbackUrl}: ${res.statusText}`);
+          throw new Error(`Failed to connect to ${wellKnownUrl}: ${res.statusText}`);
         }
         const body = await res.json();
         data = body.data || body;
@@ -1570,6 +1710,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 +1821,7 @@ var ObjectStackClient = class {
   FilterBuilder,
   ObjectStackClient,
   QueryBuilder,
+  RealtimeAPI,
   createFilter,
   createQuery
 });