@nexbasira/node

SDK TypeScript από την πλευρά του διακομιστή. Καλύπτει κάθε πόρο του δημόσιου API με τυποποιημένες μορφές αιτήματος + απόκρισης, βοηθητικά cursor-pagination και έναν επαληθευτή υπογραφής webhook που εκτελείται σε σταθερό χρόνο.

Εγκατάσταση

npm install @nexbasira/node

Απαιτεί Node 18+. Υποστηρίζονται και ESM και CommonJS.

Αρχικοποίηση

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

Πόροι

Κάθε πόρος του δημόσιου API έχει έναν τυποποιημένο client στην 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

Κοινά μοτίβα

Δημιουργία + πρόσκληση

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 με async-iterator

Τα endpoints λίστας επιστρέφουν έναν async iterator που κάνει pages διαφανώς. Τέλος στο "θυμηθείτε να περάσετε το cursor από την προηγούμενη απόκριση":

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

Idempotent POST

Περάστε ένα idempotencyKey για να κάνετε μια εγγραφή ασφαλή σε επανάληψη:

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

Το backend κρατά την απόκριση στην cache ανά (key, credential) για 24 ώρες. Ένα POST που επαναλαμβάνεται με το ίδιο key επιστρέφει την αρχική απόκριση χωρίς να ξαναδημιουργήσει τον πόρο.

Επαλήθευση 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;
  }
});

Τυποποιημένα σφάλματα

Το SDK ρίχνει μια μικρή ιεραρχία τυποποιημένων σφαλμάτων, ώστε να χειρίζεστε κάθε κλάση σκόπιμα:

Κλάση	Πότε
`AuthenticationError`	401 — κακά διαπιστευτήρια ή λείπει το key
`PermissionError`	403 — το credential στερείται του scope
`NotFoundError`	404 — ο πόρος δεν υπάρχει ή δεν είναι στην org σας
`RateLimitError`	429 — χτύπησε το throttle. Έχει `retryAfterMs`
`InvalidSignatureError`	Μόνο από το `constructEvent()` — κακή / ελλείπουσα / ληγμένη υπογραφή
`NexBasiraError`	Βασική κλάση — πιάστε αυτήν για "οποιοδήποτε σφάλμα 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;
}

Τύποι OpenAPI

Το SDK διαθέτει τύπους αιτήματος + απόκρισης παραγόμενους από openapi-typescript στο @nexbasira/node/types. Εισαγάγετέ τους απευθείας αν θέλετε ισχυρά τυποποιημένους handlers πριν από την κλήση του SDK:

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

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

@nexbasira/node SDK