@vb-os/sdk

VB-OS Cloud API SDK for Node.js. TypeScript-first, zero runtime dependencies.

Installation

npm install @vb-os/sdk

Requires Node.js 22+.

Quick Start

import { VBOSClient } from "@vb-os/sdk";

const client = new VBOSClient({
  apiKey: process.env.VBOS_API_KEY!,
});

// Verify a workload
const result = await client.verify({
  workload: { npi: 1234567890 },
  project: "my-project",
  boundary_ref: "npi-check",
});

console.log(result);

Resource Namespaces

The SDK provides 27 resource namespace clients:

| Namespace | Methods | Description | |-----------|---------|-------------| | account | 7 | Account management (delete, export) | | alertRules | 5 | Alert rule CRUD | | analytics | 5 | Analytics queries | | auditLog | 3 | Audit trail | | billing | 3 | Usage, subscription, invoices | | boundaries | 10 | Boundary management and versioning | | certificationModels | 3 | Certification model management | | certifications | 4 | Certification runs (includes wait() polling) | | connectorProviders | 2 | Connector provider catalog | | connectors | 13 | Connector CRUD, testing, gathering | | deployments | 7 | Deployment lifecycle | | environments | 6 | Environment management | | evaluations | 6 | Evaluation records and replay | | flowTemplates | 2 | Flow template catalog | | flows | 19 | Flow management and versioning | | governedWorkspaces | 12 | Governed workspace management | | keys | 7 | API key management | | members | 7 | Organization member management | | namedSets | 6 | Named set CRUD | | notifications | 3 | Notification management | | org | 10 | Organization settings and ownership | | projects | 10 | Project CRUD and members | | serviceAccounts | 5 | Service account management | | templates | 3 | Boundary template catalog | | users | 2 | Current user profile | | webhooks | 8 | Webhook management | | workspaces | 9 | Workspace management |

Plus 5 top-level methods: verify(), verifyBatch(), validate(), certify(), replay().

Total: 180 endpoint-backed methods + 1 polling helper (certifications.wait()).

Examples

Boundaries

// List boundaries in a project
const boundaries = await client.boundaries.list("project-id");

// Create a boundary
const boundary = await client.boundaries.create("project-id", {
  boundary_ref: "npi-check",
  display_name: "NPI Verification",
  dsl_source: 'require_evidence: npi\nBOUNDARY { npi > 0 }',
});

// Get versions
const versions = await client.boundaries.versions("project-id", "npi-check");

Evaluations

// List evaluations
const evals = await client.evaluations.list("project-id", { limit: 50 });

// Get evaluation detail
const detail = await client.evaluations.get("project-id", "eval-id");

// Replay an evaluation
const replay = await client.evaluations.replay("project-id", "eval-id");

Projects

// List projects
const projects = await client.projects.list();

// Create a project
const project = await client.projects.create({
  name: "Healthcare Verification",
  slug: "healthcare-verification",
  workspace_id: "workspace-id",
});

Environments

// List environments
const envs = await client.environments.list("project-id");

// Create an environment
const env = await client.environments.create("project-id", {
  name: "Production",
  slug: "production",
  type: "PRODUCTION",
});

Deployments

// Deploy a boundary version
const deployment = await client.deployments.create("project-id", "env-id", {
  boundary_version_id: "version-id",
});

// Get active deployment
const active = await client.deployments.active("project-id", "env-id");

API Keys

// Create an API key
const key = await client.keys.create("project-id", "env-id", {
  name: "Production Key",
});

// Rotate a key
await client.keys.rotate("project-id", "env-id", "key-id");

Certifications

// Start a certification run
const run = await client.certify("project-id", {
  model_id: "model-id",
});

// Wait for completion (polls until done)
const result = await client.certifications.wait("project-id", "run-id", {
  pollIntervalSeconds: 2,
  maxAttempts: 150,
});

Flows

// Create a flow
const flow = await client.flows.create("project-id", {
  name: "Onboarding Flow",
});

// Create a version
const version = await client.flows.createVersion("project-id", "flow-id", {
  definition: { steps: [] },
});

// Dry run
const dryRun = await client.flows.dryRun("project-id", "flow-id", "version-id");

Connectors

// List connector providers
const providers = await client.connectorProviders.list();

// Create a connector
const connector = await client.connectors.create("project-id", {
  provider: "provider-id",
  name: "NPI Registry",
  config: {},
});

// Test connection
const testResult = await client.connectors.test("project-id", "connector-id");

Webhooks

// Create a webhook
const webhook = await client.webhooks.create("project-id", {
  url: "https://example.com/webhook",
  events: ["evaluation.completed"],
});

// View deliveries
const deliveries = await client.webhooks.deliveries("project-id", "webhook-id");

Organization

// Get organization
const org = await client.org.get();

// Update settings
await client.org.updateSettings({ feature_flags: {} });

// Invite a member
await client.members.invite({ email: "[email protected]", role: "MEMBER" });

Pagination

All list endpoints support cursor-based pagination:

let cursor: string | undefined;
do {
  const page = await client.projects.list({ limit: 20, cursor }) as {
    items: unknown[];
    cursor: string | null;
  };
  console.log(page.items);
  cursor = page.cursor ?? undefined;
} while (cursor);

Error Handling

import {
  VBOSClient,
  VBOSAuthenticationError,
  VBOSAuthorizationError,
  VBOSNotFoundError,
  VBOSValidationError,
  VBOSRateLimitError,
  VBOSServerError,
  VBOSError,
} from "@vb-os/sdk";

try {
  await client.projects.get("nonexistent");
} catch (err) {
  if (err instanceof VBOSNotFoundError) {
    console.log("Not found:", err.message);
    console.log("Request ID:", err.requestId);
  } else if (err instanceof VBOSRateLimitError) {
    console.log("Rate limited, retry after:", err.retryAfter);
  } else if (err instanceof VBOSError) {
    console.log("API error:", err.statusCode, err.errorCode);
  }
}

Configuration

const client = new VBOSClient({
  apiKey: "your-api-key",        // Required
  baseUrl: "https://api.vb-os.org", // Default
  timeout: 30,                    // Seconds, default 30
  maxRetries: 3,                  // Default 3, retries 5xx and transport errors
});

Retry Behavior

• 5xx responses: Retried with full-jitter exponential backoff
• Transport errors (timeout, DNS, connection): Retried
• 429 (rate limit): NOT retried — raises VBOSRateLimitError immediately
• Other 4xx: NOT retried — raises the appropriate error immediately
• After retries exhausted: 5xx throws VBOSServerError; transport errors propagate the native error

Build

npm run build     # ESM + CJS via tsup
npm run typecheck # TypeScript strict mode
npm run lint      # ESLint
npm run test      # Vitest

License

Proprietary — Copyright (c) 2024-2026 MNC Labs, Inc. All rights reserved.