VectorForge Node SDK

Official TypeScript/Node.js client for VectorForge Cloud APIs.

VectorForge is a trust and confidence layer for AI and automations, providing:

• DIVTs (Digital Integrity Verification Tokens) - Cryptographic "birth certificates" for data
• AI Answer Confidence Scoring - Privacy-preserving and comprehensive scoring
• Worldstate Logging - Immutable event capture for AI operations
• Hybrid Post-Quantum Cryptography - ECDSA P-521 + ML-DSA-65 signatures

Installation

npm install @vectorforge-ai/sdk

Quick Start

Configuration

import { createVectorForgeClient } from '@vectorforge-ai/sdk';

// Option 1: Use environment variables (recommended)
// export VF_API_BASE_URL="https://api.vectorforge.ai"
// export VF_API_KEY="vf_prod_YourApiKeyHere"
const client = createVectorForgeClient();

// Option 2: Pass config directly
const client = createVectorForgeClient({
  baseUrl: "https://api.vectorforge.ai",
  apiKey: "vf_prod_YourApiKeyHere",
});

Register Content

The SDK sends your content to the VectorForge API, which performs canonicalization, hashing, and signing server-side.

Register Text

const result = await client.registerContent(
  'prompt:123',
  'What is the capital of France?',
  'prompt_receipt_v1',
  { user_id: 'user-456', session: 'sess-789' }
);

console.log(`DIVT ID: ${result.divt_id}`);
console.log(`Ledger status: ${result.ledger_status}`);

Register JSON

const result = await client.registerJson(
  'rag_snapshot:v42',
  {
    snapshot_type: 'rag-corpus',
    doc_hashes: ['hash1', 'hash2'],
    timestamp: '2025-11-21T10:00:00Z',
  },
  'rag_snapshot_v1',
  { project: 'hr-assistant', env: 'prod' }
);

Register Embedding

const result = await client.registerEmbedding(
  'chunk:doc-123:p5',
  [0.123456, -0.987654, 0.456789],
  'rag_chunk_v1',
  { document_id: 'doc-123', paragraph: 5 }
);

Register Image

import { readFile } from 'fs/promises';

const imageBuffer = await readFile('receipt.png');

const result = await client.registerImage(
  'image:receipt-456',
  imageBuffer,
  'image_receipt_v1',
  { source: 'mobile_app' }
);

Verify Content

// Verify text
const result = await client.verifyContent(divtId, 'What is the capital of France?');

// Verify JSON
const result = await client.verifyJson(divtId, { key: 'value' });

if (result.verified) {
  console.log('DIVT is valid');
  console.log(`  Hash valid: ${result.hash_valid}`);
  console.log(`  ECDSA valid: ${result.ecdsa_signature_valid}`);
  console.log(`  ML-DSA valid: ${result.ml_dsa_signature_valid}`);
}

Complete Example

import { createVectorForgeClient } from '@vectorforge-ai/sdk';

const client = createVectorForgeClient();

// Register
const promptData = {
  prompt: 'What is the capital of France?',
  response: 'Paris',
  model: 'gpt-4',
  timestamp: '2025-11-21T10:00:00Z',
};

const reg = await client.registerJson(
  'prompt_receipt:flow-abc-123',
  promptData,
  'prompt_receipt_v1',
  { workflow: 'customer_support' }
);

console.log(`Registered: ${reg.divt_id}`);

// Verify
const ver = await client.verifyJson(reg.divt_id, promptData);

if (ver.verified) {
  console.log('Verified - content is untampered');
} else {
  console.log('Verification failed - content was modified');
}

Bundle API

Get a comprehensive verification bundle including DIVT, worldstate context, and scoring.

// By DIVT ID
const bundle = await client.getBundle({
  divt_id: '019abc12-3456-7890-abcd-ef0123456789',
});

console.log(`Verified: ${bundle.divt.verified}`);
console.log(`Generated at: ${bundle.bundle_metadata.generated_at}`);

// By object ID
const bundle = await client.getBundle({
  object_id: 'prompt_receipt:flow-abc-123',
  include_history: true,
});

Scoring API

