@radardata/sdk 0.0.0-stage → 0.1.0

package/dist/esm/webhooks/assinatura.js

@@ -0,0 +1,61 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * Confere que o webhook veio mesmo do RadarData.
+ *
+ * Mandamos `X-RadarData-Signature: sha256=<hmac do CORPO CRU com o seu
+ * webhook_secret>`, mais `X-RadarData-Event`, `X-RadarData-Delivery` e
+ * `X-RadarData-Timestamp`.
+ *
+ * Aceita `string` ou `Uint8Array`, e nao `Buffer`, de proposito: `Buffer` e um
+ * global do Node e poria `@types/node` na superficie publica do pacote, o que
+ * quebra o `tsc` de quem compila para borda, Deno ou navegador. `Buffer` E um
+ * `Uint8Array`, entao o que o `express.raw()` entrega continua servindo.
+ *
+ * O CORPO TEM DE SER O CRU. Em Express e `express.raw()`, nao `express.json()`;
+ * reserializar o objeto ja decodificado muda espaco e ordem de chave, o HMAC
+ * muda junto e a conferencia falha sem motivo aparente. E o erro mais comum
+ * nesta parte, em qualquer integracao.
+ *
+ * LIMITE QUE VOCE PRECISA CONHECER: o timestamp e o id de entrega viajam em
+ * CABECALHO, fora do corpo assinado, entao a assinatura prova a ORIGEM e o
+ * CONTEUDO, e nao a hora. Ela nao protege contra reenvio de um aviso antigo e
+ * autentico por quem o tenha interceptado. A defesa pratica e guardar o
+ * `X-RadarData-Delivery` e ignorar o que ja foi processado, que voce deve
+ * fazer de qualquer forma, porque reenviamos em caso de falha.
+ */
+export function confereAssinatura(corpoCru, assinatura, segredo) {
+    if (!assinatura || !segredo)
+        return false;
+    const esperada = `sha256=${createHmac("sha256", segredo).update(corpoCru).digest("hex")}`;
+    const a = Buffer.from(esperada, "utf8");
+    const b = Buffer.from(assinatura, "utf8");
+    // `timingSafeEqual` exige tamanhos iguais e lança quando diferem; comparar
+    // o tamanho antes não vaza nada, porque o tamanho da assinatura é fixo e
+    // público.
+    if (a.length !== b.length)
+        return false;
+    // E não `===`: comparação normal vaza, pelo tempo que leva, quantos bytes
+    // iniciais bateram, e com isso dá para descobrir a assinatura byte a byte.
+    return timingSafeEqual(a, b);
+}
+/**
+ * Confere e devolve o evento decodificado, ou lança.
+ *
+ * @throws Error quando a assinatura nao confere
+ */
+export function exigirAssinatura(corpoCru, assinatura, segredo) {
+    if (!confereAssinatura(corpoCru, assinatura, segredo)) {
+        throw new Error("Assinatura do webhook do RadarData não confere.");
+    }
+    try {
+        // `TextDecoder` e nao `Buffer.toString`: existe em Node, em navegador, em
+        // Deno e em Bun, e nao arrasta os tipos do Node para a superficie publica.
+        const texto = typeof corpoCru === "string" ? corpoCru : new TextDecoder().decode(corpoCru);
+        const dados = JSON.parse(texto);
+        return dados && typeof dados === "object" ? dados : {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=assinatura.js.map

package/dist/esm/webhooks/assinatura.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assinatura.js","sourceRoot":"","sources":["../../../src/webhooks/assinatura.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAA6B,EAC7B,UAAqC,EACrC,OAAe;IAEf,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAE1C,MAAM,QAAQ,GAAG,UAAU,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAE1F,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;IAE1C,2EAA2E;IAC3E,yEAAyE;IACzE,WAAW;IACX,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAExC,0EAA0E;IAC1E,2EAA2E;IAC3E,OAAO,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAA6B,EAC7B,UAAqC,EACrC,OAAe;IAEf,IAAI,CAAC,iBAAiB,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IAED,IAAI,CAAC;QACH,0EAA0E;QAC1E,2EAA2E;QAC3E,MAAM,KAAK,GAAG,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC3F,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChC,OAAO,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAE,KAAiC,CAAC,CAAC,CAAC,EAAE,CAAC;IACtF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@radardata/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "SDK oficial do RadarData para Node e TypeScript: consultas, Verify, Motor de Analises e webhooks.",
+  "license": "MIT",
+  "homepage": "https://radardata.com.br",
+  "keywords": [
+    "radardata",
+    "kyc",
+    "verify",
+    "consultas",
+    "serpro",
+    "typescript"
+  ],
+  "author": "RadarData",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}))\"",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/src/configuracao.ts

