@opengeni/react 0.52.1 → 1.0.1

package/src/hooks/use-browser-session.ts

@@ -2,6 +2,7 @@ import type {
   BrowserAction,
   BrowserActionBatch,
   BrowserActionReceipt,
+  BrowserClipboard,
   BrowserDiagnosticBatch,
   BrowserDiagnosticsOptions,
   BrowserFrame,
@@ -9,6 +10,7 @@ import type {
   BrowserSession,
   BrowserTarget,
 } from "@opengeni/sdk/interaction";
+import { OpenGeniApiError } from "@opengeni/sdk";
 import { useCallback, useEffect, useRef, useState } from "react";
 import {
   type EmbeddedBrowserInteractionClientOverride,
@@ -45,6 +47,7 @@ export type UseBrowserSessionResult = {
     frame: BrowserFrame,
     operationId?: string,
   ) => Promise<BrowserActionReceipt>;
+  readClipboard: () => Promise<BrowserClipboard>;
   diagnostics: (options?: BrowserDiagnosticsOptions) => Promise<BrowserDiagnosticBatch>;
 };
 
@@ -118,14 +121,8 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
       ]);
       if (!mountedRef.current || requestRef.current.id !== id) return;
       const selected = chooseTarget(targetResponse.targets, selectedTargetIdRef.current);
-      const observation = selected
-        ? await client.observeBrowserTarget(workspaceId, browserSessionId, selected.id, {
-            signal: controller.signal,
-          })
-        : null;
-      if (!mountedRef.current || requestRef.current.id !== id) return;
       selectedTargetIdRef.current = selected?.id ?? null;
-      observationRef.current = { browserSessionId, observation };
+      observationRef.current = { browserSessionId, observation: null };
       setState((current) =>
         current.browserSessionId === browserSessionId
           ? {
@@ -133,12 +130,36 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
               session,
               targets: targetResponse.targets,
               selectedTargetId: selected?.id ?? null,
-              observation,
+              observation: null,
               loading: false,
               error: null,
             }
           : current,
       );
