TypeScript SDK¶

Official TypeScript/JavaScript client for the CloMan API.

Installation¶

npm install @clomanai/sdk

Requires Node.js 18+ (uses native fetch). Zero runtime dependencies.

Client¶

`CloMan`¶

import { CloMan } from "@clomanai/sdk";

const client = new CloMan("cloman_...", {
  baseUrl: "https://api.cloman.app",  // Default
  timeout: 30000,                      // Milliseconds
  maxRetries: 3,                       // Retries on 5xx
});

Parameter	Type	Default	Description
`apiKey`	`string`	—	Your CloMan API key (required, first argument).
`options.baseUrl`	`string`	`https://api.cloman.app`	API base URL. Override for self-hosted.
`options.timeout`	`number`	`30000`	Request timeout in milliseconds.
`options.maxRetries`	`number`	`3`	Max retries on 5xx server errors.

`client.decide()`¶

const result = await client.decide({
  context: "Should we approve this refund?",
  actionType: "approval",      // Default: "general"
  data: { amount: 49.99 },     // Default: {}
});

Parameter	Type	Default	Description
`context`	`string`	—	The question or situation (required).
`actionType`	`string`	`"general"`	Type of action.
`data`	`Record<string, unknown>`	`{}`	Action-specific structured data.

Returns a Promise<DecisionResponse>.

Types¶

`DecisionRequest`¶

interface DecisionRequest {
  context: string;
  actionType?: string;
  data?: Record<string, unknown>;
}

`DecisionResponse`¶

interface DecisionResponse {
  decisionId: string;
  cloneId: string;
  cloneName: string;
  decision: string;
  reasoning: string;
  confidence: number;
  confidenceLevel: string;
  requiresHumanReview: boolean;
  wasEscalated: boolean;
  alternativesConsidered: Array<Record<string, unknown>>;
  processingTimeMs: number;
  createdAt: string;
}

camelCase conversion

The SDK automatically converts the API's snake_case response fields to camelCase for idiomatic TypeScript usage.

`CloManOptions`¶

interface CloManOptions {
  baseUrl?: string;
  timeout?: number;
  maxRetries?: number;
}

Error Classes¶

All errors extend CloManError:

CloManError
├── AuthenticationError    (401)
├── AuthorizationError     (403)
├── NotFoundError          (404)
├── ValidationError        (422)
├── RateLimitError         (429)  — has .retryAfter
├── ServerError            (5xx)
└── TimeoutError           (timeout)

Every error has these properties:

Property	Type	Description
`message`	`string`	Human-readable error message.
`code`	`string`	Machine-readable error code.
`status`	`number`	HTTP status code.
`details`	`Record<string, unknown>`	Additional error details.
`requestId`	`string \\| undefined`	Request ID for debugging.

Example¶

import {
  CloMan,
  AuthenticationError,
  RateLimitError,
  CloManError,
} from "@clomanai/sdk";

const client = new CloMan("cloman_...");

try {
  const result = await client.decide({ context: "..." });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Auth failed:", error.message);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited, retry after: ${error.retryAfter}s`);
  } else if (error instanceof CloManError) {
    console.error(`API error [${error.code}]:`, error.message);
  }
}

Bundle Formats¶

The SDK ships as:

CJS — dist/index.js (for require())
ESM — dist/index.mjs (for import)
TypeScript declarations — dist/index.d.ts