@stapel/workspaces-react 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @stapel/workspaces-react
 
+## 0.8.0
+
+### Minor Changes
+
+- f9c04aa: Ручки вчерашних релизов бэкенда стали вызываемыми с фронта.
+
+  `@stapel/workspaces-react` (контракт stapel-workspaces `>=0.14 <0.15`):
+
+  - `useInvitations` / `useInfiniteInvitations` — админская таблица приглашений
+    (`GET /{ws}/invitations`) с фильтрами `status` (`pending` / `never_accepted`
+    / `all`) и `search`. Пагинация **якорная**, как у `useMembers`: страница
+    адресуется непрозрачным `next_anchor` предыдущей, номера страницы нет —
+    оффсет поехал бы ровно в тот момент, когда приглашение отзывают у админа
+    под руками.
+  - `useRevokeInvitation` / `useResendInvitation` — отзыв и повторная отправка;
+    обе возвращают обновлённый DTO. Ресенд ротирует токен и перезапускает TTL,
+    поэтому таблица инвалидируется: старый `expires_at` на экране врал бы про
+    живую креденцию.
+  - `useResetMemberPassword` — админский сброс пароля участнику.
+    `generated_password` приходит ровно один раз и **не попадает в кэш
+    запросов** (ничего не пишется через `setQueryData`, `gcTime: 0`): рантайм
+    ядра персистит весь пользовательский query-кэш в localStorage, так что
+    запись туда означала бы живой пароль на диске и в девтулзах.
+  - `useCapabilityGate` + порт `BUILTIN_CAPABILITY_LEVELS` — уровень `high` и
+    скоуп `sensitive` известны **до** кнопки, а не после 403.
+    `readVerificationEnrollment` отличает конверт «заведи фактор» (его ядро не
+    перехватывает — перехватывать нечего) от обычного челленджа.
+  - `useUpdateSecuritySettings` — `provisioned_user_policies` теперь список
+    независимых требований (#90), пустой список отправляется явно. Мердж
+    делается на клиенте: бэкенд присваивает `settings` целиком, и голый
+    `{security: …}` стёр бы остальные ключи.
+
+  `@stapel/profiles-react` (контракт stapel-profiles `>=0.9 <0.10`):
+
+  - `useProfilesBatch` — `POST /profiles/api/v1/batch`, один запрос вместо N.
+    `profileBatchEntry` отвечает четырьмя состояниями (`found` / `missing` /
+    `not_requested` / `unknown`): «профиля нет» — нормальное состояние и
+    плейсхолдер, «не спрашивали» — другое дело, и схлопывать их в `undefined`
+    значило бы вернуть тот самый дефект, ради которого батч и делался.
+    Найденные профили засеваются в кэш `useProfile`; для `missing` не
+    выдумывается ничего.
+
 ## 0.7.0
 
 ### Minor Changes

package/dist/api/generated/schema.d.ts

@@ -86,6 +86,113 @@ export interface paths {
         patch: operations["workspaces_api_v1_partial_update"];
         trace?: never;
     };
+    "/workspaces/api/v1/{workspace_id}/invitations": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * @description Who was invited and has not accepted (#109).
+         *
+         *     Before this endpoint an admin could send invitations and never see
+         *     them again: acceptance produced a member row, and everything else —
+         *     the unopened mail, the wrong address, the person who declined — was
+         *     invisible from the product. The roster answered "who is in"; nothing
+         *     answered "who is still out, and since when".
+         *
+         *     Gated on ``members.invite``: the mandate that creates invitations is
+         *     the mandate that sees and manages them. Reading the list is strictly
+         *     less than sending one, so no separate capability is minted — a role
+         *     that may invite but may not audit its own invitations would be a
+         *     distinction without a use.
+         *
+         *     The invite token is never in the response. It is a bearer credential;
+         *     a list endpoint that carried it would hand every admin a working login
+         *     link for every invited address.
+         *
+         *     **Permissions:** `IsAuthenticated`
+         */
+        get: operations["workspaces_api_v1_invitations_list"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/workspaces/api/v1/{workspace_id}/invitations/{invitation_id}/resend": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * @description Send the invitation email again (#109).
+         *
+         *     Accepts an **expired** invitation on purpose — a dead TTL is the most
+         *     common reason to resend — and refuses the three stored terminal states,
+         *     which are decisions rather than delivery failures. The token is
+         *     rotated and the TTL restarts, so the fresh letter carries a fresh link
+         *     and any stale copy of the old one stops working.
+         *
+         *     Reviving an expired invitation re-reserves a seat, so the plan ceiling
+         *     is re-checked here exactly as it is on invite: capability first ("may
+         *     YOU", 403), then the org's plan ("may the ORG", 402). An invitation
+         *     that is already pending costs no additional seat and is never blocked
+         *     by that check.
+         *
+         *     **Permissions:** `IsAuthenticated`
+         */
+        post: operations["workspaces_api_v1_invitations_resend_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/workspaces/api/v1/{workspace_id}/invitations/{invitation_id}/revoke": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * @description Withdraw a live invitation (#109).
+         *
+         *     The workspace's terminal "no", the mirror of the invitee's decline —
+         *     the two stay distinguishable in ``status`` forever. The seat the
+         *     invitation reserved is freed on commit.
+         *
+         *     Only a **pending** invitation is revocable: an accepted one produced a
+         *     membership (remove the member instead), a declined or already-revoked
+         *     one is terminal, and an expired one is already harmless. Each of those
+         *     gets its own error key rather than a shrug.
+         *
+         *     The transition is a compare-and-set under a row lock, not a blind
+         *     write: an accept committing between this view's state check and the
+         *     lock wins, and the revocation then fails honestly with
+         *     ``error.400.invitation_already_used``. The reverse — a revocation
+         *     committing between an accept's check and its lock — is the race fixed
+         *     in 0.10.0, and it is the same predicate holding both ends.
+         *
+         *     **Permissions:** `IsAuthenticated`
+         */
+        post: operations["workspaces_api_v1_invitations_revoke_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/workspaces/api/v1/{workspace_id}/members": {
         parameters: {
             query?: never;
@@ -151,6 +258,78 @@ export interface paths {
         patch: operations["workspaces_api_v1_members_partial_update"];
         trace?: never;
     };
+    "/workspaces/api/v1/{workspace_id}/members/{user_id}/password/reset": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * @description Reset a member's password on the organization's order (#110).
+         *
+         *     Five questions this endpoint has to answer out loud, because a
+         *     password reset is an account takeover performed on purpose and every
+         *     one of them is a way to get it wrong.
+         *
+         *     **Who may do it.** A mandate, not a session: capability
+         *     ``members.password.reset`` (builtin ``admin`` and ``owner``), declared
+         *     ``high``, so ``@requires_verification(scope="sensitive")`` demands a
+         *     fresh step-up on top — an ambient cookie is not enough to hand
+         *     somebody else's account over. Only an owner may reset an OWNER's
+         *     password, the same hardcoded owner protection role changes and
+         *     removals carry: otherwise an admin resets the owner and inherits the
+         *     organization. And auth refuses a staff/superuser target outright
+         *     (``error.403.privileged_account``) — org admin is a role inside one
+         *     workspace, deployment staff is a role above every workspace, and the
+         *     first must never be a route to the second.
+         *
+         *     **Whether the user finds out.** Always. A
+         *     ``workspace.member_password_reset`` letter names the workspace and the
+         *     admin who did it — a reset is indistinguishable from a takeover
+         *     unless the account holder is told which one it was. ``notified`` in
+         *     the response says honestly whether a channel existed; the letter
+         *     never carries the new password (see
+         *     :func:`~stapel_workspaces.services.reset_member_password`).
+         *
+         *     **Whether the new password is temporary.** Yes — auth raises the
+         *     workspace's ``provisioned_user_policies`` (#90), defaulting to
+         *     ``password_change``. A password the admin knows must stop working the
+         *     first time it is used, and since auth 0.15.0 that demand holds on all
+         *     19 session-issuance paths rather than only the password form. An org
+         *     may pass an explicit ``[]`` to suppress it, and that lands in auth's
+         *     audit row.
+         *
+         *     **Whether it is an existence oracle.** No: a target that is not a
+         *     resettable member of THIS workspace — an unknown UUID, a real account
+         *     that is not a member, a member of a different workspace, or the
+         *     caller's own id — all get one byte-identical 404. And the capability
+         *     check runs before any target lookup, so a caller without the mandate
+         *     learns nothing at all about anybody. ``tests/
+         *     test_api_member_password_reset.py`` compares those responses byte for
+         *     byte.
+         *
+         *     **Whether it is logged with the actor.** Twice, on purpose:
+         *     ``workspace.member_password_reset`` through the transactional outbox
+         *     (the org's activity log) and auth's own ``AuthAuditLog`` row carrying
+         *     ``actor_id`` and ``via=admin_reset`` (the deployment's security
+         *     journal). Neither carries credential material.
+         *
+         *     Own password: use auth's ``POST /password/change/``. This endpoint is
+         *     for acting on somebody else, and answers about yourself with the same
+         *     404 as about a stranger.
+         *
+         *     **Permissions:** `IsAuthenticated`
+         */
+        post: operations["workspaces_api_v1_members_password_reset_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/workspaces/api/v1/{workspace_id}/members/invite": {
         parameters: {
             query?: never;
@@ -221,6 +400,27 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/workspaces/api/v1/instance": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * @description Instance shape: how a street signup lands (personal | none) and whether self-serve registration is open. Public, unauthenticated — the screen a kicked/left member sees depends on it.
+         *
+         *     **Permissions:** `AllowAny`
+         */
+        get: operations["workspaces_api_v1_instance_retrieve"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/workspaces/api/v1/internal/{workspace_id}/members/{user_id}": {
         parameters: {
             query?: never;
@@ -403,6 +603,38 @@ export interface paths {
 export type webhooks = Record<string, never>;
 export interface components {
     schemas: {
+        /**
+         * @description Как развёрнут ЭТОТ инстанс — то, что клиенту нужно знать ДО того, как
+         *     он решит, что показать человеку без пространства.
+         *
+         *     Ось ``landing`` (``STREET_LANDING_MODE``) существовала с 03.08.2026, но
+         *     жила только в окружении бэкенда: наружу не отдавалась ничем, и отличить
+         *     закрытый контур от публичного облака на клиенте было НЕЧЕМ.
+         *
+         *     Почему это не косметика. Экран, который видит человек, выброшенный из
+         *     Спейса (или вышедший сам), в этих двух мирах разный по существу:
+         *
+         *     * ``none`` — закрытый контур: своего пространства у человека нет и
+         *     взяться неоткуда. Честный экран говорит «вы не участник, попросите
+         *     приглашение» и никуда не зовёт;
+         *     * ``personal`` — публичное облако: у него есть собственное
+         *     пространство, и туда можно вести.
+         *
+         *     Показать «создайте встречу» тому, кому инстанс её создать не даст, —
+         *     это тупик, нарисованный кнопкой.
+         */
+        InstanceShapeResponse: {
+            /**
+             * @description С чем приземляется человек «с улицы»
+             * @example personal
+             */
+            landing: string;
+            /**
+             * @description Можно ли завести учётку самому
+             * @example True
+             */
+            registration_open: boolean;
+        };
         /** @description Get-or-create result for a user's personal workspace (service-to-service). */
         InternalPersonalWorkspaceResponse: {
             /**
@@ -451,21 +683,78 @@ export interface components {
              */
             expires_at: string;
         };
-        /** @description InvitationResponse(id: uuid.UUID, workspace_id: uuid.UUID, email: str, role: str, expires_at: str, accepted_at: Optional[str], revoked_at: Optional[str], created_at: str) */
+        /**
+         * @description One invitation row — the admin's "who has not accepted yet" table (#109).
+         *
+         *     ``status`` is the derived label (``WorkspaceInvitation.status``), not a
+         *     stored column: it is what the table renders and what the frontend
+         *     routes the revoke/resend affordances on. The raw timestamps travel
+         *     alongside it because "expires in 2 days" and "declined last Tuesday"
+         *     are different rows on the same screen; the label alone cannot say
+         *     when.
+         *
+         *     The invite token is deliberately absent — it is a bearer secret that
+         *     only ever leaves this service inside the invitation email.
+         */
         InvitationResponse: {
-            /** Format: uuid */
+            /**
+             * Format: uuid
+             * @description Invitation UUID
+             * @example 0192f...
+             */
             id: string;
-            /** Format: uuid */
+            /**
+             * Format: uuid
+             * @description Workspace UUID
+             */
             workspace_id: string;
+            /**
+             * @description Invited email address (normalized lowercase)
+             * @example alice@example.com
+             */
             email: string;
+            /**
+             * @description Role granted on acceptance
+             * @example member
+             */
             role: string;
+            /**
+             * @description Derived state. One of pending / accepted / declined / revoked / expired
+             * @example pending
+             */
+            status: string;
+            /**
+             * @description ISO 8601 expiry time
+             * @example 2026-07-31T10:00:00Z
+             */
             expires_at: string;
+            /** @description ISO 8601 acceptance time; null unless accepted */
             accepted_at: string | null;
+            /** @description ISO 8601 decline time (the invitee said no); null unless declined */
+            declined_at: string | null;
+            /** @description ISO 8601 revocation time (the workspace withdrew it); null unless revoked */
             revoked_at: string | null;
+            /** @description ISO 8601 creation time */
             created_at: string;
+            /**
+             * Format: uuid
+             * @description UUID of the admin who sent it; null when that account is gone
+             * @example 0192a...
+             */
+            invited_by_id?: string | null;
+            /**
+             * @description Name hint typed for this invitee at invite time, if any; null otherwise
+             * @example Ada Lovelace
+             */
+            display_name?: string | null;
         };
         /** @description Invite payload. */
         MemberInviteRequest: {
+            /**
+             * @description Name hint for the invitee (this invite's "Имя" field), applied to every email in this request. Optional — an invite without one behaves exactly as before. NOT written into stapel-profiles directly (that store is the invitee's own): held on the invitation, copied onto the member at accept time, and shown only until stapel-profiles has a real name for the person
+             * @example Ada Lovelace
+             */
+            display_name?: string | null;
             /**
              * @description One or more emails to invite
              * @example [
@@ -483,6 +772,50 @@ export interface components {
         MemberInviteResponse: {
             invitations?: components["schemas"]["InvitationResponse"][];
         };
+        /** @description Reset a member's password on the organization's order (#110). */
+        MemberPasswordResetRequest: {
+            /** @description New password chosen by the admin. Omitted: the server generates a crypto-strong one, returned once as generated_password */
+            password?: string | null;
+            /**
+             * @description First-login steps to demand of the member afterwards — any subset of password_change / mfa_enroll. Omitted: the workspace's own security policies, falling back to password_change. A password somebody else chose has to stop working at its first use, so an EMPTY list is a deliberate, auditable choice, not a shortcut
+             * @example [
+             *       "password_change"
+             *     ]
+             */
+            first_login_policies?: string[] | null;
+            /**
+             * @description Free-text note recorded on auth's audit row (e.g. the ticket the request came in on)
+             * @example SUP-42
+             */
+            reason?: string | null;
+        };
+        /** @description Result of an administrative password reset (#110). */
+        MemberPasswordResetResponse: {
+            /**
+             * Format: uuid
+             * @description UUID of the member whose password was reset
+             */
+            user_id: string;
+            /**
+             * @description How many live sessions the reset ended. A reset that left them standing would not recover the account
+             * @example 2
+             */
+            sessions_revoked?: number;
+            /** @description Server-generated password — returned exactly ONCE, only when the request omitted password. Hand it to the member out of band; it cannot be re-fetched. A credential: never log it */
+            generated_password?: string | null;
+            /**
+             * @description The steps now demanded of the member before their next session
+             * @example [
+             *       "password_change"
+             *     ]
+             */
+            first_login_policies_applied?: string[];
+            /**
+             * @description Whether the member was told their password was reset. False means the account has no contact channel — the admin is the only one who can tell them
+             * @example true
+             */
+            notified?: boolean;
+        };
         /** @description Workspace member. */
         MemberResponse: {
             /**
@@ -520,6 +853,24 @@ export interface components {
             suspended_at?: string | null;
             /** @description Why the membership is suspended (canonical value no_mfa); null while active */
             suspension_reason?: string | null;
+            /**
+             * @description Best-effort display name — a live lookup in stapel-profiles when it is installed and has one, else the name typed at invite/provision time (never both, never invented when neither exists). Null when nobody has one yet
+             * @example Ada Lovelace
+             */
+            display_name?: string | null;
+        };
+        PaginatedInvitationResponseList: {
+            items: components["schemas"]["InvitationResponse"][];
+            /** @description Anchor value for next page */
+            next_anchor?: string | null;
+            /** @description Anchor value for previous page */
+            prev_anchor?: string | null;
+            /** @description Whether there are more items after this page */
+            has_next: boolean;
+            /** @description Whether there are items before this page */
+            has_prev: boolean;
+            /** @description Number of items in current page */
+            count: number;
         };
         PaginatedMemberResponseList: {
             items: components["schemas"]["MemberResponse"][];
@@ -588,9 +939,19 @@ export interface components {
             /** @description Server-generated initial password — returned exactly ONCE, only when the request omitted password. Store it or hand it to the user now; it cannot be re-fetched. A credential: never log it */
             generated_password?: string | null;
         };
-        /** @description RoleListResponse(roles: List[stapel_workspaces.dto.RoleResponse] = <factory>) */
+        /** @description The effective role registry (builtin four + STAPEL_WORKSPACES overlay). */
         RoleListResponse: {
+            /** @description One entry per effective role, descending rank */
             roles?: components["schemas"]["RoleResponse"][];
+            /**
+             * @description Step-up level per namespaced capability string, builtin ``members.provision`` / ``members.password.reset`` / ``workspace.security.manage`` plus the deployment's ``STAPEL_WORKSPACES["CAPABILITY_LEVELS"]`` overlay. A capability absent from this map is ``"standard"`` — the client-side default. Lets a frontend stop hardcoding its own copy of this registry
+             * @example {
+             *       "members.provision": "high"
+             *     }
+             */
+            capability_levels?: {
+                [key: string]: string;
+            };
         };
         /** @description One role of the effective registry (builtin + STAPEL_WORKSPACES overlay). */
         RoleResponse: {
@@ -657,9 +1018,17 @@ export interface components {
              */
             type?: string;
         };
-        /** @description WorkspaceListResponse(workspaces: List[stapel_workspaces.dto.WorkspaceResponse] = <factory>) */
+        /** @description The caller's own workspace list. */
         WorkspaceListResponse: {
+            /** @description The caller's active memberships (empty for a guest — see is_guest) */
             workspaces?: components["schemas"]["WorkspaceResponse"][];
+            /** @description True when the caller holds NO active mandate anywhere (permissions.is_guest) — the wire form of the mandate-model vardict's guest predicate (2026-08-03), so a frontend can render the "incomplete dashboard" without re-deriving it from workspaces == [] */
+            is_guest?: boolean;
+            /**
+             * @description Which workspace a client should open when the person has expressed no choice — the instance's STAPEL_WORKSPACES["DEFAULT_WORKSPACE_ID"], echoed back ONLY when the caller actually holds an active membership in it, else "". Exists because clients that had to guess guessed badly: meettoday took `workspaces[0]` off a list ordered by last access, so a person in two spaces landed wherever they happened to have been last (measured 2026-08-06 as "the owner cannot see his own invitations" — they were in the OTHER space). A default, not a cage: an explicit choice still wins
+             * @example a8bba7ae-5d2e-43e5-9911-0553e7df50b3
+             */
+            default_workspace_id?: string;
         };
         /** @description Workspace details. */
         WorkspaceResponse: {
@@ -845,6 +1214,82 @@ export interface operations {
             };
         };
     };
+    workspaces_api_v1_invitations_list: {
+        parameters: {
+            query?: {
+                /** @description Anchor value to paginate from (exclusive) */
+                anchor?: string;
+                /** @description Pagination direction */
+                direction?: "next" | "prev" | "center";
+                /** @description Number of items (default 100, max 500) */
+                limit?: number;
+                /** @description Case-insensitive substring filter on the invited email address. */
+                search?: string;
+                /** @description Which invitations to return. `pending` (default) — live, actionable, seat-reserving ones, i.e. who has not accepted yet. `never_accepted` — those plus the declined, revoked and expired ones. `all` — the full history, accepted rows included. */
+                status?: "all" | "never_accepted" | "pending";
+            };
+            header?: never;
+            path: {
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PaginatedInvitationResponseList"];
+                };
+            };
+        };
+    };
+    workspaces_api_v1_invitations_resend_create: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                invitation_id: string;
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["InvitationResponse"];
+                };
+            };
+        };
+    };
+    workspaces_api_v1_invitations_revoke_create: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                invitation_id: string;
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["InvitationResponse"];
+                };
+            };
+        };
+    };
     workspaces_api_v1_members_list: {
         parameters: {
             query?: {
@@ -924,6 +1369,34 @@ export interface operations {
             };
         };
     };
+    workspaces_api_v1_members_password_reset_create: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                user_id: string;
+                workspace_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["MemberPasswordResetRequest"];
+                "application/x-www-form-urlencoded": components["schemas"]["MemberPasswordResetRequest"];
+                "multipart/form-data": components["schemas"]["MemberPasswordResetRequest"];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MemberPasswordResetResponse"];
+                };
+            };
+        };
+    };
     workspaces_api_v1_members_invite_create: {
         parameters: {
             query?: never;
@@ -978,6 +1451,25 @@ export interface operations {
             };
         };
     };
+    workspaces_api_v1_instance_retrieve: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["InstanceShapeResponse"];
+                };
+            };
+        };
+    };
     workspaces_api_v1_internal_members_retrieve: {
         parameters: {
             query?: never;