JSPM

@vectorforge-ai/sdk

0.1.4
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 3
  • Score
    100M100P100Q37219F
  • License MIT

Official Node.js/TypeScript SDK for VectorForge Cloud APIs

Package Exports

  • @vectorforge-ai/sdk
  • @vectorforge-ai/sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@vectorforge-ai/sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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)


License

MIT