open-ylorde / easy-api-consumer
npm v1.2.5 TypeScript

Easy API Consumer

Uma biblioteca Node.js moderna, limpa e tipada para facilitar requisições HTTP, autenticação por token e consumo de APIs de forma centralizada, organizada e altamente reutilizável.

O Easy API Consumer foi desenvolvido para solucionar a fragmentação comum em projetos web e Node.js: repetição de URLs base, cabeçalhos de autorização manuais, manipulação dispersa de tokens e complexidade na coleta de metadados para auditoria (como IP do cliente e tipo de dispositivo).

Cliente HTTP Fluido

Interface unificada e intuitiva para operações GET, POST, PUT, PATCH e DELETE.

Gerenciamento de Auth

Controle integrado de tokens de autenticação com métodos get, set e clear para seu fluxo seguro.

Auditoria & Dispositivo

Inclusão automática dos cabeçalhos Device-Ip-Address e Device-Type para logs e segurança da API.

TypeScript Nativo

100% tipado com interfaces declarativas para payloads, respostas e configurações de requisição.

Padrão de Camada Reutilizável: Ao centralizar as instâncias em um único módulo de serviço (como lib/api.ts), toda a sua aplicação consome endpoints de forma desacoplada e padronizada.

Instalação

Instale o pacote no seu projeto Node.js utilizando o seu gerenciador de pacotes favorito:

npm install easy-api-consumer
Compatibilidade: Suporta projetos modernos usando ECMAScript Modules (ESM) e CommonJS, tanto em ambientes Node.js quanto em frameworks full-stack como Next.js, Nuxt, Astro ou Vite.

Início Rápido

Basta instanciar a classe EasyAPIConsumer informando a URL base da sua API:

quickstart.ts
import { EasyAPIConsumer } from "easy-api-consumer";

// 1. Instancie o consumidor com a URL base da sua API
const easyApi = new EasyAPIConsumer({
  baseURL: "https://api.exemplo.com",
});

// 2. Extraia os módulos auxiliares
const { api, token } = easyApi;

// 3. Defina seu token de sessão (caso o usuário esteja logado)
token.setAuthToken("seu-jwt-token-aqui");

// 4. Faça requisições autenticadas diretamente
async function carregarPerfil() {
  const perfil = await api.get("/usuarios/eu");
  console.log("Dados recebidos:", perfil);
}

carregarPerfil();

Classe EasyAPIConsumer

A classe principal é responsável por centralizar o estado das requisições. Ao ser instanciada, ela provê quatro propriedades fundamentais:

Propriedade Tipo Finalidade
api HttpClient Cliente HTTP padrão. Aplica o token de autorização nas requisições automaticamente.
noAuth HttpClient Cliente HTTP sem autenticação. Ignora qualquer token ativo (ideal para login e cadastro).
token TokenManager Módulo para ler (getAuthToken), salvar (setAuthToken) e remover (clearAuthToken) o token da sessão.
utils UtilsManager Funções utilitárias como getDeviceType() e getDeviceIpAddress().

Cliente HTTP (api & noAuth)

O cliente HTTP fornece suporte a todos os verbos comuns do protocolo HTTP. Os métodos retornam promises tipadas com a resposta do servidor.

exemplos-requisicoes.ts
// GET com parâmetros
const posts = await api.get("/posts");

// POST com payload
const novoPost = await api.post("/posts", {
  titulo: "Novo Artigo",
  conteudo: "Conteúdo do post..."
});

// PUT (Atualização completa)
await api.put("/posts/123", { titulo: "Título Atualizado" });

// PATCH (Atualização parcial)
await api.patch("/posts/123", { visualizacoes: 42 });

// DELETE
await api.delete("/posts/123");

Usando noAuth ou a opção auth: false

Em endpoints públicos (como login de usuário ou consulta a tabelas abertas), você pode usar tanto a instância noAuth quanto passar o parâmetro auth: false nas opções da requisição:

sem-autenticacao.ts
// Forma 1: Através do objeto noAuth
const statusPublico = await noAuth.get("/publico/status");

// Forma 2: Através da opção { auth: false } no cliente api padrão
const loginResult = await api.post("/auth/login", credenciais, {
  auth: false,
});

Gerenciamento de Token (token)

O módulo token permite manipular a credencial de autorização que será injetada no cabeçalho Authorization: Bearer <token>:

token-manager.ts
const { getAuthToken, setAuthToken, clearAuthToken } = easyApi.token;

// 1. Salva o token recebido no login
setAuthToken("eyJhbGciOiJIUzI1NiIsInR5...");

// 2. Recupera o token atual da memória/sessão
const tokenAtual = getAuthToken();
console.log(tokenAtual);

// 3. Limpa o token no logout
clearAuthToken();

Utilitários de Dispositivo (utils)

O Easy API Consumer traz utilitários integrados para identificação de contexto do cliente, facilitando a coleta de telemetria e segurança:

  • getDeviceType(): Identifica o sistema operacional / plataforma do cliente. Retorna uma das opções do tipo DeviceType.
  • getDeviceIpAddress(): Obtém o endereço IPv4 público do cliente de forma assíncrona.
utils-example.ts
const { getDeviceType, getDeviceIpAddress } = easyApi.utils;

