npm package: @runtimeai/sdk
Description: RuntimeAI Platform SDK — Govern, secure, and observe AI agents at scale
Author: RuntimeAI
Latest version: 1.0.0

# @runtimeai/sdk

Official TypeScript SDK for the **RuntimeAI Control Plane** — govern, secure, and observe AI agents at scale.

## Installation

```bash
npm install @runtimeai/sdk
```

## Quick Start

```typescript
import { RuntimeAI } from '@runtimeai/sdk';

const client = new RuntimeAI({
  apiUrl: 'https://api.rt19.runtimeai.io',
  apiKey: process.env.RUNTIMEAI_API_KEY!,
});

// Register an AI agent
const agent = await client.agents.register({
  name: 'contract-analyzer',
  type: 'langchain',
  owner: 'ml-team@company.com',
  risk_level: 'medium',
});
console.log(`Agent registered: ${agent.id}`);

// Discover shadow AI usage
const { findings } = await client.discovery.listFindings();
console.log(`Found ${findings.length} shadow AI instances`);

// Track costs
await client.finops.reportUsage({
  agent_id: agent.id,
  model: 'gpt-4',
  provider: 'openai',
  input_tokens: 1500,
  output_tokens: 800,
  cost_usd: 0.045,
});

// Check compliance posture
const { frameworks } = await client.compliance.listFrameworks();
for (const fw of frameworks) {
  console.log(`${fw.name}: ${fw.compliance_pct}% compliant`);
}
```

## Authentication

### API Key

```typescript
const client = new RuntimeAI({
  apiUrl: 'https://api.your-pod.runtimeai.io',
  apiKey: 'your-api-key', // X-API-Key header
});
```

### JWT Token

```typescript
const client = new RuntimeAI({
  apiUrl: 'https://api.your-pod.runtimeai.io',
  authToken: 'your-jwt-token', // Authorization: Bearer header
  tenantId: 'your-tenant-id',  // X-Tenant-ID header
});
```

## Available Clients

| Client | Methods |
|--------|---------|
| `client.agents` | `register`, `list`, `get`, `update`, `killSwitch`, `getTrustScore`, `heartbeat` |
| `client.discovery` | `listFindings`, `triageFinding`, `listScanners`, `configureScanner`, `ingest` |
| `client.finops` | `reportUsage`, `getUsageSummary`, `listBudgets`, `setBudget`, `getCostAttribution` |
| `client.policies` | `listGuardrails`, `createGuardrail`, `listSodRules`, `listConditionalAccess`, `evaluate` |
| `client.mcp` | `listTools`, `registerTool`, `invokeTool`, `listConnections`, `getTopology` |
| `client.compliance` | `listFrameworks`, `listGaps`, `uploadEvidence`, `listRiskScores` |
| `client.audit` | `list`, `search`, `get` |

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiUrl` | `string` | — | **Required.** Control Plane API URL |
| `apiKey` | `string` | — | API key (X-API-Key header) |
| `authToken` | `string` | — | JWT token (Bearer header) |
| `tenantId` | `string` | — | Tenant ID for multi-tenant ops |
| `timeout` | `number` | `30000` | HTTP timeout in ms |
| `maxRetries` | `number` | `2` | Max retries on 5xx errors |

## Error Handling

```typescript
import { RuntimeAI, RuntimeAIError } from '@runtimeai/sdk';

try {
  const agent = await client.agents.get('nonexistent-id');
} catch (error) {
  if (error instanceof RuntimeAIError) {
    console.error(`API Error: ${error.statusCode} ${error.code} — ${error.message}`);
  }
}
```

## Requirements

- Node.js >= 18.0.0 (uses native `fetch`)
- Zero runtime dependencies

## License

MIT © [RuntimeAI](https://runtimeai.io)