npm package: @raidstore/api-client
Description: Cliente para API
Author: RaidStore
Latest version: 0.1.1

# @raidstore/api-client

Cliente TypeScript para consumo de APIs HTTP usando Axios. Suporta `baseURL`, headers, timeout, helpers tipados (`get/post/put/patch/delete`) e tratamento de erros com `ApiError`/`ApiErrorCode`.

## Instalação

```bash
npm i @raidstore/api-client
```

## API principal

- `ApiClient` (alto nível): helpers que retornam apenas `data`, gerenciamento de auth e headers.
- `HttpClient` (baixo nível): wrapper do Axios com interceptors e normalização de erros.
- `ApiError`, `ApiErrorCode`: tipagem consistente de erros.
- `ApiClientOptions`: opções de configuração (baseURL, timeout, headers, auth etc.).

## Uso básico

```ts
import { ApiClient } from '@raidstore/api-client';

const api = new ApiClient({ baseURL: 'https://api.seuservidor.com', timeoutMs: 15000 });

// Helpers que retornam apenas `data`
const health = await api.get<{ status: string }>('/health');
```

## Autenticação (token)

```ts
import { ApiClient } from '@raidstore/api-client';

const api = new ApiClient({ baseURL: 'https://api.seuservidor.com' });

// Define o header Authorization (ex.: "Bearer <token>")
api.setAuthTokens({ accessToken: 'seu_jwt' });

// Remove o token
api.removeAuthTokens();

// Lê o token atual (se houver)
const current = api.getAuthTokens();
```

Também é possível ajustar o nome do header e o esquema via `ApiClientOptions`:

```ts
const api = new ApiClient({
  baseURL: 'https://api.seuservidor.com',
  authHeaderName: 'Authorization', // padrão
  authScheme: 'Bearer',            // padrão
});
```

## Requisições comuns

```ts
// GET com query params
const list = await api.get<{ items: string[] }>('/items', { page: 1, pageSize: 20 });

// POST/PUT/PATCH com body tipado
type CreateBody = { name: string };
type Item = { id: string; name: string };

const created = await api.post<Item, CreateBody>('/items', { name: 'Novo' });
const updated  = await api.put<Item, CreateBody>(`/items/${created.id}`, { name: 'Editado' });
const patched  = await api.patch<Item, Partial<CreateBody>>(`/items/${created.id}`, { name: 'Parcial' });

// DELETE
await api.delete<void>(`/items/${created.id}`);
```

## Tratamento de erros

```ts
import { ApiClient, ApiError, ApiErrorCode } from '@raidstore/api-client';

const api = new ApiClient({ baseURL: 'https://api.seuservidor.com' });

try {
  await api.get('/secure');
} catch (err) {
  if (err instanceof ApiError) {
    switch (err.code) {
      case ApiErrorCode.Unauthorized:
        // 401
        break;
      case ApiErrorCode.Forbidden:
        // 403
        break;
      case ApiErrorCode.NotFound:
        // 404
        break;
      case ApiErrorCode.Validation:
        // 4xx de validação
        break;
      case ApiErrorCode.Server:
        // 5xx
        break;
      case ApiErrorCode.Network:
      case ApiErrorCode.Timeout:
      default:
        break;
    }
  }
}
```

## Opções avançadas (interceptor de auth)

Você pode fornecer um header/token dinâmico para cada requisição (útil com refresh token). Passe no `ApiClientOptions` e ele será usado pelo `HttpClient` via interceptor:

```ts
import { ApiClient } from '@raidstore/api-client';

const api = new ApiClient({
  baseURL: 'https://api.seuservidor.com',
  // getAuthHeader tem precedência sobre getAuthToken + authScheme
  getAuthToken: async () => localStorage.getItem('access_token') || undefined,
  authScheme: 'Bearer',
});
```

## Ajustes em tempo de execução

```ts
// Mudar baseURL
api.setBaseURL('https://api.novo.com');

// Definir/remover headers padrão
api.setHeader('X-Feature-Flag', 'on');
api.setHeader('X-Feature-Flag', undefined); // remove
```

## Scripts

- `npm run dev`: build em watch via tsup
- `npm run build`: build ESM + CJS + d.ts
- `npm run clean`: limpa `dist/`

## Licença

MIT