TypeScript SDK

The TypeScript SDK (@kaplaix/sdk-ts) provides a type-safe client for instrumenting Node.js and Deno agents.

Requirements

Node.js >= 18 (uses native fetch and crypto.randomUUID)

Installation


npm install @kaplaix/sdk-ts
# or
pnpm add @kaplaix/sdk-ts

Quick start


import { KaplaixClient } from "@kaplaix/sdk-ts";
 
const client = new KaplaixClient({ apiKey: "al_live_..." });
const session = client.session({ agentId: "my-agent" });
 
await session.logToolCall({
  toolName: "web_search",
  argumentsHash: "sha256-of-args",
  responseStatus: 200,
});
 
await session.end();
await client.shutdown();

Client options

Option	Type	Default	Description
`apiKey`	`string`	required	Tenant API key (`al_live_...`)
`baseUrl`	`string`	`https://api.kaplaix.com`	API base URL
`timeout`	`number`	`10000`	Request timeout in ms
`retries`	`number`	`3`	Retry attempts on transient errors
`flushOnExit`	`boolean`	`true`	Register `beforeExit`/`SIGTERM` handlers
`metadata.agentVersion`	`string`	—	Your agent’s version string
`metadata.framework`	`string`	—	AI framework name
`guardian`	`GuardianConfig`	—	Enable Guardian Mode

Creating sessions


const session = client.session({
  agentId: "my-agent",
  sessionId: "optional-custom-id", // UUID generated if absent
  traceId: "trace-123",            // optional distributed trace ID
  runId: "run-456",                // optional execution run ID
  agentVersion: "1.2.0",           // optional agent version
  initiatorType: "human",          // optional: "human" | "agent" | "system"
  initiatorId: "user-42",          // optional initiator identifier
});

Event helpers

Tool call


await session.logToolCall({
  toolName: "database_query",
  argumentsHash: "sha256-hex",   // hash of args — never log raw args
  responseStatus: 200,           // HTTP status or exit code
  endpoint: "/api/query",        // optional
});

Data movement


await session.logDataMovement({
  operation: "export",           // "read" | "write" | "delete" | "export"
  objectIds: ["record-001"],
  diffSummary: "Exported 1 record",
});

Approval


await session.logApproval({
  approverId: "user-42",
  scope: "delete:crm:customers:bulk",
  decision: "approved",          // "approved" | "rejected"
});

Environment


await session.logEnvironment({
  isSandbox: false,
  networkSegment: "prod-vpc",
  workspace: "production-cluster",
});

Raw event

For categories without a typed helper:


await session.logEvent({
  category: "reasoning",
  payload: { summary: "Decided to proceed with deletion" },
});

Guardian Mode

Guardian Mode adds pre-execution policy checks. Use checkThen* methods instead of log*:


const client = new KaplaixClient({
  apiKey: "al_live_...",
  guardian: {
    mode: "require_approval",    // "log_only" | "block" | "require_approval"
    approvalTimeoutMs: 120_000,  // 2 minutes (default)
    pollIntervalMs: 3_000,       // 3 seconds (default)
    failOnCircuitOpen: false,    // fail-open (default)
  },
});
 
const session = client.session({ agentId: "my-agent" });
 
// Checks policy before logging
await session.checkThenLogToolCall({
  toolName: "database_query",
  argumentsHash: "sha256-hex",
  responseStatus: 200,
});

You can override or disable Guardian Mode per session:


// Disable for this session
const session = client.session({ agentId: "my-agent", guardian: null });
 
// Override mode for this session
const session = client.session({
  agentId: "my-agent",
  guardian: { mode: "block" },
});

See the Guardian API reference for full details.

Retry behavior

The SDK retries on HTTP 429, 502, 503, and 504 using exponential backoff with full jitter. Non-retryable errors (4xx) are thrown immediately.

Error handling


import {
  KaplaixError,
  KaplaixNetworkError,
  KaplaixTimeoutError,
} from "@kaplaix/sdk-ts";
 
try {
  await session.logToolCall({ toolName: "tool", argumentsHash: "hash" });
} catch (err) {
  if (err instanceof KaplaixError) {
    console.error("API error:", err.statusCode, err.body);
  } else if (err instanceof KaplaixTimeoutError) {
    console.error("Request timed out");
  } else if (err instanceof KaplaixNetworkError) {
    console.error("Network error:", err.cause);
  }
}