@dexcode/helpers
v3.1.0
Published
Helpers compartilhados entre os frontends DexCode: proxy de autenticação, PageProtected e dados do usuário do token para Next.js, cliente HTTP, utilitários de JWT, validação e máscara de CPF e CNPJ, máscaras de telefone e CEP e formatação de datas.
Readme
@dexcode/helpers
Helpers compartilhados entre os frontends DexCode.
npm install @dexcode/helperscreateProxy
Protege as rotas de um app Next.js 16+: libera rotas públicas, exige token, confere a expiração e verifica se o usuário tem acesso ao sistema.
// src/proxy.ts
import { createProxy } from "@dexcode/helpers";
export const proxy = createProxy({
typeSystemAuth: "keycloak",
system: "dexcode-system",
tokenCookieName: "access_token",
loginUrl: "/login",
publicRoutes: ["/", "/auth/*", "/produtos/*"],
});
export const config = {
matcher: ["/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp|ico)$).*)"],
};Com typeSystemAuth: "personalizado", informe sua própria regra em hasSystemAccess: (payload, system) => boolean.
Renovar a sessão (refresh token)
Com refresh, o token vencido (ou a menos de marginSeconds, padrão 30) é renovado com o refresh token do Keycloak em vez de mandar para o login. Os tokens novos vão nos cookies e já valem na própria requisição (páginas, Server Functions e gateway). O usuário só volta para o loginUrl quando a sessão do Keycloak acaba.
export const proxy = createProxy({
// ...
refresh: {
keycloakUrl: "https://sso.dexcodesystem.com",
realm: "dexcode",
clientId: "dexcode-system", // o client que emitiu o refresh token
refreshTokenCookieName: "refresh_token",
cookieDomain: ".dexcodesystem.com", // o mesmo de quem gravou o login; vazio em localhost
},
});O token é apenas decodificado; a assinatura não é validada. Valide o token de verdade no backend.
PageProtected
Server Component que só mostra a página se o usuário tiver um dos perfis. Se não tiver, redireciona no servidor para unauthorizedUrl (padrão /nao-autorizado). Sem token, ou com token expirado, redireciona para loginUrl (padrão /login). Usa next/headers, então só funciona no servidor.
// src/app/usuarios/page.tsx (Server Component)
import { PageProtected } from "@dexcode/helpers";
import { PerfilEnum } from "@/enums/PerfilEnum";
export default function UsuariosPage() {
return (
<PageProtected system="dexcode-system" perfil={[PerfilEnum.Master]}>
{/* conteúdo da página */}
</PageProtected>
);
}type="keycloak"(padrão): lê os perfis deresource_access[system].rolesdo token.systemé obrigatório. Semperfil, entra qualquer usuário com acesso ao sistema.type="custom": informe a regra emhasAccess: (payload, perfil) => boolean | Promise<boolean>.- Outras props:
tokenCookieName(padrão"access_token") eclockSkewSeconds(padrão0).
O token é apenas decodificado; a assinatura não é validada. Valide o token e o perfil de verdade no backend.
getUsuarioTokenKeycloak
Dados do usuário logado, lidos do token do Keycloak no cookie. Só no servidor (Server Components, Route Handlers, Server Actions). Retorna null sem token ou com token malformado.
import { getUsuarioTokenKeycloak } from "@dexcode/helpers";
const usuario = await getUsuarioTokenKeycloak({ tokenCookieName: "access_token" });
// {
// id: "7f3c1a52-...", // sub
// email: "[email protected]",
// nome: "Ana", // given_name
// sobrenome: "Souza", // family_name
// avatarUrl: null, // picture
// perfis: { "dexcode-system": ["Master"] } // resource_access
// }tokenCookieName: nome do cookie do token (padrão"access_token").- Com Cache Components, quem chama precisa ficar dentro de um
<Suspense>, porque lê cookies da requisição.
O token é apenas decodificado; a assinatura e a expiração não são validadas. Use os dados para mostrar na tela e deixe a proteção com o
createProxy, oPageProtectede o backend.
HttpClient e Gateway
Faz as chamadas para as APIs saírem do servidor Next.js: o browser chama /api/gateway/{service}/... no próprio app e o Gateway repassa para a API. Resolve APIs que não aceitam chamadas do browser (CORS) e mantém a URL delas fora do JavaScript do cliente.
1. URLs das APIs no .env (sem NEXT_PUBLIC_):
VIACEP_SERVICE_URL=https://viacep.com.br2. Cadastro dos serviços:
// src/config/gateway.ts
import { Gateway } from "@dexcode/helpers";
const services = {
viacep: process.env.VIACEP_SERVICE_URL,
};
export const gateway = new Gateway({ services });
// Autocomplete do "service" no HttpClient
declare module "@dexcode/helpers" {
interface GatewayRegistry {
services: typeof services;
}
}3. Rota do gateway (a pasta precisa se chamar [service], no singular):
// src/app/api/gateway/[service]/[...path]/route.ts
import { gateway } from "@/config/gateway";
const handler = gateway.handler;
export { handler as GET, handler as POST, handler as PUT, handler as PATCH, handler as DELETE };4. Uso:
import { HttpClient } from "@dexcode/helpers";
const http = new HttpClient({ service: "viacep" });
const endereco = await http.get<Endereco>({ url: "/ws/01001000/json" });
await http.post({ url: "/clientes", data: { nome: "Ana" } });- Respostas que não são 2xx lançam
HttpClientError(status,body). - O Gateway responde
404para serviço não cadastrado e502quando a API não responde. serverSide: falsefaz o browser chamar a API direto embaseUrl(só funciona se a API aceitar CORS).- O mesmo
HttpClientfunciona no servidor e no navegador (veja abaixo).
Documentação completa no site da biblioteca, em HttpClient e Gateway.
Token e servidor
- O token do usuário logado vai sozinho: o
Gateway(navegador) e oHttpClientno servidor leem o cookie do token e enviam para a API comoAuthorization: Bearer .... O cookie é o da variávelTOKEN_COOKIE_NAMEou, sem ela,access_token; outro nome vai emtokenCookieName. Oroute.tsdo gateway fica só comexport { handler as GET, ... }. - Outro token só quando precisar:
tokenna requisição (http.get({ url, token })) ouAuthorizationemconfig.headerstêm prioridade sobre o cookie. throwOnError: falsenoHttpClient: erros (e API fora do ar,503) voltam comoDefaultResponsecomvalidationResult.isValidfalse, ostatusCodee as mensagens da API, em vez de lançarHttpClientError.- Um
HttpClientpara os dois lados. O pacote entrega uma versão para cada lado pela condiçãoreact-serverdopackage.json, com o mesmo import:- no servidor (Server Components, Server Functions e route handlers): chama a API direto em
baseUrl(variável semNEXT_PUBLIC_), envia o token do usuário logado e repassa o IP e o navegador dele (forwardClientHeaders); - no navegador: passa pelo gateway; o
baseUrlfica vazio e não faz falta.
- no servidor (Server Components, Server Functions e route handlers): chama a API direto em
- Assim o mesmo service serve para a
page.tsxe para os hooks. Em Client Components, chame a API em eventos ouuseEffect, nunca no corpo do componente (no SSR a versão do navegador não chega no gateway).
import { HttpClient } from "@dexcode/helpers";
const http = new HttpClient({
service: "dexcodeservice",
baseUrl: process.env.DEXCODE_SERVICE_API_URL,
throwOnError: false,
});
const resposta = await http.get<DefaultResponse<Sistema[]>>({ url: "/api/Sistema/Usuario" });
if (!resposta.validationResult.isValid) { /* resposta.statusCode: 401, 403, 500... */ }Utilitários
decodeJwt(token): payload do JWT ounullse malformadoisTokenExpired(payload, clockSkewSeconds?): se passou doexphasKeycloakSystemAccess(payload, system): se o sistema está emresource_accessgetKeycloakSystemRoles(payload, system): perfis do usuário no sistema (resource_access[system].roles) ounullse ele não tem acessoisPublicRoute(pathname, routes): se o caminho bate com alguma rota (aceita*)
CPF
import { isValidCpf, maskCpf } from "@dexcode/helpers";
isValidCpf("529.982.247-25"); // true (aceita com ou sem máscara)
isValidCpf(undefined); // false, nunca lança erro
maskCpf("12345678909"); // "123.456.789-09"
// Formatando enquanto o usuário digita
<Input
value={cpf}
onChange={(e) => setCpf(maskCpf(e.target.value))}
maxLength={14}
inputMode="numeric"
errorMessage={cpf.length === 14 && !isValidCpf(cpf) ? "CPF inválido." : undefined}
/>isValidCpf(value): valida pelos dígitos verificadores. Vazio,null,undefined, tamanho errado ou todos os dígitos iguais retornamfalse.maskCpf(value): formata como000.000.000-00, parcial enquanto digita. Remove o que não é número e limita a 11 dígitos.
CNPJ
import { isValidCnpj, maskCnpj } from "@dexcode/helpers";
isValidCnpj("11.222.333/0001-81"); // true (aceita com ou sem máscara)
isValidCnpj("12.ABC.345/01DE-35"); // true (CNPJ alfanumérico)
isValidCnpj(undefined); // false, nunca lança erro
maskCnpj("12abc34501de35"); // "12.ABC.345/01DE-35"
<Input
value={cnpj}
onChange={(e) => setCnpj(maskCnpj(e.target.value))}
maxLength={18}
errorMessage={cnpj.length === 18 && !isValidCnpj(cnpj) ? "CNPJ inválido." : undefined}
/>isValidCnpj(value): valida pelos dígitos verificadores. Já aceita o CNPJ alfanumérico (letras nas 12 primeiras posições, emitido desde julho de 2026), em maiúsculas ou minúsculas. Vazio,null,undefined, tamanho errado ou todos os caracteres iguais retornamfalse.maskCnpj(value): formata como00.000.000/0000-00, parcial enquanto digita. Mantém dígitos e letras (em maiúsculas) e limita a 14 caracteres.
Por causa das letras, não use
inputMode="numeric"no campo de CNPJ nem guarde o CNPJ como número.
Telefone e CEP
import { maskCep, maskPhone } from "@dexcode/helpers";
maskPhone("7933036727"); // "(79) 3303-6727" (fixo)
maskPhone("79981160008"); // "(79) 98116-0008" (celular)
maskPhone("+55 79 98116-0008"); // "(79) 98116-0008" (tira o +55)
maskCep("49000000"); // "49000-000"
<Input value={telefone} onChange={(e) => setTelefone(maskPhone(e.target.value))} maxLength={15} inputMode="tel" />
<Input value={cep} onChange={(e) => setCep(maskCep(e.target.value))} maxLength={9} inputMode="numeric" />maskPhone(value): formata como(00) 0000-0000(fixo, 10 dígitos) ou(00) 00000-0000(celular, 11 dígitos), parcial enquanto digita. Remove o que não for número, tira o55do começo quando vier com código do país e limita a 11 dígitos.maskCep(value): formata como00000-000, parcial enquanto digita, e limita a 8 dígitos.
Para salvar sem máscara, use valor.replace(/\D/g, "").
Datas
import { formatDate, formatDateTime } from "@dexcode/helpers";
formatDate("2026-10-17"); // "17/10/2026"
formatDate("2026-10-18T01:30:00Z"); // "17/10/2026" (22:30 em Brasília)
formatDateTime("2026-10-17 14:30:00"); // "17/10/2026 14:30"
formatDateTime("2026-10-17T17:30:00Z"); // "17/10/2026 14:30"
formatDateTime("2026-10-17T14:30:05", { seconds: true }); // "17/10/2026 14:30:05"
formatDate(null); // ""- Aceitam texto ISO (
2026-10-17, comTou espaço, milissegundos,Zou-03:00),17/10/2026,Datee timestamp em ms. - Sem fuso (
"2026-10-17","2026-10-17 14:30"): mostra como veio, sem conversão. Evita o erro comum de"2026-10-17"virar o dia 16. - Com fuso,
Datee timestamp: converte para o horário de Brasília (America/Sao_Paulo). O resultado é o mesmo no servidor e no navegador. - Vazio ou inválido (
null,"abc", 31/02, 25:00) retorna"", sem lançar erro.
