@nexbasira/node

Serverseitiges TypeScript-SDK. Deckt jede Ressource der öffentlichen API mit typisierten Request- + Response-Formen, Cursor-Paginierungs-Helpern und einem Webhook-Signatur-Verifier ab, der in konstanter Zeit läuft.

Installation

npm install @nexbasira/node

Erfordert Node 18+. ESM + CommonJS werden beide unterstützt.

Initialisieren

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

Ressourcen

Jede Ressource der öffentlichen API hat einen typisierten Client auf der cvp-Instanz:

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

Gängige Muster

Erstellen + einladen

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

Async-Iterator-Paginierung

List-Endpoints geben einen Async-Iterator zurück, der transparent paginiert. Kein „daran-denken-den-cursor-aus-der-vorherigen-Response-zu-übergeben“ mehr:

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

Idempotenter POST

Übergeben Sie einen idempotencyKey, um einen Write retry-sicher zu machen:

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

Das Backend cacht die Response nach (key, credential) für 24 Stunden. Ein wiederholter POST mit demselben Key gibt die ursprüngliche Response zurück, ohne die Ressource neu zu erstellen.

Einen Webhook verifizieren

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

Typisierte Fehler

Das SDK wirft eine kleine Hierarchie typisierter Fehler, sodass Sie jede Klasse gezielt behandeln können:

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;
}

OpenAPI-Typen

Das SDK liefert openapi-typescript-generierte Request- + Response-Typen unter @nexbasira/node/types mit. Importieren Sie sie direkt, wenn Sie stark typisierte Handler oberhalb des SDK-Calls wünschen:

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

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

Was als Nächstes kommt

• Sessions-API-Referenz
• Webhooks im Detail
• Fehler + Rate-Limits
• Quellcode auf GitHub