# Getting Started

## Installation

```bash
npm install @applica-software-guru/iam-client
```

**Optional peer dependencies** (only needed for the React Admin adapter):

```bash
npm install ra-core react react-dom
```

## Quick Start

```typescript
import { createIamClient } from '@applica-software-guru/iam-client';

const iam = createIamClient({ apiUrl: 'https://server.com/api' });

// Authentication
await iam.auth.login({ username: 'user@test.com', password: 'secret' });

// CRUD operations (authenticated via Bearer token from login)
const { user } = await iam.users.getById('user-id');
await iam.roles.register({ code: 'EDITOR', name: 'Editor', permissions: ['read', 'write'] });
await iam.projects.search({ keyword: 'web' });
```

## Configuration

```typescript
import { createIamClient, MemoryStorage } from '@applica-software-guru/iam-client';

const iam = createIamClient({
  // Base API URL (without trailing /auth)
  apiUrl: 'https://server.com/api',

  // Storage implementation for persisting auth data (optional).
  // Defaults to LocalStorage in browser environments. Use MemoryStorage for Node.js/testing.
  storage: new MemoryStorage(),

  // System API key (sent as x-api-key header). Optional.
  // Required for /tenants/* (ROLE_SYSTEM).
  // Also accepted as an alternative to Bearer token for /users/*, /roles/*, /projects/*, /devices/*.
  // See README.md "Authentication" section for full details.
  apiKey: 'your-system-api-key'
});
```

### The `apiUrl` parameter

The URL must point to the API root (e.g. `https://server.com/api`), **not** to `/api/auth`. Each service automatically appends its own path.

### The `apiKey` parameter

The system API key grants `ROLE_SYSTEM` and is the **only** way to authenticate against `/tenants/**` endpoints. For all other endpoints (`/users/**`, `/roles/**`, `/projects/**`, `/devices/**`), you can use either the API key or a Bearer token from `iam.auth.login()`.

See the [README.md Authentication section](../README.md#authentication) for detailed scenarios and how to obtain the key.

## Entry Points

The library exposes two entry points:

| Import                                   | Contents                               |
| ---------------------------------------- | -------------------------------------- |
| `@applica-software-guru/iam-client`      | Everything: core + React Admin adapter |
| `@applica-software-guru/iam-client/core` | Core only (no React dependency)        |

```typescript
// Full import (includes React Admin adapter)
import { createIamClient, createAuthProvider } from '@applica-software-guru/iam-client';

// Core only (no React dependency)
import { createIamClient, MemoryStorage } from '@applica-software-guru/iam-client/core';
```