@stigmer/react 0.0.71 → 0.0.73

package/src/invitation/useOrgInvitations.ts

@@ -0,0 +1,88 @@
+"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";
+
+/** Return value of {@link useOrgInvitations}. */
+export interface UseOrgInvitationsReturn {
+  /** All invitations for the organization. Empty while loading or on error. */
+  readonly invitations: readonly Invitation[];
+  /** `true` while the initial fetch or a refetch is in flight. */
+  readonly isLoading: 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. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches all {@link Invitation} entries for an
+ * organization.
+ *
+ * Pass `null` to skip fetching (stable no-op). When the `org` slug
+ * changes, the previous in-flight request is discarded and a fresh
+ * fetch begins. Call `refetch()` to re-query after mutations
+ * (create / revoke).
+ *
+ * Requires `can_view_access` permission on the organization —
+ * only admins and owners can list invitation links.
+ *
+ * @param org - Organization slug, or `null` to skip fetching.
+ *
+ * @example
+ * ```tsx
+ * const { invitations, isLoading, error, refetch } = useOrgInvitations("acme");
+ *
+ * if (isLoading) return <Spinner />;
+ * invitations.map((inv) => inv.spec?.label);
+ * ```
+ */
+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 };
+}

package/src/invitation/useRedeemInvitation.ts

