Installation

npm install @solomonai/agent-api

Quickstart

1. Create a new Solomon AI Root Key in your dashboard.
2. Use the root key to initialize the client:

import { SolomonAIAgent } from "@solomonai/agent-api";

const client = new SolomonAIAgent({ rootKey: "<SOLOMON_ROOT_KEY>" });

Important: Always keep your root key safe and reset it if you suspect it has been compromised.

Usage

Vault Operations

Encrypting Data

const { result, error } = await client.vault.encrypt({
  data: "sensitive information",
  keyring: "production-keyring"
});

if (error) {
  console.error(error.message);
  return;
}

console.log("Encrypted:", result.encrypted);
console.log("Key ID:", result.keyId);

Decrypting Data

const { result, error } = await client.vault.decrypt({
  encrypted: "encrypted-string",
  keyring: "production-keyring"
});

if (error) {
  console.error(error.message);
  return;
}

console.log("Decrypted:", result.plaintext);

Bulk Encryption

const { result, error } = await client.vault.encryptBulk({
  data: ["secret1", "secret2", "secret3"],
  keyring: "production-keyring"
});

if (error) {
  console.error(error.message);
  return;
}

result.encrypted.forEach((item, index) => {
  console.log(`Item ${index}: ${item.encrypted} (Key: ${item.keyId})`);
});

Rate Limiting

Single Rate Limit Check

const { result, error } = await client.ratelimit.limit({
  identifier: "user_123",
  limit: 100,
  duration: 60000, // 1 minute in milliseconds
  cost: 1
});

if (error) {
  console.error(error.message);
  return;
}

if (!result.success) {
  console.log("Rate limit exceeded!");
  console.log(`Try again in ${result.reset - Date.now()}ms`);
  return;
}

console.log(`Remaining: ${result.remaining}/${result.limit}`);

Multiple Rate Limits

const { result, error } = await client.ratelimit.multiLimit({
  ratelimits: [
    {
      identifier: "user_123",
      limit: 100,
      duration: 60000,
      cost: 1
    },
    {
      identifier: "api_key_456", 
      limit: 1000,
      duration: 3600000, // 1 hour
      cost: 2
    }
  ]
});

if (error) {
  console.error(error.message);
  return;
}

result.ratelimits.forEach((rl, index) => {
  if (!rl.success) {
    console.log(`Rate limit ${index} exceeded!`);
  } else {
    console.log(`Rate limit ${index}: ${rl.remaining}/${rl.limit} remaining`);
  }
});

Advanced: Rate Limit Leases

// Reserve tokens with a lease
const { result, error } = await client.ratelimit.limit({
  identifier: "user_123",
  limit: 100,
  duration: 60000,
  lease: {
    cost: 10, // Reserve 10 tokens
    timeout: Date.now() + 30000 // 30 second timeout
  }
});

if (error || !result.success) {
  console.log("Rate limit exceeded or error occurred");
  return;
}

// Do some processing...
const actualCost = 5; // Only used 5 tokens

// Commit the lease with actual cost
await client.ratelimit.commitLease({
  lease: result.lease,
  cost: actualCost
});

Events

Creating Events

const ndjsonEvents = `{"event": "user_login", "userId": "123"}
{"event": "page_view", "page": "/dashboard"}`;

const { result, error } = await client.events.create(ndjsonEvents);

if (error) {
  console.error(error.message);
  return;
}

console.log(`Processed ${result.successful_rows} events`);
console.log(`Quarantined ${result.quarantined_rows} events`);

Health Checks

Service Liveness

const { result, error } = await client.health.liveness();

if (error) {
  console.error("Service is not healthy:", error.message);
  return;
}

console.log("Service status:", result.message);

Standalone Functions

For convenience, you can also import standalone functions:

Vault Functions

import { encrypt, decrypt, encryptBulk } from "@solomonai/agent-api/vault";

const { result } = await encrypt({
  data: "secret",
  keyring: "my-keyring"
});

Rate Limiting Functions

import { rateLimit, multiRateLimit, commitLease } from "@solomonai/agent-api/ratelimit";

const { result } = await rateLimit({
  identifier: "user_123",
  limit: 100,
  duration: 60000
});

Health Check Functions

import { checkLiveness } from "@solomonai/agent-api/verify";

const { result } = await checkLiveness();

Response Format

All methods return either an error or a result field, never both and never none. This approach helps with proper error handling.

Success Response

{
  result: T; // The result depends on what method you called
}

Error Response

{
  error: {
    code: string;
    message: string;
    docs: string; // URL to relevant documentation  
    requestId: string;
  }
}

Configuration Options

Base URL

You can customize the base URL for all requests:

const client = new SolomonAIAgent({
  rootKey: "<SOLOMON_ROOT_KEY>",
  baseUrl: "https://my.domain",
});

Retries

Configure retry behavior for network errors:

const client = new SolomonAIAgent({
  rootKey: "<SOLOMON_ROOT_KEY>",
  retry: {
    attempts: 3,
    backoff: (retryCount) => retryCount * 1000,
  },
});

Disable Telemetry

To opt out of anonymous telemetry data collection:

const client = new SolomonAIAgent({
  rootKey: "<SOLOMON_ROOT_KEY>",
  disableTelemetry: true,
});

Cache Options

Configure caching behavior:

const client = new SolomonAIAgent({
  rootKey: "<SOLOMON_ROOT_KEY>",
  cache: "no-cache", // or "default", "reload", etc.
});

Features

✅ Vault Operations - Encrypt, decrypt, and bulk encrypt data
✅ Rate Limiting - Advanced rate limiting with lease support
✅ Event Processing - NDJSON event ingestion
✅ Health Checks - Service liveness monitoring
✅ TypeScript First - Fully typed with OpenAPI schema
✅ Error Handling - Consistent error response format
✅ Retry Logic - Configurable retry behavior
✅ Telemetry - Optional usage analytics

Documentation

Read the full documentation