lhisp-oauth-client

Bilingual README (Português / English) for the lhisp-oauth-client library.

• Português (PT-BR)
• English

Português (PT-BR)

Cliente HTTP simples para consumir uma API protegida por OAuth2 (Client Credentials), cuidando automaticamente de:

• Obter o access_token no endpoint de autenticação
• Cache do token até expirar (com margem de ~10s)
• Enviar o token nas requisições subsequentes para a API
• Suporte opcional a certificado cliente (PFX) via https.Agent

Observação: refresh token ainda não está implementado (há um TODO no código). Quando o token expira, um novo token é solicitado.

Instalação

npm i lhisp-oauth-client
# ou
yarn add lhisp-oauth-client

Uso rápido

import { LhispOauthClient } from "lhisp-oauth-client";

const client = new LhispOauthClient({
  apiUrl: "https://api.exemplo.com",
  authUrl: "https://auth.exemplo.com/oauth/token",
  clientId: "SEU_CLIENT_ID",
  clientSecret: "SEU_CLIENT_SECRET",
});

type StatusResponse = { status: string };

async function main() {
  const resp = await client.get<StatusResponse>({
    path: "/status",
    params: { verbose: true },
  });

  console.log(resp.status);
}

main();

API (principais métodos)

• getAccessToken(): Promise<AccessToken>
  • Obtém e cacheia o token.
• getAuthToken(): string
  • Retorna o header final de autorização (por padrão "<token_type> <access_token>").
• executarRequest<ResponseType>(params): Promise<ResponseType>
  • Método base que injeta token e executa request via Axios.
• Atalhos HTTP:
  • get, post, put, patch, delete

Parâmetros do construtor

new LhispOauthClient(params) aceita:

