@stapel/workspaces-react 0.5.0 → 0.7.0

package/src/index.ts

@@ -25,6 +25,12 @@ export type {
   FlowError,
 } from "@stapel/core";
 export { toFlowError } from "./flows/errors.js";
+export { createInviteAcceptFlow } from "./flows/inviteAcceptFlow.js";
+export type {
+  InviteAcceptFlow as InviteAcceptFlowController,
+  InviteAcceptFlowDeps,
+  InviteAcceptState,
+} from "./flows/inviteAcceptFlow.js";
 export { WORKSPACES_FLOWS, flowEndpoints } from "./flows/registry.js";
 export type {
   WorkspacesFlowId,
@@ -51,7 +57,15 @@ export {
   useWorkspaces,
   useWorkspace,
   useMembers,
+  useRoles,
+  useInvitationPreview,
+  useCapabilities,
 } from "./model/queries.js";
+export type { CapabilitiesResult } from "./model/queries.js";
+
+// ── model (capability matcher + email-mask ports — backend-synced utils) ─────
+export { capabilityMatches, hasCapability } from "./model/capabilities.js";
+export { maskEmail, emailMatchesMask } from "./model/emailMask.js";
 
 // ── model (write hooks) ──────────────────────────────────────────────────────
 export {
@@ -62,6 +76,8 @@ export {
   useUpdateMemberRole,
   useRemoveMember,
   useAcceptInvitation,
+  useClaimInvitation,
+  useDeclineInvitation,
 } from "./model/mutations.js";
 export type { MemberRoleChange } from "./model/mutations.js";
 
@@ -79,6 +95,10 @@ export type {
   MemberRoleUpdate,
   Invitation,
   InvitationAccept,
+  InvitationPreview,
+  InvitationClaim,
+  RoleInfo,
+  RoleList,
   WorkspaceRole,
   WorkspaceKind,
 } from "./api/types.js";
@@ -91,6 +111,12 @@ export { Members } from "./headless/Members.js";
 export type { MembersBag } from "./headless/Members.js";
 export { AcceptInvitation } from "./headless/AcceptInvitation.js";
 export type { AcceptInvitationBag } from "./headless/AcceptInvitation.js";
+export { Can } from "./headless/Can.js";
+export type { CanBag } from "./headless/Can.js";
+export { RoleSelect } from "./headless/RoleSelect.js";
+export type { RoleSelectBag } from "./headless/RoleSelect.js";
+export { InviteAcceptFlow } from "./headless/InviteAcceptFlow.js";
+export type { InviteAcceptFlowBag } from "./headless/InviteAcceptFlow.js";
 
 // ── i18n ─────────────────────────────────────────────────────────────────────
 export {

package/src/model/capabilities.ts

@@ -0,0 +1,37 @@
+/**
+ * Client-side capability matcher (org-program §A1/§A2) — a PORT of
+ * stapel-workspaces' `capabilities.capability_matches` (which is itself
+ * mirrored by the consumer helper in `stapel_core.django.workspaces`).
+ * KEEP SEMANTICS IN SYNC with the backend: capability strings are namespaced
+ * `"<domain>.<action>"`, free-form for the client (`meetings.spotlight`,
+ * `records.view`, …); a granted string may be the exact capability, the
+ * global wildcard `"*"`, or a prefix wildcard like `"members.*"` (which
+ * matches `members.remove` AND deeper `members.role.change`).
+ *
+ * The client-side check is a UI convenience (hide/disable affordances) —
+ * NEVER an access decision: the backend re-checks every capability on every
+ * operation (`has_capability` in-service, `workspaces.check_capability`
+ * cross-service).
+ */
+
+/** Match one granted capability string against the requested one. */
+export function capabilityMatches(
+  capability: string,
+  granted: string
+): boolean {
+  if (granted === "*" || granted === capability) return true;
+  if (granted.endsWith(".*")) {
+    return capability.startsWith(granted.slice(0, -1));
+  }
+  return false;
+}
+
+/** True if any of `granted` (verbatim registry strings, wildcards included)
+ * matches `capability`. Empty/absent grants deny — deny-by-default. */
+export function hasCapability(
+  granted: readonly string[] | null | undefined,
+  capability: string
+): boolean {
+  if (!granted) return false;
+  return granted.some((g) => capabilityMatches(capability, g));
+}

package/src/model/emailMask.ts

@@ -0,0 +1,37 @@
+/**
+ * Email masking — a PORT of stapel-workspaces' `views._mask_email` (the
+ * function that produces `InvitationPreviewResponse.email_masked`). KEEP IN
+ * SYNC with the backend: first character of the local part and of the domain
+ * name survive, the TLD stays readable — `m***@e***.com`.
+ *
+ * Why the client re-implements it: the public invitation preview deliberately
+ * carries only the MASKED email (harvest-proof, org-program §B2), yet the
+ * §B4 flow must route "session & email match" vs "wrong account" BEFORE
+ * attempting the accept. Masking the signed-in account's own (fully known)
+ * email with the same algorithm and comparing the two masks is the exact
+ * decision the backend would make — without ever exposing the invitee's
+ * address. A mask collision (two addresses masking identically) merely shows
+ * the accept prompt; the backend's real email-match on accept remains the
+ * enforcement point.
+ */
+
+/** Mask an email exactly like the backend's invitation preview does. */
+export function maskEmail(email: string): string {
+  const at = email.indexOf("@");
+  const local = at === -1 ? email : email.slice(0, at);
+  const domain = at === -1 ? "" : email.slice(at + 1);
+  const dot = domain.lastIndexOf(".");
+  const maskedLocal = `${local.slice(0, 1) || "*"}***`;
+  if (dot !== -1) {
+    const domainName = domain.slice(0, dot);
+    const tld = domain.slice(dot + 1);
+    return `${maskedLocal}@${domainName.slice(0, 1) || "*"}***.${tld}`;
+  }
+  return `${maskedLocal}@${domain.slice(0, 1) || "*"}***`;
+}
+
+/** Whether `email`, masked by the backend's algorithm, equals `emailMasked`
+ * (case-insensitive on the email, as the backend matches `iexact`). */
+export function emailMatchesMask(email: string, emailMasked: string): boolean {
+  return maskEmail(email.trim().toLowerCase()) === emailMasked.toLowerCase();
+}

package/src/model/mutations.ts

@@ -9,9 +9,9 @@ import type {
   MemberInvite,
   MemberInviteResult,
   InvitationAccept,
+  InvitationClaim,
   Workspace,
   WorkspaceCreate,
-  WorkspaceRole,
   WorkspaceUpdate,
 } from "../api/types.js";
 import { useWorkspacesApi } from "./context.js";
@@ -123,10 +123,14 @@ export function useInviteMembers(
   return useMutation(options);
 }
 
-/** The variable for {@link useUpdateMemberRole}: which member, which new role. */
+/** The variable for {@link useUpdateMemberRole}: which member, which new role.
+ * `role` is an open string since stapel-workspaces 0.6.0 (org-program §A1):
+ * the effective registry is settings-extensible, so any key of GET /roles is
+ * valid — the backend validates against the registry. {@link WorkspaceRole}
+ * still names the builtin four for literals. */
 export interface MemberRoleChange {
   readonly userId: string;
-  readonly role: WorkspaceRole;
+  readonly role: string;
 }
 
 /**
@@ -186,10 +190,58 @@ export function useAcceptInvitation(): UseMutationResult<
   const queryClient = useQueryClient();
   const options: UseMutationOptions<Member, StapelApiError, InvitationAccept> = {
     mutationFn: (body) => api.acceptInvitation(body),
-    onSuccess: () => {
+    onSuccess: (_member, body) => {
       void queryClient.invalidateQueries({
         queryKey: workspacesQueryKeys.list(),
       });
+      // The preview's `status` moved pending → accepted.
+      void queryClient.invalidateQueries({
+        queryKey: workspacesQueryKeys.invitationPreview(body.token),
+      });
+    },
+  };
+  return useMutation(options);
+}
+
+/**
+ * Mint a login grant for a NOT-yet-registered invitee (POST
+ * /invitations/{token}/claim, AllowAny — org-program §B2/§B3). The variable
+ * is the invite token; the result carries the single-use `grant_token` to
+ * exchange at AUTH's `POST /grant/exchange/` (the auth-react api — this pair
+ * deliberately does not call it; see `InviteAcceptFlow`'s `onLoginGrant`
+ * seam). 409 `email_already_registered` → switch to login. The invitation is
+ * NOT consumed here. The grant token is a credential: never log it.
+ */
+export function useClaimInvitation(): UseMutationResult<
+  InvitationClaim,
+  StapelApiError,
+  string
+> {
+  const api = useWorkspacesApi();
+  const options: UseMutationOptions<InvitationClaim, StapelApiError, string> = {
+    mutationFn: (token) => api.claimInvitation(token),
+  };
+  return useMutation(options);
+}
+
+/**
+ * Decline an invitation (POST /invitations/{token}/decline, authenticated +
+ * email-match — org-program §B2). The variable is the invite token. Decline ≠
+ * revoke — the preview's `status` becomes `declined`.
+ */
+export function useDeclineInvitation(): UseMutationResult<
+  void,
+  StapelApiError,
+  string
+> {
+  const api = useWorkspacesApi();
+  const queryClient = useQueryClient();
+  const options: UseMutationOptions<void, StapelApiError, string> = {
+    mutationFn: (token) => api.declineInvitation(token),
+    onSuccess: (_result, token) => {
+      void queryClient.invalidateQueries({
+        queryKey: workspacesQueryKeys.invitationPreview(token),
+      });
     },
   };
   return useMutation(options);

package/src/model/queries.ts

@@ -1,14 +1,18 @@
 import { useQuery } from "@tanstack/react-query";
 import type { UseQueryResult } from "@tanstack/react-query";
+import { useActiveSessionReady } from "@stapel/core";
 import type { StapelApiError } from "@stapel/core";
 import type {
+  InvitationPreview,
   MemberPage,
   MembersParams,
+  RoleInfo,
   Workspace,
   WorkspaceList,
 } from "../api/types.js";
 import { useWorkspacesApi } from "./context.js";
 import { workspacesQueryKeys } from "./queryKeys.js";
+import { hasCapability } from "./capabilities.js";
 
 /**
  * Read hooks over the workspaces API. Staleness follows core's query defaults;
@@ -16,45 +20,133 @@ import { workspacesQueryKeys } from "./queryKeys.js";
  * namespaced (see `workspacesQueryKeys`).
  */
 
-/** The caller's workspaces — their accepted memberships (GET /). */
+/**
+ * The caller's workspaces — their accepted memberships (GET /).
+ *
+ * Gated on {@link useActiveSessionReady} (owner-diagnosed live incident,
+ * 2026-07-17): unlike {@link useWorkspace}/{@link useMembers} below (both
+ * naturally disabled until a `workspaceId` is picked), this is the top-level
+ * list hook with nothing else to gate it — it fires the instant a component
+ * mounts. Without the session ready-gate this is exactly the shape of hook
+ * that raced a session still bootstrapping (e.g. right after a QR
+ * `session_share` scan set fresh cookies this JS runtime hadn't caught up
+ * to yet) and read a live session as "expired" before it had a chance to
+ * resolve — zero manual `enabled` wiring needed at each call site by design.
+ */
 export function useWorkspaces(): UseQueryResult<WorkspaceList, StapelApiError> {
   const api = useWorkspacesApi();
+  const sessionReady = useActiveSessionReady();
   return useQuery({
     queryKey: workspacesQueryKeys.list(),
     queryFn: () => api.listWorkspaces(),
+    enabled: sessionReady,
   });
 }
 
 /**
  * A single workspace by id (GET /{id}). Disabled until a `workspaceId` is
- * given, so a detail hook can mount before a selection exists.
+ * given, so a detail hook can mount before a selection exists — AND until
+ * the session is ready (a `workspaceId` can be known synchronously, e.g.
+ * from a URL param, before the session has finished bootstrapping).
  */
 export function useWorkspace(
   workspaceId: string | null
 ): UseQueryResult<Workspace, StapelApiError> {
   const api = useWorkspacesApi();
+  const sessionReady = useActiveSessionReady();
   return useQuery({
     queryKey: workspacesQueryKeys.detail(workspaceId ?? ""),
     queryFn: () => api.getWorkspace(workspaceId as string),
-    enabled: workspaceId !== null && workspaceId !== "",
+    enabled: sessionReady && workspaceId !== null && workspaceId !== "",
   });
 }
 
 /**
  * A page of a workspace's members (GET /{id}/members, anchor-paginated).
- * Disabled until a `workspaceId` is given. Pass `{ anchor, direction, limit,
- * search }` to jump to a specific page or filter; omit for the newest page
- * (default limit 100).
+ * Disabled until a `workspaceId` is given (and the session is ready — see
+ * {@link useWorkspace}). Pass `{ anchor, direction, limit, search }` to jump
+ * to a specific page or filter; omit for the newest page (default limit 100).
  */
 export function useMembers(
   workspaceId: string | null,
   params?: MembersParams
 ): UseQueryResult<MemberPage, StapelApiError> {
   const api = useWorkspacesApi();
+  const sessionReady = useActiveSessionReady();
   const p = params ?? {};
   return useQuery({
     queryKey: workspacesQueryKeys.membersPage(workspaceId ?? "", p),
     queryFn: () => api.listMembers(workspaceId as string, p),
-    enabled: workspaceId !== null && workspaceId !== "",
+    enabled: sessionReady && workspaceId !== null && workspaceId !== "",
+  });
+}
+
+/**
+ * The effective role registry (GET /roles, org-program §A2): builtin four +
+ * the deployment's `STAPEL_WORKSPACES["ROLES"]` overlay, capability strings
+ * verbatim, rank-descending. Deployment-static data — role UI (RoleSelect)
+ * reads this instead of hardcoding the builtin four. Session-ready-gated like
+ * {@link useWorkspaces} (IsAuthenticated endpoint, mounts at screen top).
+ */
+export function useRoles(): UseQueryResult<
+  readonly RoleInfo[],
+  StapelApiError
+> {
+  const api = useWorkspacesApi();
+  const sessionReady = useActiveSessionReady();
+  return useQuery({
+    queryKey: workspacesQueryKeys.roles(),
+    queryFn: async () => (await api.listRoles()).roles ?? [],
+    enabled: sessionReady,
+  });
+}
+
+/**
+ * Public invitation preview (GET /invitations/{token}, AllowAny — org-program
+ * §B2): what the `/invite/{token}` page renders BEFORE any auth decision.
+ * Deliberately NOT session-gated — the whole point is that the invitee may
+ * have no session at all; the token in the URL is the bearer secret.
+ */
+export function useInvitationPreview(
+  token: string | null
+): UseQueryResult<InvitationPreview, StapelApiError> {
+  const api = useWorkspacesApi();
+  return useQuery({
+    queryKey: workspacesQueryKeys.invitationPreview(token ?? ""),
+    queryFn: () => api.getInvitationPreview(token as string),
+    enabled: token !== null && token !== "",
   });
 }
+
+/** What {@link useCapabilities} returns: the caller's granted capability
+ * strings in one workspace plus the wildcard-aware `can()` check. */
+export interface CapabilitiesResult {
+  /** Verbatim registry strings of the caller's role (wildcards included);
+   * empty while loading or when the caller is not a member. */
+  readonly capabilities: readonly string[];
+  /** Wildcard-aware check (`*` / `prefix.*` — the backend matcher, ported).
+   * UI convenience only: the backend re-checks on every operation. */
+  can(capability: string): boolean;
+  readonly isLoading: boolean;
+  readonly isError: boolean;
+  readonly error: StapelApiError | null;
+}
+
+/**
+ * The caller's capabilities in one workspace (org-program §A2): reads
+ * `my_capabilities` off the workspace detail (`WorkspaceResponse`, additive
+ * field since stapel-workspaces 0.6.0) and exposes the ported wildcard
+ * matcher. Deny-by-default: `can()` is false while loading, on error, or when
+ * the backend predates the field.
+ */
+export function useCapabilities(workspaceId: string | null): CapabilitiesResult {
+  const query = useWorkspace(workspaceId);
+  const capabilities = query.data?.my_capabilities ?? [];
+  return {
+    capabilities,
+    can: (capability) => hasCapability(capabilities, capability),
+    isLoading: query.isLoading,
+    isError: query.isError,
+    error: query.error ?? null,
+  };
+}

package/src/model/queryKeys.ts

@@ -18,6 +18,10 @@ export const workspacesQueryKeys: {
     workspaceId: string,
     params: MembersParams
   ): readonly ["workspaces", "members", string, MembersParams];
+  roles(): readonly ["workspaces", "roles"];
+  invitationPreview(
+    token: string
+  ): readonly ["workspaces", "invitation-preview", string];
 } = {
   all: [ROOT],
   list: () => [ROOT, "list"],
@@ -26,4 +30,10 @@ export const workspacesQueryKeys: {
   // invalidating `members(workspaceId)` (mutations.ts) drops every page.
   members: (workspaceId) => [ROOT, "members", workspaceId],
   membersPage: (workspaceId, params) => [ROOT, "members", workspaceId, params],
+  roles: () => [ROOT, "roles"],
+  // NOTE: the key carries the invite TOKEN (a secret). Core's query persist
+  // scope is per-user and the preview response is already public-by-design
+  // (masked email only) — but hosts logging query keys should treat this one
+  // as sensitive.
+  invitationPreview: (token) => [ROOT, "invitation-preview", token],
 };