@nexbasira/node

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

Installation

npm install @nexbasira/node

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

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

Schémas 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 liste retournent un itérateur asynchrone qui pagine de manière transparente. Fini le « penser à repasser le cursor de 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 en cache la réponse par (clé, identifiant) pendant 24 heures. Un POST réessayé avec la même clé retourne 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 afin que vous puissiez traiter chaque classe de manière 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 et de réponse générés par openapi-typescript sous @nexbasira/node/types. Importez-les directement si vous souhaitez des gestionnaires 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
• Webhooks en détail
• Erreurs + limites de débit
• Code source sur GitHub