Node.js SDK

Lightweight client for the VeriSwarm trust scoring API. Zero dependencies, uses native fetch (Node.js 18+).

GitHub: github.com/veriswarm/veriswarm-sdk/tree/main/packages/sdk-node

Installation

npm install @veriswarm/sdk

Requires Node.js 18+. TypeScript projects get type inference automatically via JSDoc annotations.

Authentication

import { VeriSwarmClient } from "@veriswarm/sdk";

const client = new VeriSwarmClient({
  baseUrl: "https://api.veriswarm.ai",
  apiKey: "vsk_your_workspace_key",
});

Find your API key in the dashboard under Settings > API Keys.

Parameter	Type	Default	Description
baseUrl	string	Required	API base URL
apiKey	string	Required	Workspace API key (vsk_...)
timeoutMs	number	15000	Request timeout in milliseconds

Core Operations

Check a Trust Decision

const decision = await client.checkDecision({
  agentId: "agt_123",
  actionType: "post_public_message",
  resourceType: "feed",
});

switch (decision.decision) {
  case "allow":  break;  // Proceed
  case "review": break;  // Queue for human review
  case "deny":   break;  // Block
}

Register an Agent

const agent = await client.registerAgent({
  tenant_id: "ten_your_workspace",
  slug: "my-assistant",
  display_name: "My Assistant",
});

Report Events

// Single event
await client.ingestEvent({
  eventId: "evt_unique_123",
  agentId: "agt_123",
  sourceType: "platform",
  eventType: "message.sent",
  occurredAt: new Date().toISOString(),
  payload: { contentLength: 140, channel: "general" },
});

// Batch (up to 50 per request)
await client.ingestEventsBatch([
  { event_id: "evt_1", agent_id: "agt_123", source_type: "platform",
    event_type: "message.sent", occurred_at: new Date().toISOString(), payload: {} },
  { event_id: "evt_2", agent_id: "agt_123", source_type: "platform",
    event_type: "tool.invoked", occurred_at: new Date().toISOString(), payload: {} },
]);

Get Trust Scores

const scores = await client.getAgentScores("agt_123");
console.log(`Risk: ${scores.risk.score}, Tier: ${scores.policy_tier}`);

Also available: getAgentScoreHistory(agentId, { limit }) and getAgentScoreBreakdown(agentId).

Moderation Flags

const flags = await client.getAgentFlags("agt_123");
await client.appealFlag("agt_123", 42);

Provider Reports

await client.ingestProviderReport({
  agent_id: "agt_123",
  provider_event_id: "provider-evt-456",
  report_type: "spam",
  severity: "high",
  confidence: 0.91,
  summary: "Burst spam detected in #general",
});

Portable Credentials

// Issue (requires agent key auth)
const result = await client.issueCredential();
console.log(result.credential);

// Verify
const verified = await client.verifyCredential(result.credential);
console.log(verified.payload.veriswarm.policy_tier);

Agent Self-Service

const myScores = await client.getMyScores();
console.log(myScores.guidance.actions); // Improvement steps

Scoring Profiles

const profile = await client.getScoringProfile();
await client.setScoringProfile("high_security");

Trust Badges

const url = client.getBadgeUrl("my-agent", { style: "card", theme: "dark" });

Guard PII Tokenization

Detect and replace PII with reversible [VS:TYPE:ID] tokens before sending data to external tools or models. Rehydrate on demand when the original values are needed.

Methods

Method	Description
tokenizePii(text, agentId?)	Detect PII and return tokenized text with a session ID
rehydratePii(text, sessionId)	Replace [VS:TYPE:ID] tokens with original values
getPiiSession(sessionId)	Retrieve metadata for a tokenization session
revokePiiSession(sessionId)	Permanently delete stored PII mappings for a session
VeriSwarmClient.guardProxyConfig(proxyUrl)	Static method -- returns MCP client config object pointing at a Guard Proxy URL

Example: Tokenize, Process, Rehydrate

// Tokenize before sending to an external tool
const result = await client.tokenizePii(
  "Contact Jane Doe at jane@example.com or 555-0123",
  "agt_123",
);
const safeText = result.text;        // "Contact [VS:PERSON:a1] at [VS:EMAIL:a2] or [VS:PHONE:a3]"
const sessionId = result.sessionId;

// ... pass safeText to external tool / model ...

// Rehydrate when you need the original values back
const original = await client.rehydratePii(safeText, sessionId);
console.log(original.text); // "Contact Jane Doe at jane@example.com or 555-0123"

// Clean up when done
await client.revokePiiSession(sessionId);

Guard Proxy Config

Generate an MCP client configuration block pointing at a Guard Proxy instance:

const config = VeriSwarmClient.guardProxyConfig("https://guard-proxy.veriswarm.ai");

Error Handling

try {
  const decision = await client.checkDecision({
    agentId: "agt_123",
    actionType: "post_message",
  });
} catch (err) {
  console.error(`API error: ${err.message}`);
}

Timeout errors are thrown as AbortError when a request exceeds timeoutMs.

For the full method reference, see the API documentation.