npm package: @solomonai/agent-api
Description: <div align="center">     <h1 align="center">@solomonai/agent-api</h1>     <h5>`@solomonai/agent-api` is a TypeScript client for Solomon AI Agent services. If you prefer a typed experience over calling HTTP endpoints directly, this SDK is for you.</h5> </d
Author: Andreas Thomas
Latest version: 1.14.1

<div align="center">
    <h1 align="center">@solomonai/agent-api</h1>
    <h5>`@solomonai/agent-api` is a TypeScript client for Solomon AI Agent services. If you prefer a typed experience over calling HTTP endpoints directly, this SDK is for you.</h5>
</div>

<div align="center">
  <a href="https://solomon-ai.app/docs">Documentation</a>
</div>
<br/>

## Installation

```bash
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:

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
// 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

```ts
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

```ts
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

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

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

### Rate Limiting Functions

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

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

### Health Check Functions

```ts
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

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

### Error Response

```ts
{
  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:

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

### Retries

Configure retry behavior for network errors:

```ts
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:

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

### Cache Options

Configure caching behavior:

```ts
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](https://solomon-ai.app/docs)