@stigmer/react 0.0.71 → 0.0.73

package/src/iam-policy/index.ts

@@ -0,0 +1,51 @@
+export {
+  useGrantableRoles,
+  type UseGrantableRolesReturn,
+} from "./useGrantableRoles";
+
+export {
+  useRoleSelector,
+  type RoleOption,
+  type UseRoleSelectorReturn,
+} from "./useRoleSelector";
+
+export {
+  useResourceAccess,
+  type ResourceAccessRef,
+  type UseResourceAccessOptions,
+  type UseResourceAccessReturn,
+} from "./useResourceAccess";
+
+export {
+  usePrincipalsCount,
+  type UsePrincipalsCountReturn,
+} from "./usePrincipalsCount";
+
+export {
+  useWhoAmI,
+  type UseWhoAmIReturn,
+} from "./useWhoAmI";
+
+export {
+  useCreateIamPolicy,
+  type UseCreateIamPolicyReturn,
+} from "./useCreateIamPolicy";
+
+export {
+  useDeleteIamPolicy,
+  type UseDeleteIamPolicyReturn,
+} from "./useDeleteIamPolicy";
+
+export {
+  useRevokeOrgAccess,
+  type UseRevokeOrgAccessReturn,
+} from "./useRevokeOrgAccess";
+
+export { RoleSelector, type RoleSelectorProps } from "./RoleSelector";
+
+export { GrantAccessForm, type GrantAccessFormProps } from "./GrantAccessForm";
+
+export {
+  OrgMembersPanel,
+  type OrgMembersPanelProps,
+} from "./OrgMembersPanel";

package/src/iam-policy/useCreateIamPolicy.ts

