# @vulog/aima-client

Core HTTP client with OAuth2 authentication, token caching, and request interceptors.

## Installation

```sh
npm install @vulog/aima-client
```

## Usage

```ts
import { getClient } from '@vulog/aima-client';

const client = getClient({
    fleetId: 'my-fleet',
    baseUrl: 'https://api.example.com',
    clientId: 'my-client-id',
    clientSecret: 'my-client-secret',
    apiKey: 'my-api-key',
});
```

## API Reference

### getClient

```ts
getClient(options: ClientOptions): Client
```

Factory that returns a cached Axios-based `Client`. Uses an LRU cache keyed by `options.name ?? options.fleetId`. Attaches OAuth2 token interceptors (client_credentials flow), auto-refreshes on 401 (up to 5 retries), and supports optional cURL logging.

| Parameter | Type | Description |
|-----------|------|-------------|
| `options` | `ClientOptions` | Configuration for the client instance |

Returns a `Client` (authenticated Axios instance).

## Types

### ClientOptions

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fleetId` | `string` | Yes | Fleet identifier |
| `baseUrl` | `string` | Yes | Base URL for API requests |
| `clientId` | `string` | Yes | OAuth2 client ID |
| `clientSecret` | `string` | Yes | OAuth2 client secret |
| `apiKey` | `string` | Yes | API key |
| `name` | `string` | No | Cache key override (defaults to `fleetId`) |
| `fleetMaster` | `string` | No | Realm override for token URL |
| `secure` | `boolean` | No | Enables password grant and refresh_token flow |
| `logCurl` | `boolean` | No | Logs a cURL command for each request |
| `logResponse` | `boolean` | No | Logs the full response |
| `store` | `Store` | No | Custom token storage (defaults to in-memory LRU) |
| `onLog` | `(...args: any[]) => void` | No | Custom logger function |
| `userAgent` | `string` | No | Overrides default `aima-node/{version} {fleetId}` |

### Client

Axios instance extended with:

| Member | Type | Description |
|--------|------|-------------|
| `signInWithPassword` | `(username: string, password: string) => Promise<Token>` | Password grant — only available when `secure: true` |
| `clientOptions` | `ClientOptions` | The options used to create this client |

### Token

| Field | Type |
|-------|------|
| `accessToken` | `string` |
| `refreshToken` | `string` |

### Store

Custom token storage interface.

| Method | Signature |
|--------|-----------|
| `getToken` | `() => Promise<Token \| undefined>` |
| `setToken` | `(token: Token) => Promise<void>` |

### ClientError

| Field | Type |
|-------|------|
| `formattedError` | `{ status?: any; data?: any; message?: any }` |
| `originalError` | `any` |