@nexbasira/node

SDK TypeScript do lado do servidor. Cobre todos os recursos da API pública com formas de request + response tipadas, helpers de paginação por cursor e um verificador de assinatura de webhook que corre em tempo constante.

Instalação

npm install @nexbasira/node

Requer Node 18+. ESM + CommonJS ambos suportados.

Inicializar

import { NexBasira } from "@nexbasira/node";

const nb = new NexBasira({
  apiKey: process.env.NB_PUBLIC_KEY!,    // nb_pub_*
  apiSecret: process.env.NB_SECRET_KEY!, // nb_sec_*
  // baseURL: "https://app.nexbasira.com/api/v1/public", // default
  // timeout: 30_000,                                          // default
});

Recursos

Cada recurso da API pública tem um cliente tipado na instância cvp:

nb.sessions       // create / list / retrieve / end / invite
nb.evidence       // list / retrieve / signed download URL
nb.whiteboards    // list per session
nb.webhooks       // register / rotate-secret / test-fire / constructEvent
nb.branding       // read-only
nb.org            // read-only

Padrões comuns

Criar + convidar

const session = await nb.sessions.create({
  notes: "Vehicle damage claim CL-2026-0042",
  scheduled_for: "2026-05-23T10:00:00Z",
  locale: "fr",
});

const invite = await nb.sessions.invite(session.id, {
  recipient_email: "alex@policyholder.com",
  send_email: true,
});

console.log(invite.url); // shown ONCE

Paginação por async-iterator

Os endpoints de listagem devolvem um async iterator que pagina de forma transparente. Acabou o "lembrar de passar o cursor da resposta anterior":

for await (const session of nb.sessions.list({ limit: 50 })) {
  console.log(session.id, session.status);
}

// Or a single page if you want pagination control:
const page = await nb.sessions.listPage({ limit: 25 });
// page.data, page.has_more, page.next_cursor

POST idempotente

Passe uma idempotencyKey para tornar uma escrita segura em retentativa:

const session = await nb.sessions.create(
  { notes: "..." },
  { idempotencyKey: crypto.randomUUID() },
);

O backend guarda a resposta em cache por (key, credential) durante 24 horas. Um POST repetido com a mesma chave devolve a resposta original sem recriar o recurso.

Verificar um webhook

import express from "express";
import { NexBasira, InvalidSignatureError } from "@nexbasira/node";

const app = express();
const nb = new NexBasira({ apiKey: "...", apiSecret: "..." });

// IMPORTANT: use express.raw() — constructEvent needs the untouched
// bytes the signature was computed over.
app.post("/nb-webhook", express.raw({ type: "application/json" }), (req, res) => {
  try {
    const event = nb.webhooks.constructEvent(
      req.body,
      req.header("NB-Signature")!,
      process.env.NB_WEBHOOK_SECRET!,
    );
    // event.type is type-narrowed; event.data is the resource shape
    switch (event.type) {
      case "session.completed":
        return onCompleted(event.data, res);
      case "audit.anchored":
        return onAnchored(event.data, res);
    }
    res.status(204).end();
  } catch (err) {
    if (err instanceof InvalidSignatureError) {
      return res.status(401).send("bad signature");
    }
    throw err;
  }
});

Erros tipados

O SDK lança uma pequena hierarquia de erros tipados para que possa tratar cada classe deliberadamente:

Classe	Quando
`AuthenticationError`	401 — credenciais inválidas ou chave em falta
`PermissionError`	403 — a credencial não tem o scope
`NotFoundError`	404 — o recurso não existe ou não está na sua organização
`RateLimitError`	429 — atingiu o throttle. Tem `retryAfterMs`
`InvalidSignatureError`	Apenas de `constructEvent()` — assinatura inválida / em falta / expirada
`NexBasiraError`	Classe base — capture esta para "qualquer erro do SDK"

try {
  await nb.sessions.create({ ... });
} catch (err) {
  if (err instanceof RateLimitError) {
    await sleep(err.retryAfterMs);
    return retry();
  }
  if (err instanceof NexBasiraError) {
    log.warn({ status: err.status, code: err.code }, "cvp error");
  }
  throw err;
}

Tipos OpenAPI

O SDK vem com tipos de request + response gerados por openapi-typescript em @nexbasira/node/types. Importe-os diretamente se quiser handlers fortemente tipados a montante da chamada ao SDK:

import type { Session, Evidence, WebhookEvent } from "@nexbasira/node/types";

function onSessionCompleted(session: Session) {
  // ...
}

SDK @nexbasira/node