npm package: @haykal/rbac-client
Description: > React Query hooks for role-based access control — manage roles, permissions, user assignments, and check current user's access.
Latest version: 1.0.0

# @haykal/rbac-client

> React Query hooks for role-based access control — manage roles, permissions, user assignments, and check current user's access.

## Installation

```bash
pnpm add @haykal/rbac-client
```

## Setup

```typescript
import { initMutator } from '@haykal/rbac-client';

initMutator(); // Connects to HaykalClient singleton
```

## Hooks

### Current User

| Hook                          | Description                          |
| ----------------------------- | ------------------------------------ |
| `useMyPermissions()`          | Current user's effective permissions |
| `useMyRoles()`                | Current user's roles                 |
| `useCheckMyPermissions(keys)` | Check specific permissions           |

### Roles

| Hook                         | Description                  |
| ---------------------------- | ---------------------------- |
| `useRoles()`                 | List all roles               |
| `useRole(id)`                | Get role by ID               |
| `useCreateRole()`            | Create role mutation         |
| `useUpdateRole()`            | Update role mutation         |
| `useDeleteRole()`            | Delete role mutation         |
| `useRolePermissions(roleId)` | Get permissions for a role   |
| `useSetRolePermissions()`    | Replace all role permissions |
| `useAddRolePermissions()`    | Add permissions to role      |
| `useRemoveRolePermissions()` | Remove permissions from role |

### Permissions

| Hook               | Description          |
| ------------------ | -------------------- |
| `usePermissions()` | List all permissions |

### User Roles

| Hook                   | Description            |
| ---------------------- | ---------------------- |
| `useUserRoles(userId)` | Get user's roles       |
| `useSetUserRoles()`    | Replace all user roles |
| `useAddUserRole()`     | Add role to user       |
| `useRemoveUserRole()`  | Remove role from user  |

## Usage Examples

### Checking Permissions in UI

```tsx
import { useMyPermissions } from '@haykal/rbac-client';

function AdminPanel() {
  const { data } = useMyPermissions();
  const permissions = data?.data ?? [];

  if (!permissions.includes('users.manage')) {
    return <div>Access denied</div>;
  }

  return <UserManagementPanel />;
}
```

### Managing Roles

```tsx
import { useRoles, useCreateRole } from '@haykal/rbac-client';

function RolesManager() {
  const { data: roles } = useRoles();
  const { mutate: createRole } = useCreateRole();

  return (
    <div>
      {roles?.data?.map((role) => (
        <div key={role.id}>{role.displayName}</div>
      ))}
      <button
        onClick={() =>
          createRole({ name: 'editor', displayName: 'Editor', permissions: [] })
        }
      >
        Add Editor Role
      </button>
    </div>
  );
}
```

## Regenerating

```bash
nx run @haykal/rbac-client:generate
```

> **Never edit files in `src/generated/`** — they are auto-generated by Orval.

## Related Packages

- `@haykal/rbac-backend` — Backend API
- `@haykal/core-client` — HTTP client and React Query provider
- `@haykal/auth-client` — Authentication hooks

## Further Reading

- [Client SDK Generation](../../../docs/client-sdk-generation.md) — Orval pipeline and regeneration
- [API Reference](../../../docs/api-reference.md) — Backend endpoints these hooks call