Merge pull request #1107 from objectstack-ai/claude/assess-frontend-backend-protocols

Implement real-time event subscriptions for metadata and data changes

Author: hotlong

apps/studio/src/components/app-sidebar.tsx

@@ -36,7 +36,7 @@ import {
   type LucideIcon,
 } from "lucide-react"
 import { useState, useEffect, useCallback, useMemo } from "react"
-import { useClient } from '@objectstack/client-react';
+import { useClient, useMetadataSubscriptionCallback } from '@objectstack/client-react';
 import type { InstalledPackage } from '@objectstack/spec/kernel';
 
 import {
@@ -260,6 +260,17 @@ export function AppSidebar({
 
   useEffect(() => { loadMetadata(); }, [loadMetadata]);
 
+  // Subscribe to metadata changes for real-time updates
+  // Subscribe to all major metadata types for live sidebar updates
+  useMetadataSubscriptionCallback('object', loadMetadata);
+  useMetadataSubscriptionCallback('view', loadMetadata);
+  useMetadataSubscriptionCallback('app', loadMetadata);
+  useMetadataSubscriptionCallback('agent', loadMetadata);
+  useMetadataSubscriptionCallback('tool', loadMetadata);
+  useMetadataSubscriptionCallback('flow', loadMetadata);
+  useMetadataSubscriptionCallback('dashboard', loadMetadata);
+  useMetadataSubscriptionCallback('report', loadMetadata);
+
   // Search helper
   const matchesSearch = (label: string, name: string) =>
     !searchQuery ||

packages/client-react/src/index.tsx

@@ -45,5 +45,15 @@ export {
   type UseMetadataResult
 } from './metadata-hooks';
 
+// Realtime Event Hooks
+export {
+  useMetadataSubscription,
+  useDataSubscription,
+  useMetadataSubscriptionCallback,
+  useDataSubscriptionCallback,
+  useRealtimeConnection,
+  useAutoRefresh
+} from './realtime-hooks';
+
 // Re-export ObjectStackClient and types from @objectstack/client
 export { ObjectStackClient, type ClientConfig } from '@objectstack/client';

packages/client-react/src/realtime-hooks.tsx

@@ -0,0 +1,262 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Real-time Event Subscription Hooks
+ *
+ * Provides React hooks for subscribing to metadata and data events.
+ * Events are automatically cleaned up when components unmount.
+ */
+
+import { useEffect, useState, useCallback } from 'react';
+import type { MetadataEvent, DataEvent } from '@objectstack/spec/api';
+import { useClient } from './context';
+
+/**
+ * Hook to subscribe to metadata events
+ *
+ * @param type - Metadata type to subscribe to (e.g., 'object', 'view', 'agent')
+ * @param options - Optional filters (packageId)
+ * @returns Latest metadata event or null
+ *
+ * @example
+ * ```tsx
+ * function ObjectList() {
+ *   const event = useMetadataSubscription('object');
+ *
+ *   useEffect(() => {
+ *     if (event?.type === 'metadata.object.created') {
+ *       console.log('New object:', event.name);
+ *       // Refresh list
+ *     }
+ *   }, [event]);
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export function useMetadataSubscription(
+  type: string,
+  options?: { packageId?: string }
+): MetadataEvent | null {
+  const client = useClient();
+  const [event, setEvent] = useState<MetadataEvent | null>(null);
+
+  useEffect(() => {
+    if (!client) return;
+
+    const unsubscribe = client.events.subscribeMetadata(
+      type,
+      (e) => setEvent(e),
+      options
+    );
+
+    return () => {
+      unsubscribe();
+    };
+  }, [client, type, options?.packageId]);
+
+  return event;
+}
+
+/**
+ * Hook to subscribe to data record events
+ *
+ * @param object - Object name to subscribe to
+ * @param options - Optional filters (recordId for specific record)
+ * @returns Latest data event or null
+ *
+ * @example
+ * ```tsx
+ * function TaskDetail({ taskId }: { taskId: string }) {
+ *   const event = useDataSubscription('project_task', { recordId: taskId });
+ *
+ *   useEffect(() => {
+ *     if (event?.type === 'data.record.updated') {
+ *       console.log('Task updated:', event.changes);
+ *       // Refresh task data
+ *     }
+ *   }, [event]);
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export function useDataSubscription(
+  object: string,
+  options?: { recordId?: string }
+): DataEvent | null {
+  const client = useClient();
+  const [event, setEvent] = useState<DataEvent | null>(null);
+
+  useEffect(() => {
+    if (!client) return;
+
+    const unsubscribe = client.events.subscribeData(
+      object,
+      (e) => setEvent(e),
+      options
+    );
+
+    return () => {
+      unsubscribe();
+    };
+  }, [client, object, options?.recordId]);
+
+  return event;
+}
+
+/**
+ * Hook to subscribe to metadata events with a callback
+ *
+ * This variant doesn't store events in state, it just triggers a callback.
+ * Useful for triggering refetches or side effects without re-renders.
+ *
+ * @param type - Metadata type to subscribe to
+ * @param callback - Callback to invoke on events
+ * @param options - Optional filters
+ *
+ * @example
+ * ```tsx
+ * function ObjectList() {
+ *   const { refetch } = useQuery(...);
+ *
+ *   useMetadataSubscriptionCallback('object', () => {
+ *     refetch(); // Refetch list when objects change
+ *   });
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export function useMetadataSubscriptionCallback(
+  type: string,
+  callback: (event: MetadataEvent) => void,
+  options?: { packageId?: string }
+): void {
+  const client = useClient();
+
+  useEffect(() => {
+    if (!client) return;
+
+    const unsubscribe = client.events.subscribeMetadata(
+      type,
+      callback,
+      options
+    );
+
+    return () => {
+      unsubscribe();
+    };
+  }, [client, type, callback, options?.packageId]);
+}
+
+/**
+ * Hook to subscribe to data events with a callback
+ *
+ * @param object - Object name to subscribe to
+ * @param callback - Callback to invoke on events
+ * @param options - Optional filters
+ *
+ * @example
+ * ```tsx
+ * function TaskList() {
+ *   const { refetch } = useQuery(...);
+ *
+ *   useDataSubscriptionCallback('project_task', () => {
+ *     refetch(); // Refetch list when tasks change
+ *   });
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export function useDataSubscriptionCallback(
+  object: string,
+  callback: (event: DataEvent) => void,
+  options?: { recordId?: string }
+): void {
+  const client = useClient();
+
+  useEffect(() => {
+    if (!client) return;
+
+    const unsubscribe = client.events.subscribeData(
+      object,
+      callback,
+      options
+    );
+
+    return () => {
+      unsubscribe();
+    };
+  }, [client, object, callback, options?.recordId]);
+}
+
+/**
+ * Hook to get connection status of realtime events
+ *
+ * @returns Whether realtime is connected
+ *
+ * @example
+ * ```tsx
+ * function ConnectionIndicator() {
+ *   const connected = useRealtimeConnection();
+ *
+ *   return (
+ *     <div>
+ *       {connected ? '🟢 Connected' : '🔴 Disconnected'}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useRealtimeConnection(): boolean {
+  const client = useClient();
+  const [connected, setConnected] = useState(true);
+
+  useEffect(() => {
+    if (!client) {
+      setConnected(false);
+      return;
+    }
+
+    // For now, assume always connected with in-memory adapter
+    // In production, this would listen to WebSocket connection events
+    setConnected(true);
+  }, [client]);
+
+  return connected;
+}
+
+/**
+ * Hook for auto-refreshing queries when data changes
+ *
+ * Combines data subscription with query refetch.
+ *
+ * @param object - Object name to watch
+ * @param refetch - Refetch function from useQuery
+ * @param options - Optional filters
+ *
+ * @example
+ * ```tsx
+ * function TaskList() {
+ *   const { data, refetch } = useQuery('project_task', {});
+ *
+ *   useAutoRefresh('project_task', refetch);
+ *
+ *   return <div>{data.map(...)}</div>;
+ * }
+ * ```
+ */
+export function useAutoRefresh(
+  object: string,
+  refetch: () => void,
+  options?: { recordId?: string }
+): void {
+  const handleEvent = useCallback((_event: DataEvent) => {
+    // Refetch on any data change
+    refetch();
+  }, [refetch]);
+
+  useDataSubscriptionCallback(object, handleEvent, options);
+}

packages/client/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,