# CLAUDE.md — Project Context for Claude Code

## Project

`@applica-software-guru/iam-client` — TypeScript client for the Applica IAM service.

## Stack

- **Language:** TypeScript
- **Build:** Vite (`npm run build`)
- **Test:** Vitest (`npm test`)
- **Lint:** ESLint (`npm run eslint`)
- **Format:** Prettier (`npm run format`)
- **Package manager:** npm

## Architecture

The library exposes `createIamClient()` which returns an `IamClient` with 6 services:

```
IamClient({ apiUrl, storage?, apiKey? })
  ├── auth: AuthService          → /auth/*
  ├── users: UserService         → /users/*
  ├── tenants: TenantService     → /tenants/*
  ├── projects: ProjectService   → /projects/*
  ├── roles: RoleService         → /roles/*
  └── devices: DeviceService     → /devices/*
```

All services share a single `HttpClient` instance that handles authentication headers (Bearer token + optional x-api-key).

## Entry Points

- `.` — Full package (core + React Admin adapter). Peer deps: `ra-core`, `react`, `react-dom` (optional).
- `./core` — Framework-agnostic core only. No React dependency.

## Directory Structure

```
src/
  core/
    iam-client.ts              # IamClient + createIamClient()
    http-client.ts             # Shared HttpClient (fetch + auth + validation)
    errors.ts                  # FailureResponse (handled/unhandled errors)
    services/                  # One service per entity
      auth.service.ts, user.service.ts, tenant.service.ts,
      project.service.ts, role.service.ts, device.service.ts
    types/                     # DTOs per entity
      common.ts, auth.types.ts, user.types.ts, tenant.types.ts,
      project.types.ts, role.types.ts, device.types.ts
    storage/                   # IStorage implementations
      local-storage.ts, memory-storage.ts
    crypto/                    # AES/Base64 utils for PIN encryption
      aes-util.ts, base64.ts
  react-admin/
    auth-provider.ts           # ApplicaAuthProvider (thin wrapper over IamClient)
    types.ts                   # IApplicaAuthProvider interface
  tests/
    core/                      # Integration tests for each service
    authProvider/              # Tests for React Admin adapter
```

## Authentication Model

The backend has 3 security chains:

- `/auth/**` — public (no auth needed)
- `/tenants/**` — **system API key only** (`x-api-key` header matching server's `iam.api-key`). Bearer tokens are NOT accepted.
- `/users/**`, `/roles/**`, `/projects/**`, `/devices/**` — Bearer token OR system API key OR tenant API key

The system API key is a static value configured in the backend's `application.yaml` under `iam.api-key`. It grants `ROLE_SYSTEM` via the `GodAuthenticationFilter`.

## Key Patterns

- Services use `HttpClient.requestAndValidate<T>()` which auto-validates `responseCode === 'ok'`
- `AuthService` uses raw `fetch` for form-urlencoded endpoints (`/auth/login`, `/auth/register`, etc.)
- All errors are `FailureResponse` instances with `handled` flag and `message` code
- Storage is async (`IStorage` interface with `Promise`-based methods)
- `ApplicaAuthProvider` normalizes URL by stripping trailing `/auth` for backward compatibility

## Commands

```bash
npm run build     # Vite build → dist/
npm test          # Vitest run
npm run eslint    # ESLint
npm run format    # Prettier
```

## Documentation

Full documentation is in the [docs/](docs/) folder. See [README.md](README.md) for the index.