@rhizzalab/report-node

Client Node do backend do host para a Report Platform: troca a credencial da sua empresa (clientId/clientSecret) por um editor token temporário (TTL ≤ 15 min, sem refresh token), que o seu frontend entrega ao widget @rhizzalab/report-react.

O secret nunca vai ao navegador — use este pacote apenas no servidor. A troca é servidor-a-servidor por construção: o endpoint não responde a CORS de navegador. Quem decide userId, workspaceId e escopos é o SEU backend, a partir da sessão autenticada do seu sistema — nunca o browser.

• Node ≥ 18 (usa o fetch global), ESM + CJS, tipos incluídos.
• Zero dependências de runtime.
• Sem estado e sem cache: renovar o token = chamar de novo.

Instalação

npm install @rhizzalab/report-node

Uso

import { createReportPlatformClient, isReportNodeError } from "@rhizzalab/report-node";

const client = createReportPlatformClient({
  clientId: process.env.RP_CLIENT_ID!,
  clientSecret: process.env.RP_CLIENT_SECRET!,
  // apiBaseUrl?  — default: API de produção (DEFAULT_API_BASE_URL)
  // fetch?, timeoutMs? — injetáveis (default: fetch global / 10 s)
});

const { accessToken, tokenType, expiresIn } = await client.issueEditorToken({
  userId: "usuario-42", // o id do usuário NO SEU sistema
  workspaceId: "obra-7", // opcional — identificação/medição (ADR 0048), nunca autorização
  reports: [{ reportType: "maiscontrole.proposal", scopes: ["editor:read"] }],
});

• apiBaseUrl omitido → API de produção (DEFAULT_API_BASE_URL, reexportada pelo pacote). Apontando para outro ambiente (dev local, staging, self-hosted), passe a URL explicitamente; string vazia ou em branco é TypeError — configuração errada falha alto, nunca cai em fallback silencioso. Barra final é normalizada.
• workspaceId é o identificador, no seu sistema, da conta/obra/projeto/ equipe em que o usuário está trabalhando. Serve para identificação e medição (auditoria, página "Uso", correlação de logs) — não muda escopos nem autoriza nada (ADR 0048).
• Peça o mínimo de escopos que a tela precisa; a lista fechada está em SCOPES (reexportada pelo pacote).
• O pedido é validado antes da rede (espelho estrutural do contrato: userId/workspaceId com 1..255 caracteres, reports não vazio, escopos da lista fechada) — erro estrutural não gasta round-trip.
• console.log(client), JSON.stringify(client) e util.inspect(client) nunca expõem o clientSecret; mensagens de erro são redigidas defensivamente (o secret e o header Basic nunca aparecem).

Erros

Toda falha é um ReportNodeError (com type guard isReportNodeError):

| kind | Quando | Campos extras | | ------------ | -------------------------------------------------------------------- | --------------------------------------- | | validation | o pedido falhou a validação estrutural local, antes da rede | issues: [{ path, message }] | | api | a API respondeu não-2xx | code, status, requestId, issues | | network | falha de rede ou timeout (a mensagem indica quando foi timeout) | — | | contract | a API respondeu 2xx com corpo fora do contrato EditorTokenResponse | — |

try {
  await client.issueEditorToken(request);
} catch (error) {
  if (isReportNodeError(error) && error.kind === "api" && error.status === 401) {
    // credencial recusada — confira clientId/clientSecret
  }
  throw error;
}

Referência do protocolo

O pacote encapsula POST /v1/auth/editor-tokens com Authorization: Basic base64(clientId:clientSecret). O protocolo de fio (curl/fetch cru) continua documentado no guia de integração da plataforma — este client é o caminho curto, não um contrato novo.