@opengeni/react 0.52.1 → 1.0.1

package/src/hooks/use-attached-browsers.ts

@@ -5,7 +5,7 @@ import {
   type EmbeddedBrowserInteractionClientOverride,
   useEmbeddedBrowserInteraction,
 } from "../session-context";
-import { usePageLiveActivity } from "./internal";
+import { useInteractionInvalidation } from "./use-interaction-invalidation";
 
 export type UseAttachedBrowsersOptions = EmbeddedBrowserInteractionClientOverride & {
   enabled?: boolean | undefined;
@@ -27,11 +27,10 @@ export type UseAttachedBrowsersResult = {
 export function useAttachedBrowsers(
   options: UseAttachedBrowsersOptions = {},
 ): UseAttachedBrowsersResult {
-  const { client, workspaceId } = useEmbeddedBrowserInteraction(options);
+  const { client, workspaceId, workspaceInteractionEvent, workspaceInteractionConnectionState } =
+    useEmbeddedBrowserInteraction(options);
   const enabled = options.enabled ?? true;
   const includeDisconnected = options.includeDisconnected ?? false;
-  const pageLive = usePageLiveActivity();
-  const pollIntervalMs = Math.max(1_000, options.pollIntervalMs ?? 3_000);
   const [state, setState] = useState(() => emptyState(workspaceId, enabled));
   const requestRef = useRef<{ id: number; controller: AbortController | null }>({
     id: 0,
@@ -105,13 +104,16 @@ export function useAttachedBrowsers(
     };
   }, [cancelLoad, enabled, load, workspaceId]);
 
-  useEffect(() => {
-    if (!enabled || !pageLive) return;
-    const timer = setInterval(() => {
-      if (!requestRef.current.controller) void load(false);
-    }, pollIntervalMs);
-    return () => clearInterval(timer);
-  }, [enabled, load, pageLive, pollIntervalMs]);
+  useInteractionInvalidation({
+    workspaceId,
+    key: `${workspaceId}:${includeDisconnected}`,
+    enabled,
+    event: workspaceInteractionEvent,
+    connectionState: workspaceInteractionConnectionState,
+    knownRevision: visible.revision,
+    refresh,
+    fallbackPollIntervalMs: options.pollIntervalMs,
+  });
 
   return {
     revision: visible.revision,

package/src/hooks/use-auth-runs.ts

@@ -0,0 +1,278 @@
+import type {
+  AuthRun,
+  AuthRunMutationResponse,
+  ProtectedAuthFillRequest,
+  ProtectedAuthFillResponse,
+  ReportAuthRunRequest,
+  StartAuthRunRequest,
+  VerifyAuthRunRequest,
+} from "@opengeni/sdk/interaction";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { EmbeddedBrowserInteractionClientLike } from "../client";
+import {
+  type EmbeddedBrowserInteractionClientOverride,
+  useEmbeddedBrowserInteraction,
+} from "../session-context";
+import { useInteractionInvalidation } from "./use-interaction-invalidation";
+
+export type UseAuthRunsOptions = EmbeddedBrowserInteractionClientOverride & {
+  enabled?: boolean | undefined;
+  browserSessionId?: string | null | undefined;
+  siteAuthConnectionId?: string | null | undefined;
+  includeSettled?: boolean | undefined;
+};
+
+export type UseAuthRunsResult = {
+  runs: AuthRun[];
+  loading: boolean;
+  refreshing: boolean;
+  mutating: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  start: (
+    browserSessionId: string,
+    request: Omit<StartAuthRunRequest, "operationId"> & { operationId?: string },
+  ) => Promise<AuthRunMutationResponse>;
+  report: (
+    browserSessionId: string,
+    authRunId: string,
+    request: Omit<ReportAuthRunRequest, "operationId"> & { operationId?: string },
+  ) => Promise<AuthRunMutationResponse>;
+  protectedFill: (
+    browserSessionId: string,
+    authRunId: string,
+    request: Omit<ProtectedAuthFillRequest, "operationId"> & { operationId?: string },
+  ) => Promise<ProtectedAuthFillResponse>;
+  verify: (
+    browserSessionId: string,
+    authRunId: string,
+    request: Omit<VerifyAuthRunRequest, "operationId"> & { operationId?: string },
+  ) => Promise<AuthRunMutationResponse>;
+};
+
+/** Live authentication state machines tied to exact browser document generations. */
+export function useAuthRuns(options: UseAuthRunsOptions = {}): UseAuthRunsResult {
+  const { client, workspaceId, workspaceInteractionEvent, workspaceInteractionConnectionState } =
+    useEmbeddedBrowserInteraction(options);
+  const enabled = options.enabled ?? true;
+  const browserSessionId = options.browserSessionId ?? null;
+  const siteAuthConnectionId = options.siteAuthConnectionId ?? null;
+  const includeSettled = options.includeSettled ?? false;
+  const key = `${workspaceId}:${browserSessionId ?? "*"}:${siteAuthConnectionId ?? "*"}:${includeSettled}`;
+  const [state, setState] = useState(() => emptyState(key, enabled));
+  const [mutationCount, setMutationCount] = useState(0);
+  const requestRef = useRef<{ id: number; controller: AbortController | null }>({
+    id: 0,
+    controller: null,
+  });
+  const mountedRef = useRef(true);
+  const visible = state.key === key ? state : emptyState(key, enabled);
+
+  const cancelLoad = useCallback(() => {
+    requestRef.current.controller?.abort();
+    requestRef.current = { id: requestRef.current.id + 1, controller: null };
+  }, []);
+
+  const load = useCallback(
+    async (foreground: boolean): Promise<void> => {
+      if (!enabled) return;
+      const id = requestRef.current.id + 1;
+      requestRef.current.controller?.abort();
+      const controller = new AbortController();
+      requestRef.current = { id, controller };
+      setState((current) => ({
+        ...(current.key === key ? current : emptyState(key, true)),
+        loading: foreground,
+        refreshing: !foreground,
+        error: foreground || current.key !== key ? null : current.error,
+      }));
+      try {
+        const response = await client.listAuthRuns(workspaceId, {
+          ...(browserSessionId ? { browserSessionId } : {}),
+          ...(siteAuthConnectionId ? { siteAuthConnectionId } : {}),
+          includeSettled,
+          signal: controller.signal,
+        });
+        if (!mountedRef.current || requestRef.current.id !== id) return;
+        setState({
+          key,
+          runs: sortRuns(response.runs),
+          loading: false,
+          refreshing: false,
+          error: null,
+        });
+      } catch (cause) {
+        if (controller.signal.aborted || !mountedRef.current || requestRef.current.id !== id)
+          return;
+        setState((current) => ({
+          ...(current.key === key ? current : emptyState(key, true)),
+          loading: false,
+          refreshing: false,
+          error: asError(cause),
+        }));
+      } finally {
+        if (requestRef.current.id === id) requestRef.current = { id, controller: null };
+      }
+    },
+    [browserSessionId, client, enabled, includeSettled, key, siteAuthConnectionId, workspaceId],
+  );
+
+  const refresh = useCallback(async () => await load(false), [load]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    if (!enabled) {
+      cancelLoad();
+      setState(emptyState(key, false));
+      return;
+    }
+    void load(true);
+    return () => {
+      mountedRef.current = false;
+      cancelLoad();
+    };
+  }, [cancelLoad, enabled, key, load]);
+
+  useInteractionInvalidation({
+    workspaceId,
+    key,
+    enabled,
+    event: workspaceInteractionEvent,
+    connectionState: workspaceInteractionConnectionState,
+    refresh,
+  });
+
+  const mutate = useCallback(async <T>(operation: () => Promise<T>): Promise<T> => {
+    setMutationCount((count) => count + 1);
+    try {
+      return await operation();
+    } finally {
+      if (mountedRef.current) setMutationCount((count) => Math.max(0, count - 1));
+    }
+  }, []);
+
+  const merge = useCallback(
+    (run: AuthRun) => {
+      setState((current) => {
+        if (current.key !== key) return current;
+        const runs = current.runs.filter((candidate) => candidate.id !== run.id);
+        const matches =
+          (!browserSessionId || run.browserSessionId === browserSessionId) &&
+          (!siteAuthConnectionId || run.siteAuthConnectionId === siteAuthConnectionId);
+        if (matches && (includeSettled || !isSettled(run))) runs.push(run);
+        return { ...current, runs: sortRuns(runs), error: null };
+      });
+    },
+    [browserSessionId, includeSettled, key, siteAuthConnectionId],
+  );
+
+  const start = useCallback(
+    async (
+      scopeBrowserSessionId: string,
+      request: Omit<StartAuthRunRequest, "operationId"> & { operationId?: string },
+    ): Promise<AuthRunMutationResponse> =>
+      await mutate(async () => {
+        const response = await client.startBrowserAuthRun(workspaceId, scopeBrowserSessionId, {
+          ...request,
+          operationId: request.operationId ?? crypto.randomUUID(),
+        });
+        merge(response.run);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  const report = useCallback(
+    async (
+      scopeBrowserSessionId: string,
+      authRunId: string,
+      request: Omit<ReportAuthRunRequest, "operationId"> & { operationId?: string },
+    ): Promise<AuthRunMutationResponse> =>
+      await mutate(async () => {
+        const response = await client.reportBrowserAuthRun(
+          workspaceId,
+          scopeBrowserSessionId,
+          authRunId,
+          { ...request, operationId: request.operationId ?? crypto.randomUUID() },
+        );
+        merge(response.run);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  const protectedFill = useCallback(
+    async (
+      scopeBrowserSessionId: string,
+      authRunId: string,
+      request: Omit<ProtectedAuthFillRequest, "operationId"> & { operationId?: string },
+    ): Promise<ProtectedAuthFillResponse> =>
+      await mutate(async () => {
+        const response = await client.protectedBrowserAuthFill(
+          workspaceId,
+          scopeBrowserSessionId,
+          authRunId,
+          { ...request, operationId: request.operationId ?? crypto.randomUUID() },
+        );
+        merge(response.run);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  const verify = useCallback(
+    async (
+      scopeBrowserSessionId: string,
+      authRunId: string,
+      request: Omit<VerifyAuthRunRequest, "operationId"> & { operationId?: string },
+    ): Promise<AuthRunMutationResponse> =>
+      await mutate(async () => {
+        const response = await client.verifyBrowserAuthRun(
+          workspaceId,
+          scopeBrowserSessionId,
+          authRunId,
+          { ...request, operationId: request.operationId ?? crypto.randomUUID() },
+        );
+        merge(response.run);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  return {
+    runs: visible.runs,
+    loading: visible.loading,
+    refreshing: visible.refreshing,
+    mutating: mutationCount > 0,
+    error: visible.error,
+    refresh,
+    start,
+    report,
+    protectedFill,
+    verify,
+  };
+}
+
+function emptyState(key: string, loading: boolean) {
+  return {
+    key,
+    runs: [] as AuthRun[],
+    loading,
+    refreshing: false,
+    error: null as Error | null,
+  };
+}
+
+function sortRuns(runs: readonly AuthRun[]): AuthRun[] {
+  return [...runs].sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt));
+}
+
+function isSettled(run: AuthRun): boolean {
+  return run.state === "verified" || run.state === "failed" || run.state === "cancelled";
+}
+
+function asError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+
+export type AuthRunsClient = EmbeddedBrowserInteractionClientLike;

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

@@ -0,0 +1,218 @@
+import type { BrowserDownload, BrowserDownloadSaveResponse } from "@opengeni/sdk/interaction";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { EmbeddedBrowserInteractionClientLike } from "../client";
+import {
+  type EmbeddedBrowserInteractionClientOverride,
+  useEmbeddedBrowserInteraction,
+} from "../session-context";
+import { usePageLiveActivity } from "./internal";
+
+export type UseBrowserDownloadsOptions = EmbeddedBrowserInteractionClientOverride & {
+  browserSessionId: string | null;
+  enabled?: boolean | undefined;
+  pollIntervalMs?: number | undefined;
+};
+
+export type BrowserDownloadSaveOptions = {
+  operationId?: string | undefined;
+  overwrite?: boolean | undefined;
+};
+
+export type UseBrowserDownloadsResult = {
+  downloads: BrowserDownload[];
+  loading: boolean;
+  refreshing: boolean;
+  savingDownloadIds: string[];
+  error: Error | null;
+  refresh: () => Promise<void>;
+  saveToWorkspace: (
+    downloadId: string,
+    destinationPath: string,
+    options?: BrowserDownloadSaveOptions,
+  ) => Promise<BrowserDownloadSaveResponse>;
+};
+
+/** Exact browser-produced files for one BrowserSession. Bytes remain private
+ * until `saveToWorkspace` performs the canonical workspace mutation. */
+export function useBrowserDownloads(
+  options: UseBrowserDownloadsOptions,
+): UseBrowserDownloadsResult {
+  const { client, workspaceId } = useEmbeddedBrowserInteraction(options);
+  const browserSessionId = options.browserSessionId;
+  const enabled = (options.enabled ?? true) && browserSessionId !== null;
+  const pageLive = usePageLiveActivity();
+  const pollIntervalMs = Math.max(750, options.pollIntervalMs ?? 2_000);
+  const scope = browserSessionId ?? "none";
+  const [state, setState] = useState(() => emptyState(scope, enabled));
+  const [saving, setSaving] = useState<Record<string, number>>({});
+  const visible = state.scope === scope ? state : emptyState(scope, enabled);
+  const requestRef = useRef<{ id: number; controller: AbortController | null }>({
+    id: 0,
+    controller: null,
+  });
+  const mountedRef = useRef(true);
+  const retryOperationsRef = useRef(new Map<string, string>());
+
+  const cancelLoad = useCallback(() => {
+    requestRef.current.controller?.abort();
+    requestRef.current = { id: requestRef.current.id + 1, controller: null };
+  }, []);
+
+  const load = useCallback(
+    async (foreground: boolean): Promise<void> => {
+      if (!enabled || !browserSessionId) return;
+      const id = requestRef.current.id + 1;
+      requestRef.current.controller?.abort();
+      const controller = new AbortController();
+      requestRef.current = { id, controller };
+      setState((current) => ({
+        ...(current.scope === scope ? current : emptyState(scope, true)),
+        loading: foreground,
+        refreshing: !foreground,
+        error: foreground || current.scope !== scope ? null : current.error,
+      }));
+      try {
+        const response = await client.listBrowserDownloads(workspaceId, browserSessionId, {
+          signal: controller.signal,
+        });
+        if (!mountedRef.current || requestRef.current.id !== id) return;
+        setState({
+          scope,
+          downloads: sortDownloads(response.downloads),
+          loading: false,
+          refreshing: false,
+          error: null,
+        });
+      } catch (cause) {
+        if (controller.signal.aborted || !mountedRef.current || requestRef.current.id !== id)
+          return;
+        setState((current) => ({
+          ...(current.scope === scope ? current : emptyState(scope, true)),
+          loading: false,
+          refreshing: false,
+          error: asError(cause),
+        }));
+      } finally {
+        if (requestRef.current.id === id) requestRef.current = { id, controller: null };
+      }
+    },
+    [browserSessionId, client, enabled, scope, workspaceId],
+  );
+
+  const refresh = useCallback(async () => await load(false), [load]);
+
+  useEffect(() => {
+    retryOperationsRef.current.clear();
+    setSaving({});
+  }, [scope]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    if (!enabled) {
+      cancelLoad();
+      setState(emptyState(scope, false));
+      return () => {
+        mountedRef.current = false;
+        cancelLoad();
+      };
+    }
+    void load(true);
+    return () => {
+      mountedRef.current = false;
+      cancelLoad();
+    };
+  }, [cancelLoad, enabled, load, scope]);
+
+  useEffect(() => {
+    if (!enabled || !pageLive || Object.keys(saving).length > 0) return;
+    const timer = setInterval(() => {
+      if (!requestRef.current.controller) void refresh();
+    }, pollIntervalMs);
+    return () => clearInterval(timer);
+  }, [enabled, pageLive, pollIntervalMs, refresh, saving]);
+
+  const saveToWorkspace = useCallback(
+    async (
+      downloadId: string,
+      destinationPath: string,
+      saveOptions: BrowserDownloadSaveOptions = {},
+    ): Promise<BrowserDownloadSaveResponse> => {
+      if (!browserSessionId) throw new Error("No BrowserSession is selected.");
+      const overwrite = saveOptions.overwrite ?? false;
+      const attemptKey = `${browserSessionId}\u0000${downloadId}\u0000${destinationPath}\u0000${overwrite}`;
+      const operationId =
+        saveOptions.operationId ??
+        retryOperationsRef.current.get(attemptKey) ??
+        crypto.randomUUID();
+      retryOperationsRef.current.set(attemptKey, operationId);
+      setSaving((current) => ({ ...current, [downloadId]: (current[downloadId] ?? 0) + 1 }));
+      try {
+        const response = await client.saveBrowserDownload(
+          workspaceId,
+          browserSessionId,
+          downloadId,
+          { operationId, destinationPath, overwrite },
+        );
+        retryOperationsRef.current.delete(attemptKey);
+        if (mountedRef.current) {
+          setState((current) =>
+            current.scope === scope
+              ? {
+                  ...current,
+                  downloads: sortDownloads([
+                    ...current.downloads.filter((download) => download.id !== response.download.id),
+                    response.download,
+                  ]),
+                  error: null,
+                }
+              : current,
+          );
+        }
+        return response;
+      } finally {
+        if (mountedRef.current) {
+          setSaving((current) => {
+            const count = (current[downloadId] ?? 1) - 1;
+            if (count > 0) return { ...current, [downloadId]: count };
+            const { [downloadId]: _removed, ...rest } = current;
+            return rest;
+          });
+        }
+      }
+    },
+    [browserSessionId, client, scope, workspaceId],
+  );
+
+  return {
+    downloads: visible.downloads,
+    loading: visible.loading,
+    refreshing: visible.refreshing,
+    savingDownloadIds: Object.keys(saving),
+    error: visible.error,
+    refresh,
+    saveToWorkspace,
+  };
+}
+
+function emptyState(scope: string, loading: boolean) {
+  return {
+    scope,
+    downloads: [] as BrowserDownload[],
+    loading,
+    refreshing: false,
+    error: null as Error | null,
+  };
+}
+
+function sortDownloads(downloads: readonly BrowserDownload[]): BrowserDownload[] {
+  return [...downloads].sort(
+    (left, right) =>
+      right.startedAt.localeCompare(left.startedAt) || left.id.localeCompare(right.id),
+  );
+}
+
+function asError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+
+export type BrowserDownloadsClient = EmbeddedBrowserInteractionClientLike;