npm package: @ortha/admin-identity
Description: Authentication UI plugin for the Ortha admin application — provides login, signup, and invite code verification pages. All auth routes are public (guest-only) and redirect authenticated users to the home page.
Latest version: 0.0.4

# @ortha/admin-identity

Authentication UI plugin for the Ortha admin application — provides login, signup, and invite code verification pages. All auth routes are public (guest-only) and redirect authenticated users to the home page.

## Installation

Internal monorepo dependency — import directly:

```ts
import { identityPlugin } from '@ortha/admin-identity';
import type { CurrentUser, Role, Permission } from '@ortha/admin-identity';
```

## Usage

### Registering the plugin

```ts
import { bootstrap } from '@ortha/admin-platform-bootstrap';
import { identityPlugin } from '@ortha/admin-identity';

bootstrap(document.getElementById('root')!, [
    identityPlugin()
    // ...other plugins
]);
```

### Using API hooks

```ts
import { useLogin, useCurrentUser, useRoles } from '@ortha/admin-identity';

const LoginComponent = () => {
    const login = useLogin();

    const handleSubmit = (data: { email: string; password: string }) => {
        login.mutate(data);
    };
};

const ProfileComponent = () => {
    const { data: user } = useCurrentUser();
    const { data: roles } = useRoles();
};
```

## Routes

| Path           | Page                       | Auth Required |
| -------------- | -------------------------- | ------------- |
| `/auth`        | Auth layout wrapper        | No            |
| `/auth/login`  | Login form                 | No            |
| `/auth/signup` | Signup form (invite-gated) | No            |
| `/auth/invite` | Invite code verification   | No            |

## API Reference

### Plugin

| Export             | Kind    | Description                          |
| ------------------ | ------- | ------------------------------------ |
| `identityPlugin()` | factory | Admin plugin — registers auth routes |

### Hooks

| Export            | Kind | Description                                   |
| ----------------- | ---- | --------------------------------------------- |
| `useLogin`        | hook | Login mutation (`POST /api/identity/login`)   |
| `useSignup`       | hook | Signup mutation (`POST /api/identity/signup`) |
| `useInviteVerify` | hook | Invite verify mutation                        |
| `useInviteCreate` | hook | Invite create mutation                        |
| `useRefresh`      | hook | Token refresh mutation                        |
| `useCurrentUser`  | hook | Current user query (`GET /api/identity/me`)   |
| `useRoles`        | hook | Roles query (`GET /api/identity/roles`)       |
| `currentUserKey`  | fn   | Query key factory for current user cache      |
| `rolesKey`        | fn   | Query key factory for roles cache             |

### Types

| Export            | Kind | Description                          |
| ----------------- | ---- | ------------------------------------ |
| `CurrentUser`     | type | Current user entity                  |
| `CurrentUserRole` | type | Current user's role with permissions |
| `Permission`      | type | Permission (action + resource)       |
| `Role`            | type | Role entity                          |

## Internal Structure

```
src/lib/
├── identityPlugin/index.ts         # Plugin factory with route registration
├── types/index.ts                  # Shared entity types (CurrentUser, Role, etc.)
├── api/
│   ├── useLogin/index.ts           # LoginBody + login() + useLogin mutation
│   ├── useSignup/index.ts          # SignupBody + signup() + useSignup mutation
│   ├── useInviteVerify/index.ts    # InviteVerifyBody + useInviteVerify mutation
│   ├── useInviteCreate/index.ts    # InviteCreateBody + useInviteCreate mutation
│   ├── useRefresh/index.ts         # refresh() + useRefresh mutation
│   ├── useCurrentUser/index.ts     # currentUserKey + useCurrentUser query
│   └── useRoles/index.ts          # rolesKey + useRoles query
└── pages/
    ├── LoginPage/index.tsx
    ├── SignUpPage/index.tsx
    └── InviteCodePage/index.tsx
```

## Key Patterns

- Auth pages use `react-hook-form` with `ajvResolver` from `@ortha/admin-utils`.
- API hooks use TanStack React Query and `httpClient` from `@ortha/admin-platform-core`.
- Request/response types specific to one hook are co-located inside that hook's file.
- Shared entity types live in `types/index.ts`.
- Error handling uses `handleMutationError` from `@ortha/admin-utils`.
- This plugin has no dependencies on other feature plugins — it is foundational.

## Dependencies

- `@ortha/admin-platform-core` — `httpClient`, auth store
- `@ortha/admin-platform-plugin-registry` — plugin types
- `@ortha/admin-utils` — `ajvResolver`, `handleMutationError`
- `@ortha/design-system` — theme and UI components

## Building

```bash
nx build admin-identity
```