@vorim/sdk 1.0.0 → 1.0.1

package/README.md

@@ -1,8 +1,11 @@
 # @vorim/sdk
 
-Official TypeScript SDK for **Vorim AI** — the AI Agent Identity & Trust Layer.
+The official TypeScript SDK for **[Vorim AI](https://vorim.ai)** — the identity and trust layer for AI agents.
 
-Register agents with cryptographic identities, enforce fine-grained permissions, emit immutable audit trails, and verify trust scores.
+Register agents with cryptographic identities, enforce scoped permissions, emit tamper-evident audit trails, and verify trust scores — all in a few lines of code.
+
+[![npm version](https://img.shields.io/npm/v/@vorim/sdk.svg)](https://www.npmjs.com/package/@vorim/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 ## Install
 
@@ -10,92 +13,224 @@ Register agents with cryptographic identities, enforce fine-grained permissions,
 npm install @vorim/sdk
 ```
 
+```bash
+yarn add @vorim/sdk
+```
+
+```bash
+pnpm add @vorim/sdk
+```
+
 ## Quick Start
 
 ```typescript
-import createVorim from '@vorim/sdk';
+import createVorim from "@vorim/sdk";
 
 const vorim = createVorim({
-  apiKey: 'agid_sk_live_your_api_key_here',
+  apiKey: "agid_sk_live_...",
 });
 
-// Register an agent with Ed25519 keypair
+// 1. Register an agent — returns Ed25519 keypair (private key shown once)
 const { agent, private_key } = await vorim.register({
-  name: 'InvoiceBot',
-  capabilities: ['api_access', 'email_send'],
-  scopes: ['agent:read', 'agent:write'],
+  name: "invoice-processor",
+  capabilities: ["read_documents", "extract_data"],
+  scopes: ["agent:read", "agent:execute"],
 });
 
-// Check permissions (sub-5ms via Redis cache)
-const { allowed } = await vorim.check(agent.agent_id, 'agent:write');
+console.log(agent.agent_id); // agid_acme_a1b2c3d4
+console.log(agent.trust_score); // 50 (initial score)
+
+// 2. Check permissions before acting (sub-5ms via Redis cache)
+const { allowed } = await vorim.check(agent.agent_id, "agent:execute");
+
+if (allowed) {
+  // 3. Perform the action, then emit an audit event
+  await vorim.emit({
+    agent_id: agent.agent_id,
+    event_type: "tool_call",
+    action: "process_invoice",
+    resource: "INV-2026-0042",
+    result: "success",
+    latency_ms: 142,
+  });
+}
+
+// 4. Verify any agent's trust (public API, no auth needed)
+const trust = await vorim.verify(agent.agent_id);
+console.log(trust.trust_score); // 0–100
+console.log(trust.active_scopes); // ['agent:read', 'agent:execute']
+```
+
+## Features
 
-// Emit audit event
+| Feature | Description |
+|---------|-------------|
+| **Cryptographic Identity** | Ed25519 keypairs with SHA-256 fingerprints for every agent |
+| **7 Permission Scopes** | `read`, `write`, `execute`, `transact`, `communicate`, `delegate`, `elevate` |
+| **Immutable Audit Trail** | ULID-ordered events with input/output content hashing |
+| **Trust Scoring** | 5-factor algorithm producing a 0–100 score |
+| **Payload Signing** | Client-side Ed25519 signatures via Web Crypto or Node.js |
+| **Dual Runtime** | Works in Node.js 18+ and modern browsers |
+| **Zero Dependencies** | Types are bundled — no external dependencies |
+
+## API Reference
+
+### Identity
+
+```typescript
+// Register a new agent (returns keypair — private key shown once)
+const result = await vorim.register({
+  name: "my-agent",
+  description: "Processes invoices",
+  capabilities: ["read_documents"],
+  scopes: ["agent:read", "agent:execute"],
+});
+
+// Get agent details
+const agent = await vorim.getAgent("agid_acme_a1b2c3d4");
+
+// List all agents in your organisation
+const { agents, meta } = await vorim.listAgents({ page: 1, per_page: 20 });
+
+// Permanently revoke an agent
+await vorim.revoke("agid_acme_a1b2c3d4");
+```
+
+### Permissions
+
+```typescript
+// Check if an agent has a specific permission
+const { allowed, remaining_quota } = await vorim.check(
+  "agid_acme_a1b2c3d4",
+  "agent:execute"
+);
+
+// Grant a time-bounded permission with rate limiting
+await vorim.grant("agid_acme_a1b2c3d4", "agent:transact", {
+  valid_until: "2026-06-01T00:00:00Z",
+  rate_limit: { max: 100, window: "1h" },
+});
+```
+
+### Permission Scopes
+
+| Scope | Description |
+|-------|-------------|
+| `agent:read` | Read data and resources |
+| `agent:write` | Create or modify resources |
+| `agent:execute` | Execute tools and functions |
+| `agent:transact` | Perform financial transactions |
+| `agent:communicate` | Send messages and notifications |
+| `agent:delegate` | Delegate tasks to other agents |
+| `agent:elevate` | Request elevated privileges |
+
+### Audit
+
+```typescript
+// Emit a single audit event
 await vorim.emit({
-  agent_id: agent.agent_id,
-  event_type: 'api_request',
-  action: 'POST /invoices',
-  result: 'success',
+  agent_id: "agid_acme_a1b2c3d4",
+  event_type: "tool_call",
+  action: "send_email",
+  resource: "user@example.com",
+  result: "success",
+  latency_ms: 230,
+  metadata: { template: "invoice_reminder" },
 });
 
-// Verify trust (public API, no auth needed)
-const trust = await vorim.verify(agent.agent_id);
-console.log(trust.trust_score); // 0-100
+// Batch emit up to 1,000 events
+await vorim.emitBatch([
+  { agent_id: "agid_acme_a1b2c3d4", event_type: "api_request", action: "GET /users", result: "success" },
+  { agent_id: "agid_acme_a1b2c3d4", event_type: "api_request", action: "POST /orders", result: "denied" },
+]);
 ```
 
-## Features
+### Trust Verification
+
+```typescript
+// Public endpoint — no API key required
+const trust = await vorim.verify("agid_acme_a1b2c3d4");
+
+console.log(trust.verified);          // true
+console.log(trust.trust_score);       // 82
+console.log(trust.status);            // 'active'
+console.log(trust.owner.org_name);    // 'Acme Corp'
+console.log(trust.active_scopes);     // ['agent:read', 'agent:execute']
+console.log(trust.key_fingerprint);   // 'a1b2c3d4...'
+console.log(trust.revocation_status); // false
+```
 
-- **Cryptographic Identity** — Ed25519 keypairs, SHA-256 fingerprints
-- **7 Permission Scopes** — `agent:read`, `write`, `execute`, `transact`, `communicate`, `delegate`, `elevate`
-- **Immutable Audit Trail** — ULID-ordered events with content hashes
-- **Trust Scoring** — Multi-factor algorithm (0-100)
-- **Payload Signing** — Client-side Ed25519 signatures via Web Crypto or Node.js crypto
-- **Dual Runtime** — Works in Node.js 18+ and modern browsers
-
-## API
-
-| Method | Description |
-|---|---|
-| `vorim.register(input)` | Register agent with keypair |
-| `vorim.getAgent(agentId)` | Get agent details |
-| `vorim.listAgents(params?)` | List organisation agents |
-| `vorim.revoke(agentId)` | Permanently revoke agent |
-| `vorim.check(agentId, scope)` | Check permission |
-| `vorim.grant(agentId, scope, options?)` | Grant permission |
-| `vorim.emit(event)` | Emit single audit event |
-| `vorim.emitBatch(events)` | Emit up to 1,000 events |
-| `vorim.verify(agentId)` | Public trust verification |
-| `vorim.sign(payload, privateKey)` | Ed25519 payload signing |
+**Trust Score Factors:**
+- Agent status (active, suspended, revoked)
+- Account age (older = more trusted)
+- Success rate over last 30 days
+- Denial ratio (high denials = lower trust)
+- Scope breadth (too many scopes = higher risk)
+
+### Payload Signing
+
+```typescript
+// Sign a payload with the agent's Ed25519 private key
+const signature = await vorim.sign(
+  JSON.stringify({ action: "transfer", amount: 500 }),
+  privateKeyPem
+);
+// Returns: "ed25519:base64signature..."
+
+// Include signature in audit events for non-repudiation
+await vorim.emit({
+  agent_id: "agid_acme_a1b2c3d4",
+  event_type: "tool_call",
+  action: "transfer_funds",
+  result: "success",
+  signature,
+});
+```
 
 ## Configuration
 
 ```typescript
+import createVorim from "@vorim/sdk";
+
 const vorim = createVorim({
-  apiKey: 'agid_sk_live_...',     // Required — your API key
-  baseUrl: 'https://api.vorim.ai', // Optional — API base URL
-  timeout: 10000,                   // Optional — request timeout (ms)
+  apiKey: "agid_sk_live_...",          // Required
+  baseUrl: "https://api.vorim.ai",    // Optional (default)
+  timeout: 10000,                      // Optional — ms (default: 10000)
 });
 ```
 
 ## Error Handling
 
 ```typescript
-import { VorimError } from '@vorim/sdk';
+import createVorim, { VorimError } from "@vorim/sdk";
 
 try {
-  await vorim.check('invalid_id', 'agent:read');
+  await vorim.check("invalid_id", "agent:read");
 } catch (err) {
   if (err instanceof VorimError) {
-    console.log(err.status);  // 404
-    console.log(err.code);    // 'AGENT_NOT_FOUND'
-    console.log(err.message); // 'Agent not found'
+    console.log(err.status);   // 404
+    console.log(err.code);     // 'AGENT_NOT_FOUND'
+    console.log(err.message);  // 'Agent invalid_id not found in the trust registry'
+    console.log(err.details);  // Additional error context
   }
 }
 ```
 
-## Documentation
+## Protocol
+
+`@vorim/sdk` implements the [Vorim Agent Identity Protocol (VAIP)](https://github.com/Kzino/vorim-protocol) — an open standard for AI agent identity, permissions, and cryptographic audit trails.
+
+Read the full specification: [SPEC.md](https://github.com/Kzino/vorim-protocol/blob/main/SPEC.md)
 
-Full documentation at [vorim.dev/docs](https://vorim.dev/docs)
+## Requirements
+
+- Node.js 18+ or modern browser with Web Crypto API
+- TypeScript 5.0+ (optional, but recommended)
 
 ## License
 
-MIT
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+Built by [Vorim AI](https://vorim.ai)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vorim/sdk",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Official TypeScript SDK for Vorim AI — AI Agent Identity, Permissions & Audit",
   "type": "module",
   "main": "dist/index.cjs",