npm package: @reziiix-ai/sdk
Description: Official SDK for the REZIIIX AI Governance Platform — scan agent actions, enforce policies, and verify compliance receipts.
Author: REZIIIX PTE LTD
Latest version: 1.0.0

# @reziiix/sdk

Official SDK for the **REZIIIX AI Governance Platform**. Scan agent actions, enforce policies, detect PII, and verify compliance receipts — all with a single API call.

## Install

```bash
npm install @reziiix/sdk
```

## Quick Start

```typescript
import { ReziiixClient } from '@reziiix/sdk';

const client = new ReziiixClient({
  apiKey: 'rzx_your-api-key-here',
});

// Scan an agent action before it executes
const result = await client.scan({
  agentId: 'my-agent',
  action: 'Send email with customer data',
  context: { userId: 'user-123', isExternal: true },
});

console.log(result.ok);                  // true
console.log(result.results.piiFound);    // number of PII entities detected
console.log(result.results.durationMs);  // evaluation time in ms
```

## Configuration

```typescript
const client = new ReziiixClient({
  apiKey: 'rzx_...',                  // Required — create at Developer Hub → API Keys
  endpoint: 'https://reziiix.com',    // Optional — defaults to https://reziiix.com
  timeout: 15000,                     // Optional — request timeout in ms (default: 10000)
});
```

## API

### `client.scan(options)`

The primary method. Scans an AI agent action through the full governance pipeline: intent classification → PII detection → policy evaluation → cryptographic receipt.

```typescript
const result = await client.scan({
  agentId: 'email-agent',              // required
  action: 'Export customer PII to CSV', // required
  context: {                            // optional — extra data for policy evaluation
    userId: 'user-123',
    isExternal: true,
    recipientCount: 5,
  },
  mode: 'sample',                      // optional — 'sample' (default) or 'csv'
  data: 'base64-csv-string...',        // required when mode is 'csv'
});
```

**Returns:**
```typescript
{
  ok: true,
  results: {
    totalRecords: 500,
    piiFound: 45,
    rowsWithPii: 23,
    detectionRate: '4.60%',
    violationsByType: { EMAIL_ADDRESS: 18, PHONE_NUMBER: 12, PERSON: 15 },
    classificationDistribution: { Public: 477, Internal: 23 },
    sampleViolations: [{ row: 12, type: 'EMAIL_ADDRESS', severity: 'WARN', count: 2 }],
    durationMs: 245,
    engines: ['presidio', 'regex']
  }
}
```

### `client.policies.list()`

List all active governance policies (built-in + custom).

```typescript
const { data: policies } = await client.policies.list();

for (const policy of policies) {
  console.log(`${policy.id}: ${policy.effect} — ${policy.description}`);
}
```

### `client.agents.list()`

List all registered AI agents with activity stats.

```typescript
const { data: agents } = await client.agents.list();

for (const agent of agents) {
  console.log(`${agent.agentName}: ${agent.totalActions} actions, ${agent.blockRate}% blocked`);
}
```

### `client.agents.get(agentId)`

Get detailed info for a specific agent including recent actions and distributions.

```typescript
const { data: agent } = await client.agents.get('my-agent');

console.log(agent.recentActions);
console.log(agent.toolDistribution);
console.log(agent.classificationDistribution);
```

### `client.receipts.list(filters?)`

List cryptographic governance receipts with optional filters.

```typescript
const { data: receipts } = await client.receipts.list({
  agent: 'my-agent',
  decision: 'FORBID',
  from: '2026-03-01',
  to: '2026-03-13',
  limit: 100,
});
```

### `client.receipts.verify(receiptIds)`

Batch verify the integrity of governance receipts.

```typescript
const { results } = await client.receipts.verify([
  'receipt-id-1',
  'receipt-id-2',
]);

for (const r of results) {
  console.log(`${r.receiptId}: verified=${r.verified}`);
}
```

### `client.stats()`

Get aggregated dashboard metrics.

```typescript
const { data } = await client.stats();

console.log(`Governance Score: ${data.governanceScore}`);
console.log(`Decisions Today: ${data.decisionsToday}`);
console.log(`Active Agents: ${data.activeAgents}`);
console.log(`Open Anomalies: ${data.openAnomalies}`);
```

## Error Handling

The SDK throws typed errors for different failure modes:

```typescript
import {
  ReziiixClient,
  ReziiixAuthError,
  ReziiixApiError,
  ReziiixValidationError,
  ReziiixTimeoutError,
} from '@reziiix/sdk';

try {
  await client.scan({ agentId: 'x', action: 'y' });
} catch (err) {
  if (err instanceof ReziiixAuthError) {
    // 401/403 — API key is invalid, expired, or revoked
    console.error('Auth failed:', err.message);
  }
  if (err instanceof ReziiixApiError) {
    // Server returned an error (5xx, 4xx)
    console.error(`API error (${err.status}):`, err.message);
  }
  if (err instanceof ReziiixValidationError) {
    // Client-side validation failed (missing required fields)
    console.error('Validation:', err.message);
  }
  if (err instanceof ReziiixTimeoutError) {
    // Request exceeded the configured timeout
    console.error('Timeout:', err.message);
  }
}
```

All errors extend `ReziiixError` which has:
- `message` — human-readable description
- `code` — machine-readable code (`AUTH_ERROR`, `API_ERROR`, `VALIDATION_ERROR`, `TIMEOUT_ERROR`)
- `status` — HTTP status code (when applicable)

## API Key Scopes

| Scope | Permission |
|---|---|
| `scan` | Call the scan endpoint |
| `orchestrate` | Full pipeline orchestration |
| `admin` | Key management + policy access |

Create API keys in the **Developer Hub** at `https://reziiix.com/developers` (admin role required).

## Requirements

- **Node.js 18+** (uses native `fetch`)
- **TypeScript 5+** (optional — JS works too)

## License

MIT — REZIIIX PTE LTD