@truststate/sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MyreneBot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# TrustState Node.js / TypeScript SDK
+
+[![npm version](https://img.shields.io/npm/v/@truststate/sdk.svg)](https://www.npmjs.com/package/@truststate/sdk)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+TypeScript/JavaScript SDK for the [TrustState](https://truststate.apps.trustchainlabs.com) compliance API — validate, audit, and enforce compliance rules on any entity or data record. Built for financial services, AI governance, and regulated industries.
+
+## Install
+
+```bash
+npm install @truststate/sdk
+# or
+yarn add @truststate/sdk
+```
+
+Requires Node.js 18+ (uses native `fetch` and `crypto.randomUUID()`).
+
+## Quickstart
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+// 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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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`
+
+```typescript
+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`
+
+```typescript
+interface BatchResult {
+  batchId: string;
+  total: number;
+  accepted: number;
+  rejected: number;
+  results: ComplianceResult[];
+  feedLabel?: string | null;
+  mock: boolean;
+}
+```
+
+### `CheckItem`
+
+```typescript
+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

package/dist/client.d.ts

@@ -0,0 +1,96 @@
+/**
+ * TrustStateClient — async HTTP client for the TrustState compliance API.
+ *
+ * Uses native fetch (Node 18+) and crypto.randomUUID(). Zero runtime dependencies.
+ *
+ * @example
+ * ```typescript
+ * import { TrustStateClient } from "@truststate/sdk";
+ *
+ * const client = new TrustStateClient({ apiKey: "your-key" });
+ * const result = await client.check("AgentResponse", { text: "Hello!", score: 0.95 });
+ * console.log(result.passed, result.recordId);
+ * ```
+ */
+import type { BatchResult, CheckItem, ComplianceResult, EvidenceItem, TrustStateClientOptions } from "./types.js";
+export declare class TrustStateClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly defaultSchemaVersion;
+    private readonly defaultActorId;
+    private readonly mock;
+    private readonly mockPassRate;
+    private readonly timeoutMs;
+    constructor(options: TrustStateClientOptions);
+    /**
+     * Submit a single record for compliance checking.
+     *
+     * Internally wraps the record in a one-item batch call (POST /v1/write/batch).
+     *
+     * @param entityType - Entity category (e.g. "AgentResponse").
+     * @param data - The record payload to validate.
+     * @param options - Optional overrides for action, entityId, schemaVersion, actorId.
+     * @returns ComplianceResult with pass/fail status and, if passed, a recordId.
+     * @throws TrustStateError on HTTP 4xx/5xx.
+     */
+    check(entityType: string, data: Record<string, unknown>, options?: {
+        action?: string;
+        entityId?: string;
+        schemaVersion?: string;
+        actorId?: string;
+    }): Promise<ComplianceResult>;
+    /**
+     * Submit multiple records for compliance checking in a single API call.
+     *
+     * @param items - Array of CheckItem objects.
+     * @param options - Optional default schemaVersion and actorId for items that omit them.
+     * @returns BatchResult with per-item results and aggregate counts.
+     * @throws TrustStateError on HTTP 4xx/5xx.
+     */
+    checkBatch(items: CheckItem[], options?: {
+        defaultSchemaVersion?: string;
+        defaultActorId?: string;
+        /** Label identifying this feed/source — echoed back on every item result. */
+        feedLabel?: string;
+    }): Promise<BatchResult>;
+    /**
+     * Retrieve an immutable compliance record from the ledger.
+     *
+     * @param recordId - The record ID returned by a previous check() that passed.
+     * @param bearerToken - A valid Bearer token for the TrustState API.
+     * @returns The full record object from the API.
+     * @throws TrustStateError on HTTP 4xx/5xx.
+     */
+    /** Fetch an FX rate oracle evidence item.
+     * @example
+     * const fx = await client.fetchFxRate("MYR", "USD");
+     * const result = await client.checkWithEvidence("SukukBond", data, [fx]);
+     */
+    fetchFxRate(fromCurrency: string, toCurrency: string, providerId?: string, maxAgeSeconds?: number): Promise<EvidenceItem>;
+    /** Fetch a KYC status oracle evidence item. */
+    fetchKycStatus(subjectId: string, providerId?: string, maxAgeSeconds?: number): Promise<EvidenceItem>;
+    /** Fetch a credit score oracle evidence item. */
+    fetchCreditScore(subjectId: string, providerId?: string, maxAgeSeconds?: number): Promise<EvidenceItem>;
+    /** Fetch a sanctions screening oracle evidence item. */
+    fetchSanctions(subjectId: string, providerId?: string, maxAgeSeconds?: number): Promise<EvidenceItem>;
+    /** Submit a compliance check with oracle evidence attached.
+     * @example
+     * const fx = await client.fetchFxRate("MYR", "USD");
+     * const result = await client.checkWithEvidence("SukukBond", payload, [fx]);
+     */
+    checkWithEvidence(entityType: string, data: Record<string, unknown>, evidence: EvidenceItem[], options?: {
+        action?: string;
+        entityId?: string;
+        schemaVersion?: string;
+        actorId?: string;
+    }): Promise<ComplianceResult>;
+    private makeEvidenceItem;
+    private parseEvidenceResponse;
+    verify(recordId: string, bearerToken: string): Promise<unknown>;
+    private get;
+    private post;
+    private parseBatchResponse;
+    private mockSingleResult;
+    private mockBatchResult;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAIpB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAU;IAC/B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,EAAE,uBAAuB;IAc5C;;;;;;;;;;OAUG;IACG,KAAK,CACT,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;KACb,GACL,OAAO,CAAC,gBAAgB,CAAC;IA2B5B;;;;;;;OAOG;IACG,UAAU,CACd,KAAK,EAAE,SAAS,EAAE,EAClB,OAAO,GAAE;QACP,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,6EAA6E;QAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;KACf,GACL,OAAO,CAAC,WAAW,CAAC;IA+BvB;;;;;;;OAOG;IAKH;;;;OAIG;IACG,WAAW,CACf,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,UAAU,SAAe,EACzB,aAAa,SAAM,GAClB,OAAO,CAAC,YAAY,CAAC;IAUxB,+CAA+C;IACzC,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,UAAU,SAAe,EACzB,aAAa,SAAQ,GACpB,OAAO,CAAC,YAAY,CAAC;IASxB,iDAAiD;IAC3C,gBAAgB,CACpB,SAAS,EAAE,MAAM,EACjB,UAAU,SAAkB,EAC5B,aAAa,SAAQ,GACpB,OAAO,CAAC,YAAY,CAAC;IASxB,wDAAwD;IAClD,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,UAAU,SAAoB,EAC9B,aAAa,SAAO,GACnB,OAAO,CAAC,YAAY,CAAC;IASxB;;;;OAIG;IACG,iBAAiB,CACrB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GAC7F,OAAO,CAAC,gBAAgB,CAAC;IAkB5B,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,qBAAqB;IAsBvB,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;YAiCvD,GAAG;YAuBH,IAAI;IAoClB,OAAO,CAAC,kBAAkB;IAkC1B,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,eAAe;CAoBxB"}