TrustState Node.js / TypeScript SDK

TypeScript/JavaScript SDK for the TrustState compliance API — validate, audit, and enforce compliance rules on any entity or data record. Built for financial services, AI governance, and regulated industries.

Install

npm install @truststate/sdk
# or
yarn add @truststate/sdk

Requires Node.js 18+ (uses native fetch and crypto.randomUUID()).

Quickstart

import { TrustStateClient } from "@truststate/sdk";

const client = new TrustStateClient({ apiKey: "ts_your_api_key" });

const result = await client.check("SukukBond", {
  id: "BOND-001",
  issuerId: "ISS-001",
  currency: "MYR",
  faceValue: 5_000_000,
  maturityDate: "2030-06-01",
  status: "DRAFT",
});

if (result.passed) {
  console.log("✅ Passed — record ID:", result.recordId);
} else {
  console.log("❌ Failed —", result.failReason, `(step ${result.failedStep})`);
}

Batch Writes

Submit multiple records in a single API call. Useful for feed-based pipelines.

const result = await client.checkBatch(
  [
    { entityType: "SukukBond", data: { id: "BOND-001", ... } },
    { entityType: "SukukBond", data: { id: "BOND-002", ... } },
    { entityType: "SukukBond", data: { id: "BOND-003", ... } },
  ],
  {
    feedLabel: "core-banking-feed",  // echoed on every item result
  }
);

console.log(`Accepted: ${result.accepted}/${result.total}`);
result.results.forEach((item) => {
  console.log(`  ${item.entityId}: ${item.passed ? "✅" : "❌"} ${item.feedLabel}`);
});

BYOP Evidence (Oracle Data)

Attach oracle evidence to compliance checks — FX rates, KYC status, credit scores, sanctions screening.

// Fetch evidence from registered oracle providers
const fx    = await client.fetchFxRate("MYR", "USD");
const kyc   = await client.fetchKycStatus("actor-jasim");
const score = await client.fetchCreditScore("actor-jasim");

// Submit with evidence attached
const result = await client.checkWithEvidence(
  "SukukBond",
  { id: "BOND-001", issuerId: "ISS-001", currency: "MYR", faceValue: 5_000_000 },
  [fx, kyc, score],
);

Mock Mode

Test without making any API calls. Useful for unit tests and local development.

const client = new TrustStateClient({
  apiKey: "any",
  mock: true,
  mockPassRate: 0.8,   // 80% of checks will pass
});

const result = await client.check("SukukBond", { id: "TEST-001", ... });
console.log(result.mock);   // true

Express Middleware

Automatically validate incoming request bodies against TrustState policies.

import express from "express";
import { TrustStateMiddleware } from "@truststate/sdk";

const app = express();

app.use(
  TrustStateMiddleware({
    apiKey: "ts_your_api_key",
    entityType: "AgentResponse",
    extractData: (req) => req.body,
  })
);

Configuration

| Option | Type | Default | Description | |---|---|---|---| | apiKey | string | required | Your TrustState API key | | baseUrl | string | production URL | Override the API base URL | | defaultSchemaVersion | string | auto-resolved | Schema version (auto-resolved by server if omitted) | | defaultActorId | string | "" | Actor ID for the audit trail | | mock | boolean | false | Enable mock mode (no HTTP calls) | | mockPassRate | number | 1.0 | Pass probability in mock mode (0.0–1.0) | | timeoutMs | number | 30000 | HTTP timeout in milliseconds |

API Reference

check(entityType, data, options?)

Submit a single record for compliance checking.

const result = await client.check("SukukBond", data, {
  action: "upsert",
  entityId: "BOND-001",
  schemaVersion: "1.0",
  actorId: "core-banking-feed",
});

Returns: Promise<ComplianceResult>

checkBatch(items, options?)

Submit up to 500 records in a single call.

const result = await client.checkBatch(items, {
  feedLabel: "core-banking-feed",
  defaultActorId: "core-banking-feed",
});

Returns: Promise<BatchResult>

checkWithEvidence(entityType, data, evidence, options?)

Submit a record with oracle evidence attached.

Returns: Promise<ComplianceResult>

fetchFxRate(from, to, options?)

fetchKycStatus(subjectId, options?)

fetchCreditScore(subjectId, options?)

fetchSanctions(subjectId, options?)

Fetch oracle evidence items from registered providers.

Returns: Promise<EvidenceItem>

verify(recordId, bearerToken)

Retrieve an immutable compliance record from the ledger.

Returns: Promise<Record<string, unknown>>

Types

ComplianceResult

interface ComplianceResult {
  passed: boolean;
  recordId?: string;       // present when passed=true
  requestId: string;
  entityId: string;
  failReason?: string;     // present when passed=false
  failedStep?: number;     // 8=schema validation, 9=policy check
  feedLabel?: string | null;
  mock: boolean;
}

BatchResult

interface BatchResult {
  batchId: string;
  total: number;
  accepted: number;
  rejected: number;
  results: ComplianceResult[];
  feedLabel?: string | null;
  mock: boolean;
}

CheckItem

interface CheckItem {
  entityType: string;
  data: Record<string, unknown>;
  action?: string;           // default "upsert"
  entityId?: string;         // auto-generated if omitted
  schemaVersion?: string;    // auto-resolved if omitted
  actorId?: string;
}

Requirements

• Node.js 18+
• No external runtime dependencies (uses native fetch, crypto)

License

MIT © Trustchain Labs