+      if (!selected) return;
+      try {
+        const observation = await client.observeBrowserTarget(
+          workspaceId,
+          browserSessionId,
+          selected.id,
+          { signal: controller.signal },
+        );
+        if (!mountedRef.current || requestRef.current.id !== id) return;
+        observationRef.current = { browserSessionId, observation };
+        setState((current) =>
+          current.browserSessionId === browserSessionId &&
+          current.selectedTargetId === observation.target.id
+            ? { ...current, observation }
+            : current,
+        );
+      } catch (cause) {
+        if (controller.signal.aborted || !mountedRef.current || requestRef.current.id !== id)
+          return;
+        // Target inventory and the media plane remain authoritative for the
+        // human-facing browser. A failed semantic snapshot must not blank or
+        // disable an otherwise live visual browser.
+        void cause;
+      }
     } catch (cause) {
       if (controller.signal.aborted || !mountedRef.current || requestRef.current.id !== id) return;
       setState((current) =>
@@ -239,19 +260,50 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
     async (targetId: string): Promise<BrowserTarget> => {
       if (!browserSessionId) throw new Error("No BrowserSession is selected.");
       return await runMutation(browserSessionId, async () => {
-        const target = await client.selectBrowserTarget(workspaceId, browserSessionId, targetId);
-        const observation = await client.observeBrowserTarget(
-          workspaceId,
-          browserSessionId,
-          target.id,
-        );
+        let targets = visible.targets;
+        let target: BrowserTarget;
+        let observation: BrowserObservation;
+        try {
+          observation = await client.selectBrowserTarget(workspaceId, browserSessionId, targetId);
+          target = observation.target;
+        } catch (cause) {
+          if (!isMissingBrowserTarget(cause)) throw cause;
+          // A physical/attached tab may disappear between inventory and click.
+          // Reconcile once from the authoritative controller inventory and move
+          // to its live selected/first page instead of leaving a dead tab ID in
+          // React state. Session-level 404s are deliberately not swallowed.
+          const response = await client.listBrowserTargets(workspaceId, browserSessionId);
+          targets = response.targets;
+          const fallback = chooseTarget(targets, null);
+          if (!fallback) {
+            selectedTargetIdRef.current = null;
+            observationRef.current = { browserSessionId, observation: null };
+            setState((current) =>
+              current.browserSessionId === browserSessionId
+                ? {
+                    ...current,
+                    targets,
+                    selectedTargetId: null,
+                    observation: null,
+                  }
+                : current,
+            );
+            throw cause;
+          }
+          observation = await client.selectBrowserTarget(
+            workspaceId,
+            browserSessionId,
+            fallback.id,
+          );
+          target = observation.target;
+        }
         selectedTargetIdRef.current = target.id;
         observationRef.current = { browserSessionId, observation };
         setState((current) =>
           current.browserSessionId === browserSessionId
             ? {
                 ...current,
-                targets: current.targets.map((candidate) => ({
+                targets: targets.map((candidate) => ({
                   ...candidate,
                   selected: candidate.id === target.id,
                 })),
@@ -263,23 +315,19 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
         return target;
       });
     },
-    [browserSessionId, client, runMutation, workspaceId],
+    [browserSessionId, client, runMutation, visible.targets, workspaceId],
   );
 
   const openTarget = useCallback(
     async (url?: string): Promise<BrowserTarget> => {
       if (!browserSessionId) throw new Error("No BrowserSession is selected.");
       return await runMutation(browserSessionId, async () => {
-        const target = await client.openBrowserTarget(
+        const observation = await client.openBrowserTarget(
           workspaceId,
           browserSessionId,
           url === undefined ? {} : { url },
         );
-        const observation = await client.observeBrowserTarget(
-          workspaceId,
-          browserSessionId,
-          target.id,
-        );
+        const target = observation.target;
         selectedTargetIdRef.current = target.id;
         observationRef.current = { browserSessionId, observation };
         setState((current) =>
@@ -362,10 +410,11 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
       if (!fence) {
         throw new Error("The browser page is not ready for input.");
       }
-      return await runMutation(browserSessionId, async () => {
+      try {
         const receipt = await client.actInBrowser(workspaceId, browserSessionId, {
           operationId,
           ...fence,
+          observationMode: "none",
           action,
         });
         if (receipt.observation) {
@@ -382,13 +431,17 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
                 }
               : current,
           );
-        } else {
-          void refresh();
         }
         return receipt;
-      });
+      } catch (cause) {
+        const error = cause instanceof Error ? cause : new Error(String(cause));
+        setState((current) =>
+          current.browserSessionId === browserSessionId ? { ...current, error } : current,
+        );
+        throw error;
+      }
     },
-    [browserSessionId, client, refresh, runMutation, workspaceId],
+    [browserSessionId, client, workspaceId],
   );
 
   const act = useCallback(
@@ -424,6 +477,15 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
     [browserSessionId, client, workspaceId],
   );
 
+  const readClipboard = useCallback(async (): Promise<BrowserClipboard> => {
+    if (!browserSessionId) throw new Error("No BrowserSession is selected.");
+    const clipboard = await client.readBrowserClipboard(workspaceId, browserSessionId);
+    if (clipboard.browserSessionId !== browserSessionId) {
+      throw new Error("Browser clipboard belongs to another BrowserSession.");
+    }
+    return clipboard;
+  }, [browserSessionId, client, workspaceId]);
+
   return {
     session: visible.session,
     targets: visible.targets,
@@ -439,6 +501,7 @@ export function useBrowserSession(options: UseBrowserSessionOptions): UseBrowser
     closeTarget,
     act,
     actFromFrame,
+    readClipboard,
     diagnostics,
   };
 }
@@ -474,3 +537,7 @@ function replaceTarget(targets: readonly BrowserTarget[], target: BrowserTarget)
   next.push(target);
   return next.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
 }
+
+function isMissingBrowserTarget(error: unknown): boolean {
+  return error instanceof OpenGeniApiError && error.code === "target_not_found";
+}

package/src/hooks/use-browser-sessions.ts

@@ -9,13 +9,13 @@ import {
   type EmbeddedBrowserInteractionClientOverride,
   useEmbeddedBrowserInteraction,
 } from "../session-context";
-import { usePageLiveActivity } from "./internal";
+import { useInteractionInvalidation } from "./use-interaction-invalidation";
 
 export type UseBrowserSessionsOptions = EmbeddedBrowserInteractionClientOverride & {
   /** Current agent/session relevance. Workspace peers remain in `sessions`. */
   sessionId?: string | undefined;
   enabled?: boolean | undefined;
-  /** Temporary invalidation path until the interaction event stream lands. */
+  /** Polling fallback used only while the workspace invalidation stream is unavailable. */
   pollIntervalMs?: number | undefined;
 };
 
@@ -50,10 +50,14 @@ export type UseBrowserSessionsResult = {
 export function useBrowserSessions(
   options: UseBrowserSessionsOptions = {},
 ): UseBrowserSessionsResult {
-  const { client, workspaceId, registerSessionReconciler } = useEmbeddedBrowserInteraction(options);
+  const {
+    client,
+    workspaceId,
+    registerSessionReconciler,
+    workspaceInteractionEvent,
+    workspaceInteractionConnectionState,
+  } = useEmbeddedBrowserInteraction(options);
   const enabled = options.enabled ?? true;
-  const pageLive = usePageLiveActivity();
-  const pollIntervalMs = Math.max(1_000, options.pollIntervalMs ?? 3_000);
   const [state, setState] = useState<{
     workspaceId: string;
     revision: number;
@@ -137,15 +141,16 @@ export function useBrowserSessions(
     };
   }, [cancelLoad, enabled, load, workspaceId]);
 
-  useEffect(() => {
-    if (!enabled || !pageLive) return;
-    const timer = setInterval(() => {
-      // Let a slow list request finish. A poll must not repeatedly abort and
-      // restart the same read; an explicit Refresh may still replace it.
-      if (!requestRef.current.controller) void load(false);
-    }, pollIntervalMs);
-    return () => clearInterval(timer);
-  }, [enabled, load, pageLive, pollIntervalMs]);
+  useInteractionInvalidation({
+    workspaceId,
+    key: workspaceId,
+    enabled,
+    event: workspaceInteractionEvent,
+    connectionState: workspaceInteractionConnectionState,
+    knownRevision: visibleState.revision,
+    refresh,
+    fallbackPollIntervalMs: options.pollIntervalMs,
+  });
 
   useEffect(() => {
     if (!enabled || !options.sessionId) return;

package/src/hooks/use-channels.ts

@@ -0,0 +1,99 @@
+import type { Channel, CreateChannelRequest, Session, UpdateChannelRequest } from "@opengeni/sdk";
+import { useCallback } from "react";
+import { useOpenGeni, type ClientOverride } from "../provider";
+import { useMutationRunner, usePolledValue } from "./internal";
+
+export type UseChannelsOptions = ClientOverride & {
+  pollIntervalMs?: number | undefined;
+  enabled?: boolean | undefined;
+};
+
+export type UseChannelsResult = {
+  channels: Channel[];
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  create: (request: CreateChannelRequest) => Promise<Channel | null>;
+  update: (channelId: string, request: UpdateChannelRequest) => Promise<Channel | null>;
+  remove: (channelId: string) => Promise<boolean>;
+  /** Re-file a session into a channel; null moves it back to the inbox. */
+  moveSession: (sessionId: string, channelId: string | null) => Promise<Session | null>;
+  mutating: boolean;
+  mutationError: Error | null;
+  clearMutationError: () => void;
+};
+
+/**
+ * Workspace-shared channels: rail organization for root sessions
+ * ("workstreams") by work type. Pure metadata — filing a session into a
+ * channel never affects execution.
+ */
+export function useChannels(options: UseChannelsOptions = {}): UseChannelsResult {
+  const { client, workspaceId } = useOpenGeni(options);
+  const load = useCallback(
+    async () => await client.listChannels(workspaceId),
+    [client, workspaceId],
+  );
+  const { data, loading, error, refresh } = usePolledValue(load, {
+    pollIntervalMs: options.pollIntervalMs,
+    enabled: options.enabled,
+  });
+  const { run, mutating, mutationError, clearMutationError } = useMutationRunner();
+
+  const create = useCallback(
+    async (request: CreateChannelRequest): Promise<Channel | null> => {
+      const result = await run(() => client.createChannel(workspaceId, request));
+      if (result) {
+        await refresh();
+      }
+      return result;
+    },
+    [client, workspaceId, run, refresh],
+  );
+
+  const update = useCallback(
+    async (channelId: string, request: UpdateChannelRequest): Promise<Channel | null> => {
+      const result = await run(() => client.updateChannel(workspaceId, channelId, request));
+      if (result) {
+        await refresh();
+      }
+      return result;
+    },
+    [client, workspaceId, run, refresh],
+  );
+
+  const remove = useCallback(
+    async (channelId: string): Promise<boolean> => {
+      const result = await run(async () => {
+        await client.deleteChannel(workspaceId, channelId);
+        return true;
+      });
+      if (result) {
+        await refresh();
+      }
+      return result === true;
+    },
+    [client, workspaceId, run, refresh],
+  );
+
+  const moveSession = useCallback(
+    async (sessionId: string, channelId: string | null): Promise<Session | null> => {
+      return await run(() => client.updateSessionChannel(workspaceId, sessionId, { channelId }));
+    },
+    [client, workspaceId, run],
+  );
+
+  return {
+    channels: data ?? [],
+    loading,
+    error,
+    refresh,
+    create,
+    update,
+    remove,
+    moveSession,
+    mutating,
+    mutationError,
+    clearMutationError,
+  };
+}