@@ -0,0 +1,66 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { IamPolicy } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+import type { IamPolicySpec } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useCreateIamPolicy}. */
+export interface UseCreateIamPolicyReturn {
+  /** Grant access by creating an IAM policy binding. */
+  readonly create: (spec: IamPolicySpec) => Promise<IamPolicy>;
+  /** `true` while the create request is in flight. */
+  readonly isCreating: boolean;
+  /** Error from the last failed create, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `iamPolicy.create()` with loading/error
+ * state.
+ *
+ * Creates an IAM policy binding — granting a principal (identity
+ * account, team, etc.) a specific role on a resource. The caller
+ * provides the full {@link IamPolicySpec} with `principal`, `resource`,
+ * and `relation` (the role string, e.g. "admin").
+ *
+ * @example
+ * ```tsx
+ * const { create, isCreating, error } = useCreateIamPolicy();
+ *
+ * await create({
+ *   principal: { kind: "identity_account", id: accountId },
+ *   resource: { kind: "organization", id: orgId },
+ *   relation: "admin",
+ * });
+ * ```
+ */
+export function useCreateIamPolicy(): UseCreateIamPolicyReturn {
+  const stigmer = useStigmer();
+  const [isCreating, setIsCreating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const create = useCallback(
+    async (spec: IamPolicySpec): Promise<IamPolicy> => {
+      setIsCreating(true);
+      setError(null);
+
+      try {
+        return await stigmer.iamPolicy.create(spec);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { create, isCreating, error, clearError };
+}

package/src/iam-policy/useDeleteIamPolicy.ts

@@ -0,0 +1,65 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { IamPolicy } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+import type { IamPolicySpec } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/spec_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useDeleteIamPolicy}. */
+export interface UseDeleteIamPolicyReturn {
+  /** Revoke access by deleting an IAM policy binding. */
+  readonly remove: (spec: IamPolicySpec) => Promise<IamPolicy>;
+  /** `true` while the delete request is in flight. */
+  readonly isDeleting: boolean;
+  /** Error from the last failed delete, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `iamPolicy.delete()` with loading/error
+ * state.
+ *
+ * Removes an IAM policy binding — revoking a principal's role on a
+ * resource. The caller provides the same {@link IamPolicySpec} that was
+ * used when creating the binding.
+ *
+ * @example
+ * ```tsx
+ * const { remove, isDeleting, error } = useDeleteIamPolicy();
+ *
+ * await remove({
+ *   principal: { kind: "identity_account", id: accountId },
+ *   resource: { kind: "organization", id: orgId },
+ *   relation: "admin",
+ * });
+ * ```
+ */
+export function useDeleteIamPolicy(): UseDeleteIamPolicyReturn {
+  const stigmer = useStigmer();
+  const [isDeleting, setIsDeleting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const remove = useCallback(
+    async (spec: IamPolicySpec): Promise<IamPolicy> => {
+      setIsDeleting(true);
+      setError(null);
+
+      try {
+        return await stigmer.iamPolicy.delete(spec);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsDeleting(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { remove, isDeleting, error, clearError };
+}

package/src/iam-policy/useGrantableRoles.ts

@@ -0,0 +1,45 @@
+"use client";
+
+import { useMemo } from "react";
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+import { getGrantableRoles, hasGrantableRoles } from "@stigmer/sdk";
+
+/** Return value of {@link useGrantableRoles}. */
+export interface UseGrantableRolesReturn {
+  /** Roles that can be granted on the given resource kind. Empty if none. */
+  readonly roles: readonly IamRole[];
+  /** Whether the kind has at least one user-grantable role. */
+  readonly hasRoles: boolean;
+}
+
+/**
+ * Returns the list of IAM roles that can be granted on the given
+ * resource kind.
+ *
+ * This is a local read — no network call. The data comes from the
+ * `grantable_roles` field in each `ApiResourceKind`'s proto metadata,
+ * generated at build time.
+ *
+ * @param kind - The resource kind to query, or `null` while loading.
+ *
+ * @example
+ * ```tsx
+ * const { roles, hasRoles } = useGrantableRoles(ApiResourceKind.agent);
+ * // roles = [IamRole.owner, IamRole.viewer]
+ * // hasRoles = true
+ * ```
+ */
+export function useGrantableRoles(
+  kind: ApiResourceKind | null,
+): UseGrantableRolesReturn {
+  return useMemo(() => {
+    if (kind === null) {
+      return { roles: [], hasRoles: false };
+    }
+    return {
+      roles: getGrantableRoles(kind),
+      hasRoles: hasGrantableRoles(kind),
+    };
+  }, [kind]);
+}

package/src/iam-policy/usePrincipalsCount.ts

@@ -0,0 +1,96 @@
+"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";
+
+/** Return value of {@link usePrincipalsCount}. */
+export interface UsePrincipalsCountReturn {
+  /** Number of distinct principals with access. `0` while loading. */
+  readonly count: number;
+  /** `true` while the fetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Re-fetch the count from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches the count of principals with access to an
+ * organization.
+ *
+ * Wraps `iamPolicy.getPrincipalsCount()`. Useful for member count
+ * badges in navigation and summary statistics.
+ *
+ * Pass `null` as `orgId` to skip fetching (stable no-op).
+ *
+ * @param orgId         - Organization ID, or `null` to skip.
+ * @param principalKind - Kind of principals to count. Defaults to `"identity_account"`.
+ *
+ * @example
+ * ```tsx
+ * const { count, isLoading } = usePrincipalsCount(orgId);
+ * // count = 5
+ * ```
+ */
+export function usePrincipalsCount(
+  orgId: string | null,
+  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 };
+}

package/src/iam-policy/useResourceAccess.ts

@@ -0,0 +1,128 @@
+"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 {
+  ListResourceAccessInputSchema,
+} 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";
+
+/** Resource reference for the access query. */
+export interface ResourceAccessRef {
+  /** Resource kind (e.g. "organization", "agent"). */
+  readonly kind: string;
+  /** Resource ID. */
+  readonly id: string;
+}
+
+/** Options for {@link useResourceAccess}. */
+export interface UseResourceAccessOptions {
+  /** Include roles inherited from parent resources. Defaults to `false`. */
+  readonly includeInherited?: boolean;
+}
+
+/** Return value of {@link useResourceAccess}. */
+export interface UseResourceAccessReturn {
+  /** Principals with their role grants on the resource. */
+  readonly members: readonly PrincipalAccess[];
+  /** `true` while the fetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Re-fetch the access list from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches the list of principals and their roles on a
+ * resource.
+ *
+ * Wraps `iamPolicy.listResourceAccessByPrincipal()`. Returns each
+ * principal with full display information (`ApiResourceRefView`) and
+ * all their role grants, optionally including roles inherited from
+ * parent resources.
+ *
+ * Pass `null` as `resource` to skip fetching (stable no-op).
+ *
+ * **Generic** — works for organizations, agents, environments, or any
+ * resource kind that has IAM policies.
+ *
+ * @param resource - The resource to query access for, or `null` to skip.
+ * @param options  - Optional configuration.
+ *
+ * @example
+ * ```tsx
+ * const { members, isLoading } = useResourceAccess(
+ *   { kind: "organization", id: orgId },
+ *   { includeInherited: true },
+ * );
+ * ```
+ */
+export function useResourceAccess(
+  resource: ResourceAccessRef | null,
+  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 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 };
+}

package/src/iam-policy/useRevokeOrgAccess.ts

@@ -0,0 +1,74 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { RevokeOrgAccessInputSchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useRevokeOrgAccess}. */
+export interface UseRevokeOrgAccessReturn {
+  /**
+   * Remove all of a user's access to an organization.
+   *
+   * Deletes every IAM policy granting the identity account access
+   * to the organization and its child resources (agents, environments,
+   * etc.) in a single operation.
+   */
+  readonly revoke: (accountId: string, orgId: string) => Promise<void>;
+  /** `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 `iamPolicy.revokeOrgAccess()` with
+ * loading/error state.
+ *
+ * Removes all IAM policy bindings for a specific identity account
+ * within an organization — including bindings on child resources
+ * (agents, environments, etc.). This is the "remove member from org"
+ * operation.
+ *
+ * @example
+ * ```tsx
+ * const { revoke, isRevoking, error } = useRevokeOrgAccess();
+ *
+ * await revoke("ia-alice-123", "org-demo-456");
+ * refetchMembers();
+ * ```
+ */
+export function useRevokeOrgAccess(): UseRevokeOrgAccessReturn {
+  const stigmer = useStigmer();
+  const [isRevoking, setIsRevoking] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const revoke = useCallback(
+    async (accountId: string, orgId: string): Promise<void> => {
+      setIsRevoking(true);
+      setError(null);
+
+      try {
+        await stigmer.iamPolicy.revokeOrgAccess(
+          create(RevokeOrgAccessInputSchema, {
+            identityAccountId: accountId,
+            organizationId: orgId,
+          }),
+        );
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsRevoking(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { revoke, isRevoking, error, clearError };
+}

package/src/iam-policy/useRoleSelector.ts

@@ -0,0 +1,97 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import type { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+import {
+  getGrantableRoles,
+  iamRoleDisplayName,
+  iamRoleDescription,
+  iamRoleToString,
+} from "@stigmer/sdk";
+
+/** A single role option with display metadata. */
+export interface RoleOption {
+  /** The IamRole enum value. */
+  readonly role: IamRole;
+  /** Human-readable display name (e.g. "Admin"). */
+  readonly label: string;
+  /** Short description suitable for tooltips (e.g. "Edit access and member management"). */
+  readonly description: string;
+  /** The FGA relation string (e.g. "admin"). */
+  readonly value: string;
+}
+
+/** Return value of {@link useRoleSelector}. */
+export interface UseRoleSelectorReturn {
+  /** Available role options for the given resource kind. */
+  readonly options: readonly RoleOption[];
+  /** Currently selected role, or `null` if nothing is selected. */
+  readonly selected: IamRole | null;
+  /** FGA relation string for the selected role, or `""` if nothing is selected. */
+  readonly selectedValue: string;
+  /** Select a role. */
+  readonly select: (role: IamRole) => void;
+  /** Clear the selection. */
+  readonly clear: () => void;
+  /** Whether at least one role option exists. */
+  readonly hasOptions: boolean;
+}
+
+/**
+ * Headless hook for selecting an IAM role for a given resource kind.
+ *
+ * Provides role options with display metadata (label, description,
+ * FGA relation string) and selection state. Use this directly if you
+ * need a custom role picker UI; for the styled version, use
+ * {@link RoleSelector}.
+ *
+ * @param kind - The resource kind to show grantable roles for, or `null`.
+ * @param defaultRole - Optional initial selection.
+ *
+ * @example
+ * ```tsx
+ * const { options, selected, select } = useRoleSelector(ApiResourceKind.organization);
+ *
+ * options.map(opt => (
+ *   <button key={opt.value} onClick={() => select(opt.role)}>
+ *     {opt.label} — {opt.description}
+ *   </button>
+ * ));
+ * ```
+ */
+export function useRoleSelector(
+  kind: ApiResourceKind | null,
+  defaultRole?: IamRole,
+): UseRoleSelectorReturn {
+  const [selected, setSelected] = useState<IamRole | null>(
+    defaultRole ?? null,
+  );
+
+  const options = useMemo<readonly RoleOption[]>(() => {
+    if (kind === null) return [];
+    return getGrantableRoles(kind).map((role) => ({
+      role,
+      label: iamRoleDisplayName(role),
+      description: iamRoleDescription(role),
+      value: iamRoleToString(role),
+    }));
+  }, [kind]);
+
+  const selectedValue = useMemo(
+    () => (selected !== null ? iamRoleToString(selected) : ""),
+    [selected],
+  );
+
+  const select = useCallback((role: IamRole) => setSelected(role), []);
+  const clear = useCallback(() => setSelected(null), []);
+
+  return {
+    options,
+    selected,
+    selectedValue,
+    select,
+    clear,
+    hasOptions: options.length > 0,
+  };
+}