@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/roles.md

@@ -0,0 +1,812 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.roles`: Roles
+
+20 operations (14 read, 2 write, 4 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.roles.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [roles.d.ts](roles.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`createRole`](#op-createrole) | `POST /api/v1/roles` | write | `account:write` | Create Role |
+| [`deleteRole`](#op-deleterole) | `DELETE /api/v1/roles/{role_id}` | destructive | `account:delete` | Delete Role |
+| [`deleteServiceProviderAssignments`](#op-deleteserviceproviderassignments) | `DELETE /api/v1/roles/service-provider/assignments/{email}` | destructive | `account:delete` | Delete Service Provider Assignments |
+| [`getDomainSettings`](#op-getdomainsettings) | `GET /api/v1/roles/domain-settings` | read | `account:read` | Get Domain Settings |
+| [`getJoinRequestCount`](#op-getjoinrequestcount) | `GET /api/v1/roles/join-requests/count` | read | `account:read` | Get Join Request Count |
+| [`getMyPermissions`](#op-getmypermissions) | `GET /api/v1/roles/me/permissions` | read | `account:read` | Get My Permissions |
+| [`getRole`](#op-getrole) | `GET /api/v1/roles/{role_id}` | read | `account:read` | Get Role |
+| [`getUserRole`](#op-getuserrole) | `GET /api/v1/roles/users/{user_id}` | read | `account:read` | Get User Role |
+| [`listJoinRequests`](#op-listjoinrequests) | `GET /api/v1/roles/join-requests` | read | `account:read` | List Join Requests |
+| [`listOrgUsers`](#op-listorgusers) | `GET /api/v1/roles/org-users` | read | `account:read` | List Org Users |
+| [`listPendingInvites`](#op-listpendinginvites) | `GET /api/v1/roles/pending-invites` | read | `account:read` | List Pending Invites |
+| [`listPermissions`](#op-listpermissions) | `GET /api/v1/roles/permissions` | read | `account:read` | List Permissions |
+| [`listPermissionsGrouped`](#op-listpermissionsgrouped) | `GET /api/v1/roles/permissions/grouped` | read | `account:read` | List Permissions Grouped |
+| [`listRoleOptions`](#op-listroleoptions) | `GET /api/v1/roles/options` | read | `account:read` | List Role Options |
+| [`listRoles`](#op-listroles) | `GET /api/v1/roles` | read | `account:read` | List Roles |
+| [`listServiceProviderAssignments`](#op-listserviceproviderassignments) | `GET /api/v1/roles/service-provider/assignments` | read | `account:read` | List Service Provider Assignments |
+| [`listServiceProviderAvailableLists`](#op-listserviceprovideravailablelists) | `GET /api/v1/roles/service-provider/available-lists` | read | `account:read` | List Service Provider Available Lists |
+| [`rejectJoinRequest`](#op-rejectjoinrequest) | `POST /api/v1/roles/join-requests/{request_id}/reject` | write | `account:write` | Reject Join Request |
+| [`revokePendingInvite`](#op-revokependinginvite) | `DELETE /api/v1/roles/pending-invites/{email}` | destructive | `account:delete` | Revoke Pending Invite |
+| [`updateRole`](#op-updaterole) | `PUT /api/v1/roles/{role_id}` | destructive | `account:delete` | Update Role |
+
+---
+
+<a id="op-createrole"></a>
+
+### `g8.api.roles.createRole(input)`
+
+**Create Role**
+
+- HTTP: `POST /api/v1/roles`
+- operationId: `create_role_roles_post` (also callable as `g8.api.call("create_role_roles_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `account:write`
+
+Define a new role. It grants nobody anything until it is assigned.
+
+Two of the app's own guards run inside the handler and are not duplicated
+here: `_assert_can_grant_permissions` refuses a permission the CALLER does
+not hold, and `_require_teams_manage` refuses `manages_role_slugs` without
+`teams:manage`. Both reach the caller as a 403 with the app's own message.
+
+This is `write` rather than `destructive` on purpose: a brand-new role is
+held by no one, so creating it changes nobody's access. Editing one does -
+which is why `PUT /roles/{role_id}` is tiered differently.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `RoleCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`RoleCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes | min length 1, max length 100 |
+| `body.slug` | `string` | yes | min length 1, max length 50, pattern `^[a-z][a-z0-9_-]*$` |
+| `body.description` | `string \| null` | no |  |
+| `body.manages_role_slugs` | `Array<string> \| null` | no |  |
+| `body.permissions` | `Array<string>` | no |  |
+| `body.rep_limits` | `RepLimitsSettings \| null` | no |  |
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.roles.createRole({ body: { name: "Example", slug: "example" } });
+```
+
+---
+
+<a id="op-deleterole"></a>
+
+### `g8.api.roles.deleteRole(input)`
+
+**Delete Role**
+
+- HTTP: `DELETE /api/v1/roles/{role_id}`
+- operationId: `delete_role_roles__role_id__delete` (also callable as `g8.api.call("delete_role_roles__role_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `account:delete`
+
+Remove a role definition.
+
+The app refuses while anyone still holds it, so this cannot silently strip
+a colleague's access - re-role them first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.role_id` | `string` | yes | Role id (UUID). |
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.roles.deleteRole({ path: { role_id: "id" } });
+```
+
+---
+
+<a id="op-deleteserviceproviderassignments"></a>
+
+### `g8.api.roles.deleteServiceProviderAssignments(input)`
+
+**Delete Service Provider Assignments**
+
+- HTTP: `DELETE /api/v1/roles/service-provider/assignments/{email}`
+- operationId: `delete_service_provider_assignments_roles_service_provider_assignments__email__delete` (also callable as `g8.api.call("delete_service_provider_assignments_roles_service_provider_assignments__email__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `account:delete`
+
+Revoke every list a service provider was given. Their access ends here.
+
+Published although the PUT that grants assignments is not. This one only
+deletes rows in `service_provider_list_assignments`; the PUT additionally
+RE-ROLES the named person - see the PR body.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.email` | `string` | yes | The service provider's email address. |
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.roles.deleteServiceProviderAssignments({ path: { email: "jane@acme.com" } });
+```
+
+---
+
+<a id="op-getdomainsettings"></a>
+
+### `g8.api.roles.getDomainSettings(input?)`
+
+**Get Domain Settings**
+
+- HTTP: `GET /api/v1/roles/domain-settings`
+- operationId: `get_domain_settings_roles_domain_settings_get` (also callable as `g8.api.call("get_domain_settings_roles_domain_settings_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+Which email domains can reach this organisation, and how.
+
+`domain_autojoin` is the consequential field: with it on, anybody with an
+address at one of these domains joins automatically, at
+`autojoin_default_role_id`. The WRITE half of this is not published - see
+the module docstring.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.roles.getDomainSettings();
+```
+
+---
+
+<a id="op-getjoinrequestcount"></a>
+
+### `g8.api.roles.getJoinRequestCount(input?)`
+
+**Get Join Request Count**
+
+- HTTP: `GET /api/v1/roles/join-requests/count`
+- operationId: `get_join_request_count_roles_join_requests_count_get` (also callable as `g8.api.call("get_join_request_count_roles_join_requests_count_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+How many people are waiting. The cheap poll behind a queue badge.
+
+Declared BEFORE `/roles/{role_id}` so the literal wins - that route parses
+a UUID, so a flip would answer 422 rather than 404, which is much harder
+to recognise as a routing problem.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.roles.getJoinRequestCount();
+```
+
+---
+
+<a id="op-getmypermissions"></a>
+
+### `g8.api.roles.getMyPermissions(input?)`
+
+**Get My Permissions**
+
+- HTTP: `GET /api/v1/roles/me/permissions`
+- operationId: `get_my_permissions_roles_me_permissions_get` (also callable as `g8.api.call("get_my_permissions_roles_me_permissions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+What THIS KEY may do, as the app's own permission machinery sees it.
+
+Worth calling before anything else on this surface: the non-escalation
+guard on every write below bounds what you may grant by what this answer
+contains. A machine key with no human behind it holds no role permissions
+and will see an empty set - that is the documented fail-closed policy, not
+a lookup failure.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.roles.getMyPermissions();
+```
+
+---
+
+<a id="op-getrole"></a>
+
+### `g8.api.roles.getRole(input)`
+
+**Get Role**
+
+- HTTP: `GET /api/v1/roles/{role_id}`
+- operationId: `get_role_roles__role_id__get` (also callable as `g8.api.call("get_role_roles__role_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+One role, with the full permission list it grants.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.role_id` | `string` | yes | Role id (UUID). |
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.roles.getRole({ path: { role_id: "id" } });
+```
+
+---
+
+<a id="op-getuserrole"></a>
+
+### `g8.api.roles.getUserRole(input)`
+
+**Get User Role**
+
+- HTTP: `GET /api/v1/roles/users/{user_id}`
+- operationId: `get_user_role_roles_users__user_id__get` (also callable as `g8.api.call("get_user_role_roles_users__user_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+The role one person holds in this organisation.
+
+404 when they hold none - which is a real state, not an error: a member
+can exist in the organisation with no role assigned yet.
+
+The WRITE twin, `PUT /v1/roles/users/{user_id}`, is not published. It
+maps a role slug of `owner` or `admin` onto the identity provider's own
+Owner/Admin and syncs it, so it can make somebody an administrator of the
+tenant.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.user_id` | `string` | yes | Identity-provider user id. |
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.roles.getUserRole({ path: { user_id: "id" } });
+```
+
+---
+
+<a id="op-listjoinrequests"></a>
+
+### `g8.api.roles.listJoinRequests(input?)`
+
+**List Join Requests**
+
+- HTTP: `GET /api/v1/roles/join-requests`
+- operationId: `list_join_requests_roles_join_requests_get` (also callable as `g8.api.call("list_join_requests_roles_join_requests_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+People waiting to be let into the organisation.
+
+Read-only here. Approving or rejecting one admits a human being to the
+tenant and can make them an administrator of it, so it stays in the
+product - see the module docstring.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.status` | `string \| null` | no | Queue state to list: `pending`, `approved` or `rejected`. default `"pending"` |
+
+**Returns** `ApiResponse_OrgListPayload_`: the envelope `{ data: OrgListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OrgListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.roles.listJoinRequests();
+```
+
+---
+
+<a id="op-listorgusers"></a>
+
+### `g8.api.roles.listOrgUsers(input?)`
+
+**List Org Users**
+
+- HTTP: `GET /api/v1/roles/org-users`
+- operationId: `list_org_users_roles_org_users_get` (also callable as `g8.api.call("list_org_users_roles_org_users_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+Everyone in the organisation, with the role each of them holds.
+
+The join between the identity provider's membership list and this org's
+own role assignments - which is the only place both halves appear
+together.
+
+On the app's ungated sibling router, so no admin gate here either: the
+directory is what every owner and assignee picker in the product is built
+from, and `settings:read` OR `team:read` is the app's own bar for it.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgListPayload_`: the envelope `{ data: OrgListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OrgListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.roles.listOrgUsers();
+```
+
+---
+
+<a id="op-listpendinginvites"></a>
+
+### `g8.api.roles.listPendingInvites(input?)`
+
+**List Pending Invites**
+
+- HTTP: `GET /api/v1/roles/pending-invites`
+- operationId: `list_pending_invites_roles_pending_invites_get` (also callable as `g8.api.call("list_pending_invites_roles_pending_invites_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+Invitations sent but not yet accepted, and the role each one carries.
+
+An invitation is a role assignment that has not landed yet: the role is
+applied on the invitee's first login. That makes this list the honest
+answer to "who is about to get access, and to what".
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgListPayload_`: the envelope `{ data: OrgListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OrgListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.roles.listPendingInvites();
+```
+
+---
+
+<a id="op-listpermissions"></a>
+
+### `g8.api.roles.listPermissions(input?)`
+
+**List Permissions**
+
+- HTTP: `GET /api/v1/roles/permissions`
+- operationId: `list_permissions_roles_permissions_get` (also callable as `g8.api.call("list_permissions_roles_permissions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+Every permission a role can be built from.
+
+The source of the strings `POST /roles` and `PUT /roles/{role_id}` accept
+in `permissions`. Read this first: a permission the org does not have is
+rejected, and the app's non-escalation guard additionally refuses anything
+the CALLER does not already hold.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgListPayload_`: the envelope `{ data: OrgListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OrgListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.roles.listPermissions();
+```
+
+---
+
+<a id="op-listpermissionsgrouped"></a>
+
+### `g8.api.roles.listPermissionsGrouped(input?)`
+
+**List Permissions Grouped**
+
+- HTTP: `GET /api/v1/roles/permissions/grouped`
+- operationId: `list_permissions_grouped_roles_permissions_grouped_get` (also callable as `g8.api.call("list_permissions_grouped_roles_permissions_grouped_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+The same catalogue, bucketed by the product area each permission gates.
+
+The shape a permission picker is built from. Open-shaped: the buckets grow
+as the product does, and a dropped one would read as "that area has no
+permissions" rather than "we did not tell you".
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.roles.listPermissionsGrouped();
+```
+
+---
+
+<a id="op-listroleoptions"></a>
+
+### `g8.api.roles.listRoleOptions(input?)`
+
+**List Role Options**
+
+- HTTP: `GET /api/v1/roles/options`
+- operationId: `list_role_options_roles_options_get` (also callable as `g8.api.call("list_role_options_roles_options_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+Roles as a PICKER: id, name, slug. No permission lists.
+
+Deliberately ungated, matching the app: choosing a role from a list is not
+an administrative act, and gating it is what made the picker render empty
+for every ordinary member.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgListPayload_`: the envelope `{ data: OrgListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OrgListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.roles.listRoleOptions();
+```
+
+---
+
+<a id="op-listroles"></a>
+
+### `g8.api.roles.listRoles(input?)`
+
+**List Roles**
+
+- HTTP: `GET /api/v1/roles`
+- operationId: `list_roles_roles_get` (also callable as `g8.api.call("list_roles_roles_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+Every role in the organisation, with its permissions and holder count.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgListPayload_`: the envelope `{ data: OrgListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OrgListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.roles.listRoles();
+```
+
+---
+
+<a id="op-listserviceproviderassignments"></a>
+
+### `g8.api.roles.listServiceProviderAssignments(input?)`
+
+**List Service Provider Assignments**
+
+- HTTP: `GET /api/v1/roles/service-provider/assignments`
+- operationId: `list_service_provider_assignments_roles_service_provider_assignments_get` (also callable as `g8.api.call("list_service_provider_assignments_roles_service_provider_assignments_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+Which lists each outside service provider can see.
+
+A service provider is a non-employee working inside the tenant, and this
+is the whole of what they are allowed to reach. Worth auditing.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgListPayload_`: the envelope `{ data: OrgListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OrgListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.roles.listServiceProviderAssignments();
+```
+
+---
+
+<a id="op-listserviceprovideravailablelists"></a>
+
+### `g8.api.roles.listServiceProviderAvailableLists(input?)`
+
+**List Service Provider Available Lists**
+
+- HTTP: `GET /api/v1/roles/service-provider/available-lists`
+- operationId: `list_service_provider_available_lists_roles_service_provider_available_lists_get` (also callable as `g8.api.call("list_service_provider_available_lists_roles_service_provider_available_lists_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `account:read`
+
+The lists that COULD be delegated, scoped to what the caller can see.
+
+Not every list in the org: the app applies the caller's own list-read
+scope, so a manager cannot delegate a list they cannot read themselves.
+
+**Input**: none.
+
+**Returns** `ApiResponse_OrgListPayload_`: the envelope `{ data: OrgListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`OrgListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.roles.listServiceProviderAvailableLists();
+```
+
+---
+
+<a id="op-rejectjoinrequest"></a>
+
+### `g8.api.roles.rejectJoinRequest(input)`
+
+**Reject Join Request**
+
+- HTTP: `POST /api/v1/roles/join-requests/{request_id}/reject`
+- operationId: `reject_join_request_roles_join_requests__request_id__reject_post` (also callable as `g8.api.call("reject_join_request_roles_join_requests__request_id__reject_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `account:write`
+
+Turn a pending join request down. Nobody gains access.
+
+Published although its twin `approve` is not, for the same reason
+`DELETE /roles/pending-invites/{email}` is: this direction only ever
+REFUSES access, and the direction that admits a person - possibly at an
+Owner or Admin role - is the one that needs a human.
+
+400 when the request is no longer pending; 404 when it is not this
+organisation's.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.request_id` | `string` | yes | Join request id (UUID). |
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.roles.rejectJoinRequest({ path: { request_id: "id" } });
+```
+
+---
+
+<a id="op-revokependinginvite"></a>
+
+### `g8.api.roles.revokePendingInvite(input)`
+
+**Revoke Pending Invite**
+
+- HTTP: `DELETE /api/v1/roles/pending-invites/{email}`
+- operationId: `revoke_pending_invite_roles_pending_invites__email__delete` (also callable as `g8.api.call("revoke_pending_invite_roles_pending_invites__email__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `account:delete`
+
+Withdraw an invitation before it is accepted.
+
+Published although its counterpart `POST /invite` is not, and the
+asymmetry is deliberate: this only ever REMOVES a pending grant. The
+direction that hands someone access is the one that needs a human.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.email` | `string` | yes | Email address the invitation was sent to. |
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.roles.revokePendingInvite({ path: { email: "jane@acme.com" } });
+```
+
+---
+
+<a id="op-updaterole"></a>
+
+### `g8.api.roles.updateRole(input)`
+
+**Update Role**
+
+- HTTP: `PUT /api/v1/roles/{role_id}`
+- operationId: `update_role_roles__role_id__put` (also callable as `g8.api.call("update_role_roles__role_id__put", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `account:delete`
+
+Redefine a role. THIS CHANGES WHAT EVERY HOLDER MAY DO, IMMEDIATELY.
+
+`permissions` REPLACES the list rather than merging into it, so a value
+left out is a permission taken away from everyone who holds the role. That
+is why this operation is tiered `destructive` rather than `write`: it is a
+privilege change, and "re-define what the sales team may do" must not ride
+along in the same grant as "rename a team".
+
+The app refuses to edit the permissions of its locked system roles
+(`admin`, `service_provider`) - stripping `roles:manage` from `admin`
+would lock the organisation out with no recovery path - and refuses to
+grant anything the caller does not hold. Both reach you as a 403.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.role_id` | `string` | yes | Role id (UUID). |
+| `body` | `RoleUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`RoleUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.description` | `string \| null` | no |  |
+| `body.manages_role_slugs` | `Array<string> \| null` | no |  |
+| `body.name` | `string \| null` | no | min length 1, max length 100 |
+| `body.permissions` | `Array<string> \| null` | no |  |
+| `body.rep_limits` | `RepLimitsSettings \| null` | no |  |
+
+**Returns** `ApiResponse_OrgPayload_`: the envelope `{ data: OrgPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.roles.updateRole({ path: { role_id: "id" }, body: {} });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-replimitssettings"></a>
+
+### `RepLimitsSettings`
+
+Per-role reveal/ownership limits. Mirrors `roles.RepLimitsSettings`. The three `Literal`s are closed here rather than left as strings because they reach the app's own `Literal` inside `_apply_rep_limits`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `conflict_company_owned` | `"allow" \| "warn" \| "block"` | no | default `"allow"` |
+| `conflict_contact_active` | `"allow" \| "warn" \| "block"` | no | default `"allow"` |
+| `max_companies` | `integer \| null` | no | min 0 |
+| `max_contacts` | `integer \| null` | no | min 0 |
+| `reveal_monthly_credit_budget` | `integer \| null` | no | min 0 |
+| `reveal_policy` | `"within_limits" \| "monthly_credit_budget" \| "no_limit"` | no | default `"no_limit"` |