@@ -0,0 +1,50 @@
+/** O que o SDK precisa saber para falar com o RadarData. */
+export interface Configuracao {
+  /** Token de API da empresa, criado no painel. Nunca o de sessao do painel. */
+  token: string;
+  /** Base da api. Trocavel para apontar o SDK a um ambiente seu. */
+  base?: string;
+  /** Milissegundos de espera por resposta. */
+  timeoutMs?: number;
+  /**
+   * Tentativas em chamada IDEMPOTENTE. Vale so onde o SDK manda
+   * `Idempotency-Key`; onde nao manda, repetir criaria cobranca nova e o SDK
+   * nao repete, qualquer que seja este numero.
+   */
+  tentativas?: number;
+  /** Para teste: um `fetch` seu no lugar do global. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export const VERSAO = "0.1.0";
+
+/** @internal */
+export interface ConfigResolvida extends Required<Omit<Configuracao, "fetch">> {
+  fetch: typeof globalThis.fetch;
+}
+
+/** @internal */
+export function resolver(c: Configuracao): ConfigResolvida {
+  if (!c.token) throw new Error("RadarData: token de API é obrigatório.");
+
+  const buscar = c.fetch ?? globalThis.fetch;
+  if (typeof buscar !== "function") {
+    throw new Error(
+      "RadarData: `fetch` não existe neste runtime. Use Node 18 ou mais novo, ou passe um `fetch` na configuração.",
+    );
+  }
+
+  return {
+    token: c.token,
+    base: (c.base ?? "https://api.radardata.com.br/api/v2").replace(/\/+$/, ""),
+    timeoutMs: c.timeoutMs ?? 30_000,
+    tentativas: c.tentativas ?? 3,
+    fetch: buscar,
+  };
+}
+
+/** @internal */
+export function userAgent(): string {
+  const v = typeof process !== "undefined" ? process.versions?.node : undefined;
+  return `radardata-sdk-node/${VERSAO}${v ? ` node/${v}` : ""}`;
+}

package/src/dados.ts

@@ -0,0 +1,93 @@
+/** Tipos do que a api devolve, onde tipar compensa. */
+
+/**
+ * Saldo da conta, em CENTAVOS.
+ *
+ * Centavo inteiro, nunca float: o sistema inteiro guarda dinheiro assim, e
+ * converter para ponto flutuante aqui reintroduziria o erro de
+ * arredondamento que o inteiro existe para evitar.
+ */
+export interface Saldo {
+  readonly centavos: number;
+  /** O que da para gastar agora: desconta o que ja esta reservado. */
+  readonly disponivelCentavos: number;
+  /** PRE (saldo) ou POS (fatura). */
+  readonly modoCobranca: string;
+}
+
+/**
+ * Um servico do catalogo, com o preco DAQUELA conta.
+ *
+ * O preco vem resolvido por empresa: duas contas podem ver precos diferentes
+ * para o mesmo slug, e por isso ele nao e constante no SDK.
+ */
+export interface Servico {
+  readonly slug: string;
+  readonly nome: string;
+  readonly categoria: string | null;
+  readonly descricao: string | null;
+  /** CPF, CNPJ, PLACA... o que a consulta espera receber. */
+  readonly tipoDocumento: string | null;
+  readonly precoCentavos: number;
+}
+
+/**
+ * Uma sessao de Verify.
+ *
+ * `url` so vem na CRIACAO: e o link que voce manda para a pessoa. Depois
+ * disso a consulta devolve estado e resultado, e nao o link de novo.
+ */
+export interface SessaoVerify {
+  readonly id: string;
+  /** pending, in_progress, completed, expired, canceled. */
+  readonly status: string;
+  readonly url: string | null;
+  /** APROVADO, REPROVADO, REVISAO_MANUAL; null enquanto nao concluiu. */
+  readonly resultado: string | null;
+  readonly expiraEm: string | null;
+  readonly referenceId: string | null;
+  /** Quanto este run custou para voce, em centavos. */
+  readonly custoCentavos: number;
+  /** O corpo cru, para o que o SDK nao tipou. */
+  readonly cru: Record<string, unknown>;
+}
+
+/** @internal */
+export function paraSaldo(d: Record<string, unknown>): Saldo {
+  return {
+    centavos: Number(d.saldo ?? 0),
+    disponivelCentavos: Number(d.saldo_disponivel ?? 0),
+    modoCobranca: String(d.modo_cobranca ?? ""),
+  };
+}
+
+/** @internal */
+export function paraServico(d: Record<string, unknown>): Servico {
+  return {
+    slug: String(d.slug ?? ""),
+    nome: String(d.nome ?? ""),
+    categoria: (d.categoria as string | null) ?? null,
+    descricao: (d.descricao as string | null) ?? null,
+    tipoDocumento: (d.tipo_documento as string | null) ?? null,
+    precoCentavos: Number(d.preco ?? 0),
+  };
+}
+
+/** @internal */
+export function paraSessao(d: Record<string, unknown>): SessaoVerify {
+  return {
+    id: String(d.session_id ?? ""),
+    status: String(d.status ?? ""),
+    url: (d.url as string | null) ?? null,
+    resultado: (d.outcome as string | null) ?? null,
+    expiraEm: (d.expires_at as string | null) ?? null,
+    referenceId: (d.reference_id as string | null) ?? null,
+    custoCentavos: Number(d.custo_total_centavos ?? 0),
+    cru: d,
+  };
+}
+
+/** Em reais, para exibir. O calculo continua em centavos. */
+export function emReais(centavos: number): string {
+  return (centavos / 100).toLocaleString("pt-BR", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+}

package/src/erros.ts

@@ -0,0 +1,70 @@
+/**
+ * Erros do SDK, um por situacao.
+ *
+ * A api devolve sempre `{"error": {"code": "...", "message": "..."}}`, e o
+ * `code` e o que vale para decidir no codigo: a `message` e escrita para
+ * pessoa e muda. Por isso ele fica acessivel aqui, e cada classe existe para
+ * um `catch` especifico, em vez de obrigar quem integra a comparar strings.
+ */
+export class ErroRadarData extends Error {
+  constructor(
+    mensagem: string,
+    readonly codigo: string | null = null,
+    readonly status: number | null = null,
+    /** O corpo cru, para quando o SDK nao previu algo. */
+    readonly corpo: Record<string, unknown> = {},
+    opcoes?: { cause?: unknown },
+  ) {
+    super(mensagem, opcoes);
+    this.name = new.target.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/** 401, token ausente, invalido ou revogado. */
+export class NaoAutenticado extends ErroRadarData {}
+
+/** 402, a conta nao tem saldo para esta operacao. */
+export class SaldoInsuficiente extends ErroRadarData {}
+
+/** 403, o token existe mas nao tem o escopo daquela rota. */
+export class SemEscopo extends ErroRadarData {}
+
+/** 404, recurso inexistente ou de outra empresa. */
+export class NaoEncontrado extends ErroRadarData {}
+
+/** 422, o que foi enviado nao passou na validacao. Veja `corpo`. */
+export class EntradaInvalida extends ErroRadarData {}
+
+/** 429, teto de chamadas atingido. */
+export class MuitasTentativas extends ErroRadarData {}
+
+/** 5xx, falha nossa. */
+export class ErroDoServidor extends ErroRadarData {}
+
+/**
+ * Nao houve resposta: timeout, DNS, conexao recusada.
+ *
+ * Separado dos erros com status de proposito: aqui o SDK NAO SABE se a
+ * operacao aconteceu. Numa chamada que gasta saldo isso importa, e o jeito de
+ * descobrir e consultar pela mesma chave de idempotencia, nao repetir as
+ * cegas.
+ */
+export class FalhaDeRede extends ErroRadarData {}
+
+/** @internal */
+export function erroDoStatus(
+  status: number,
+  mensagem: string,
+  codigo: string | null,
+  corpo: Record<string, unknown>,
+): ErroRadarData {
+  if (status === 401) return new NaoAutenticado(mensagem, codigo, status, corpo);
+  if (status === 402) return new SaldoInsuficiente(mensagem, codigo, status, corpo);
+  if (status === 403) return new SemEscopo(mensagem, codigo, status, corpo);
+  if (status === 404) return new NaoEncontrado(mensagem, codigo, status, corpo);
+  if (status === 422) return new EntradaInvalida(mensagem, codigo, status, corpo);
+  if (status === 429) return new MuitasTentativas(mensagem, codigo, status, corpo);
+  if (status >= 500) return new ErroDoServidor(mensagem, codigo, status, corpo);
+  return new ErroRadarData(mensagem, codigo, status, corpo);
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+import { type Configuracao, resolver } from "./configuracao.js";
+import { Analises } from "./recursos/analises.js";
+import { Catalogo } from "./recursos/catalogo.js";
+import { Consultas } from "./recursos/consultas.js";
+import { Verify } from "./recursos/verify.js";
+import { Webhooks } from "./recursos/webhooks.js";
+import { Transporte } from "./transporte.js";
+
+/**
+ * Ponto de entrada do SDK.
+ *
+ * ```ts
+ * import { RadarData } from "@radardata/sdk";
+ *
+ * const radar = new RadarData({ token: process.env.RADARDATA_TOKEN! });
+ * const saldo = await radar.catalogo.saldo();
+ * ```
+ *
+ * O token e o de API, criado no painel, e NAO o de sessao do painel. Ele
+ * carrega escopos: uma chamada fora do escopo do token volta `SemEscopo`, e
+ * isso e proposital, para um token de servidor nao poder redirecionar os seus
+ * webhooks.
+ */
+export class RadarData {
+  readonly catalogo: Catalogo;
+
+  readonly consultas: Consultas;
+
+  readonly verify: Verify;
+
+  readonly analises: Analises;
+
+  readonly webhooks: Webhooks;
+
+  constructor(config: Configuracao) {
+    const t = new Transporte(resolver(config));
+
+    this.catalogo = new Catalogo(t);
+    this.consultas = new Consultas(t);
+    this.verify = new Verify(t);
+    this.analises = new Analises(t);
+    this.webhooks = new Webhooks(t);
+  }
+}
+
+export { chaveIdempotencia } from "./transporte.js";
+export { confereAssinatura, exigirAssinatura } from "./webhooks/assinatura.js";
+export { emReais } from "./dados.js";
+export type { Configuracao } from "./configuracao.js";
+export type { Saldo, Servico, SessaoVerify } from "./dados.js";
+export {
+  EntradaInvalida,
+  ErroDoServidor,
+  ErroRadarData,
+  FalhaDeRede,
+  MuitasTentativas,
+  NaoAutenticado,
+  NaoEncontrado,
+  SaldoInsuficiente,
+  SemEscopo,
+} from "./erros.js";
+export { Analises } from "./recursos/analises.js";
+export { Catalogo } from "./recursos/catalogo.js";
+export { Consultas } from "./recursos/consultas.js";
+export { Verify } from "./recursos/verify.js";
+export { Webhooks } from "./recursos/webhooks.js";

package/src/recursos/analises.ts

@@ -0,0 +1,61 @@
+import { type Transporte, chaveIdempotencia } from "../transporte.js";
+
+/**
+ * Motor de Analises. Escopo `analises`. GASTA SALDO.
+ *
+ * E ASSINCRONO: criar devolve o id e o resultado chega por webhook. Consultar
+ * em laco funciona, mas o webhook e o caminho previsto; veja
+ * `confereAssinatura` para conferir que o aviso e nosso.
+ *
+ * Um 404 aqui pode querer dizer "o Motor nao esta liberado para a sua conta",
+ * e nao "caminho errado": enquanto ele nao esta liberado, nada dele aparece
+ * para o cliente, de proposito.
+ */
+export class Analises {
+  constructor(private readonly t: Transporte) {}
+
+  /** Produtos liberados para esta conta. */
+  async produtos(): Promise<Record<string, unknown>[]> {
+    return this.t.pedir<Record<string, unknown>[]>("GET", "analises/produtos");
+  }
+
+  async criar(
+    slug: string,
+    campos: Record<string, unknown>,
+    opcoes: Record<string, unknown> = {},
+    chave?: string,
+  ): Promise<Record<string, unknown>> {
+    return this.t.pedir("POST", `analises/${encodeURIComponent(slug)}`, {
+      corpo: { campos, ...opcoes },
+      chaveIdempotencia: chave ?? chaveIdempotencia(),
+    });
+  }
+
+  async mostrar(id: string): Promise<Record<string, unknown>> {
+    return this.t.pedir("GET", `analises/${encodeURIComponent(id)}`);
+  }
+
+  async decidir(id: string, decisao: string, motivo?: string): Promise<Record<string, unknown>> {
+    const corpo: Record<string, unknown> = { decisao };
+    if (motivo !== undefined) corpo.motivo = motivo;
+    return this.t.pedir("POST", `analises/${encodeURIComponent(id)}/decisao`, { corpo });
+  }
+
+  async monitorar(
+    slug: string,
+    campos: Record<string, unknown>,
+    opcoes: Record<string, unknown> = {},
+  ): Promise<Record<string, unknown>> {
+    return this.t.pedir("POST", `analises/monitorar/${encodeURIComponent(slug)}`, {
+      corpo: { campos, ...opcoes },
+    });
+  }
+
+  async monitoramentos(): Promise<Record<string, unknown>[]> {
+    return this.t.pedir<Record<string, unknown>[]>("GET", "analises/monitoramentos");
+  }
+
+  async cancelarMonitoramento(id: string): Promise<Record<string, unknown>> {
+    return this.t.pedir("DELETE", `analises/monitoramentos/${encodeURIComponent(id)}`);
+  }
+}

package/src/recursos/catalogo.ts

@@ -0,0 +1,17 @@
+import { type Saldo, type Servico, paraSaldo, paraServico } from "../dados.js";
+import type { Transporte } from "../transporte.js";
+
+/** Catalogo e saldo. Escopo `leitura`, nao gasta nada. */
+export class Catalogo {
+  constructor(private readonly t: Transporte) {}
+
+  /** O que ESTA conta pode consultar, com o preco dela. */
+  async servicos(): Promise<Servico[]> {
+    const dados = await this.t.pedir<Record<string, unknown>[]>("GET", "servicos");
+    return dados.map(paraServico);
+  }
+
+  async saldo(): Promise<Saldo> {
+    return paraSaldo(await this.t.pedir("GET", "saldo"));
+  }
+}

package/src/recursos/consultas.ts

@@ -0,0 +1,32 @@
+import { type Transporte, chaveIdempotencia } from "../transporte.js";
+
+/**
+ * Consultas. Escopo `consultas`. GASTA SALDO.
+ *
+ * O retorno vem como objeto solto e nao tipado de proposito: cada servico
+ * devolve um corpo diferente, a lista cresce, e tipar tudo aqui faria o SDK
+ * desatualizar a cada servico novo sem ninguem perceber.
+ */
+export class Consultas {
+  constructor(private readonly t: Transporte) {}
+
+  /**
+   * Executa uma consulta pelo slug do servico.
+   *
+   * A chave de idempotencia e GERADA quando voce nao passa uma, e e ela que
+   * torna seguro repetir: a mesma chave devolve a mesma resposta em vez de
+   * cobrar de novo. Guarde a sua se quiser poder reconsultar o resultado
+   * depois de um timeout.
+   */
+  async executar(
+    slug: string,
+    documento: string,
+    extras: Record<string, unknown> = {},
+    chave?: string,
+  ): Promise<Record<string, unknown>> {
+    return this.t.pedir("POST", slug, {
+      corpo: { documento, ...extras },
+      chaveIdempotencia: chave ?? chaveIdempotencia(),
+    });
+  }
+}

package/src/recursos/verify.ts

@@ -0,0 +1,40 @@
+import { type SessaoVerify, paraSessao } from "../dados.js";
+import type { Transporte } from "../transporte.js";
+
+/**
+ * Verify: verificacao de identidade. Escopo `verify`. GASTA SALDO.
+ *
+ * ATENCAO ao criar: esta rota NAO tem idempotencia na api, entao o SDK nao
+ * repete a chamada sozinho. Se der timeout, NAO chame de novo as cegas: mande
+ * um `reference_id` seu na criacao e, na duvida, procure por ele antes de
+ * criar outra, senao voce paga duas sessoes.
+ */
+export class Verify {
+  constructor(private readonly t: Transporte) {}
+
+  /**
+   * Cria a sessao e devolve a URL para mandar a pessoa.
+   *
+   * @param fluxo uuid do fluxo ou o alias dele (ex.: "kyc-cnpj")
+   * @param input o que o fluxo pede de entrada (ex.: cpf)
+   * @param opcoes prefill, consent, redirect_url, webhook_url, reference_id
+   */
+  async criarSessao(
+    fluxo: string,
+    input: Record<string, unknown> = {},
+    opcoes: Record<string, unknown> = {},
+  ): Promise<SessaoVerify> {
+    const corpo: Record<string, unknown> = { flow_id: fluxo, ...opcoes };
+    if (Object.keys(input).length > 0) corpo.input = input;
+
+    return paraSessao(await this.t.pedir("POST", "verify/sessions", { corpo }));
+  }
+
+  async sessao(id: string): Promise<SessaoVerify> {
+    return paraSessao(await this.t.pedir("GET", `verify/sessions/${encodeURIComponent(id)}`));
+  }
+
+  async cancelar(id: string): Promise<SessaoVerify> {
+    return paraSessao(await this.t.pedir("POST", `verify/sessions/${encodeURIComponent(id)}/cancel`));
+  }
+}

package/src/recursos/webhooks.ts

@@ -0,0 +1,43 @@
+import type { Transporte } from "../transporte.js";
+
+/**
+ * Para onde mandamos os eventos, e o segredo que os assina.
+ *
+ * Escopo `webhooks`, que e proposital e separado: de a um token de
+ * PROVISIONAMENTO, nao ao token que o seu servidor usa todo dia. Quem tem
+ * este escopo pode redirecionar os seus eventos. O token padrao NAO o tem, e
+ * por isso estas chamadas devolvem `SemEscopo` com um token comum.
+ */
+export class Webhooks {
+  constructor(private readonly t: Transporte) {}
+
+  /** Destino atual e o PREFIXO do segredo, nunca o segredo. */
+  async atual(): Promise<Record<string, unknown>> {
+    return this.t.pedir("GET", "webhooks");
+  }
+
+  async definir(url: string, eventos: string[] = []): Promise<Record<string, unknown>> {
+    const corpo: Record<string, unknown> = { url };
+    if (eventos.length > 0) corpo.eventos = eventos;
+    return this.t.pedir("PUT", "webhooks", { corpo });
+  }
+
+  async remover(): Promise<Record<string, unknown>> {
+    return this.t.pedir("DELETE", "webhooks");
+  }
+
+  /**
+   * Gira o segredo e devolve o novo, UMA unica vez.
+   *
+   * Guarde na hora: a consulta nunca mais mostra o valor inteiro. E lembre
+   * que girar invalida a assinatura dos avisos em voo.
+   */
+  async girarSegredo(): Promise<Record<string, unknown>> {
+    return this.t.pedir("POST", "webhooks/secret/rotate");
+  }
+
+  /** Dispara um evento de teste para o seu endpoint. */
+  async testar(url?: string): Promise<Record<string, unknown>> {
+    return this.t.pedir("POST", "webhooks/testar", { corpo: url ? { url } : null });
+  }
+}