Publikt API + SDK:er + embed-widget
Fyra förstaparts-SDK:er över ett versionerat REST-API. Cursor-paginering, Idempotency-Key-headers, HMAC-webhook-signering, async-iterator-hjälpare, typade fel. De developer-experience-bitarna som bör finnas — inte eftertankar.
De fyra SDK:erna
@nexbasira/node
Serversidan. Typad mot OpenAPI-schemat; async-iteratorer för paginerade listor; constructEvent(body, sig, secret) för webhook-verifiering. Noll runtime-beroenden utöver globala fetch.
nexbasira (PyPI)
Serversidan. Pydantic v2-modeller genererade från schemat. Sync- + async-klienter delar samma yta; webhook-verifiering finns i WebhookSigner.verify(body, sig, secret).
@nexbasira/react
Hooks + komponenter för operatörsytan. <CertivisioSessionView /> renderar UI:t i sessionen med branding, bevis och chatt. Släpp in i din befintliga React-app — ingen portalomdirigering.
Iframe-widget
<script src=".../nb-embed.js"> + en div — integrationen med lägst friktion. För driftteam som kör operatörs-UI:t från en icke-React-stack. Branding ärvs från den inbäddande sidan via postMessage.
Byggd på OpenAPI-specen
Node- + Python-SDK:erna genereras från samma filtrerade OpenAPI 3.1-schema som vi publicerar på app.nexbasira.com/api/public-schema/ — så om du vill hoppa över SDK:n och generera din egen typade klient i Go eller Rust kan du det:
# Node typed client
npx openapi-typescript https://app.nexbasira.com/api/public-schema/ -o src/nb-types.ts
# Python typed models
datamodel-codegen \
--url https://app.nexbasira.com/api/public-schema/ \
--input-file-type openapi \
--output-model-type pydantic_v2.BaseModel \
--output cvp_models.pyDen handskrivna ergonomiska ytan (typade fel, async-iteratorer, webhook-verifiering) läggs ovanpå de genererade typerna. Du väljer inte mellan "snabb typad klient" och "bra DX" — båda levereras.
REST-konventioner, tråkiga med flit
| Konvention | Varför |
|---|---|
| Cursor-paginering | Stabil under samtidiga skrivningar. next_cursor i svaret; skicka tillbaka den som ?cursor=…. |
Idempotency-Key-header | Skicka ett UUID; gör om vid timeout; servern returnerar det ursprungliga svaret hur som helst. |
| HMAC-SHA256-webhooks | NB-Signature: t=…,v1=…. SDK:erna levererar en enrads-verifiering; 5-minuters replay-fönster. |
| Versionerat URL-prefix | /api/v1/public/. Brytande ändringar flyttas till /v2/ med 12 månaders överlapp. |
| Scope-begränsade uppgifter | Varje uppgift bär explicita scopes (sessions:write, evidence:read, …). Rotera utan att förlora en tenant. |
| Typat felkuvert | Samma format för varje endpoint. code, detail, retry_after_seconds när det är relevant. |
Stabilitetslöfte
Additiva ändringar — nya valfria fält, nya endpoints, nya webhook-event-typer — levereras på plats; SDK:erna behandlar okända fält som framåtkompatibla. Brytande ändringar flyttas till ett nytt URL-prefix och överlappar med föregående version i minst 12 månader. Du vaknar inte upp till en grön-till-röd-migrering en tisdagmorgon.
Börja med snabbstarten
Skapa en session, prägla en fältinbjudan, verifiera en webhook — på under 5 minuter. Kopiera-klistra curl + Node + Python på samma sida.