Skip to main content

TypeScript / Node.js SDK

The official Xavigate Node.js SDK. Generated from the OpenAPI spec + hand-tuned wrappers.

npm: @xavigate/node
Source: github.com/xavigate/xavigate-node
Requires: Node.js 18+

Install​

npm install @xavigate/node
# or
yarn add @xavigate/node
# or
pnpm add @xavigate/node

Initialize​

import Xavigate from '@xavigate/node';

const client = new Xavigate({
  apiKey: process.env.XAVIGATE_API_KEY, // test_sk_* or live_sk_*
});

The key prefix determines the environment — test_* → sandbox, live_* → production. No separate env config needed.

Quick example​

// Create a subject, run MNTEST, get profile
const subject = await client.nature.subjects.create({
  external_subject_id: 'user_42',
  consent_artifact: {
    consent_text_version: 'v1',
    consented_at: new Date().toISOString(),
    ui_snapshot_hash: 'sha256:abc123',
  },
});

const assessment = await client.nature.assessments.start(subject.id, {
  language: 'en',
});

await client.nature.assessments.submitResponses(subject.id, assessment.id, {
  responses: myItemResponses, // [{ item_id: 'mn_001', value: 4 }, ...]
});

// Poll or listen to webhook for completion
const profile = await client.nature.profiles.get(subject.id);
console.log(profile.scores.natures);

Auto-pagination​

// Iterate all subjects without managing cursors
for await (const subject of client.nature.subjects.list()) {
  console.log(subject.id, subject.external_subject_id);
}

Error handling​

import { XavigateError, XavigateAuthError } from '@xavigate/node';

try {
  await client.nature.subjects.create({ ... });
} catch (err) {
  if (err instanceof XavigateAuthError) {
    // 401 — key revoked, missing, or invalid
  } else if (err instanceof XavigateError) {
    console.error(err.error_code, err.request_id, err.status);
  }
}

Webhook verification​

import { verifyWebhook } from '@xavigate/node/webhooks';

// In your webhook handler:
const event = verifyWebhook(
  rawBody,    // string
  headers,    // { 'webhook-id', 'webhook-timestamp', 'webhook-signature' }
  signingSecret
);

Configuration options​

const client = new Xavigate({
  apiKey: 'test_sk_...',
  maxRetries: 3,           // default: 3 (handles 429 + network errors)
  timeout: 30_000,         // ms; default: 30s
  baseURL: '...',          // override for mock server testing
});

TypeScript types​

All request/response shapes are fully typed. Types are exported from the package root:

import type { NatureSubject, NatureProfile, NatureAssessment } from '@xavigate/node';