@truststate/sdk 0.2.0

package/dist/middleware.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * TrustState middleware for Express and Next.js.
+ *
+ * @example Express
+ * ```typescript
+ * import express from "express";
+ * import { TrustStateClient, trustStateMiddleware } from "@truststate/sdk";
+ *
+ * const app = express();
+ * const client = new TrustStateClient({ apiKey: "your-key" });
+ * app.use(express.json());
+ * app.use(trustStateMiddleware(client));
+ * ```
+ *
+ * @example Next.js API route
+ * ```typescript
+ * import { withCompliance } from "@truststate/sdk";
+ * import { client } from "@/lib/truststate";
+ *
+ * export default withCompliance(client, "AgentResponse", async (req, res) => {
+ *   res.json({ message: "Compliant response" });
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trustStateMiddleware = trustStateMiddleware;
+exports.withCompliance = withCompliance;
+// ---------------------------------------------------------------------------
+// Express middleware
+// ---------------------------------------------------------------------------
+/**
+ * Express middleware that gates requests on TrustState compliance.
+ *
+ * Reads X-Compliance-Entity-Type and X-Compliance-Action headers.
+ * If X-Compliance-Entity-Type is present (or defaultEntityType is set),
+ * the request body is submitted to TrustState before the request proceeds.
+ *
+ * Failed checks return HTTP 422. Passed checks attach X-Compliance-Record-Id
+ * to the response headers.
+ */
+function trustStateMiddleware(client, options = {}) {
+    const { defaultEntityType, defaultAction = "CREATE", entityIdHeader = "X-Compliance-Entity-Id", } = options;
+    return async function (req, res, next) {
+        const entityType = req.headers["x-compliance-entity-type"] ??
+            defaultEntityType;
+        // Pass through if no entity type configured
+        if (!entityType) {
+            next();
+            return;
+        }
+        const action = req.headers["x-compliance-action"] ?? defaultAction;
+        const entityId = req.headers[entityIdHeader.toLowerCase()];
+        const data = req.body ?? {};
+        try {
+            const result = await client.check(entityType, data, {
+                action,
+                entityId: entityId ?? undefined,
+            });
+            if (!result.passed) {
+                res.status(422).json({
+                    error: "Compliance check failed",
+                    failReason: result.failReason,
+                    failedStep: result.failedStep,
+                    entityId: result.entityId,
+                });
+                return;
+            }
+            // Attach record ID to response for downstream use
+            if (result.recordId) {
+                res.setHeader("X-Compliance-Record-Id", result.recordId);
+            }
+            next();
+        }
+        catch (err) {
+            res.status(503).json({
+                error: "Compliance service unavailable",
+                detail: err.message,
+            });
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Next.js route handler wrapper
+// ---------------------------------------------------------------------------
+/**
+ * Wraps a Next.js API route handler with TrustState compliance checking.
+ *
+ * The request body is submitted to TrustState before the handler runs.
+ * Returns 422 if the check fails.
+ *
+ * @param client - TrustStateClient instance.
+ * @param entityType - The TrustState entity type to validate against.
+ * @param handler - The Next.js route handler to wrap.
+ * @param options - Optional action and entityIdHeader overrides.
+ */
+function withCompliance(client, entityType, handler, options = {}) {
+    const { action = "CREATE", entityIdHeader = "x-compliance-entity-id" } = options;
+    return async function (req, res) {
+        const entityId = req.headers[entityIdHeader];
+        const data = req.body ?? {};
+        try {
+            const result = await client.check(entityType, data, {
+                action,
+                entityId: entityId ?? undefined,
+            });
+            if (!result.passed) {
+                res.status(422).json({
+                    error: "Compliance check failed",
+                    failReason: result.failReason,
+                    failedStep: result.failedStep,
+                    entityId: result.entityId,
+                });
+                return;
+            }
+            if (result.recordId) {
+                res.setHeader("X-Compliance-Record-Id", result.recordId);
+            }
+            await handler(req, res);
+        }
+        catch (err) {
+            res.status(503).json({
+                error: "Compliance service unavailable",
+                detail: err.message,
+            });
+        }
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * TrustState SDK — TypeScript type definitions.
+ */
+/** Result of a single compliance check. */
+export interface ComplianceResult {
+    /** True if all compliance checks passed. */
+    passed: boolean;
+    /** Immutable ledger record ID — only present when passed=true. */
+    recordId?: string;
+    /** Unique API request identifier (useful for support/debugging). */
+    requestId: string;
+    /** The entity identifier submitted (caller-supplied or auto-generated). */
+    entityId: string;
+    /** Human-readable reason for failure — only present when passed=false. */
+    failReason?: string;
+    /** Numeric step that failed. 8 = schema validation, 9 = policy check. */
+    failedStep?: number;
+    /** Feed label from the batch request — useful for identifying source feeds. */
+    feedLabel?: string | null;
+    /** True when this result was synthesised locally in mock mode (no HTTP call). */
+    mock: boolean;
+}
+/** Aggregated result for a batch compliance submission. */
+export interface BatchResult {
+    /** Unique identifier for this batch request. */
+    batchId: string;
+    /** Total number of items submitted. */
+    total: number;
+    /** Number of items that passed compliance checks. */
+    accepted: number;
+    /** Number of items that failed compliance checks. */
+    rejected: number;
+    /** Per-item results in the same order as the submitted items. */
+    results: ComplianceResult[];
+    /** Feed label echoed from the batch request. */
+    feedLabel?: string | null;
+    /** True when running in mock mode (no HTTP calls made). */
+    mock: boolean;
+}
+/** A single item in a batch submission. */
+export interface CheckItem {
+    /** The TrustState entity type (e.g. "AgentResponse", "Transaction"). */
+    entityType: string;
+    /** The record payload to validate. */
+    data: Record<string, unknown>;
+    /** Action being performed. Defaults to "CREATE". */
+    action?: string;
+    /** Optional stable entity identifier. Auto-generated if omitted. */
+    entityId?: string;
+    /** Schema version to validate against. Uses client default if omitted. */
+    schemaVersion?: string;
+    /** Actor ID for the audit trail. Uses client default if omitted. */
+    actorId?: string;
+}
+/** A single oracle evidence item to submit alongside a compliance write. */
+export interface EvidenceItem {
+    /** Unique ID for this evidence item. Auto-generated if not set. */
+    evidenceId: string;
+    /** Registered oracle provider ID (e.g. "reuters-fx"). */
+    providerId: string;
+    /** Oracle provider type (e.g. "fx_rate", "kyc_status"). */
+    providerType: string;
+    /** Key-value subject descriptor (e.g. { from: "MYR", to: "USD" }). */
+    subject: Record<string, unknown>;
+    /** The oracle-reported value. */
+    observedValue: string | number;
+    /** ISO-8601 timestamp when the value was observed by the oracle. */
+    observedAt: string;
+    /** ISO-8601 timestamp when you fetched this value. Defaults to now. */
+    retrievedAt: string;
+    /** Maximum acceptable age of this evidence in seconds. Default 300. */
+    maxAgeSeconds: number;
+    /** Optional sha256:<hex> hash of the raw proof document. */
+    proofHash?: string;
+    /** Optional URL for the raw proof document (background verified by TrustState). */
+    rawProofUri?: string;
+    /** Optional cryptographic attestation from the oracle provider. */
+    attestation?: {
+        type: string;
+        algorithm: string;
+        signature: string;
+    };
+    /** True when synthesised locally in mock mode. */
+    mock?: boolean;
+}
+/** Options for check_batch / checkBatch. */
+export interface BatchOptions {
+    /** Optional label identifying this feed/source (e.g. "core-banking-feed"). */
+    feedLabel?: string;
+    /** Override default schema version for this batch. */
+    defaultSchemaVersion?: string;
+    /** Override default actor ID for this batch. */
+    defaultActorId?: string;
+}
+/** Constructor options for TrustStateClient. */
+export interface TrustStateClientOptions {
+    /** Your TrustState API key (sent as X-API-Key header). */
+    apiKey: string;
+    /** Override the default API base URL. */
+    baseUrl?: string;
+    /**
+     * Default schema version applied when not specified per-call.
+     * If omitted, the server auto-resolves to the active schema for each entity type.
+     */
+    defaultSchemaVersion?: string;
+    /** Default actor ID for the audit trail. */
+    defaultActorId?: string;
+    /**
+     * Enable mock mode. When true, all HTTP calls are skipped and
+     * synthetic results are returned locally.
+     */
+    mock?: boolean;
+    /**
+     * Probability (0.0–1.0) that a mock check returns passed=true.
+     * 1.0 = always pass, 0.0 = always fail.
+     */
+    mockPassRate?: number;
+    /** HTTP request timeout in milliseconds. */
+    timeoutMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * TrustState SDK — TypeScript type definitions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@truststate/sdk",
+  "version": "0.2.0",
+  "description": "TypeScript/JavaScript SDK for TrustState compliance validation",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "src", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": ["truststate", "compliance", "AI governance", "audit", "fintech"],
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5",
+    "@types/node": "^20",
+    "jest": "^29",
+    "@types/jest": "^29",
+    "ts-jest": "^29"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MyreneBot/truststate-js"
+  },
+  "homepage": "https://trustchainlabs.com",
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    },
+    "testMatch": ["**/tests/**/*.test.ts"]
+  }
+}