Privacy Score (No Raw Content Sent)

const result = await client.scorePrivacy({
  query_id: 'query-123',
  answer_id: 'answer-456',
  evidence: [
    {
      object_id: 'chunk:doc-1:p1',
      divt_id: '019abc...',
      tenant_id: 'my-tenant',
      similarity: 0.95,
      chunk_confidence: 0.9,
    },
  ],
});

console.log(`Overall confidence: ${result.overall_confidence}`);
console.log(`Integrity score: ${result.integrity_score}`);

Full Score (With Groq Judge)

const result = await client.scoreFull({
  query: 'What is the capital of France?',
  answer: 'The capital of France is Paris.',
  evidence: [
    {
      object_id: 'chunk:doc-1:p1',
      divt_id: '019abc...',
      tenant_id: 'my-tenant',
      text: 'Paris is the capital city of France.',
      similarity: 0.95,
    },
  ],
  options: { log_worldstate: 'minimal' },
});

console.log(`Support: ${result.support_score}`);
console.log(`Faithfulness: ${result.faithfulness_score}`);

Worldstate

Get Single Record

const item = await client.getWorldstateItem({
  wsl_id: '019abc12-3456-7890-abcd-ef0123456789',
  include_data: true,
});

console.log(`Kind: ${item.kind}`);
console.log(`Data: ${JSON.stringify(item.data)}`);

List Records

const result = await client.listWorldstate({
  kind: 'prompt_receipt',
  created_from: '2025-11-01T00:00:00Z',
  limit: 50,
});

for (const item of result.items) {
  console.log(`${item.wsl_id}: ${item.data_summary}`);
}

// Paginate
let cursor = result.cursor;
while (cursor) {
  const page = await client.listWorldstate({ cursor });
  cursor = page.cursor;
}

Stream Events (SSE)

await client.streamEvents(
  {
    since: new Date(Date.now() - 3600000).toISOString(),
    types: ['divt_registered', 'scoring_event'],
    limit: 50,
  },
  (event) => {
    console.log(`[${event.type}] ${event.id} at ${event.timestamp}`);
  }
);

Low-Level API

For advanced use cases (e.g., pre-computed hashes), use the low-level methods directly:

// Register with pre-computed hash (custom mode)
const result = await client.register({
  object_id: 'doc-123',
  hash_mode: 'custom',
  hash_version: 'custom_v1',
  hash_b64: preComputedHashB64,
  data_type: 'prompt_receipt_v1',
});

// Verify with pre-computed hash
const result = await client.verify({
  divt_id: '019abc12-...',
  hash_b64: preComputedHashB64,
});

Canonicalization Utilities

The SDK includes canonicalization functions for offline hash computation:

import { canon } from '@vectorforge-ai/sdk';

const hashB64 = canon.hashContentV1('Hello, World!');
const hashB64 = canon.hashJsonV1({ key: 'value' });
const hashB64 = canon.hashEmbeddingV1([0.1, 0.2, 0.3], 6);
const hashB64 = await canon.hashImageV1(imageBuffer, 1024);

Error Handling

import { VectorForgeAPIError } from '@vectorforge-ai/sdk';

try {
  await client.registerContent('doc-123', 'Hello', 'test_v1');
} catch (error) {
  if (error instanceof VectorForgeAPIError) {
    console.error(`${error.statusCode}: ${error.message}`);
    console.error(`Code: ${error.error}`);
  }
}

Common errors:

• invalid_api_key (401) - API key invalid or expired
• quota_exceeded (429) - Monthly limit reached
• rate_limit_exceeded (429) - Too many requests
• plan_limitation (403) - Feature not on your plan

Type Support

import type {
  RegisterInput, RegisterResult,
  VerifyInput, VerifyResult,
  BundleInput, BundleResult,
  PrivacyScoreInput, FullScoreInput, ScoreResult,
  StreamEventsInput, StreamEvent,
} from '@vectorforge-ai/sdk';

Requirements

• Node.js >= 18.0.0
• Dependencies: js-sha3
• Optional: sharp >= 0.33.0 (for image registration)

Related

• Python SDK
• MCP Server
• CLI

License

MIT