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.
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
Início Rápido
Basta instanciar a classe EasyAPIConsumer informando a URL base da sua API:
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.
// 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:
// 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>:
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 tipoDeviceType.getDeviceIpAddress(): Obtém o endereço IPv4 público do cliente de forma assíncrona.
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:
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:
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:
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:
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:
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:
Device-Type: ["linux"]
Os tipos suportados são definidos pelo tipo exportado DeviceType:
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.
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).