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/sdkQuick 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 expiredquota_exceeded(429) - Monthly limit reachedrate_limit_exceeded(429) - Too many requestsplan_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
License
MIT