@objectstack/client 4.0.1 → 4.0.3

package/.turbo/turbo-build.log

@@ -1,22 +1,22 @@
 
-> @objectstack/client@4.0.1 build /home/runner/work/spec/spec/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
 CLI Using tsconfig: tsconfig.json
 CLI tsup v8.5.1
-CLI Using tsup config: /home/runner/work/spec/spec/tsup.config.ts
+CLI Using tsup config: /home/runner/work/framework/framework/tsup.config.ts
 CLI Target: es2020
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.js     55.15 KB
-CJS dist/index.js.map 109.54 KB
-CJS ⚡️ Build success in 80ms
-ESM dist/index.mjs     53.98 KB
-ESM dist/index.mjs.map 109.49 KB
-ESM ⚡️ Build success in 90ms
+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 5542ms
-DTS dist/index.d.mts 33.59 KB
-DTS dist/index.d.ts  33.59 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,21 @@
 # @objectstack/client
 
+## 4.0.3
+
+### Patch Changes
+
+- @objectstack/spec@4.0.3
+- @objectstack/core@4.0.3
+
+## 4.0.2
+
+### Patch Changes
+
+- 5f659e9: fix ai
+- Updated dependencies [5f659e9]
+  - @objectstack/spec@4.0.2
+  - @objectstack/core@4.0.2
+
 ## 4.0.0
 
 ### Minor 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, AiChatRequest, AiChatResponse, 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, AiChatRequest, AiChatResponse, 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, 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.
@@ -332,7 +403,8 @@ declare class ObjectStackClient {
         } | undefined;
         services?: Record<string, {
             enabled: boolean;
-            status: "degraded" | "stub" | "available" | "unavailable";
+            status: "degraded" | "stub" | "available" | "registered" | "unavailable";
+            handlerReady?: boolean | undefined;
             route?: string | undefined;
             provider?: string | undefined;
             version?: string | undefined;
@@ -388,8 +460,11 @@ declare 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: (type: string, name: string) => Promise<unknown>;
+        getItem: (type: string, name: string, options?: {
+            packageId?: string;
+        }) => Promise<unknown>;
         /**
          * Save a metadata item
          * @param type - Metadata type (e.g., 'object', 'plugin')
@@ -397,6 +472,16 @@ declare class ObjectStackClient {
          * @param item - The metadata content to save
          */
         saveItem: (type: string, name: string, item: any) => Promise<unknown>;
+        /**
+         * Delete a metadata item
+         * @param type - Metadata type (e.g., 'object', 'plugin')
+         * @param name - Item name (snake_case identifier)
+         */
+        deleteItem: (type: string, name: string) => Promise<{
+            type: string;
+            name: string;
+            deleted: boolean;
+        }>;
         /**
          * Get object metadata with cache support
          * Supports ETag-based conditional requests for efficient caching
@@ -600,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
      */
@@ -742,10 +832,6 @@ declare class ObjectStackClient {
          * 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
          */
@@ -928,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, AiChatRequest, AiChatResponse, 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, AiChatRequest, AiChatResponse, 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, 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.
@@ -332,7 +403,8 @@ declare class ObjectStackClient {
         } | undefined;
         services?: Record<string, {
             enabled: boolean;
-            status: "degraded" | "stub" | "available" | "unavailable";
+            status: "degraded" | "stub" | "available" | "registered" | "unavailable";
+            handlerReady?: boolean | undefined;
             route?: string | undefined;
             provider?: string | undefined;
             version?: string | undefined;
@@ -388,8 +460,11 @@ declare 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: (type: string, name: string) => Promise<unknown>;
+        getItem: (type: string, name: string, options?: {
+            packageId?: string;
+        }) => Promise<unknown>;
         /**
          * Save a metadata item
          * @param type - Metadata type (e.g., 'object', 'plugin')
@@ -397,6 +472,16 @@ declare class ObjectStackClient {
          * @param item - The metadata content to save
          */
         saveItem: (type: string, name: string, item: any) => Promise<unknown>;
+        /**
+         * Delete a metadata item
+         * @param type - Metadata type (e.g., 'object', 'plugin')
+         * @param name - Item name (snake_case identifier)
+         */
+        deleteItem: (type: string, name: string) => Promise<{
+            type: string;
+            name: string;
+            deleted: boolean;
+        }>;
         /**
          * Get object metadata with cache support
          * Supports ETag-based conditional requests for efficient caching
@@ -600,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
      */
@@ -742,10 +832,6 @@ declare class ObjectStackClient {
          * 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
          */
@@ -928,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() {
@@ -338,10 +468,15 @@ var ObjectStackClient = class {
        * 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, name) => {
+      getItem: async (type, name, options) => {
         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);
       },
       /**
@@ -358,6 +493,18 @@ var ObjectStackClient = class {
         });
         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, name) => {
+        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
        * Supports ETag-based conditional requests for efficient caching
@@ -1101,17 +1248,7 @@ var ObjectStackClient = class {
         });
         return this.unwrapResponse(res);
       },
-      /**
-       * Multi-turn AI chat
-       */
-      chat: async (request) => {
-        const route = this.getRoute("ai");
-        const res = await this.fetch(`${this.baseUrl}${route}/chat`, {
-          method: "POST",
-          body: JSON.stringify(request)
-        });
-        return this.unwrapResponse(res);
-      },
+      // AI chat method removed — use Vercel AI SDK `useChat()` / `@ai-sdk/react` directly.
       /**
        * AI-powered field value suggestions
        */
@@ -1493,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 });
   }
   /**
@@ -1563,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
    */
@@ -1667,6 +1812,7 @@ var ObjectStackClient = class {
   FilterBuilder,
   ObjectStackClient,
   QueryBuilder,
+  RealtimeAPI,
   createFilter,
   createQuery
 });