• apiUrl (string, obrigatório): URL base da API (ex.: https://api.exemplo.com)
• authUrl (string, obrigatório): endpoint OAuth2 para obter token
• clientId (string, obrigatório)
• clientSecret (string, obrigatório)

Opcionalmente:

• certificado (string | Buffer): certificado cliente PFX
  • Se for string, o código assume base64 e faz Buffer.from(certificado, "base64")
• senhaCertificado (string): senha do PFX
• authScope (string): adiciona scope no request de token
• grantType (string): padrão client_credentials
• authContentType (ContentType): padrão application/x-www-form-urlencoded
• authData (Record<string,string>): campos extras enviados ao endpoint de token
• headers (object): headers aplicados nas requisições para a API
• authHeaders (object): headers extras somente na obtenção do token
• authHeaderName (string): nome do header usado para credenciais Basic (padrão Authorization)
• tokenHeaderName (string): nome do header onde o token é enviado (padrão Authorization)
• sendAuthCredentialsOnRequestBody (boolean): envia client_id e client_secret também no body
• formatAccessToken ((token?) => string): personaliza o valor enviado no header do token
• timeout (number): timeout das requisições (ms). Padrão 60000
• logger (Logger): logger compatível (com .child() + métodos info/warn/error/debug)

Content-Type

Você pode escolher o Content-Type das requisições para API via contentType:

import { ContentType } from "lhisp-oauth-client";

await client.post({
  path: "/clientes",
  contentType: ContentType.APPLICATION_JSON,
  data: { name: "Maria" },
});

Nota: o contentType de autenticação (request do token) é controlado por authContentType.

Exemplo: credenciais no body (alguns servidores exigem)

import { LhispOauthClient, ContentType } from "lhisp-oauth-client";

const client = new LhispOauthClient({
  apiUrl: "https://api.exemplo.com",
  authUrl: "https://auth.exemplo.com/oauth/token",
  clientId: "SEU_CLIENT_ID",
  clientSecret: "SEU_CLIENT_SECRET",
  authContentType: ContentType.APPLICATION_JSON,
  sendAuthCredentialsOnRequestBody: true,
});

await client.get({ path: "/status" });

Exemplo: header de token customizado

import { LhispOauthClient } from "lhisp-oauth-client";

const client = new LhispOauthClient({
  apiUrl: "https://api.exemplo.com",
  authUrl: "https://auth.exemplo.com/oauth/token",
  clientId: "SEU_CLIENT_ID",
  clientSecret: "SEU_CLIENT_SECRET",
  tokenHeaderName: "x-token",
});

await client.get({ path: "/status" });

Exemplo: usando certificado (PFX)

import fs from "node:fs";
import { LhispOauthClient } from "lhisp-oauth-client";

const pfxBuffer = fs.readFileSync("./certificado.pfx");

const client = new LhispOauthClient({
  apiUrl: "https://api.exemplo.com",
  authUrl: "https://auth.exemplo.com/oauth/token",
  clientId: "SEU_CLIENT_ID",
  clientSecret: "SEU_CLIENT_SECRET",
  certificado: pfxBuffer,
  senhaCertificado: "SENHA_DO_PFX",
});

await client.get({ path: "/status" });

English

A lightweight HTTP client to consume an API protected by OAuth2 (Client Credentials). It automatically:

• Fetches an access_token from the auth endpoint
• Caches the token until it expires (with a ~10s safety margin)
• Sends the token on subsequent API requests
• Optionally supports client certificate (PFX) via https.Agent

Note: refresh token is not implemented yet (there is a TODO in the code). When the token expires, a new token is requested.

Install

npm i lhisp-oauth-client
# or
yarn add lhisp-oauth-client

Quick start

import { LhispOauthClient } from "lhisp-oauth-client";

const client = new LhispOauthClient({
  apiUrl: "https://api.example.com",
  authUrl: "https://auth.example.com/oauth/token",
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
});

type StatusResponse = { status: string };

async function main() {
  const resp = await client.get<StatusResponse>({
    path: "/status",
    params: { verbose: true },
  });

  console.log(resp.status);
}

main();

API (main methods)

• getAccessToken(): Promise<AccessToken>
  • Fetches and caches the token.
• getAuthToken(): string
  • Returns the final auth header value (by default "<token_type> <access_token>").
• executarRequest<ResponseType>(params): Promise<ResponseType>
  • Base method that injects the token and performs the request via Axios.
• HTTP helpers:
  • get, post, put, patch, delete

Constructor parameters

new LhispOauthClient(params) accepts:

Required:

• apiUrl (string): API base URL (e.g. https://api.example.com)
• authUrl (string): OAuth2 token endpoint
• clientId (string)
• clientSecret (string)

Optional:

• certificado (string | Buffer): PFX client certificate
  • If string, it is treated as base64 and converted using Buffer.from(certificado, "base64")
• senhaCertificado (string): PFX password
• authScope (string): adds scope to the token request
• grantType (string): default client_credentials
• authContentType (ContentType): default application/x-www-form-urlencoded
• authData (Record<string,string>): extra fields sent to the token endpoint
• headers (object): headers applied to API calls
• authHeaders (object): extra headers only for token retrieval
• authHeaderName (string): Basic credentials header name (default Authorization)
• tokenHeaderName (string): token header name (default Authorization)
• sendAuthCredentialsOnRequestBody (boolean): also sends client_id and client_secret in the request body
• formatAccessToken ((token?) => string): customize token header value
• timeout (number): request timeout in ms (default 60000)
• logger (Logger): compatible logger (must support .child() and info/warn/error/debug)

Content-Type

You can set the API request Content-Type using contentType:

import { ContentType } from "lhisp-oauth-client";

await client.post({
  path: "/customers",
  contentType: ContentType.APPLICATION_JSON,
  data: { name: "Alice" },
});

Note: the auth/token request content type is controlled by authContentType.

Example: credentials in request body

import { LhispOauthClient, ContentType } from "lhisp-oauth-client";

const client = new LhispOauthClient({
  apiUrl: "https://api.example.com",
  authUrl: "https://auth.example.com/oauth/token",
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
  authContentType: ContentType.APPLICATION_JSON,
  sendAuthCredentialsOnRequestBody: true,
});

await client.get({ path: "/status" });

Example: custom token header

import { LhispOauthClient } from "lhisp-oauth-client";

const client = new LhispOauthClient({
  apiUrl: "https://api.example.com",
  authUrl: "https://auth.example.com/oauth/token",
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
  tokenHeaderName: "x-token",
});

await client.get({ path: "/status" });

Example: using a PFX certificate

import fs from "node:fs";
import { LhispOauthClient } from "lhisp-oauth-client";

const pfxBuffer = fs.readFileSync("./certificate.pfx");

const client = new LhispOauthClient({
  apiUrl: "https://api.example.com",
  authUrl: "https://auth.example.com/oauth/token",
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
  certificado: pfxBuffer,
  senhaCertificado: "PFX_PASSWORD",
});

await client.get({ path: "/status" });