@opengeni/react 0.52.1 → 1.0.1

package/src/hooks/use-interaction-interventions.ts

@@ -0,0 +1,242 @@
+import type {
+  CreateInteractionInterventionRequest,
+  InteractionIntervention,
+  InteractionInterventionMutationResponse,
+  ResolveInteractionInterventionRequest,
+} from "@opengeni/sdk/interaction";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { EmbeddedInterventionClientLike } from "../client";
+import {
+  type EmbeddedInterventionClientOverride,
+  useEmbeddedInterventions,
+} from "../session-context";
+import { useInteractionInvalidation } from "./use-interaction-invalidation";
+
+export type UseInteractionInterventionsOptions = EmbeddedInterventionClientOverride & {
+  enabled?: boolean | undefined;
+  resourceKind?: "browser_session" | "computer_session" | undefined;
+  resourceId?: string | null | undefined;
+  includeSettled?: boolean | undefined;
+  pollIntervalMs?: number | undefined;
+};
+
+export type UseInteractionInterventionsResult = {
+  interventions: InteractionIntervention[];
+  loading: boolean;
+  refreshing: boolean;
+  mutating: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  create: (
+    request: Omit<CreateInteractionInterventionRequest, "operationId"> & {
+      operationId?: string;
+    },
+  ) => Promise<InteractionInterventionMutationResponse>;
+  resolve: (
+    interventionId: string,
+    request: Omit<ResolveInteractionInterventionRequest, "operationId"> & {
+      operationId?: string;
+    },
+  ) => Promise<InteractionInterventionMutationResponse>;
+};
+
+/** Human-action bridge shared by Browser and Computer surfaces. */
+export function useInteractionInterventions(
+  options: UseInteractionInterventionsOptions = {},
+): UseInteractionInterventionsResult {
+  const { client, workspaceId, workspaceInteractionEvent, workspaceInteractionConnectionState } =
+    useEmbeddedInterventions(options);
+  const enabled = (options.enabled ?? true) && options.resourceId !== null;
+  const resourceKind = options.resourceKind;
+  const resourceId = options.resourceId ?? undefined;
+  const includeSettled = options.includeSettled ?? false;
+  const key = `${workspaceId}:${resourceKind ?? "*"}:${resourceId ?? "*"}:${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, replace = true): Promise<void> => {
+      if (!enabled) return;
+      if (requestRef.current.controller && !replace) return;
+      const id = requestRef.current.id + 1;
+      requestRef.current.controller?.abort();
+      const controller = new AbortController();
+      requestRef.current = { id, controller };
+      if (foreground || replace) {
+        setState((current) => ({
+          ...(current.key === key ? current : emptyState(key, true)),
+          loading: foreground,
+          refreshing: !foreground,
+          error: foreground ? null : current.error,
+        }));
+      }
+      try {
+        const response = await client.listInteractionInterventions(workspaceId, {
+          ...(resourceKind ? { resourceKind } : {}),
+          ...(resourceId ? { resourceId } : {}),
+          includeSettled,
+          signal: controller.signal,
+        });
+        if (!mountedRef.current || requestRef.current.id !== id) return;
+        setState({
+          key,
+          interventions: sortInterventions(response.interventions),
+          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 };
+      }
+    },
+    [client, enabled, includeSettled, key, resourceId, resourceKind, workspaceId],
+  );
+
+  const refresh = useCallback(async () => await load(false, true), [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,
+    fallbackPollIntervalMs: options.pollIntervalMs ?? 2_000,
+  });
+
+  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(
+    (intervention: InteractionIntervention) => {
+      setState((current) => {
+        if (current.key !== key) return current;
+        const interventions = current.interventions.filter(
+          (candidate) => candidate.id !== intervention.id,
+        );
+        const matches =
+          (!resourceKind || intervention.resourceKind === resourceKind) &&
+          (!resourceId || intervention.resourceId === resourceId);
+        if (matches && (includeSettled || intervention.status === "open")) {
+          interventions.push(intervention);
+        }
+        return {
+          ...current,
+          interventions: sortInterventions(interventions),
+          error: null,
+        };
+      });
+    },
+    [includeSettled, key, resourceId, resourceKind],
+  );
+
+  const create = useCallback(
+    async (
+      request: Omit<CreateInteractionInterventionRequest, "operationId"> & {
+        operationId?: string;
+      },
+    ): Promise<InteractionInterventionMutationResponse> =>
+      await mutate(async () => {
+        const response = await client.createInteractionIntervention(workspaceId, {
+          ...request,
+          operationId: request.operationId ?? crypto.randomUUID(),
+        });
+        merge(response.intervention);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  const resolve = useCallback(
+    async (
+      interventionId: string,
+      request: Omit<ResolveInteractionInterventionRequest, "operationId"> & {
+        operationId?: string;
+      },
+    ): Promise<InteractionInterventionMutationResponse> =>
+      await mutate(async () => {
+        const response = await client.resolveInteractionIntervention(workspaceId, interventionId, {
+          ...request,
+          operationId: request.operationId ?? crypto.randomUUID(),
+        });
+        merge(response.intervention);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  return {
+    interventions: visible.interventions,
+    loading: visible.loading,
+    refreshing: visible.refreshing,
+    mutating: mutationCount > 0,
+    error: visible.error,
+    refresh,
+    create,
+    resolve,
+  };
+}
+
+function emptyState(key: string, loading: boolean) {
+  return {
+    key,
+    interventions: [] as InteractionIntervention[],
+    loading,
+    refreshing: false,
+    error: null as Error | null,
+  };
+}
+
+function sortInterventions(
+  interventions: readonly InteractionIntervention[],
+): InteractionIntervention[] {
+  return [...interventions].sort(
+    (left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt),
+  );
+}
+
+function asError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+
+export type InteractionInterventionsClient = EmbeddedInterventionClientLike;

package/src/hooks/use-interaction-invalidation.ts

@@ -0,0 +1,66 @@
+import type { StreamConnectionState, WorkspaceInteractionRevisionEvent } from "@opengeni/sdk";
+import { useEffect, useRef } from "react";
+import { usePageLiveActivity } from "./internal";
+
+export type InteractionInvalidationOptions = {
+  workspaceId: string;
+  /** Distinguishes filtered projections of the same workspace catalog. */
+  key: string;
+  enabled: boolean;
+  event: WorkspaceInteractionRevisionEvent | null;
+  connectionState: StreamConnectionState | "idle" | "error";
+  /** Catalog responses carry the workspace revision; live-state lists do not. */
+  knownRevision?: number | undefined;
+  refresh: () => Promise<void>;
+  fallbackPollIntervalMs?: number | undefined;
+};
+
+/**
+ * Refetch authoritative lists on the shared latest-revision stream. Poll only
+ * while that stream is unavailable, preserving standalone-hook degradation
+ * without multiplying healthy-provider traffic.
+ */
+export function useInteractionInvalidation(options: InteractionInvalidationOptions): void {
+  const {
+    workspaceId,
+    key,
+    enabled,
+    event,
+    connectionState,
+    knownRevision,
+    refresh,
+    fallbackPollIntervalMs,
+  } = options;
+  const pageLive = usePageLiveActivity();
+  const lastUnversionedEvent = useRef<{ key: string; sequence: number }>({
+    key,
+    sequence: 0,
+  });
+  const eventSequence = event?.workspaceId === workspaceId ? event.sequence : 0;
+
+  useEffect(() => {
+    if (!enabled || eventSequence <= 0) return;
+    if (knownRevision !== undefined) {
+      if (eventSequence > knownRevision) void refresh();
+      return;
+    }
+    if (lastUnversionedEvent.current.key !== key) {
+      lastUnversionedEvent.current = { key, sequence: 0 };
+    }
+    if (eventSequence <= lastUnversionedEvent.current.sequence) return;
+    lastUnversionedEvent.current = { key, sequence: eventSequence };
+    void refresh();
+  }, [enabled, eventSequence, key, knownRevision, refresh]);
+
+  useEffect(() => {
+    if (!enabled || !pageLive || connectionState === "live") return;
+    const interval = boundedPollInterval(fallbackPollIntervalMs ?? 3_000);
+    const timer = setInterval(() => void refresh(), interval);
+    return () => clearInterval(timer);
+  }, [connectionState, enabled, fallbackPollIntervalMs, pageLive, refresh]);
+}
+
+function boundedPollInterval(value: number): number {
+  if (!Number.isFinite(value)) return 3_000;
+  return Math.min(60_000, Math.max(1_000, Math.floor(value)));
+}

package/src/hooks/use-machine-chip.ts

@@ -2,6 +2,7 @@ import { useMemo } from "react";
 import type { MachineState } from "@opengeni/sdk";
 import type { SessionCapabilitiesState } from "./use-session-capabilities";
 import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
+import { connectionStatusForState } from "../types/machines";
 
 /** The one truthful machine indicator. Honest staleness beats
  *  fake liveness: a cold/asleep box reads "offline — as of <time>", never "live". */
@@ -65,9 +66,18 @@ export function deriveMachineChip(input: DeriveMachineChipInput): MachineChip {
   const asOf = input.capturedAt ?? null;
   const offlineLabel = asOf ? `Offline — as of ${formatAsOf(asOf, now)}` : "Offline";
 
-  // 1. Only holder-confirmed warm is live. Draining is teardown-owned and may
-  // already have lost its provider instance, so it uses the capture-backed label.
-  if (sandboxAcceptsLiveIo(input.liveness)) {
+  // A connected machine has no Modal group lease, so capability negotiation
+  // legitimately reports `cold` until a stream holder is minted. Its fleet
+  // probe is the authoritative reachability signal; do not label an online Mac
+  // "Offline" merely because there is no unrelated Modal lease.
+  const selfhostedOnline =
+    input.activeIsSelfhosted === true &&
+    input.activeMachineState != null &&
+    connectionStatusForState(input.activeMachineState) === "online";
+
+  // 1. A holder-confirmed warm provider or online connected machine is live.
+  // Draining remains teardown-owned and may already have lost its instance.
+  if (sandboxAcceptsLiveIo(input.liveness) || selfhostedOnline) {
     return { state: "live", label: "Live", asOf: null };
   }
 

package/src/hooks/use-network-routes.ts

@@ -0,0 +1,214 @@
+import type {
+  CreateNetworkRouteRequest,
+  NetworkRoute,
+  NetworkRouteMutationResponse,
+  UpdateNetworkRouteRequest,
+} 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 UseNetworkRoutesOptions = EmbeddedBrowserInteractionClientOverride & {
+  enabled?: boolean | undefined;
+  includeArchived?: boolean | undefined;
+};
+
+export type UseNetworkRoutesResult = {
+  revision: number;
+  routes: NetworkRoute[];
+  loading: boolean;
+  refreshing: boolean;
+  mutating: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  create: (
+    request: Omit<CreateNetworkRouteRequest, "operationId"> & { operationId?: string },
+  ) => Promise<NetworkRouteMutationResponse>;
+  update: (
+    networkRouteId: string,
+    request: Omit<UpdateNetworkRouteRequest, "operationId"> & { operationId?: string },
+  ) => Promise<NetworkRouteMutationResponse>;
+};
+
+/** Workspace network-route registry. Route mutations never expose brokered credentials. */
+export function useNetworkRoutes(options: UseNetworkRoutesOptions = {}): UseNetworkRoutesResult {
+  const { client, workspaceId, workspaceInteractionEvent, workspaceInteractionConnectionState } =
+    useEmbeddedBrowserInteraction(options);
+  const enabled = options.enabled ?? true;
+  const includeArchived = options.includeArchived ?? false;
+  const key = `${workspaceId}:${includeArchived ? "all" : "active"}`;
+  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.listNetworkRoutes(workspaceId, {
+          includeArchived,
+          signal: controller.signal,
+        });
+        if (!mountedRef.current || requestRef.current.id !== id) return;
+        setState({
+          key,
+          revision: response.revision,
+          routes: sortRoutes(response.routes),
+          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 };
+      }
+    },
+    [client, enabled, includeArchived, key, workspaceId],
+  );
+
+  useEffect(() => {
+    mountedRef.current = true;
+    if (!enabled) {
+      cancelLoad();
+      setState(emptyState(key, false));
+      return;
+    }
+    void load(true);
+    return () => {
+      mountedRef.current = false;
+      cancelLoad();
+    };
+  }, [cancelLoad, enabled, key, load]);
+
+  const refresh = useCallback(async () => await load(false), [load]);
+  useInteractionInvalidation({
+    workspaceId,
+    key,
+    enabled,
+    event: workspaceInteractionEvent,
+    connectionState: workspaceInteractionConnectionState,
+    knownRevision: visible.revision,
+    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(
+    (route: NetworkRoute) => {
+      setState((current) => {
+        if (current.key !== key) return current;
+        const routes = current.routes.filter((candidate) => candidate.id !== route.id);
+        if (includeArchived || route.status !== "archived") routes.push(route);
+        return { ...current, routes: sortRoutes(routes), error: null };
+      });
+    },
+    [includeArchived, key],
+  );
+
+  const create = useCallback(
+    async (
+      request: Omit<CreateNetworkRouteRequest, "operationId"> & { operationId?: string },
+    ): Promise<NetworkRouteMutationResponse> =>
+      await mutate(async () => {
+        const response = await client.createNetworkRoute(workspaceId, {
+          ...request,
+          operationId: request.operationId ?? crypto.randomUUID(),
+        });
+        merge(response.route);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  const update = useCallback(
+    async (
+      networkRouteId: string,
+      request: Omit<UpdateNetworkRouteRequest, "operationId"> & { operationId?: string },
+    ): Promise<NetworkRouteMutationResponse> =>
+      await mutate(async () => {
+        const response = await client.updateNetworkRoute(workspaceId, networkRouteId, {
+          ...request,
+          operationId: request.operationId ?? crypto.randomUUID(),
+        });
+        merge(response.route);
+        return response;
+      }),
+    [client, merge, mutate, workspaceId],
+  );
+
+  return {
+    revision: visible.revision,
+    routes: visible.routes,
+    loading: visible.loading,
+    refreshing: visible.refreshing,
+    mutating: mutationCount > 0,
+    error: visible.error,
+    refresh,
+    create,
+    update,
+  };
+}
+
+function emptyState(key: string, loading: boolean) {
+  return {
+    key,
+    revision: 0,
+    routes: [] as NetworkRoute[],
+    loading,
+    refreshing: false,
+    error: null as Error | null,
+  };
+}
+
+function sortRoutes(routes: readonly NetworkRoute[]): NetworkRoute[] {
+  return [...routes].sort(
+    (left, right) =>
+      Number(left.status === "archived") - Number(right.status === "archived") ||
+      left.name.localeCompare(right.name),
+  );
+}
+
+function asError(cause: unknown): Error {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+
+export type NetworkRoutesClient = EmbeddedBrowserInteractionClientLike;