@stigmer/react 0.0.101 → 0.1.1

package/src/iam-policy/usePrincipalsCount.ts

@@ -1,10 +1,9 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import { GetPrincipalsCountInputSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link usePrincipalsCount}. */
 export interface UsePrincipalsCountReturn {
@@ -12,6 +11,8 @@ export interface UsePrincipalsCountReturn {
   readonly count: number;
   /** `true` while the fetch is in flight. */
   readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
   /** Error from the last failed request, or `null` when healthy. */
   readonly error: Error | null;
   /** Re-fetch the count from the server. */
@@ -41,56 +42,19 @@ export function usePrincipalsCount(
   principalKind: string = "identity_account",
 ): UsePrincipalsCountReturn {
   const stigmer = useStigmer();
-  const [count, setCount] = useState(0);
-  const [isLoading, setIsLoading] = useState(!!orgId);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
 
-  const [prevOrgId, setPrevOrgId] = useState(orgId);
-  if (orgId !== prevOrgId) {
-    setPrevOrgId(orgId);
-    if (orgId) {
-      setIsLoading(true);
-      setCount(0);
-      setError(null);
-    } else {
-      setIsLoading(false);
-      setCount(0);
-      setError(null);
-    }
-  }
-
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
-
-  useEffect(() => {
-    if (!orgId) return;
-
-    const cancelled = { current: false };
-
-    stigmer.iamPolicy
-      .getPrincipalsCount(
-        create(GetPrincipalsCountInputSchema, {
-          orgId,
-          principalKind,
-        }),
-      )
-      .then(
-        (result) => {
-          if (cancelled.current) return;
-          setCount(result.count);
-          setIsLoading(false);
-        },
-        (err) => {
-          if (cancelled.current) return;
-          setError(toError(err));
-          setIsLoading(false);
-        },
-      );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [orgId, principalKind, stigmer, fetchKey]);
-
-  return { count, isLoading, error, refetch };
+  const { data: count, isLoading, isRefetching, error, refetch } = useFetch(
+    orgId
+      ? () =>
+          stigmer.iamPolicy
+            .getPrincipalsCount(
+              create(GetPrincipalsCountInputSchema, { orgId, principalKind }),
+            )
+            .then((r) => r.count)
+      : null,
+    [orgId, principalKind, stigmer],
+    0,
+  );
+
+  return { count, isLoading, isRefetching, error, refetch };
 }

package/src/iam-policy/useResourceAccess.ts

@@ -1,6 +1,5 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import type { PrincipalAccess } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
 import {
@@ -8,7 +7,7 @@ import {
 } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
 import { ApiResourceRefSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Resource reference for the access query. */
 export interface ResourceAccessRef {
@@ -30,6 +29,8 @@ export interface UseResourceAccessReturn {
   readonly members: readonly PrincipalAccess[];
   /** `true` while the fetch is in flight. */
   readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
   /** Error from the last failed request, or `null` when healthy. */
   readonly error: Error | null;
   /** Re-fetch the access list from the server. */
@@ -66,63 +67,25 @@ export function useResourceAccess(
   options?: UseResourceAccessOptions,
 ): UseResourceAccessReturn {
   const stigmer = useStigmer();
-  const [members, setMembers] = useState<PrincipalAccess[]>([]);
-  const [isLoading, setIsLoading] = useState(!!resource);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
-
   const kind = resource?.kind ?? null;
   const id = resource?.id ?? null;
   const includeInherited = options?.includeInherited ?? false;
 
-  const [prevKey, setPrevKey] = useState<string | null>(
-    kind && id ? `${kind}:${id}` : null,
+  const { data: members, isLoading, isRefetching, error, refetch } = useFetch(
+    kind && id
+      ? () => {
+          const input = create(ListResourceAccessInputSchema, {
+            resource: create(ApiResourceRefSchema, { kind, id }),
+            includeInherited,
+          });
+          return stigmer.iamPolicy
+            .listResourceAccessByPrincipal(input)
+            .then((r) => [...r.entries]);
+        }
+      : null,
+    [kind, id, includeInherited, stigmer],
+    [] as PrincipalAccess[],
   );
-  const currentKey = kind && id ? `${kind}:${id}` : null;
-  if (currentKey !== prevKey) {
-    setPrevKey(currentKey);
-    if (currentKey) {
-      setIsLoading(true);
-      setMembers([]);
-      setError(null);
-    } else {
-      setIsLoading(false);
-      setMembers([]);
-      setError(null);
-    }
-  }
-
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
-
-  useEffect(() => {
-    if (!kind || !id) return;
-
-    const cancelled = { current: false };
-
-    const input = create(ListResourceAccessInputSchema, {
-      resource: create(ApiResourceRefSchema, { kind, id }),
-      includeInherited,
-    });
-
-    stigmer.iamPolicy
-      .listResourceAccessByPrincipal(input)
-      .then(
-        (result) => {
-          if (cancelled.current) return;
-          setMembers([...result.entries]);
-          setIsLoading(false);
-        },
-        (err) => {
-          if (cancelled.current) return;
-          setError(toError(err));
-          setIsLoading(false);
-        },
-      );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [kind, id, includeInherited, stigmer, fetchKey]);
 
-  return { members, isLoading, error, refetch };
+  return { members, isLoading, isRefetching, error, refetch };
 }

package/src/identity-provider/useIdentityProvider.ts

@@ -1,9 +1,8 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import type { IdentityProvider } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/api_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link useIdentityProvider}. */
 export interface UseIdentityProviderReturn {
@@ -11,6 +10,8 @@ export interface UseIdentityProviderReturn {
   readonly identityProvider: IdentityProvider | null;
   /** `true` while the initial fetch or a refetch is in flight. */
   readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
   /** Error from the last failed request, or `null` when healthy. */
   readonly error: Error | null;
   /** Discard cached data and re-fetch from the server. */
@@ -44,43 +45,12 @@ export function useIdentityProvider(
   id: string | null,
 ): UseIdentityProviderReturn {
   const stigmer = useStigmer();
-  const [identityProvider, setIdentityProvider] =
-    useState<IdentityProvider | null>(null);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
 
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+  const { data: identityProvider, isLoading, isRefetching, error, refetch } = useFetch(
+    id ? () => stigmer.identityProvider.get(id) : null,
+    [id, stigmer],
+    null as IdentityProvider | null,
+  );
 
-  useEffect(() => {
-    if (!id) {
-      setIdentityProvider(null);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
-
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.identityProvider.get(id).then(
-      (result) => {
-        if (cancelled.current) return;
-        setIdentityProvider(result);
-        setIsLoading(false);
-      },
-      (err) => {
-        if (cancelled.current) return;
-        setError(toError(err));
-        setIsLoading(false);
-      },
-    );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [id, stigmer, fetchKey]);
-
-  return { identityProvider, isLoading, error, refetch };
+  return { identityProvider, isLoading, isRefetching, error, refetch };
 }

package/src/identity-provider/useIdentityProviderList.ts

@@ -1,11 +1,10 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import type { IdentityProvider } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/api_pb";
 import { ListIdentityProvidersByOrgInputSchema } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/io_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link useIdentityProviderList}. */
 export interface UseIdentityProviderListReturn {
@@ -13,6 +12,8 @@ export interface UseIdentityProviderListReturn {
   readonly identityProviders: readonly IdentityProvider[];
   /** `true` while the initial fetch or a refetch is in flight. */
   readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
   /** Error from the last failed request, or `null` when healthy. */
   readonly error: Error | null;
   /** Discard cached data and re-fetch from the server. */
@@ -57,44 +58,17 @@ export function useIdentityProviderList(
   org: string | null,
 ): UseIdentityProviderListReturn {
   const stigmer = useStigmer();
-  const [identityProviders, setIdentityProviders] = useState<
-    IdentityProvider[]
-  >([]);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
 
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+  const { data: identityProviders, isLoading, isRefetching, error, refetch } = useFetch(
+    org
+      ? () =>
+          stigmer.identityProvider
+            .listByOrg(create(ListIdentityProvidersByOrgInputSchema, { org }))
+            .then((r) => [...r.entries])
+      : null,
+    [org, stigmer],
+    [] as IdentityProvider[],
+  );
 
-  useEffect(() => {
-    if (!org) {
-      setIdentityProviders([]);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
-
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.identityProvider.listByOrg(create(ListIdentityProvidersByOrgInputSchema, { org })).then(
-      (result) => {
-        if (cancelled.current) return;
-        setIdentityProviders([...result.entries]);
-        setIsLoading(false);
-      },
-      (err) => {
-        if (cancelled.current) return;
-        setError(toError(err));
-        setIsLoading(false);
-      },
-    );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [org, stigmer, fetchKey]);
-
-  return { identityProviders, isLoading, error, refetch };
+  return { identityProviders, isLoading, isRefetching, error, refetch };
 }

package/src/index.ts

@@ -682,6 +682,7 @@ export type {
 export {
   useRunnerList,
   useLaunchLocalRunner,
+  useRunnerCredential,
   useStopRunner,
   useDeleteRunner,
   RunnerPicker,
@@ -689,6 +690,7 @@ export {
   phaseLabel,
   phaseDotColor,
   isActivePhase,
+  isTransitionalPhase,
   PHASE_SORT_ORDER,
 } from "./runner";
 export type {
@@ -697,6 +699,8 @@ export type {
   UseLaunchLocalRunnerOptions,
   UseLaunchLocalRunnerReturn,
   LaunchLocalRunnerResult,
+  RunnerCredential,
+  UseRunnerCredentialReturn,
   StopRunnerInput,
   UseStopRunnerReturn,
   UseDeleteRunnerReturn,

package/src/internal/__tests__/useFetch.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useFetch } from "../useFetch";
+
+async function flush(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+describe("useFetch — refetchInterval", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("polls at the specified interval", async () => {
+    let callCount = 0;
+    const fetchFn = vi.fn(async () => ++callCount);
+
+    const { result } = renderHook(() =>
+      useFetch(fetchFn, [], 0, { refetchInterval: 1000 }),
+    );
+
+    // Flush the initial dep-change fetch.
+    await flush();
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+    expect(result.current.data).toBe(1);
+
+    // Advance by one interval — should trigger a poll.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1000);
+    });
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+    expect(result.current.data).toBe(2);
+
+    // Another interval tick.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1000);
+    });
+    expect(fetchFn).toHaveBeenCalledTimes(3);
+  });
+
+  it("does not poll when refetchInterval is false", async () => {
+    const fetchFn = vi.fn(async () => "data");
+
+    renderHook(() => useFetch(fetchFn, [], "", { refetchInterval: false }));
+
+    await flush();
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(10_000);
+    });
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not poll when fetchFn is null", async () => {
+    const { result } = renderHook(() =>
+      useFetch(null, [], "init", { refetchInterval: 1000 }),
+    );
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(5000);
+    });
+
+    expect(result.current.data).toBe("init");
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it("cleans up interval on unmount", async () => {
+    const fetchFn = vi.fn(async () => "data");
+
+    const { unmount } = renderHook(() =>
+      useFetch(fetchFn, [], "", { refetchInterval: 1000 }),
+    );
+
+    await flush();
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+
+    unmount();
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(5000);
+    });
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips poll tick while a fetch is in flight", async () => {
+    let resolveInflight: ((v: string) => void) | null = null;
+
+    const fetchFn = vi.fn(async () => "first");
+
+    const { result } = renderHook(() =>
+      useFetch(fetchFn, [], "", { refetchInterval: 500 }),
+    );
+
+    // Initial fetch resolves immediately.
+    await flush();
+    expect(result.current.data).toBe("first");
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+
+    // Make the next fetch hang until manually resolved.
+    fetchFn.mockImplementation(
+      () =>
+        new Promise<string>((resolve) => {
+          resolveInflight = resolve;
+        }),
+    );
+
+    // First interval tick triggers a new fetch that hangs.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500);
+    });
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+
+    // Another tick fires but fetch is still in flight — should be skipped.
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500);
+    });
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+
+    // Resolve the in-flight fetch.
+    await act(async () => {
+      resolveInflight!("second");
+      await Promise.resolve();
+    });
+    expect(result.current.data).toBe("second");
+  });
+});

package/src/internal/useFetch.ts

@@ -0,0 +1,121 @@
+"use client";
+
+import { type DependencyList, useCallback, useEffect, useRef, useState } from "react";
+import { toError } from "./toError";
+
+/** Options for {@link useFetch}. */
+export interface UseFetchOptions {
+  /**
+   * Poll interval in milliseconds. When set to a positive number, the
+   * hook re-fetches on a timer. Set to `false` or `0` to disable.
+   *
+   * The timer is paused while a fetch is already in flight to prevent
+   * request piling on slow connections.
+   */
+  readonly refetchInterval?: number | false;
+}
+
+/** Return value of {@link useFetch}. */
+export interface UseFetchReturn<T> {
+  /** The most recently resolved data, or `initialData` before the first success. */
+  readonly data: T;
+  /**
+   * `true` only when no data has been fetched yet (first load).
+   * Once data arrives, subsequent refetches keep this `false`.
+   */
+  readonly isLoading: boolean;
+  /**
+   * `true` while a background refetch is in flight and stale data is
+   * being shown. Always `false` during the initial load.
+   */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Imperatively trigger a re-fetch. Stale data remains visible. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Generic data-fetching hook with stale-while-revalidate semantics.
+ *
+ * - Pass `null` for `fetchFn` to disable fetching (idle state).
+ * - On the **first** fetch, `isLoading` is `true` so consumers can
+ *   show a skeleton.
+ * - On **subsequent** fetches (refetch or dep change after first success),
+ *   `isLoading` stays `false` and `isRefetching` becomes `true` —
+ *   existing data remains visible, preventing skeleton flash.
+ * - On error during a refetch, stale data is preserved.
+ *
+ * @param fetchFn  Async function that returns data, or `null` to skip.
+ * @param deps     Dependency list — a new fetch fires when any dep changes.
+ * @param initialData  Value returned before the first successful fetch.
+ * @param options  Optional configuration (e.g. polling interval).
+ *
+ * @internal Not part of the public `@stigmer/react` API.
+ */
+export function useFetch<T>(
+  fetchFn: (() => Promise<T>) | null,
+  deps: DependencyList,
+  initialData: T,
+  options?: UseFetchOptions,
+): UseFetchReturn<T> {
+  const [data, setData] = useState<T>(initialData);
+  const [error, setError] = useState<Error | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const hasDataRef = useRef(false);
+  const isFetchingRef = useRef(false);
+  const [isFetching, setIsFetching] = useState(false);
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  useEffect(() => {
+    if (!fetchFn) {
+      setData(initialData);
+      setIsFetching(false);
+      isFetchingRef.current = false;
+      setError(null);
+      hasDataRef.current = false;
+      return;
+    }
+
+    const cancelled = { current: false };
+    setIsFetching(true);
+    isFetchingRef.current = true;
+    setError(null);
+
+    fetchFn().then(
+      (result) => {
+        if (cancelled.current) return;
+        setData(result);
+        hasDataRef.current = true;
+        setIsFetching(false);
+        isFetchingRef.current = false;
+      },
+      (err) => {
+        if (cancelled.current) return;
+        setError(toError(err));
+        setIsFetching(false);
+        isFetchingRef.current = false;
+      },
+    );
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [...deps, fetchKey]);
+
+  const refetchInterval = options?.refetchInterval;
+  useEffect(() => {
+    if (!refetchInterval || refetchInterval <= 0 || !fetchFn) return;
+    const id = setInterval(() => {
+      if (!isFetchingRef.current) refetch();
+    }, refetchInterval);
+    return () => clearInterval(id);
+  }, [refetchInterval, fetchFn, refetch]);
+
+  const isLoading = isFetching && !hasDataRef.current;
+  const isRefetching = isFetching && hasDataRef.current;
+
+  return { data, isLoading, isRefetching, error, refetch };
+}

package/src/invitation/useInvitationPreview.ts

@@ -1,11 +1,10 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import type { InvitationPreview } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/io_pb";
 import { InvitationTokenInputSchema } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/io_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link useInvitationPreview}. */
 export interface UseInvitationPreviewReturn {
@@ -13,6 +12,8 @@ export interface UseInvitationPreviewReturn {
   readonly preview: InvitationPreview | null;
   /** `true` while the initial fetch or a refetch is in flight. */
   readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
   /** Error from the last failed request, or `null` when healthy. */
   readonly error: Error | null;
   /** Discard cached data and re-fetch the preview from the server. */
@@ -60,44 +61,17 @@ export function useInvitationPreview(
   token: string | null,
 ): UseInvitationPreviewReturn {
   const stigmer = useStigmer();
-  const [preview, setPreview] = useState<InvitationPreview | null>(null);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
 
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+  const { data: preview, isLoading, isRefetching, error, refetch } = useFetch(
+    token
+      ? () =>
+          stigmer.invitation.getByToken(
+            create(InvitationTokenInputSchema, { token }),
+          )
+      : null,
+    [token, stigmer],
+    null as InvitationPreview | null,
+  );
 
-  useEffect(() => {
-    if (!token) {
-      setPreview(null);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
-
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.invitation
-      .getByToken(create(InvitationTokenInputSchema, { token }))
-      .then(
-        (result) => {
-          if (cancelled.current) return;
-          setPreview(result);
-          setIsLoading(false);
-        },
-        (err) => {
-          if (cancelled.current) return;
-          setError(toError(err));
-          setIsLoading(false);
-        },
-      );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [token, stigmer, fetchKey]);
-
-  return { preview, isLoading, error, refetch };
+  return { preview, isLoading, isRefetching, error, refetch };
 }