@nexbasira/node

SDK TypeScript côté serveur. Couvre chaque ressource de l'API publique avec des formes de requête + réponse typées, des helpers de pagination par curseur, et un vérificateur de signature de webhook qui s'exécute en temps constant.

Installation

npm install @nexbasira/node

Nécessite Node 18+. ESM + CommonJS pris en charge tous les deux.

Initialisation

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

Ressources

Chaque ressource de l'API publique dispose d'un client typé sur l'instance 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

Patterns courants

Créer + inviter

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

Pagination par itérateur asynchrone

Les endpoints de listage renvoient un itérateur asynchrone qui pagine de façon transparente. Fini le « penser à passer cursor depuis la réponse précédente » :

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 idempotent

Passez un idempotencyKey pour rendre une écriture sûre en cas de nouvelle tentative :

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

Le backend met la réponse en cache par (clé, identifiant) pendant 24 heures. Un POST rejoué avec la même clé renvoie la réponse d'origine sans recréer la ressource.

Vérifier 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;
  }
});

Erreurs typées

Le SDK lève une petite hiérarchie d'erreurs typées pour que vous puissiez gérer chaque classe de façon délibérée :

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

Types OpenAPI

Le SDK est livré avec des types de requête + réponse générés par openapi-typescript sous @nexbasira/node/types. Importez-les directement si vous voulez des handlers fortement typés en amont de l'appel au SDK :

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

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

Et ensuite

• Référence de l'API Sessions
• Plongée dans les webhooks
• Erreurs + limites de débit
• Source sur GitHub