npm package: @haykal/user-management-client
Description: > React Query hooks for user management — paginated listing, CRUD, bulk operations, import/export, and statistics.
Latest version: 1.0.0

# @haykal/user-management-client

> React Query hooks for user management — paginated listing, CRUD, bulk operations, import/export, and statistics.

## Installation

```bash
pnpm add @haykal/user-management-client
```

## Setup

Initialize the HTTP client mutator (typically done once in your app's provider):

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

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

## Hooks

### Custom Hooks (Hand-written Wrappers)

These hooks add cache invalidation, optimistic updates, and friendly APIs on top of the generated code.

| Hook                    | Description                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------ |
| `useUsers(query)`       | Paginated/filtered user list with `search`, `isActive`, `page`, `limit`, `sort`, `filter` params |
| `useUser(id)`           | Single user by ID (30s stale time, conditional fetch)                                            |
| `useUserStats()`        | User statistics (total, active, inactive, etc.)                                                  |
| `useCreateUser()`       | Create user mutation with auto cache invalidation                                                |
| `useUpdateUser()`       | Update user mutation                                                                             |
| `useDeleteUser()`       | Delete user mutation                                                                             |
| `useToggleUserStatus()` | Toggle active/inactive status                                                                    |

### Generated Hooks

All generated hooks from the OpenAPI spec are also available as re-exports.

## Usage Examples

### Listing Users with Filtering

```tsx
import { useUsers } from '@haykal/user-management-client';

function UserList() {
  const { data, isLoading } = useUsers({
    search: 'john',
    isActive: true,
    page: 1,
    limit: 20,
    sort: '-createdAt',
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <ul>
      {data?.data?.map((user) => (
        <li key={user.id}>{user.email}</li>
      ))}
    </ul>
  );
}
```

### Creating a User

```tsx
import { useCreateUser } from '@haykal/user-management-client';

function CreateUserForm() {
  const { mutate, isPending } = useCreateUser();

  const handleSubmit = (data: CreateUserDto) => {
    mutate(data, {
      onSuccess: () => {
        // User list cache is automatically invalidated
      },
    });
  };
}
```

## Regenerating

Requires the backend running at `localhost:8080`:

```bash
nx run @haykal/user-management-client:generate
```

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

## Related Packages

- `@haykal/user-management-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
- [Admin App Development](../../../docs/admin-app-development.md) — Using hooks in the admin dashboard
- [API Reference](../../../docs/api-reference.md) — Backend endpoints these hooks call