@stigmer/react 0.0.101 → 0.1.0

package/src/invitation/useOrgInvitations.ts

@@ -1,11 +1,10 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import type { Invitation } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/api_pb";
 import { ListInvitationsByOrgInputSchema } 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 useOrgInvitations}. */
 export interface UseOrgInvitationsReturn {
@@ -13,6 +12,8 @@ export interface UseOrgInvitationsReturn {
   readonly invitations: readonly Invitation[];
   /** `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 invitation list from the server. */
@@ -45,44 +46,17 @@ export function useOrgInvitations(
   org: string | null,
 ): UseOrgInvitationsReturn {
   const stigmer = useStigmer();
-  const [invitations, setInvitations] = useState<Invitation[]>([]);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
 
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
-
-  useEffect(() => {
-    if (!org) {
-      setInvitations([]);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
-
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.invitation
-      .listByOrg(create(ListInvitationsByOrgInputSchema, { org }))
-      .then(
-        (result) => {
-          if (cancelled.current) return;
-          setInvitations([...result.entries]);
-          setIsLoading(false);
-        },
-        (err) => {
-          if (cancelled.current) return;
-          setError(toError(err));
-          setIsLoading(false);
-        },
-      );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [org, stigmer, fetchKey]);
-
-  return { invitations, isLoading, error, refetch };
+  const { data: invitations, isLoading, isRefetching, error, refetch } = useFetch(
+    org
+      ? () =>
+          stigmer.invitation
+            .listByOrg(create(ListInvitationsByOrgInputSchema, { org }))
+            .then((r) => [...r.entries])
+      : null,
+    [org, stigmer],
+    [] as Invitation[],
+  );
+
+  return { invitations, isLoading, isRefetching, error, refetch };
 }

package/src/library/ResourceListView.tsx

@@ -22,8 +22,8 @@ export interface ResourceListViewProps {
   readonly items: readonly SearchResult[];
   /** Whether data is currently being fetched. */
   readonly isLoading: boolean;
-  /** Error message from the data hook. Shown as an alert when present and not loading. */
-  readonly error?: string | null;
+  /** Error from the data hook. Shown as an alert when present and not loading. */
+  readonly error?: Error | null;
   /** Total number of results across all pages. Shown in the pagination bar when provided. */
   readonly totalCount?: number;
   /** Total number of pages available. Enables pagination controls when greater than 1. */
@@ -375,7 +375,7 @@ export function ResourceListView({
 
       {showSkeletons && (isGrid ? <SkeletonCards /> : <SkeletonRows />)}
 
-      {showError && <ErrorState message={error!} onRetry={onRetry} />}
+      {showError && <ErrorState message={error!.message} onRetry={onRetry} />}
 
       {showEmpty && (
         <EmptyState

package/src/library/useDetectSkillPackage.ts

@@ -24,7 +24,7 @@ export interface UseDetectSkillPackageReturn {
   readonly isLoading: boolean;
 
   /** Error message from the SKILL.md fetch, or `null` when healthy. */
-  readonly error: string | null;
+  readonly error: Error | null;
 }
 
 /**

package/src/mcp-server/McpServerPicker.tsx

@@ -580,7 +580,7 @@ export function McpServerPicker({
         autoFocus
       />
 
-      {error && <p className="text-xs text-destructive">{error}</p>}
+      {error && <p className="text-xs text-destructive">{error.message}</p>}
 
       {/* Scrollable results list */}
       <div className="relative">

package/src/mcp-server/useMcpServer.ts

@@ -1,10 +1,9 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { isNotFound } from "@stigmer/sdk";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link useMcpServer}. */
 export interface UseMcpServerReturn {
@@ -12,6 +11,8 @@ export interface UseMcpServerReturn {
   readonly mcpServer: McpServer | null;
   /** `true` while the initial fetch or a refetch is in flight. */
   readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight. */
+  readonly isRefetching: boolean;
   /** Error from the last failed request, or `null` when healthy. */
   readonly error: Error | null;
   /** Discard cached data and re-fetch the MCP server from the server. */
@@ -60,47 +61,21 @@ export function useMcpServer(
   slug: string | null,
 ): UseMcpServerReturn {
   const stigmer = useStigmer();
-  const [mcpServer, setMcpServer] = useState<McpServer | 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), []);
-
-  useEffect(() => {
-    if (!org || !slug) {
-      setMcpServer(null);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
-
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.mcpServer.getByReference({ org, slug }).then(
-      (result) => {
-        if (cancelled.current) return;
-        setMcpServer(result);
-        setIsLoading(false);
-      },
-      (err) => {
-        if (cancelled.current) return;
-        if (isNotFound(err)) {
-          setMcpServer(null);
-          setIsLoading(false);
-          return;
+  const { data: mcpServer, isLoading, isRefetching, error, refetch } = useFetch(
+    org && slug
+      ? async () => {
+          try {
+            return await stigmer.mcpServer.getByReference({ org, slug });
+          } catch (err) {
+            if (isNotFound(err)) return null;
+            throw err;
+          }
         }
-        setError(toError(err));
-        setIsLoading(false);
-      },
-    );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [org, slug, stigmer, fetchKey]);
+      : null,
+    [org, slug, stigmer],
+    null,
+  );
 
-  return { mcpServer, isLoading, error, refetch };
+  return { mcpServer, isLoading, isRefetching, error, refetch };
 }

package/src/mcp-server/useMcpServerCount.ts

@@ -29,7 +29,7 @@ export interface UseMcpServerCountReturn {
   /** `true` while the count fetch is in flight. */
   readonly isLoading: boolean;
   /** Error message from the last failed request, or `null` when healthy. */
-  readonly error: string | null;
+  readonly error: Error | null;
   /** Discard cached data and re-fetch the count from the server. */
   readonly refetch: () => void;
 }

package/src/mcp-server/useMcpServerList.ts

@@ -36,8 +36,8 @@ export interface UseMcpServerListReturn {
   readonly currentPage: number;
   /** `true` while the initial fetch or a refetch is in flight. */
   readonly isLoading: boolean;
-  /** Error message from the last failed request, or `null` when healthy. */
-  readonly error: string | null;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
   /** Discard cached data and re-fetch the current page from the server. */
   readonly refetch: () => void;
 }

package/src/mcp-server/useOAuthGrantStatus.ts

@@ -1,13 +1,12 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import {
   OAuthConnectionHealth,
   GetOAuthGrantStatusInputSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link useOAuthGrantStatus}. */
 export interface UseOAuthGrantStatusReturn {
@@ -32,6 +31,8 @@ export interface UseOAuthGrantStatusReturn {
   readonly connectionHealth: OAuthConnectionHealth;
   /** `true` while the grant status is being fetched. */
   readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight. */
+  readonly isRefetching: boolean;
   /** Error from the last failed request, or `null` when healthy. */
   readonly error: Error | null;
   /** Discard cached data and re-fetch the grant status. */
@@ -40,15 +41,20 @@ export interface UseOAuthGrantStatusReturn {
 
 const BIGINT_ZERO = BigInt(0);
 
-const IDLE: UseOAuthGrantStatusReturn = {
+interface OAuthGrantData {
+  connected: boolean;
+  accessTokenExpiresAt: bigint;
+  targetEnvVar: string;
+  authMethod: string;
+  connectionHealth: OAuthConnectionHealth;
+}
+
+const IDLE_DATA: OAuthGrantData = {
   connected: false,
   accessTokenExpiresAt: BIGINT_ZERO,
   targetEnvVar: "",
   authMethod: "",
   connectionHealth: OAuthConnectionHealth.OAUTH_CONNECTION_HEALTH_UNSPECIFIED,
-  isLoading: false,
-  error: null,
-  refetch: () => {},
 };
 
 /**
@@ -75,69 +81,25 @@ export function useOAuthGrantStatus(
   org: string | null,
 ): UseOAuthGrantStatusReturn {
   const stigmer = useStigmer();
-  const [connected, setConnected] = useState(false);
-  const [accessTokenExpiresAt, setAccessTokenExpiresAt] = useState(BIGINT_ZERO);
-  const [targetEnvVar, setTargetEnvVar] = useState("");
-  const [authMethod, setAuthMethod] = useState("");
-  const [connectionHealth, setConnectionHealth] = useState(
-    OAuthConnectionHealth.OAUTH_CONNECTION_HEALTH_UNSPECIFIED,
-  );
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
-
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
-
-  useEffect(() => {
-    if (!resourceId || !org) {
-      setConnected(false);
-      setAccessTokenExpiresAt(BIGINT_ZERO);
-      setTargetEnvVar("");
-      setAuthMethod("");
-      setConnectionHealth(OAuthConnectionHealth.OAUTH_CONNECTION_HEALTH_UNSPECIFIED);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
 
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.mcpServer
-      .getOAuthGrantStatus(create(GetOAuthGrantStatusInputSchema, { resourceId, org }))
-      .then(
-        (result) => {
-          if (cancelled.current) return;
-          setConnected(result.connected);
-          setAccessTokenExpiresAt(result.accessTokenExpiresAt);
-          setTargetEnvVar(result.targetEnvVar);
-          setAuthMethod(result.authMethod);
-          setConnectionHealth(result.connectionHealth);
-          setIsLoading(false);
-        },
-        (err) => {
-          if (cancelled.current) return;
-          setError(toError(err));
-          setIsLoading(false);
-        },
-      );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [resourceId, org, stigmer, fetchKey]);
-
-  if (!resourceId || !org) return { ...IDLE, refetch };
+  const { data, isLoading, isRefetching, error, refetch } = useFetch<OAuthGrantData>(
+    resourceId && org
+      ? async () => {
+          const result = await stigmer.mcpServer.getOAuthGrantStatus(
+            create(GetOAuthGrantStatusInputSchema, { resourceId, org }),
+          );
+          return {
+            connected: result.connected,
+            accessTokenExpiresAt: result.accessTokenExpiresAt,
+            targetEnvVar: result.targetEnvVar,
+            authMethod: result.authMethod,
+            connectionHealth: result.connectionHealth,
+          };
+        }
+      : null,
+    [resourceId, org, stigmer],
+    IDLE_DATA,
+  );
 
-  return {
-    connected,
-    accessTokenExpiresAt,
-    targetEnvVar,
-    authMethod,
-    connectionHealth,
-    isLoading,
-    error,
-    refetch,
-  };
+  return { ...data, isLoading, isRefetching, error, refetch };
 }

package/src/mcp-server/useOrgOAuthApp.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import {
   GetOrgOAuthAppInputSchema,
@@ -9,6 +9,7 @@ import {
 } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link useOrgOAuthApp}. */
 export interface UseOrgOAuthAppReturn {
@@ -24,6 +25,8 @@ export interface UseOrgOAuthAppReturn {
   readonly clientId: string | null;
   /** `true` while the override status is being fetched. */
   readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight. */
+  readonly isRefetching: boolean;
   /** Error from the last failed fetch, or `null` when healthy. */
   readonly error: Error | null;
   /** Discard cached data and re-fetch the override status. */
@@ -68,11 +71,22 @@ export interface UseOrgOAuthAppReturn {
   readonly clearErrors: () => void;
 }
 
-const IDLE: UseOrgOAuthAppReturn = {
+interface OrgOAuthAppData {
+  hasOverride: boolean;
+  oauthAppId: string | null;
+  clientId: string | null;
+}
+
+const IDLE_DATA: OrgOAuthAppData = {
   hasOverride: false,
   oauthAppId: null,
   clientId: null,
+};
+
+const IDLE: UseOrgOAuthAppReturn = {
+  ...IDLE_DATA,
   isLoading: false,
+  isRefetching: false,
   error: null,
   refetch: () => {},
   setOrgOAuthApp: () => Promise.resolve(""),
@@ -119,63 +133,33 @@ export function useOrgOAuthApp(
 ): UseOrgOAuthAppReturn {
   const stigmer = useStigmer();
 
-  const [hasOverride, setHasOverride] = useState(false);
-  const [oauthAppId, setOauthAppId] = useState<string | null>(null);
-  const [clientId, setClientId] = useState<string | null>(null);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
+  const { data, isLoading, isRefetching, error, refetch } = useFetch<OrgOAuthAppData>(
+    resourceId && org
+      ? async () => {
+          const result = await stigmer.mcpServer.getOrgOAuthApp(
+            create(GetOrgOAuthAppInputSchema, { resourceId, org }),
+          );
+          return {
+            hasOverride: result.hasOverride,
+            oauthAppId: result.oauthAppId || null,
+            clientId: result.clientId || null,
+          };
+        }
+      : null,
+    [resourceId, org, stigmer],
+    IDLE_DATA,
+  );
 
   const [isSetting, setIsSetting] = useState(false);
   const [setError_, setSetError] = useState<Error | null>(null);
   const [isDeleting, setIsDeleting] = useState(false);
   const [deleteError, setDeleteError] = useState<Error | null>(null);
 
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
-
   const clearErrors = useCallback(() => {
     setSetError(null);
     setDeleteError(null);
   }, []);
 
-  useEffect(() => {
-    if (!resourceId || !org) {
-      setHasOverride(false);
-      setOauthAppId(null);
-      setClientId(null);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
-
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.mcpServer
-      .getOrgOAuthApp(
-        create(GetOrgOAuthAppInputSchema, { resourceId, org }),
-      )
-      .then(
-        (result) => {
-          if (cancelled.current) return;
-          setHasOverride(result.hasOverride);
-          setOauthAppId(result.oauthAppId || null);
-          setClientId(result.clientId || null);
-          setIsLoading(false);
-        },
-        (err) => {
-          if (cancelled.current) return;
-          setError(toError(err));
-          setIsLoading(false);
-        },
-      );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [resourceId, org, stigmer, fetchKey]);
-
   const setOrgOAuthApp = useCallback(
     async (newClientId: string, clientSecret: string): Promise<string> => {
       if (!resourceId || !org) {
@@ -233,10 +217,9 @@ export function useOrgOAuthApp(
   if (!resourceId || !org) return { ...IDLE, refetch, clearErrors };
 
   return {
-    hasOverride,
-    oauthAppId,
-    clientId,
+    ...data,
     isLoading,
+    isRefetching,
     error,
     refetch,
     setOrgOAuthApp,

package/src/oauth-app/useOAuthAppList.ts

@@ -1,11 +1,10 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import { create } from "@bufbuild/protobuf";
 import { ListOAuthAppsByOrgInputSchema } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/io_pb";
 import type { OAuthApp } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/api_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link useOAuthAppList}. */
 export interface UseOAuthAppListReturn {
@@ -13,6 +12,8 @@ export interface UseOAuthAppListReturn {
   readonly oauthApps: readonly OAuthApp[];
   /** `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 list from the server. */
@@ -41,44 +42,17 @@ export function useOAuthAppList(
   org: string | null,
 ): UseOAuthAppListReturn {
   const stigmer = useStigmer();
-  const [oauthApps, setOauthApps] = useState<OAuthApp[]>([]);
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
 
-  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
-
-  useEffect(() => {
-    if (!org) {
-      setOauthApps([]);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
-
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.oauthapp
-      .listByOrg(create(ListOAuthAppsByOrgInputSchema, { org }))
-      .then(
-        (result) => {
-          if (cancelled.current) return;
-          setOauthApps([...result.entries]);
-          setIsLoading(false);
-        },
-        (err) => {
-          if (cancelled.current) return;
-          setError(toError(err));
-          setIsLoading(false);
-        },
-      );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [org, stigmer, fetchKey]);
-
-  return { oauthApps, isLoading, error, refetch };
+  const { data: oauthApps, isLoading, isRefetching, error, refetch } = useFetch(
+    org
+      ? () =>
+          stigmer.oauthapp
+            .listByOrg(create(ListOAuthAppsByOrgInputSchema, { org }))
+            .then((r) => [...r.entries])
+      : null,
+    [org, stigmer],
+    [] as OAuthApp[],
+  );
+
+  return { oauthApps, isLoading, isRefetching, error, refetch };
 }

package/src/organization/useOrganization.ts

@@ -1,9 +1,8 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import type { Organization } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
 import { useStigmer } from "../hooks";
-import { toError } from "../internal/toError";
+import { useFetch } from "../internal/useFetch";
 
 /** Return value of {@link useOrganization}. */
 export interface UseOrganizationReturn {
@@ -11,6 +10,8 @@ export interface UseOrganizationReturn {
   readonly organization: Organization | 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 organization from the server. */
@@ -38,42 +39,12 @@ export function useOrganization(
   id: string | null,
 ): UseOrganizationReturn {
   const stigmer = useStigmer();
-  const [organization, setOrganization] = useState<Organization | 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: organization, isLoading, isRefetching, error, refetch } = useFetch(
+    id ? () => stigmer.organization.get(id) : null,
+    [id, stigmer],
+    null as Organization | null,
+  );
 
-  useEffect(() => {
-    if (!id) {
-      setOrganization(null);
-      setIsLoading(false);
-      setError(null);
-      return;
-    }
-
-    const cancelled = { current: false };
-    setIsLoading(true);
-    setError(null);
-
-    stigmer.organization.get(id).then(
-      (result) => {
-        if (cancelled.current) return;
-        setOrganization(result);
-        setIsLoading(false);
-      },
-      (err) => {
-        if (cancelled.current) return;
-        setError(toError(err));
-        setIsLoading(false);
-      },
-    );
-
-    return () => {
-      cancelled.current = true;
-    };
-  }, [id, stigmer, fetchKey]);
-
-  return { organization, isLoading, error, refetch };
+  return { organization, isLoading, isRefetching, error, refetch };
 }