@nexbasira/node

SDK de TypeScript del lado del servidor. Cubre todos los recursos de la API pública con formas de solicitud y respuesta tipadas, utilidades de paginación por cursor y un verificador de firma de webhook que se ejecuta en tiempo constante.

Instalar

npm install @nexbasira/node

Requiere Node 18+. Compatible con ESM y CommonJS.

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 de la API pública tiene un cliente tipado en la instancia 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

Patrones comunes

Crear + invitar

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

Paginación por iterador asíncrono

Los endpoints de listado devuelven un iterador asíncrono que pagina de forma transparente. Ya no hay que «recordar pasar el cursor de la respuesta 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

Pase una idempotencyKey para que una escritura sea segura ante reintentos:

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

El backend almacena en caché la respuesta por (clave, credencial) durante 24 horas. Un POST reintentado con la misma clave devuelve la respuesta original sin volver a crear el recurso.

Verificar un 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;
  }
});

Errores tipados

El SDK lanza una pequeña jerarquía de errores tipados para que pueda manejar cada clase de forma deliberada:

Clase	Cuándo
`AuthenticationError`	401 — credenciales incorrectas o clave ausente
`PermissionError`	403 — la credencial carece del alcance
`NotFoundError`	404 — el recurso no existe o no está en su organización
`RateLimitError`	429 — alcanzó el límite. Tiene `retryAfterMs`
`InvalidSignatureError`	Solo de `constructEvent()`: firma incorrecta / ausente / expirada
`NexBasiraError`	Clase base: capture esto para «cualquier error del 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 de OpenAPI

El SDK incluye tipos de solicitud y respuesta generados con openapi-typescript bajo @nexbasira/node/types. Impórtelos directamente si desea manejadores fuertemente tipados por encima de la llamada al SDK:

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

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

SDK @nexbasira/node