Package Exports

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

Readme

@verifiedstate/sdk

TypeScript SDK for the VerifiedState verified memory API.

Install

npm install @verifiedstate/sdk

Quick Start

import { VerifiedStateClient } from '@verifiedstate/sdk';

const client = new VerifiedStateClient({
  apiKey: 'vs_live_...',
  baseUrl: 'https://api.verifiedstate.ai', // optional, this is the default
});

// Store content
const artifact = await client.ingest({
  namespace_id: 'your-namespace-uuid',
  content: 'The user prefers dark mode and uses PostgreSQL.',
  source_type: 'user_input',
});

// Extract assertions
const extracted = await client.extract({
  namespace_id: 'your-namespace-uuid',
  artifact_id: artifact.artifact_id,
});

// Verify an assertion
const receipt = await client.verify({
  assertion_id: extracted.assertion_ids[0],
  namespace_id: 'your-namespace-uuid',
});

// Query memory
const results = await client.query({
  namespace_id: 'your-namespace-uuid',
  query_text: 'What database does the user prefer?',
});

API Methods

`ingest(params)`

Store raw content and create an artifact with spans.

const result = await client.ingest({
  namespace_id: 'uuid',
  content: 'Raw text content to store',
  source_type: 'user_input', // or 'document', 'api', etc.
  source_id: 'optional-external-id',
});
// => { artifact_id, span_count, r2_stored }

`extract(params)`

Extract structured assertions from an artifact using LLM.

const result = await client.extract({
  namespace_id: 'uuid',
  artifact_id: 'artifact-uuid',
});
// => { assertions_created, assertion_ids }

`verify(params)`

Run the verification ladder and produce a signed receipt.

const result = await client.verify({
  assertion_id: 'assertion-uuid',
  namespace_id: 'uuid',
});
// => { receipt_id, status, final_confidence, conflicts_found }

`query(params)`

Multi-channel retrieval with intent-aware routing.

const result = await client.query({
  namespace_id: 'uuid',
  query_text: 'What is the user's preferred language?',
  mode: 'current',    // 'current' | 'point_in_time' | 'trusted'
  limit: 10,
  filters: { valid_only: true },
});
// => { assertions, receipts, total, answerable, channels_used }

Structured queries:

const result = await client.query({
  namespace_id: 'uuid',
  query: { subject: 'user:42', predicate: 'prefers' },
});

`receipt(receiptId)`

Retrieve a verification receipt by ID.

const detail = await client.receipt('receipt-uuid');
// => { receipt, assertion, evidence_spans }

`chain(writerPrincipal)`

Get the Merkle chain for a writer.

const chain = await client.chain('agent:billing');
// => { writer_principal, current_hash, assertion_count, recent_assertions }

`compress(params)`

Compress an artifact to IR1 format.

const result = await client.compress({
  namespace_id: 'uuid',
  artifact_id: 'artifact-uuid',
});
// => { encoded_artifact_id, compression_ratio }

`decompress(params)`

Decompress an encoded artifact.

const result = await client.decompress({
  namespace_id: 'uuid',
  encoded_artifact_id: 'encoded-uuid',
});
// => { content, verified }

`challenge(params)`

Challenge an assertion with counter-evidence.

const result = await client.challenge({
  assertion_id: 'assertion-uuid',
  namespace_id: 'uuid',
  reason: 'Contradicted by updated policy',
  counter_evidence: 'Policy v2 states...',
});
// => { challenge_id, status }

`retract(params)`

Retract an assertion.

const result = await client.retract({
  assertion_id: 'assertion-uuid',
  namespace_id: 'uuid',
  reason: 'Information no longer valid',
});
// => { retraction_id, status }

`health(namespaceId)`

Get memory health metrics.

const health = await client.health('namespace-uuid');
// => { namespace_id, total_assertions, verified_count, disputed_count, coverage_score }

Proof Meter

Billing attestation for AI agents. Every transaction signed, chained, and independently verifiable.

// Create a spend authorization
const cap = await client.meter.authorize({
  namespace_id: 'your-namespace-uuid',
  authorizedAgentId: 'agent-alpha',
  maxBudgetCents: 1000,
  scope: { allowedProviders: ['openai', 'anthropic'] },
});

// Submit a spend receipt
const receipt = await client.meter.spend({
  namespace_id: 'your-namespace-uuid',
  capabilityId: cap.capability_id,
  actorId: 'agent-alpha',
  providerId: 'openai',
  usageUnit: 'tokens',
  usageQuantity: 1500,
  costCents: 45,
  occurredAt: new Date().toISOString(),
});
// => { receipt_id, receipt_hash, signature, status: 'verified' }

// Check remaining budget
const budget = await client.meter.budget(cap.capability_id);
// => { spent_cents, remaining_cents, receipt_count, children }

// Verify a receipt (cryptographic integrity check)
const check = await client.meter.verify(receipt.receipt_id);
// => { verified: true, checks: { hash_integrity, signature_valid, chain_continuity, merkle_inclusion } }

// Settle receipts into a Merkle root
const settlement = await client.meter.settle({
  namespace_id: 'your-namespace-uuid',
  capabilityId: cap.capability_id,
});
// => { settlement_id, merkle_root, total_cost_cents, receipt_count }

Real-Time Subscriptions

Subscribe once. Get instant answers.

// Subscribe to your namespace
await client.subscribe(namespaceId);

// Four-tier retrieval — automatically takes the fastest path
const fact = await client.quickQuery(namespaceId, 'user|prefers.drink|morning');

Retrieval speed:

Existence check: 0.01ms (local filter, no network)
Cached facts: <1ms (live in memory via real-time stream)
Direct queries: <5ms (pre-computed state)
Complex queries: <100ms (full retrieval)

Before VerifiedState: 80ms per query, every time. After VerifiedState: 0.01ms to know if a fact exists, <1ms to retrieve it.

New Methods

subscribe(namespaceId) — load filter + cache + start receiving state
unsubscribe() — clean up subscription and clear cache
refreshFilter(namespaceId) — refresh existence filter (call every ~5 min for long-running agents)
quickQuery(namespaceId, slotKey) — four-tier retrieval with automatic fastest path
resync(namespaceId) — catch up on missed deltas

Error Handling

import { VerifiedStateError } from '@verifiedstate/sdk';

try {
  await client.query({ namespace_id: 'uuid', query_text: '...' });
} catch (err) {
  if (err instanceof VerifiedStateError) {
    console.error(err.status, err.message, err.body);
  }
}

License

MIT