@chox/sdk

TypeScript SDK for Chox — AI governance proxy. Evaluate AI tool calls before execution to prevent unintended financial operations, data deletions, and other risky actions.

Why Chox?

As AI agents gain access to external APIs (Stripe, Slack, SQL), they need governance. Chox sits between your agent and those APIs to:

• Evaluate every tool call (financial operations, data deletions, message sends, etc.)
• Classify the action type and risk level
• Return a verdict — allow, block, escalate, or warn — before the agent proceeds
• Log all activity for audit trails

This SDK wraps the POST /api/v1/evaluate endpoint with a clean API, automatic retry on network failures (fail-open), and strict TypeScript types.

Install

npm install @chox/sdk

Quickstart

import { ChoxClient } from "@chox/sdk";

const chox = new ChoxClient({
  baseUrl: "https://chox.example.com",
  token: "chox_token_...",
});

// Evaluate before a risky operation
const verdict = await chox.evaluate({
  tool: "stripe.create_charge",
  arguments: { amount: 5000, currency: "USD" },
  context: { user_id: "user_123" },
});

if (verdict.verdict === "allow") {
  // Safe to proceed
  await stripe.charges.create({ amount: 5000, currency: "USD" });
} else if (verdict.verdict === "block") {
  throw new Error(`Action blocked: ${verdict.reason}`);
} else if (verdict.verdict === "escalate") {
  // Requires human approval
  await sendToApprovalQueue(verdict.reason);
}

Configuration

const chox = new ChoxClient({
  baseUrl: "https://chox.example.com",  // Required: Your Chox gateway URL
  token: "chox_token_...",              // Required: Caller token or admin key
  failOpen: true,                        // Optional: Default true. If Chox is unreachable, return allow verdict
  timeoutMs: 5000,                       // Optional: Default 5000ms. Request timeout
});

Authentication

• Caller token (chox_token_...): Use this in production. Tied to a specific AI system in Chox, can only evaluate with that token.
• Admin key (chox_admin_...): Use this for setup/testing. Can manage projects, integrations, and callers, but not recommended for ongoing agent evaluation.

Verdicts

The evaluate() method returns a verdict with these fields:

interface EvaluateResponse {
  request_id: string;                    // Unique request ID for audit logging
  verdict: "allow" | "block" | "escalate" | "warn";
  action_type: "read" | "write" | "delete" | "financial" | "unknown";
  risk_score: number;                    // 0 (safe) to 1 (critical)
  reason: string;                        // Human-readable explanation
  evaluated_at: string;                  // ISO 8601 timestamp
}

Verdict meanings:

• allow — Safe to proceed
• block — Blocked by policy; do not proceed
• escalate — Requires human approval (e.g., large transfer)
• warn — Proceed with caution; log prominently

Error Handling

import { ChoxError, ChoxNetworkError } from "@chox/sdk";

try {
  const verdict = await chox.evaluate({ tool: "stripe.create_charge" });
} catch (err) {
  if (err instanceof ChoxError) {
    // API returned non-2xx status
    console.error(`Chox API error ${err.status}: ${err.body}`);
  } else if (err instanceof ChoxNetworkError) {
    // Network timeout or unreachable
    console.error(`Network error: ${err.message}`);
    if (err.cause) console.error(`Caused by:`, err.cause);
  }
}

Note: If failOpen: true (default), network errors and timeouts return an allow verdict instead of throwing, so your agent never gets blocked by Chox being temporarily down.

API Reference

Evaluate

const verdict = await chox.evaluate({
  tool: string,                           // Dot-notation tool name, e.g., "stripe.create_charge"
  arguments?: Record<string, unknown>,   // Tool arguments as JSON
  caller_token?: string,                 // Optional override caller token
  context?: Record<string, unknown>,     // Optional context (user_id, session, etc.)
});

Projects

chox.projects.create({ name: string, slug: string })  // Create a project
chox.projects.get()                                    // Get authenticated project

Callers (AI Systems)

chox.callers.create({ name: string, description?: string })  // Register an AI system
chox.callers.list()                                           // List all callers
chox.callers.delete(id: string)                              // Remove a caller

Integrations

chox.integrations.create({               // Register an external API
  name: string,                          // e.g., "stripe"
  integration_type: "http" | "mcp",     // HTTP proxy or MCP server
  destination_url: string,               // e.g., "https://api.stripe.com"
})
chox.integrations.list()                 // List all integrations
chox.integrations.delete(id: string)     // Remove an integration

Logs

chox.logs.list({                          // Query evaluation logs
  caller_id?: string,
  integration?: string,
  action_type?: string,
  start?: string,  // ISO 8601 timestamp
  end?: string,    // ISO 8601 timestamp
  limit?: number,
  offset?: number,
})
chox.logs.get(id: string)                 // Get a specific log entry

Stats

chox.stats.actions({ start?, end? })     // Breakdown by action type
chox.stats.hourly({ start?, end? })      // Hourly activity counts
chox.stats.integrations({ start?, end? }) // Per-integration traffic
chox.stats.total()                        // Total request count

License

MIT