@raidstore/api-client

Client para consumo de API baseado em Axios. Suporta baseURL, headers, timeout, helpers tipados (get/post/put/patch/delete) e tratamento de erros com ApiError/ApiErrorCode.

Instalação

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

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)

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:

const api = new ApiClient({
  baseURL: 'https://api.seuservidor.com',
  authHeaderName: 'Authorization', // padrão
  authScheme: 'Bearer',            // padrão
});

Requisições comuns

// 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

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:

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

// 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