Skip to main content

TypeScript Control-Plane Quickstart

Use @keeptrusts/control-plane from trusted server environments when you need privileged Keeptrusts APIs such as decision events, trail verification, exports, and wallet reads.

Use this page when​

  • You need decision events or request-level spend attribution.
  • You need trail events, digests, public-key retrieval, or verification helpers.
  • You are building backend automation and can safely hold a bearer token.

Install​

npm install @keeptrusts/control-plane

Create a server-only client​

import {
  KeeptrustsControlPlane,
  getEventCostAttribution,
  listEvents,
} from "@keeptrusts/control-plane";

const client = new KeeptrustsControlPlane({
  baseUrl: "https://api.keeptrusts.example",
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN,
});

const response = await listEvents(client, {
  since: "2026-05-31T00:00:00Z",
  agentId: "agent-support-web",
  limit: 10,
});

for (const event of response.events) {
  const attribution = getEventCostAttribution(event);
  console.log(event.request_id, attribution.total_cost_usd, attribution.source_spend_log_id);
}

Why this package is server-only​

The package enforces a server-only runtime boundary and throws a configuration error if it is bundled into browser code.

Use it for:

  • privileged event reads
  • evidence and trail workflows
  • exports and wallet administration
  • backend automation tied to bearer-token auth

Event detail with citations​

import { KeeptrustsControlPlane, getEvent } from "@keeptrusts/control-plane";

const client = new KeeptrustsControlPlane({ bearerToken: process.env.KEEPTRUSTS_API_TOKEN });
const event = await getEvent(client, "evt_01J...");

console.log(event.request_id, event.citations.length);
console.log(event.event_cost_attribution.source_spend_log_id);

Use event reads for request-level spend attribution. Wallet reads do not replace event-level cost data.

Evidence and verification flow​

import {
  buildEvidenceBundle,
  exportBundleAsZip,
  KeeptrustsControlPlane,
  downloadDigest,
  getPublicKey,
  listDigests,
  verifyTrail,
} from "@keeptrusts/control-plane";

const client = new KeeptrustsControlPlane({ bearerToken: process.env.KEEPTRUSTS_API_TOKEN });

const digests = await listDigests(client, {
  startTime: "2026-05-31T00:00:00Z",
  endTime: "2026-05-31T23:59:59Z",
});

const digest = await downloadDigest(client, digests.digests[0].digest_id);
const publicKey = await getPublicKey(client);
const verification = await verifyTrail(client, {
  startTime: "2026-05-31T00:00:00Z",
  endTime: "2026-05-31T23:59:59Z",
  deepVerify: false,
});

console.log(digest.storage_key, publicKey.kid, verification.chain_integrity);

const bundle = await buildEvidenceBundle("req_123", { client });
const archive = exportBundleAsZip(bundle);

Doctor checks​

import { runDoctor } from "@keeptrusts/control-plane";

const report = await runDoctor({
  baseUrl: process.env.KEEPTRUSTS_API_URL,
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN,
  gatewayUrl: process.env.KEEPTRUSTS_GATEWAY_URL,
  mcpBaseUrl: `${process.env.KEEPTRUSTS_GATEWAY_URL}/mcp`,
  expectedTokenScopes: ["events:read", "org.trail:read"],
});

Wallet reads are for balance workflows​

import {
  KeeptrustsControlPlane,
  getWalletBalance,
  listWallets,
} from "@keeptrusts/control-plane";

const client = new KeeptrustsControlPlane({ bearerToken: process.env.KEEPTRUSTS_API_TOKEN });

const balance = await getWalletBalance(client);
const wallets = await listWallets(client);

console.log(balance.effective_available_balance, wallets.wallets.length);

Use these APIs for balance and transaction workflows only. For request-level spend, go back to the event APIs.

Boundary checklist​

  • ✅ server process, API route, worker, or backend automation
  • ✅ bearer token available through secure server-side configuration
  • ❌ browser bundle or client component
  • ❌ frontend code that only needs gateway-routed inference

Next steps​

For AI systems​

  • Package: @keeptrusts/control-plane.
  • Runtime: server-only.
  • Use KeeptrustsControlPlane plus helpers such as listEvents(), getEvent(), listDigests(), downloadDigest(), and verifyTrail().
  • Request-level spend attribution comes from event_cost_attribution and source_spend_log_id.

For engineers​

  • Never bundle this package into browser code.
  • Use event reads for spend attribution and citations.
  • Use trail and evidence helpers for audit-grade verification workflows.
  • Use wallet helpers for balances and transactions, not per-request reporting.