@stapel/workspaces-react 0.6.0 → 0.8.0

package/dist/model/stepUp.js

@@ -0,0 +1,79 @@
+/**
+ * Step-up ahead of the button, not behind it (org-program §A3).
+ *
+ * Some workspace operations are declared **high**: the backend gates them
+ * with `stapel_core`'s `@requires_verification(scope="sensitive")` on top of
+ * the capability check, so an ambient cookie is never enough. A client that
+ * only learns this from the 403 shows the admin a button, a spinner and a
+ * refusal; this module lets it know BEFORE the click.
+ *
+ * Two things travel from the backend, and they are not the same thing:
+ *
+ * 1. **A step-up CHALLENGE** — `verification.challenge_id` is present. This
+ *    one nobody has to handle here: `@stapel/core`'s client intercepts it,
+ *    hands it to the app's verification controller (auth-react's factor
+ *    machines) and replays the original request with
+ *    `X-Verification-Token`. It is a detour, not a failure.
+ * 2. **An ENROLLMENT demand** — `verification.enroll === true` and there is
+ *    NO challenge id, because the user holds no factor that could be
+ *    challenged. Core deliberately does not intercept this one (there is
+ *    nothing to drive), so it surfaces as a plain 403 and the app must send
+ *    the user to factor enrollment first. {@link readVerificationEnrollment}
+ *    is how a hook says "this is that, and these are the factors".
+ *
+ * KEEP IN SYNC with stapel-workspaces `capabilities.BUILTIN_CAPABILITY_LEVELS`
+ * — a PORT for the same reason `capabilityMatches` is one: `GET /roles`
+ * publishes each role's capabilities but not their levels, so the level map
+ * cannot be read off the wire. A deployment may raise further capabilities via
+ * `STAPEL_WORKSPACES["CAPABILITY_LEVELS"]`; those are additive, so treating an
+ * unlisted capability as `standard` can only ever under-promise (the backend
+ * still challenges, and core still drives it).
+ */
+import { isStapelApiError } from "@stapel/core";
+/** The verification scope every `high` workspace capability is gated under. */
+export const SENSITIVE_SCOPE = "sensitive";
+/** PORT of `BUILTIN_CAPABILITY_LEVELS` — everything unlisted is `standard`. */
+export const BUILTIN_CAPABILITY_LEVELS = {
+    "members.provision": "high",
+    "members.password.reset": "high",
+    "workspace.security.manage": "high",
+};
+/** The declared step-up level of one capability string. */
+export function capabilityLevel(capability) {
+    return BUILTIN_CAPABILITY_LEVELS[capability] ?? "standard";
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * Read the enrollment demand out of a rejected request, or `null` when the
+ * error is anything else (including a step-up CHALLENGE, which carries a
+ * `challenge_id` and is core's business, not the consumer's).
+ */
+export function readVerificationEnrollment(error) {
+    // Both dialects, narrowed through the imported predicate (never through a
+    // shape this call site invented): the typed error carries the parsed body,
+    // a rethrown raw envelope IS the body.
+    const body = asRecord(isStapelApiError(error) ? error.body : error);
+    if (body === null)
+        return null;
+    const verification = asRecord(body["verification"]);
+    if (verification === null)
+        return null;
+    if (verification["enroll"] !== true)
+        return null;
+    if (typeof verification["challenge_id"] === "string")
+        return null;
+    const factors = verification["factors"];
+    return {
+        scope: typeof verification["scope"] === "string"
+            ? verification["scope"]
+            : SENSITIVE_SCOPE,
+        factors: Array.isArray(factors)
+            ? factors.filter((f) => typeof f === "string")
+            : [],
+    };
+}
+//# sourceMappingURL=stepUp.js.map

package/dist/model/stepUp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepUp.js","sourceRoot":"","sources":["../../src/model/stepUp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAK3C,+EAA+E;AAC/E,MAAM,CAAC,MAAM,yBAAyB,GAAqC;IACzE,mBAAmB,EAAE,MAAM;IAC3B,wBAAwB,EAAE,MAAM;IAChC,2BAA2B,EAAE,MAAM;CACpC,CAAC;AAEF,2DAA2D;AAC3D,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,OAAO,yBAAyB,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC;AAC7D,CAAC;AAaD,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzE,CAAC,CAAE,KAAiC;QACpC,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAc;IAEd,0EAA0E;IAC1E,2EAA2E;IAC3E,uCAAuC;IACvC,MAAM,IAAI,GAAG,QAAQ,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACpE,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;IACpD,IAAI,YAAY,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,YAAY,CAAC,QAAQ,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,OAAO,YAAY,CAAC,cAAc,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAClE,MAAM,OAAO,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;IACxC,OAAO;QACL,KAAK,EACH,OAAO,YAAY,CAAC,OAAO,CAAC,KAAK,QAAQ;YACvC,CAAC,CAAC,YAAY,CAAC,OAAO,CAAC;YACvB,CAAC,CAAC,eAAe;QACrB,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;YAC7B,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;YAC3D,CAAC,CAAC,EAAE;KACP,CAAC;AACJ,CAAC"}

package/llms.txt

@@ -1,6 +1,6 @@
-# @stapel/workspaces-react 0.6.0
+# @stapel/workspaces-react 0.8.0
 
-Headless React flow pair for stapel-workspaces (contract >=0.4 <0.5) — business + state, zero visual opinion.
+Headless React flow pair for stapel-workspaces (contract >=0.14 <0.15) — business + state, zero visual opinion.
 Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
 verification-403 interception, i18n engine, analytics facade, TanStack Query layer.
 
@@ -16,37 +16,59 @@ verification-403 interception, i18n engine, analytics facade, TanStack Query lay
 ## Layers
 api (typed client) · model (hooks, session) · flows (machines) · headless · i18n
 
+## Machines (createFlowMachine; analytics funnel flow.<id>.<step>)
+- createInviteAcceptFlow
+
 ## Documented flows (flows.json — canonical id, steps, endpoints)
 
 ## Operations (typed; use the named op, never a path string)
 Request/response schema names are in manifest.json + the generated types.
-- workspaces_api_v1_create: POST /workspaces/api/v1/
-- workspaces_api_v1_destroy: DELETE /workspaces/api/v1/{workspace_id}
-- workspaces_api_v1_internal_members_retrieve: GET /workspaces/api/v1/internal/{workspace_id}/members/{user_id}
-- workspaces_api_v1_internal_users_personal_create: POST /workspaces/api/v1/internal/users/{user_id}/personal
-- workspaces_api_v1_invitations_accept_create: POST /workspaces/api/v1/invitations/accept
-- workspaces_api_v1_members_destroy: DELETE /workspaces/api/v1/{workspace_id}/members/{user_id}
-- workspaces_api_v1_members_invite_create: POST /workspaces/api/v1/{workspace_id}/members/invite
-- workspaces_api_v1_members_list: GET /workspaces/api/v1/{workspace_id}/members
-- workspaces_api_v1_members_partial_update: PATCH /workspaces/api/v1/{workspace_id}/members/{user_id}
-- workspaces_api_v1_partial_update: PATCH /workspaces/api/v1/{workspace_id}
-- workspaces_api_v1_retrieve: GET /workspaces/api/v1/
-- workspaces_api_v1_retrieve_2: GET /workspaces/api/v1/{workspace_id}
+Paths are relative to `/workspaces/api/v1/`.
+- workspaces_api_v1_create: POST /
+- workspaces_api_v1_destroy: DELETE /{workspace_id}
+- workspaces_api_v1_internal_members_retrieve: GET /internal/{workspace_id}/members/{user_id}
+- workspaces_api_v1_internal_users_personal_create: POST /internal/users/{user_id}/personal
+- workspaces_api_v1_invitations_accept_create: POST /invitations/accept
+- workspaces_api_v1_invitations_claim_create: POST /invitations/{token}/claim
+- workspaces_api_v1_invitations_decline_create: POST /invitations/{token}/decline
+- workspaces_api_v1_invitations_list: GET /{workspace_id}/invitations
+- workspaces_api_v1_invitations_resend_create: POST /{workspace_id}/invitations/{invitation_id}/resend
+- workspaces_api_v1_invitations_retrieve: GET /invitations/{token}
+- workspaces_api_v1_invitations_revoke_create: POST /{workspace_id}/invitations/{invitation_id}/revoke
+- workspaces_api_v1_members_destroy: DELETE /{workspace_id}/members/{user_id}
+- workspaces_api_v1_members_invite_create: POST /{workspace_id}/members/invite
+- workspaces_api_v1_members_list: GET /{workspace_id}/members
+- workspaces_api_v1_members_partial_update: PATCH /{workspace_id}/members/{user_id}
+- workspaces_api_v1_members_password_reset_create: POST /{workspace_id}/members/{user_id}/password/reset
+- workspaces_api_v1_members_provision_create: POST /{workspace_id}/members/provision
+- workspaces_api_v1_partial_update: PATCH /{workspace_id}
+- workspaces_api_v1_retrieve: GET /
+- workspaces_api_v1_retrieve_2: GET /{workspace_id}
+- workspaces_api_v1_roles_retrieve: GET /roles
 
 ## Query hooks (server state; keys come only from the key factory)
 - useAcceptInvitation (mutation) → acceptInvitation
+- useClaimInvitation (mutation) → claimInvitation
 - useCreateWorkspace (mutation) → createWorkspace
+- useDeclineInvitation (mutation) → declineInvitation
 - useDeleteWorkspace (mutation) → deleteWorkspace
+- useInvitationPreview (query) → getInvitationPreview
+- useInvitations (query) → listInvitations
 - useInviteMembers (mutation) → inviteMembers
 - useMembers (query) → listMembers
 - useRemoveMember (mutation) → removeMember
+- useResendInvitation (mutation) → resendInvitation
+- useResetMemberPassword (mutation) → resetMemberPassword
+- useRevokeInvitation (mutation) → revokeInvitation
+- useRoles (query) → listRoles
 - useUpdateMemberRole (mutation) → updateMemberRole
+- useUpdateSecuritySettings (mutation) → getWorkspace+updateWorkspace
 - useUpdateWorkspace (mutation) → updateWorkspace
 - useWorkspace (query) → getWorkspace
 - useWorkspaces (query) → listWorkspaces
 
 ## Errors (render t(code, params); UX from remediation)
-52 keys (full catalog: manifest.json §errors). By remediation: fix_input 24 · retry 12 · contact_support 5 · verify 5 · wait_and_retry 5 · reauthenticate 1.
+60 keys (full catalog: manifest.json §errors). By remediation: fix_input 28 · retry 12 · contact_support 7 · wait_and_retry 6 · verify 5 · reauthenticate 2.
 Param-bearing keys (interpolation slots matter):
 - error.400.field.blank [400] → fix_input {field}
 - error.400.field.does_not_exist [400] → fix_input {field}
@@ -59,6 +81,9 @@ Param-bearing keys (interpolation slots matter):
 - error.400.field.null [400] → fix_input {field}
 - error.400.field.required [400] → fix_input {field}
 - error.400.field.unique [400] → fix_input {field}
+- error.402.member_limit_reached [402] → fix_input {limit}
+- error.403.membership_suspended [403] → fix_input {reason}
+- error.403.missing_capability [403] → contact_support {capability}
 - error.429.rate_limit [429] → wait_and_retry {retry_after_minutes}
 
 ## Analytics events (typed; defineEvent → events.json, drift-gated)
@@ -82,13 +107,22 @@ const { tracked } = useTracked();
 
 ## Demos (defineDemo → manifest.demos; compiled, linted, rendered examples)
 - workspaces.accept → <AcceptInvitation> [default]  demo/AcceptInvitation.demo.tsx
+- workspaces.can → <Can> [default]  demo/Can.demo.tsx
+- workspaces.invite-accept → <InviteAcceptFlow> [default]  demo/InviteAcceptFlow.demo.tsx
 - workspaces.list → <WorkspaceList> [default]  demo/WorkspaceList.demo.tsx
 - workspaces.members → <Members> [default]  demo/Members.demo.tsx
 - workspaces.provider → <WorkspacesProvider> [default]  demo/Workspaces.demo.tsx
+- workspaces.role-select → <RoleSelect> [default]  demo/RoleSelect.demo.tsx
 Each source file is the canonical usage snippet (open the default variant).
 
 ## Snippets
 ```tsx
+// A flow machine drives state; you render each step.
+const flow = createInviteAcceptFlow({ api: useWorkspacesApi() });
+const s = useFlow(flow.machine);
+if (s.step.endsWith('Error')) return <p>{t(s.error.code, s.error.params)}</p>;
+```
+```tsx
 // Error rendering + remediation branch (one pattern for every pair).
 const r = explainWorkspacesError(err.code); // 'wait_and_retry' | 'verify' | ...
 return <Alert action={r}>{t(err.code, err.params)}</Alert>;