Package Exports

vcl-sdk
vcl-sdk/dist/index.js
vcl-sdk/dist/index.mjs

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 (vcl-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

VCL TypeScript SDK

A drop-in replacement for OpenAI and Anthropic clients that generates cryptographically signed receipts for every AI inference request.

Installation

npm install vcl-sdk
# or
yarn add vcl-sdk
# or
pnpm add vcl-sdk

Quick Start

import { VCLClient } from 'vcl-sdk';

const client = new VCLClient({
  apiKey: 'vcl_your_api_key',
  baseUrl: 'https://your-vcl-server.com'
});

// OpenAI-compatible usage
const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});

console.log(response.choices[0].message.content);

// Get the receipt for this request
const receipt = await client.getLastReceipt();
console.log('Receipt ID:', receipt?.receipt_id);
console.log('Input tokens:', receipt?.execution.input.token_count);
console.log('Output tokens:', receipt?.execution.output.token_count);
console.log('Compute units:', receipt?.execution.compute_units);

Anthropic-Compatible Usage

import { VCLClient } from 'vcl-sdk';

const client = new VCLClient({
  apiKey: 'vcl_your_api_key',
  baseUrl: 'https://your-vcl-server.com'
});

const response = await client.messages.create({
  model: 'claude-3-sonnet-20240229',
  messages: [{ role: 'user', content: 'Hello!' }],
  max_tokens: 1024
});

console.log(response.content[0].text);

Streaming

// OpenAI streaming
for await (const chunk of client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true
})) {
  const content = chunk.choices?.[0]?.delta?.content;
  if (content) process.stdout.write(content);
}

// Anthropic streaming
for await (const chunk of client.messages.create({
  model: 'claude-3-sonnet-20240229',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  max_tokens: 1024,
  stream: true
})) {
  if (chunk.type === 'content_block_delta') {
    process.stdout.write(chunk.delta.text);
  }
}

Receipt Verification

import { VCLClient, ReceiptNotFoundError } from 'vcl-sdk';

const client = new VCLClient({
  apiKey: 'vcl_...',
  baseUrl: 'https://...'
});

// Make a request
await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Hello!' }]
});

// Verify the receipt
const receiptId = client.getLastReceiptId();
if (receiptId) {
  try {
    const result = await client.verifyReceipt(receiptId);
    console.log('Valid:', result.valid);
    console.log('Model:', result.model);
    console.log('Timestamp:', result.timestamp);
  } catch (e) {
    if (e instanceof ReceiptNotFoundError) {
      console.log('Receipt not found');
    }
  }
}

Receipt Details

const receipt = await client.getLastReceipt();

if (receipt) {
  // Basic info
  console.log('Receipt ID:', receipt.receipt_id);
  console.log('Timestamp:', receipt.timestamp);
  console.log('Provider:', receipt.provider.name);

  // Execution details
  console.log('Model:', receipt.execution.model_name);
  console.log('Input tokens:', receipt.execution.input.token_count);
  console.log('Output tokens:', receipt.execution.output.token_count);
  console.log('Compute units:', receipt.execution.compute_units);

  // Verification
  console.log('Receipt hash:', receipt.verification.receipt_hash);
  console.log('Signature:', receipt.verification.signature);

  // On-chain anchor (if available)
  if (receipt.verification.anchor?.tx_hash) {
    const anchor = receipt.verification.anchor;
    console.log('Chain:', anchor.chain);
    console.log('TX Hash:', anchor.tx_hash);
    console.log('Block:', anchor.block_num);
    console.log('Merkle Root:', anchor.merkle_root);
  }

  // TEE attestation (if available)
  if (receipt.tee_attestation?.type) {
    const tee = receipt.tee_attestation;
    console.log('TEE Type:', tee.type);
    console.log('MR Enclave:', tee.mr_enclave);
  }
}

API Key Management

// List your API keys
const { keys } = await client.listApiKeys();
for (const key of keys) {
  console.log(`${key.name}: ${key.key_prefix}...`);
}

// Create a new key
const newKey = await client.createApiKey('Production');
console.log('New key:', newKey.key); // Save this!

// Delete a key
await client.deleteApiKey('key-id-here');

Usage Statistics

const stats = await client.getStats();
console.log('Total receipts:', stats.total_receipts);
console.log('Total compute units:', stats.total_compute_units);

Error Handling

import {
  VCLClient,
  VCLError,
  AuthenticationError,
  RateLimitError
} from 'vcl-sdk';

const client = new VCLClient({
  apiKey: 'vcl_...',
  baseUrl: 'https://...'
});

try {
  const response = await client.chat.completions.create({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Hello!' }]
  });
} catch (e) {
  if (e instanceof AuthenticationError) {
    console.log('Invalid API key');
  } else if (e instanceof RateLimitError) {
    console.log('Rate limit exceeded, try again later');
  } else if (e instanceof VCLError) {
    console.log(`Error: ${e.message} (status: ${e.statusCode})`);
  }
}

TypeScript Types

The SDK exports all types for TypeScript users:

import type {
  VCLClientOptions,
  Message,
  ChatCompletionRequest,
  AnthropicMessageRequest,
  Receipt,
  Anchor,
  TEEAttestation,
  Verification,
  Execution,
  VerificationResult,
  Stats,
  APIKey,
  Health
} from 'vcl-sdk';

License

MIT