@@ -0,0 +1,82 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { Invitation } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/api_pb";
+import { RedeemInvitationInputSchema } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useRedeemInvitation}. */
+export interface UseRedeemInvitationReturn {
+  /**
+   * Redeem an invitation by its token.
+   *
+   * Creates an IAM policy granting the invitation's configured role
+   * to the authenticated user on the invitation's organization.
+   * Resolves with the updated {@link Invitation} so callers can
+   * access the organization and role information for post-redemption
+   * UI (e.g. "You've joined Acme as viewer").
+   */
+  readonly redeem: (token: string) => Promise<Invitation>;
+  /** `true` while the redeem request is in flight. */
+  readonly isRedeeming: boolean;
+  /** Error from the last failed redeem, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `invitation.redeem()` with loading and
+ * error state.
+ *
+ * Redeems an invitation by its shareable token. The server validates
+ * that the invitation is active, not expired, and not at its
+ * redemption limit, then creates an IAM policy granting the
+ * configured role to the authenticated user.
+ *
+ * The redeemer's identity is resolved from the authentication header
+ * — the token itself is the authorization mechanism (no FGA check
+ * on the invitation resource).
+ *
+ * Returns the updated {@link Invitation} including the incremented
+ * `status.redemptionCount` and the new entry in
+ * `status.redemptions`.
+ *
+ * @example
+ * ```tsx
+ * const { redeem, isRedeeming, error } = useRedeemInvitation();
+ *
+ * const invitation = await redeem("abc123...");
+ * // invitation.metadata?.org contains the org the user just joined
+ * ```
+ */
+export function useRedeemInvitation(): UseRedeemInvitationReturn {
+  const stigmer = useStigmer();
+  const [isRedeeming, setIsRedeeming] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const redeem = useCallback(
+    async (token: string): Promise<Invitation> => {
+      setIsRedeeming(true);
+      setError(null);
+
+      try {
+        return await stigmer.invitation.redeem(
+          create(RedeemInvitationInputSchema, { token }),
+        );
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsRedeeming(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { redeem, isRedeeming, error, clearError };
+}

package/src/invitation/useRevokeInvitation.ts

@@ -0,0 +1,66 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { Invitation } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useRevokeInvitation}. */
+export interface UseRevokeInvitationReturn {
+  /** Revoke an invitation by its resource ID. Resolves with the updated resource for confirmation display. */
+  readonly revoke: (id: string) => Promise<Invitation>;
+  /** `true` while the revoke request is in flight. */
+  readonly isRevoking: boolean;
+  /** Error from the last failed revoke, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `invitation.revoke()` with loading and
+ * error state.
+ *
+ * Revokes an active invitation by its resource ID, setting its state
+ * to `revoked` and preventing further redemptions. The operation is
+ * idempotent — revoking an already-revoked invitation is a no-op
+ * that returns the unchanged resource.
+ *
+ * Returns the updated {@link Invitation} so callers can verify the
+ * new state. Call `refetch()` on the list hook after revocation to
+ * refresh the invitation list.
+ *
+ * @example
+ * ```tsx
+ * const { revoke, isRevoking, error } = useRevokeInvitation();
+ *
+ * await revoke("inv-abc123");
+ * refetch(); // refresh the invitation list
+ * ```
+ */
+export function useRevokeInvitation(): UseRevokeInvitationReturn {
+  const stigmer = useStigmer();
+  const [isRevoking, setIsRevoking] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const revoke = useCallback(
+    async (id: string): Promise<Invitation> => {
+      setIsRevoking(true);
+      setError(null);
+
+      try {
+        return await stigmer.invitation.revoke(id);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsRevoking(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { revoke, isRevoking, error, clearError };
+}

package/src/library/detect-skill-package.ts

@@ -15,7 +15,10 @@ import { parse as parseYaml } from "yaml";
  * - **Package detection** (`detectSkillPackage`): Skill packages (directory with SKILL.md) — pushed via `pushFromExecutionArtifact()`
  */
 export type SkillPackageDetection =
-  | { readonly detected: false }
+  | {
+      /** Discriminant — `false` when no skill package was detected. */
+      readonly detected: false;
+    }
   | {
       /** Discriminant — always `true` when a skill package was detected. */
       readonly detected: true;

package/src/library/detect-stigmer-resource.ts

@@ -22,7 +22,10 @@ export type StigmerResourceKind = "Agent" | "McpServer";
  * can narrow the type with a simple `if (result.detected)` check.
  */
 export type StigmerResourceDetection =
-  | { readonly detected: false }
+  | {
+      /** Discriminant — `false` when no recognized resource was found. */
+      readonly detected: false;
+    }
   | {
       /** Discriminant — always `true` when a resource was found. */
       readonly detected: true;

package/src/library/parse-resource-yaml.ts

@@ -28,8 +28,18 @@ import type { StigmerResourceKind } from "./detect-stigmer-resource";
  * ```
  */
 export type ParsedResource =
-  | { readonly kind: "Agent"; readonly input: AgentInput }
-  | { readonly kind: "McpServer"; readonly input: McpServerInput };
+  | {
+      /** The parsed resource is an Agent blueprint. */
+      readonly kind: "Agent";
+      /** SDK input suitable for `stigmer.agent.apply()`. */
+      readonly input: AgentInput;
+    }
+  | {
+      /** The parsed resource is an MCP server definition. */
+      readonly kind: "McpServer";
+      /** SDK input suitable for `stigmer.mcpServer.apply()`. */
+      readonly input: McpServerInput;
+    };
 
 /**
  * Parses a Stigmer resource YAML string into the corresponding SDK input

package/src/mcp-server/McpServerDetailView.tsx

@@ -24,7 +24,8 @@ import type { EnvVarFormVariable } from "../environment/EnvVarForm";
 import { VisibilityToggle } from "../library/VisibilityToggle";
 import { Tabs, type TabItem } from "../internal/Tabs";
 
-type CapabilityTab = "tools" | "policies" | "resources";
+/** Tab identifier for the MCP server capability panel. */
+export type CapabilityTab = "tools" | "policies" | "resources";
 
 /** Props for {@link McpServerDetailView}. */
 export interface McpServerDetailViewProps {

package/src/mcp-server/index.ts

@@ -44,7 +44,10 @@ export type {
 } from "./useMcpServerSetup";
 
 export { McpServerDetailView } from "./McpServerDetailView";
-export type { McpServerDetailViewProps } from "./McpServerDetailView";
+export type {
+  McpServerDetailViewProps,
+  CapabilityTab,
+} from "./McpServerDetailView";
 
 export { useDiscoverCapabilities } from "./useDiscoverCapabilities";
 export type { UseDiscoverCapabilitiesReturn } from "./useDiscoverCapabilities";

package/src/mcp-server/mcpServerSetupReducer.ts

@@ -46,26 +46,44 @@ export function toServerKey(ref: ResourceRef): string {
  *   the "no env_spec needed" and "env vars resolved" cases.
  */
 export type McpServerSetupPhase =
-  | { readonly status: "loading" }
   | {
+      /** Fetching the full MCP server resource (spec + status). */
+      readonly status: "loading";
+    }
+  | {
+      /** The server has env vars missing from the user's personal environment. */
       readonly status: "needsSetup";
+      /** The fetched MCP server resource. */
       readonly mcpServer: McpServer;
+      /** Environment variables the user must provide before proceeding. */
       readonly missingVariables: EnvVarFormVariable[];
+      /** Tools discovered by the MCP server's status probe. */
       readonly discoveredTools: DiscoveredTool[];
+      /** Per-tool approval policies from the server spec. */
       readonly toolApprovals: ToolApprovalPolicy[];
     }
   | {
+      /** Environment variables are being persisted or the instance is being provisioned. */
       readonly status: "submitting";
+      /** The fetched MCP server resource. */
       readonly mcpServer: McpServer;
+      /** Environment variables collected from the user. */
       readonly missingVariables: EnvVarFormVariable[];
+      /** Tools discovered by the MCP server's status probe. */
       readonly discoveredTools: DiscoveredTool[];
+      /** Per-tool approval policies from the server spec. */
       readonly toolApprovals: ToolApprovalPolicy[];
     }
   | {
+      /** The server is fully configured and ready for session creation. */
       readonly status: "ready";
+      /** The fetched MCP server resource. */
       readonly mcpServer: McpServer;
+      /** Tools discovered by the MCP server's status probe. */
       readonly discoveredTools: DiscoveredTool[];
+      /** Per-tool approval policies from the server spec. */
       readonly toolApprovals: ToolApprovalPolicy[];
+      /** Tool names enabled for this session, after user selection. */
       readonly enabledTools: string[];
     };
 
@@ -80,6 +98,7 @@ export type McpServerSetupPhase =
  * Matches the pattern established by `AgentSetupState`.
  */
 export type McpServerSetupEntry = McpServerSetupPhase & {
+  /** Error from the last async transition, or `null` when healthy. */
   readonly error: Error | null;
 };
 
@@ -107,45 +126,104 @@ export type McpServerSetupState = Readonly<
  * produced by {@link toServerKey}) identifying the target entry.
  */
 export type McpServerSetupAction =
-  | { readonly type: "ADD_SERVER"; readonly key: string }
   | {
+      /** Add a new server entry in `loading` phase. */
+      readonly type: "ADD_SERVER";
+      /** Server key (`"org/slug"`). */
+      readonly key: string;
+    }
+  | {
+      /** Server resolved but needs env var collection. */
       readonly type: "RESOLVE_NEEDS_SETUP";
+      /** Server key (`"org/slug"`). */
       readonly key: string;
+      /** The fetched MCP server resource. */
       readonly mcpServer: McpServer;
+      /** Variables the user must provide. */
       readonly missingVariables: EnvVarFormVariable[];
+      /** Tools discovered by the server's status probe. */
       readonly discoveredTools: DiscoveredTool[];
+      /** Per-tool approval policies from the server spec. */
       readonly toolApprovals: ToolApprovalPolicy[];
     }
   | {
+      /** Server resolved and is ready (no env vars needed). */
       readonly type: "RESOLVE_READY";
+      /** Server key (`"org/slug"`). */
       readonly key: string;
+      /** The fetched MCP server resource. */
       readonly mcpServer: McpServer;
+      /** Tools discovered by the server's status probe. */
       readonly discoveredTools: DiscoveredTool[];
+      /** Per-tool approval policies from the server spec. */
       readonly toolApprovals: ToolApprovalPolicy[];
+      /** Tool names enabled for this session. */
       readonly enabledTools: string[];
     }
   | {
+      /** Re-evaluate missing variables after pool values arrive. */
       readonly type: "POOL_RESOLVE";
+      /** Server key (`"org/slug"`). */
       readonly key: string;
+      /** Updated missing variables (may be empty if pool covered all). */
       readonly missingVariables: EnvVarFormVariable[];
+      /** Tool names enabled for this session. */
       readonly enabledTools: string[];
     }
-  | { readonly type: "SUBMIT_START"; readonly key: string }
   | {
+      /** Begin persisting env vars for this server. */
+      readonly type: "SUBMIT_START";
+      /** Server key (`"org/slug"`). */
+      readonly key: string;
+    }
+  | {
+      /** Env var submission succeeded — server is ready. */
       readonly type: "SUBMIT_DONE";
+      /** Server key (`"org/slug"`). */
       readonly key: string;
+      /** Tool names enabled for this session. */
       readonly enabledTools: string[];
     }
   | {
+      /** Update the enabled tools list for a ready server. */
       readonly type: "SET_ENABLED_TOOLS";
+      /** Server key (`"org/slug"`). */
       readonly key: string;
+      /** New set of enabled tool names. */
       readonly enabledTools: string[];
     }
-  | { readonly type: "SUBMIT_FAIL"; readonly key: string; readonly error: Error }
-  | { readonly type: "SET_ERROR"; readonly key: string; readonly error: Error }
-  | { readonly type: "CLEAR_ERROR"; readonly key: string }
-  | { readonly type: "REMOVE_SERVER"; readonly key: string }
-  | { readonly type: "RESET" };
+  | {
+      /** Env var submission failed — revert to `needsSetup`. */
+      readonly type: "SUBMIT_FAIL";
+      /** Server key (`"org/slug"`). */
+      readonly key: string;
+      /** The error that occurred during submission. */
+      readonly error: Error;
+    }
+  | {
+      /** Set an error on a specific server entry. */
+      readonly type: "SET_ERROR";
+      /** Server key (`"org/slug"`). */
+      readonly key: string;
+      /** The error to set. */
+      readonly error: Error;
+    }
+  | {
+      /** Clear the error on a specific server entry. */
+      readonly type: "CLEAR_ERROR";
+      /** Server key (`"org/slug"`). */
+      readonly key: string;
+    }
+  | {
+      /** Remove a server entry from the state. */
+      readonly type: "REMOVE_SERVER";
+      /** Server key (`"org/slug"`). */
+      readonly key: string;
+    }
+  | {
+      /** Reset all server entries to the initial empty state. */
+      readonly type: "RESET";
+    };
 
 // ---------------------------------------------------------------------------
 // Initial state

package/src/models/ModelSelector.tsx

@@ -40,6 +40,15 @@ export interface ModelSelectorProps {
  *
  * Platform builders who need different rendering use
  * `useModelRegistry()` directly.
+ *
+ * @example
+ * ```tsx
+ * function ComposerHeader() {
+ *   const [modelId, setModelId] = useState<string>();
+ *
+ *   return <ModelSelector value={modelId} onValueChange={setModelId} />;
+ * }
+ * ```
  */
 export function ModelSelector({
   value,

package/src/models/registry.ts

@@ -40,7 +40,17 @@ export const DISABLED_PROVIDERS: ReadonlySet<Provider> = new Set([
   "ollama",
 ]);
 
-/** UI-relevant metadata for a single platform-supported LLM model. */
+/**
+ * UI-relevant metadata for a single platform-supported LLM model.
+ *
+ * @example
+ * ```tsx
+ * const { getModel, defaultModel } = useModelRegistry();
+ * const model = getModel(selectedId) ?? defaultModel;
+ *
+ * <span>{model.displayName} ({model.costTier})</span>
+ * ```
+ */
 export interface ModelInfo {
   /** Unique model identifier sent to the backend (e.g. `"claude-sonnet-4.5"`). */
   readonly modelId: string;

package/src/models/useModelRegistry.ts

@@ -30,6 +30,26 @@ export interface UseModelRegistryReturn {
  * Pure data layer — no rendering, no side effects. Platform builders
  * who want full control over rendering import this hook and build
  * their own UI.
+ *
+ * @example
+ * ```tsx
+ * function CustomModelPicker({ onSelect }: { onSelect: (id: string) => void }) {
+ *   const { models, byProvider, defaultModel, getModel } = useModelRegistry();
+ *
+ *   return (
+ *     <select
+ *       defaultValue={defaultModel.modelId}
+ *       onChange={(e) => onSelect(e.target.value)}
+ *     >
+ *       {models.map((m) => (
+ *         <option key={m.modelId} value={m.modelId}>
+ *           {m.displayName} ({m.costTier})
+ *         </option>
+ *       ))}
+ *     </select>
+ *   );
+ * }
+ * ```
  */
 export function useModelRegistry(): UseModelRegistryReturn {
   return useMemo(() => {