// Exemplo de retorno: "windows" | "linux" | "macos" | "android" | "ios" | "unknown"
const dispositivo = getDeviceType();
console.log("Dispositivo atual:", dispositivo);

// Exemplo de retorno: "203.0.113.195"
const ip = await getDeviceIpAddress();
console.log("IP do cliente:", ip);

Guia de Arquitetura Passo a Passo

Veja como estruturar uma aplicação real com TypeScript, separando contratos (interfaces), configuração central e serviços de endpoints.

1. Definindo as Interfaces de Requisição

Crie os tipos dos corpos de requisição e dados esperados:

interfaces/ILogin.ts
export interface ILoginBody {
  email: string;
  password: string;
}

export interface IRegisterBody {
  username: string;
  email: string;
  password: string;
}

2. Configuração do Cliente Central

Inicialize o EasyAPIConsumer em um módulo isolado e exporte apenas o necessário:

lib/api.ts
import { EasyAPIConsumer } from "easy-api-consumer";

const easyApi = new EasyAPIConsumer({
  baseURL: "https://api.seusite.com.br",
});

const { api, noAuth, utils, token } = easyApi;
const { getDeviceType, getDeviceIpAddress } = utils;
const { getAuthToken, setAuthToken, clearAuthToken } = token;

export {
  api,
  noAuth,
  getAuthToken,
  setAuthToken,
  clearAuthToken,
  getDeviceType,
  getDeviceIpAddress,
};

3. Criando a Camada de Endpoints

Agrupe as rotas da API por domínio ou funcionalidade, aproveitando os metadados de IP e dispositivo:

lib/endpoints/auth.ts
import { api } from "../api";
import type { ILoginBody, IRegisterBody } from "@/interfaces/ILogin";

export const authApi = {
  login: (body: ILoginBody) =>
    api.post("/auth/login", body, {
      includesDeviceIpAddress: true,
      includesDeviceType: true,
      auth: false,
    }),

  register: (body: IRegisterBody) =>
    api.post("/auth/register", body, {
      auth: false,
    }),

  me: () =>
    api.get("/auth/me", {
      includesDeviceIpAddress: true,
    }),

  logout: () =>
    api.post("/auth/logout", {}, {
      includesDeviceIpAddress: true,
    }),
};

4. Consumindo na Aplicação

No seu componente, hook ou serviço de aplicação, basta importar o endpoint e disparar a ação:

exemplo-consumo.ts
import { authApi } from "@/lib/endpoints/auth";
import { setAuthToken } from "@/lib/api";

const handleLogin = async () => {
  try {
    const response = await authApi.login({
      email: "usuario@exemplo.com",
      password: "minhasenhasecreta",
    });

    // Salva o token retornado pela API
    setAuthToken(response.data.token);
    console.log("Login efetuado com sucesso!");
  } catch (erro) {
    console.error("Falha ao realizar login:", erro);
  }
};

Headers de Auditoria & Contexto

O Easy API Consumer inclui recursos para enriquecer suas requisições com dados de contexto do cliente:

includesDeviceIpAddress?: boolean

Determina se o endereço IPv4 do cliente deve ser incluído nos cabeçalhos da requisição HTTP. Quando ativado com true, o IP é injetado no cabeçalho:

Header HTTP
Device-Ip-Address: 192.0.2.1

includesDeviceType?: boolean

Quando ativado, identifica o tipo de sistema/dispositivo do cliente e o envia no cabeçalho Device-Type:

Header HTTP
Device-Type: ["linux"]

Os tipos suportados são definidos pelo tipo exportado DeviceType:

types.ts
export type DeviceType =
  | "android"
  | "ios"
  | "windows"
  | "macos"
  | "linux"
  | "unknown";

Referência da API

Método / Opção Parâmetros Retorno Descrição
new EasyAPIConsumer(config) { baseURL: string } EasyAPIConsumer Instancia o gerenciador de conexões com a URL base especificada.
api.get(url, options?) url: string, options?: RequestConfig Promise<T> Executa requisição GET autenticada.
api.post(url, data?, options?) url: string, data?: any, options?: RequestConfig Promise<T> Executa requisição POST com payload serializado em JSON.
api.put(url, data?, options?) url: string, data?: any, options?: RequestConfig Promise<T> Executa requisição PUT completa.
api.patch(url, data?, options?) url: string, data?: any, options?: RequestConfig Promise<T> Executa requisição PATCH de atualização parcial.
api.delete(url, options?) url: string, options?: RequestConfig Promise<T> Executa requisição DELETE de exclusão.
token.setAuthToken(token) token: string void Armazena a chave de autenticação para as próximas chamadas.
token.getAuthToken() string | null Retorna o token atualmente carregado na sessão.
token.clearAuthToken() void Remove o token ativo, desautenticando as chamadas subsequentes.
utils.getDeviceType() DeviceType Retorna o sistema operacional do ambiente de execução.
utils.getDeviceIpAddress() Promise<string> Resolve o endereço IPv4 público do cliente.

Licença & Créditos

Este projeto é software livre licenciado sob os termos da licença GPL-3.0-only.

Atribuição de Créditos: A implementação de request.ts foi adaptada a partir de código originalmente concebido por SorPuti, adaptado e estendido para o ecossistema do easy-api-consumer por Davi de Sousa (yLorde).

Copyright © 2026 Davi de Sousa (yLorde).