@stigmer/react 0.0.71 → 0.0.73

package/src/invitation/InvitationRedemption.tsx

@@ -0,0 +1,434 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { cn } from "@stigmer/theme";
+import { getUserMessage, iamRoleDisplayName } from "@stigmer/sdk";
+import type { Invitation } from "@stigmer/protos/ai/stigmer/iam/invitation/v1/api_pb";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { useInvitationPreview } from "./useInvitationPreview";
+import { useRedeemInvitation } from "./useRedeemInvitation";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Props for {@link InvitationRedemption}. */
+export interface InvitationRedemptionProps {
+  /** The invitation token from the invite URL. */
+  readonly token: string;
+  /**
+   * Whether the current user is authenticated.
+   *
+   * When `false`, the component shows a "Sign in to accept" CTA
+   * instead of the accept button. When `true` or omitted, the
+   * accept button calls `redeem` directly.
+   *
+   * @default true
+   */
+  readonly isAuthenticated?: boolean;
+  /**
+   * Fired after the invitation is successfully redeemed.
+   *
+   * The returned {@link Invitation} contains the organization and
+   * role information needed for post-redemption navigation
+   * (e.g. redirecting to the org dashboard).
+   */
+  readonly onAccepted?: (invitation: Invitation) => void;
+  /**
+   * Fired when an unauthenticated user clicks "Sign in to accept".
+   *
+   * The host application controls what "sign in" means — this
+   * callback typically triggers a redirect to the login page with
+   * a return URL back to the invite page.
+   */
+  readonly onAuthRequired?: () => void;
+  /** Additional CSS class names for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Self-contained invite acceptance flow.
+ *
+ * Fetches the invitation preview by token (public endpoint, no auth
+ * required), displays the organization info and role being offered,
+ * and provides an accept button that redeems the invitation.
+ *
+ * Handles all states: loading, invalid (expired / revoked / fully
+ * redeemed), authentication required, redemption in flight,
+ * success, and error — with appropriate UX for each.
+ *
+ * The component is auth-agnostic: it delegates authentication
+ * decisions to the host application via `isAuthenticated` and
+ * `onAuthRequired` props. Platform builders who render this
+ * component only for authenticated users can ignore both props.
+ *
+ * All visual properties flow through `--stgm-*` design tokens.
+ *
+ * @example
+ * ```tsx
+ * <InvitationRedemption
+ *   token={tokenFromUrl}
+ *   onAccepted={(inv) => router.push("/dashboard")}
+ * />
+ *
+ * <InvitationRedemption
+ *   token={tokenFromUrl}
+ *   isAuthenticated={!!currentUser}
+ *   onAccepted={(inv) => router.push(`/org/${inv.metadata?.org}`)}
+ *   onAuthRequired={() => router.push(`/login?return=/invite/${token}`)}
+ * />
+ * ```
+ */
+export function InvitationRedemption({
+  token,
+  isAuthenticated = true,
+  onAccepted,
+  onAuthRequired,
+  className,
+}: InvitationRedemptionProps) {
+  const { preview, isLoading, error: fetchError, refetch } = useInvitationPreview(token);
+  const { redeem, isRedeeming, error: redeemError, clearError } = useRedeemInvitation();
+  const [accepted, setAccepted] = useState<Invitation | null>(null);
+
+  const handleAccept = useCallback(async () => {
+    clearError();
+    try {
+      const invitation = await redeem(token);
+      setAccepted(invitation);
+      onAccepted?.(invitation);
+    } catch {
+      // error state is managed by useRedeemInvitation
+    }
+  }, [token, redeem, clearError, onAccepted]);
+
+  // Loading state
+  if (isLoading) {
+    return (
+      <div
+        className={cn("mx-auto max-w-sm", className)}
+        aria-busy="true"
+        aria-label="Loading invitation"
+      >
+        <LoadingSkeleton />
+      </div>
+    );
+  }
+
+  // Fetch error
+  if (fetchError) {
+    return (
+      <div className={cn("mx-auto max-w-sm", className)}>
+        <ErrorCard
+          message={getUserMessage(fetchError)}
+          onRetry={refetch}
+        />
+      </div>
+    );
+  }
+
+  // No preview returned
+  if (!preview) {
+    return (
+      <div className={cn("mx-auto max-w-sm", className)}>
+        <ErrorCard message="This invitation could not be found." />
+      </div>
+    );
+  }
+
+  // Redemption success
+  if (accepted) {
+    const orgName = preview.organizationName || "the organization";
+    const roleName = iamRoleDisplayName(preview.role);
+    return (
+      <div className={cn("mx-auto max-w-sm", className)}>
+        <div className="rounded-lg border border-primary/30 bg-primary-subtle p-6 text-center">
+          <SuccessIcon />
+          <h2 className="mt-3 text-base font-semibold text-foreground">
+            You&rsquo;ve joined {orgName}
+          </h2>
+          <p className="mt-1 text-sm text-muted-foreground">
+            You now have <span className="font-medium text-foreground">{roleName}</span> access.
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  const orgName = preview.organizationName || "Unknown organization";
+  const orgLogo = preview.organizationLogoUrl;
+  const orgInitial = orgName.charAt(0).toUpperCase();
+  const roleName = iamRoleDisplayName(preview.role);
+  const expiresAt = preview.expiresAt ? timestampDate(preview.expiresAt) : null;
+
+  return (
+    <div className={cn("mx-auto max-w-sm", className)}>
+      <div className="rounded-lg border border-border bg-card p-6">
+        {/* Org identity */}
+        <div className="flex flex-col items-center text-center">
+          {orgLogo ? (
+            <img
+              src={orgLogo}
+              alt={`${orgName} logo`}
+              className="size-12 rounded-full object-cover"
+            />
+          ) : (
+            <div className="flex size-12 items-center justify-center rounded-full bg-muted text-lg font-semibold text-muted-foreground">
+              {orgInitial}
+            </div>
+          )}
+
+          <h2 className="mt-3 text-base font-semibold text-foreground">
+            Join {orgName}
+          </h2>
+
+          {preview.label && (
+            <p className="mt-1 text-sm text-muted-foreground">
+              {preview.label}
+            </p>
+          )}
+        </div>
+
+        {/* Role + expiry details */}
+        <div className="mt-4 flex items-center justify-center gap-3 text-xs text-muted-foreground">
+          <span className="inline-flex items-center gap-1">
+            <ShieldIcon />
+            {roleName} access
+          </span>
+          {expiresAt && (
+            <>
+              <Separator />
+              <span>{formatExpiry(expiresAt)}</span>
+            </>
+          )}
+        </div>
+
+        {/* Invalid state */}
+        {!preview.isValid && (
+          <InvalidNotice reason={preview.invalidReason} />
+        )}
+
+        {/* Action area */}
+        {preview.isValid && (
+          <div className="mt-5">
+            {isAuthenticated ? (
+              <>
+                <button
+                  type="button"
+                  onClick={handleAccept}
+                  disabled={isRedeeming}
+                  className={cn(
+                    "w-full inline-flex items-center justify-center gap-1.5 rounded-md px-4 py-2 text-sm font-medium",
+                    "bg-primary text-primary-foreground hover:bg-primary/90",
+                    "disabled:pointer-events-none disabled:opacity-50",
+                    "transition-colors",
+                  )}
+                >
+                  {isRedeeming && <SpinnerIcon />}
+                  {isRedeeming ? "Accepting\u2026" : "Accept Invitation"}
+                </button>
+                {redeemError && (
+                  <p className="mt-2 text-center text-[0.65rem] text-destructive" role="alert">
+                    {getUserMessage(redeemError)}
+                  </p>
+                )}
+              </>
+            ) : (
+              <button
+                type="button"
+                onClick={onAuthRequired}
+                className={cn(
+                  "w-full inline-flex items-center justify-center gap-1.5 rounded-md px-4 py-2 text-sm font-medium",
+                  "bg-primary text-primary-foreground hover:bg-primary/90",
+                  "transition-colors",
+                )}
+              >
+                Sign in to accept
+              </button>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// InvalidNotice (internal)
+// ---------------------------------------------------------------------------
+
+function InvalidNotice({ reason }: { reason: string }) {
+  return (
+    <div className="mt-4 rounded-md bg-muted/50 px-3 py-2.5 text-center">
+      <WarningIcon />
+      <p className="mt-1 text-xs text-muted-foreground">
+        {reason || "This invitation is no longer valid."}
+      </p>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// ErrorCard (internal)
+// ---------------------------------------------------------------------------
+
+function ErrorCard({
+  message,
+  onRetry,
+}: {
+  message: string;
+  onRetry?: () => void;
+}) {
+  return (
+    <div className="rounded-lg border border-destructive/30 bg-destructive/5 p-6 text-center">
+      <p className="text-sm text-destructive">{message}</p>
+      {onRetry && (
+        <button
+          type="button"
+          onClick={onRetry}
+          className={cn(
+            "mt-3 inline-flex items-center rounded-md px-3 py-1.5 text-xs font-medium",
+            "text-muted-foreground hover:text-foreground hover:bg-accent/50",
+            "transition-colors",
+          )}
+        >
+          Try again
+        </button>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// LoadingSkeleton (internal)
+// ---------------------------------------------------------------------------
+
+function LoadingSkeleton() {
+  return (
+    <div className="rounded-lg border border-border bg-card p-6 space-y-4">
+      <div className="flex flex-col items-center gap-3">
+        <div className="size-12 rounded-full bg-muted/40 animate-pulse" />
+        <div className="h-5 w-40 rounded bg-muted/40 animate-pulse" />
+        <div className="h-4 w-56 rounded bg-muted/40 animate-pulse" />
+      </div>
+      <div className="flex justify-center gap-3">
+        <div className="h-4 w-24 rounded bg-muted/40 animate-pulse" />
+        <div className="h-4 w-24 rounded bg-muted/40 animate-pulse" />
+      </div>
+      <div className="h-10 w-full rounded-md bg-muted/40 animate-pulse" />
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+function formatExpiry(date: Date): string {
+  const now = Date.now();
+  const diffMs = date.getTime() - now;
+
+  if (diffMs <= 0) return "Expired";
+
+  const days = Math.ceil(diffMs / 86_400_000);
+  if (days === 1) return "Expires tomorrow";
+  if (days <= 30) return `Expires in ${days} days`;
+
+  return `Expires ${date.toLocaleDateString(undefined, {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+  })}`;
+}
+
+// ---------------------------------------------------------------------------
+// Separator (internal)
+// ---------------------------------------------------------------------------
+
+function Separator() {
+  return (
+    <span className="text-border" aria-hidden="true">
+      &middot;
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Icons
+// ---------------------------------------------------------------------------
+
+function ShieldIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      className="shrink-0"
+    >
+      <path d="M8 1.5l5.5 2v4.5c0 3.5-2.5 5.5-5.5 7-3-1.5-5.5-3.5-5.5-7V3.5L8 1.5z" />
+    </svg>
+  );
+}
+
+function WarningIcon() {
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      className="mx-auto text-muted-foreground"
+    >
+      <circle cx="8" cy="8" r="6" />
+      <path d="M8 5v3.5M8 10.5v.5" />
+    </svg>
+  );
+}
+
+function SuccessIcon() {
+  return (
+    <svg
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      className="mx-auto text-primary"
+    >
+      <circle cx="12" cy="12" r="10" />
+      <path d="M8 12l2.5 2.5L16 9" />
+    </svg>
+  );
+}
+
+function SpinnerIcon() {
+  return (
+    <svg
+      width="14"
+      height="14"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      className="animate-spin"
+      aria-hidden="true"
+    >
+      <path d="M8 2a6 6 0 1 0 6 6" />
+    </svg>
+  );
+}

package/src/invitation/index.ts

@@ -0,0 +1,16 @@
+export { useOrgInvitations } from "./useOrgInvitations";
+export type { UseOrgInvitationsReturn } from "./useOrgInvitations";
+export { useCreateInvitation } from "./useCreateInvitation";
+export type { UseCreateInvitationReturn } from "./useCreateInvitation";
+export { useRevokeInvitation } from "./useRevokeInvitation";
+export type { UseRevokeInvitationReturn } from "./useRevokeInvitation";
+export { useInvitationPreview } from "./useInvitationPreview";
+export type { UseInvitationPreviewReturn } from "./useInvitationPreview";
+export { useRedeemInvitation } from "./useRedeemInvitation";
+export type { UseRedeemInvitationReturn } from "./useRedeemInvitation";
+export { InvitationCreatedAlert } from "./InvitationCreatedAlert";
+export type { InvitationCreatedAlertProps } from "./InvitationCreatedAlert";
+export { InvitationManager } from "./InvitationManager";
+export type { InvitationManagerProps } from "./InvitationManager";
+export { InvitationRedemption } from "./InvitationRedemption";
+export type { InvitationRedemptionProps } from "./InvitationRedemption";

package/src/invitation/useCreateInvitation.ts

@@ -0,0 +1,83 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { InvitationInput } from "@stigmer/sdk";
+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 useCreateInvitation}. */
+export interface UseCreateInvitationReturn {
+  /**
+   * Create an invitation link for an organization.
+   *
+   * Resolves with the server-created {@link Invitation} including the
+   * generated token in `status.token`. Callers must capture this token
+   * to construct the invite URL — it is always available via `get` and
+   * `listByOrg`, but surfacing it immediately after creation is the
+   * expected UX flow.
+   */
+  readonly create: (input: InvitationInput) => Promise<Invitation>;
+  /** `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 `invitation.create()` with loading and
+ * error state.
+ *
+ * Creates an invitation resource. The caller provides an
+ * {@link InvitationInput} with `name`, `org`, `role`, `expiresAt`,
+ * and optionally `maxRedemptions` and `label`.
+ *
+ * The returned {@link Invitation} contains the server-generated token
+ * in `status?.token`. Use this to build the invite URL:
+ * `https://<host>/invite/<token>`.
+ *
+ * Creating an invitation requires `can_grant_access` on the
+ * organization — typically limited to admins and owners.
+ *
+ * @example
+ * ```tsx
+ * const { create, isCreating, error } = useCreateInvitation();
+ *
+ * const invitation = await create({
+ *   name: "engineering-link",
+ *   org: "acme",
+ *   role: IamRole.VIEWER,
+ *   expiresAt: new Date(Date.now() + 30 * 86_400_000),
+ *   label: "Engineering team invite",
+ * });
+ * const inviteUrl = `${window.location.origin}/invite/${invitation.status?.token}`;
+ * ```
+ */
+export function useCreateInvitation(): UseCreateInvitationReturn {
+  const stigmer = useStigmer();
+  const [isCreating, setIsCreating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const create = useCallback(
+    async (input: InvitationInput): Promise<Invitation> => {
+      setIsCreating(true);
+      setError(null);
+
+      try {
+        return await stigmer.invitation.create(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { create, isCreating, error, clearError };
+}

package/src/invitation/useInvitationPreview.ts

@@ -0,0 +1,103 @@
+"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";
+
+/** Return value of {@link useInvitationPreview}. */
+export interface UseInvitationPreviewReturn {
+  /** The invitation preview, or `null` while loading or on error. */
+  readonly preview: InvitationPreview | null;
+  /** `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 preview from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches an {@link InvitationPreview} by its
+ * shareable token.
+ *
+ * Pass `null` to skip fetching (stable no-op). When the `token`
+ * changes, the previous in-flight request is discarded and a fresh
+ * fetch begins.
+ *
+ * This hook calls the `getByToken` endpoint, which is **public** —
+ * it requires no authentication. The server returns a safe projection
+ * containing only the information needed to render the invite
+ * acceptance page: organization name/logo, the role being offered,
+ * expiry, and whether the invitation is still valid.
+ *
+ * Check `preview.isValid` before offering the redemption action.
+ * When `false`, `preview.invalidReason` contains a human-readable
+ * explanation (expired, revoked, or fully redeemed).
+ *
+ * **Note**: Although authentication is not required by the server,
+ * the hook still requires a `StigmerProvider` ancestor because it
+ * needs the transport configuration (API base URL) to make the
+ * request.
+ *
+ * @param token - The invitation token from the invite URL, or `null`
+ *   to skip fetching.
+ *
+ * @example
+ * ```tsx
+ * const { preview, isLoading, error } = useInvitationPreview(token);
+ *
+ * if (isLoading) return <Spinner />;
+ * if (!preview) return <NotFound />;
+ * if (!preview.isValid) return <Expired reason={preview.invalidReason} />;
+ *
+ * return <p>Join {preview.organizationName} as {preview.role}</p>;
+ * ```
+ */
+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), []);
+
+  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 };
+}