@vorim/sdk 1.0.1 → 1.0.2

package/README.md

@@ -1,11 +1,31 @@
 # @vorim/sdk
 
-The official TypeScript SDK for **[Vorim AI](https://vorim.ai)** — the identity and trust layer for AI agents.
+**The identity and trust layer for AI agents.**
 
-Register agents with cryptographic identities, enforce scoped permissions, emit tamper-evident audit trails, and verify trust scores — all in a few lines of code.
+Register agents with cryptographic Ed25519 identities, enforce scoped permissions in under 5ms, 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)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue.svg)](https://www.typescriptlang.org/)
+[![Node](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
+[![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen.svg)]()
+
+---
+
+## Why Vorim?
+
+AI agents are shipping into production without identity, permissions, or audit trails. This is a problem:
+
+- **No identity** — agents share API keys. You can't tell which agent did what.
+- **No permissions** — agents get all-or-nothing access. No scoped, time-bounded controls.
+- **No audit trail** — no tamper-evident record of agent actions. Compliance teams are blind.
+- **No trust signal** — third parties can't verify an agent before interacting with it.
+
+Vorim solves all four. One SDK. One protocol. Ships in minutes.
+
+> **EU AI Act** (enforced Aug 2025) mandates traceability and audit trails for high-risk AI systems. Vorim makes your agents compliant out of the box.
+
+---
 
 ## Install
 
@@ -14,13 +34,14 @@ npm install @vorim/sdk
 ```
 
 ```bash
+# or
 yarn add @vorim/sdk
-```
-
-```bash
+# or
 pnpm add @vorim/sdk
 ```
 
+---
+
 ## Quick Start
 
 ```typescript
@@ -30,17 +51,17 @@ const vorim = createVorim({
   apiKey: "agid_sk_live_...",
 });
 
-// 1. Register an agent — returns Ed25519 keypair (private key shown once)
+// 1. Register an agent — Ed25519 keypair generated, private key shown once
 const { agent, private_key } = await vorim.register({
   name: "invoice-processor",
   capabilities: ["read_documents", "extract_data"],
   scopes: ["agent:read", "agent:execute"],
 });
 
-console.log(agent.agent_id); // agid_acme_a1b2c3d4
-console.log(agent.trust_score); // 50 (initial score)
+console.log(agent.agent_id);    // agid_acme_a1b2c3d4
+console.log(agent.trust_score); // 50 (initial)
 
-// 2. Check permissions before acting (sub-5ms via Redis cache)
+// 2. Check permissions before acting (<5ms via Redis)
 const { allowed } = await vorim.check(agent.agent_id, "agent:execute");
 
 if (allowed) {
@@ -55,31 +76,119 @@ if (allowed) {
   });
 }
 
-// 4. Verify any agent's trust (public API, no auth needed)
+// 4. Verify any agent's trust (public endpoint, no auth required)
 const trust = await vorim.verify(agent.agent_id);
-console.log(trust.trust_score); // 0–100
+console.log(trust.trust_score);  // 0–100
 console.log(trust.active_scopes); // ['agent:read', 'agent:execute']
 ```
 
-## Features
+---
 
-| 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 |
+## Framework Integration
+
+### LangChain
+
+```typescript
+import createVorim from "@vorim/sdk";
+import { ChatOpenAI } from "@langchain/openai";
+import { AgentExecutor } from "langchain/agents";
+
+const vorim = createVorim({ apiKey: "agid_sk_live_..." });
+
+// Register your LangChain agent with Vorim
+const { agent: identity } = await vorim.register({
+  name: "langchain-research-agent",
+  capabilities: ["web_browsing", "api_calls"],
+  scopes: ["agent:read", "agent:execute", "agent:communicate"],
+});
+
+// Check permissions before every tool call
+async function guardedToolCall(toolName: string, input: any) {
+  const { allowed } = await vorim.check(identity.agent_id, "agent:execute");
+  if (!allowed) throw new Error("Permission denied by Vorim");
+
+  const result = await executeTool(toolName, input);
+
+  // Audit every action
+  await vorim.emit({
+    agent_id: identity.agent_id,
+    event_type: "tool_call",
+    action: `${toolName}: ${JSON.stringify(input)}`,
+    result: "success",
+  });
+
+  return result;
+}
+```
+
+### CrewAI
+
+```typescript
+import createVorim from "@vorim/sdk";
+
+const vorim = createVorim({ apiKey: "agid_sk_live_..." });
+
+// Register each crew member as a Vorim agent
+const researcher = await vorim.register({
+  name: "crew-researcher",
+  capabilities: ["web_browsing"],
+  scopes: ["agent:read"],
+});
+
+const writer = await vorim.register({
+  name: "crew-writer",
+  capabilities: ["file_access"],
+  scopes: ["agent:read", "agent:write"],
+});
+
+// Verify permissions before delegation
+const { allowed } = await vorim.check(writer.agent.agent_id, "agent:write");
+```
+
+### OpenAI Agents SDK
+
+```typescript
+import createVorim from "@vorim/sdk";
+import OpenAI from "openai";
+
+const vorim = createVorim({ apiKey: "agid_sk_live_..." });
+const openai = new OpenAI();
+
+// Register your OpenAI agent
+const { agent: identity } = await vorim.register({
+  name: "openai-assistant",
+  capabilities: ["api_calls", "code_execution"],
+  scopes: ["agent:read", "agent:execute"],
+});
+
+// Wrap function calls with Vorim permission checks
+async function handleFunctionCall(call: any) {
+  const { allowed } = await vorim.check(identity.agent_id, "agent:execute");
+  if (!allowed) return { error: "Blocked by Vorim trust layer" };
+
+  const result = await executeFunction(call);
+
+  await vorim.emit({
+    agent_id: identity.agent_id,
+    event_type: "tool_call",
+    action: call.name,
+    resource: JSON.stringify(call.arguments),
+    result: "success",
+  });
+
+  return result;
+}
+```
+
+---
 
 ## API Reference
 
 ### Identity
 
 ```typescript
-// Register a new agent (returns keypair — private key shown once)
-const result = await vorim.register({
+// Register a new agent (private key returned once — store it securely)
+const { agent, private_key } = await vorim.register({
   name: "my-agent",
   description: "Processes invoices",
   capabilities: ["read_documents"],
@@ -99,20 +208,20 @@ await vorim.revoke("agid_acme_a1b2c3d4");
 ### Permissions
 
 ```typescript
-// Check if an agent has a specific permission
+// Check if an agent has a specific permission (<5ms)
 const { allowed, remaining_quota } = await vorim.check(
   "agid_acme_a1b2c3d4",
   "agent:execute"
 );
 
-// Grant a time-bounded permission with rate limiting
+// Grant a time-bounded, rate-limited permission
 await vorim.grant("agid_acme_a1b2c3d4", "agent:transact", {
   valid_until: "2026-06-01T00:00:00Z",
   rate_limit: { max: 100, window: "1h" },
 });
 ```
 
-### Permission Scopes
+#### Permission Scopes
 
 | Scope | Description |
 |-------|-------------|
@@ -151,16 +260,16 @@ await vorim.emitBatch([
 // 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
+trust.verified;          // true
+trust.trust_score;       // 82
+trust.status;            // 'active'
+trust.owner.org_name;    // 'Acme Corp'
+trust.active_scopes;     // ['agent:read', 'agent:execute']
+trust.key_fingerprint;   // 'a1b2c3d4...'
+trust.revocation_status; // false
 ```
 
-**Trust Score Factors:**
+**Trust score factors:**
 - Agent status (active, suspended, revoked)
 - Account age (older = more trusted)
 - Success rate over last 30 days
@@ -170,7 +279,7 @@ console.log(trust.revocation_status); // false
 ### Payload Signing
 
 ```typescript
-// Sign a payload with the agent's Ed25519 private key
+// Sign a payload with the agent's Ed25519 private key (client-side)
 const signature = await vorim.sign(
   JSON.stringify({ action: "transfer", amount: 500 }),
   privateKeyPem
@@ -187,20 +296,43 @@ await vorim.emit({
 });
 ```
 
+### Embeddable Trust Badge
+
+Every registered agent gets a public SVG trust badge you can embed anywhere:
+
+```html
+<!-- Embed in your docs, landing page, or agent marketplace listing -->
+<img src="https://api.vorim.ai/v1/trust/badge/agid_acme_a1b2c3d4.svg" alt="Vorim Trust Badge" />
+```
+
+The badge displays the agent's current trust score and updates in real-time. Use it to signal trust to end users, partners, and other agents.
+
+---
+
 ## Configuration
 
 ```typescript
 import createVorim from "@vorim/sdk";
 
 const vorim = createVorim({
-  apiKey: "agid_sk_live_...",          // Required
-  baseUrl: "https://api.vorim.ai",    // Optional (default)
-  timeout: 10000,                      // Optional — ms (default: 10000)
+  apiKey: "agid_sk_live_...",         // Required — your Vorim API key
+  baseUrl: "https://api.vorim.ai",   // Optional (default)
+  timeout: 10000,                     // Optional — request timeout in ms (default: 10000)
 });
 ```
 
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | — | Your Vorim API key (`agid_sk_live_...` or `agid_sk_test_...`) |
+| `baseUrl` | `string` | `https://api.vorim.ai` | API base URL (override for self-hosted) |
+| `timeout` | `number` | `10000` | Request timeout in milliseconds |
+
+---
+
 ## Error Handling
 
+All errors throw `VorimError` with structured fields:
+
 ```typescript
 import createVorim, { VorimError } from "@vorim/sdk";
 
@@ -208,24 +340,65 @@ try {
   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 invalid_id not found in the trust registry'
-    console.log(err.details);  // Additional error context
+    err.status;   // 404
+    err.code;     // 'AGENT_NOT_FOUND'
+    err.message;  // 'Agent invalid_id not found in the trust registry'
+    err.details;  // Additional context (optional)
   }
 }
 ```
 
+| Error Code | Status | Meaning |
+|-----------|--------|---------|
+| `INVALID_CREDENTIALS` | 401 | Bad or expired API key |
+| `AGENT_NOT_FOUND` | 404 | Agent ID doesn't exist |
+| `PERMISSION_DENIED` | 403 | Agent lacks required scope |
+| `RATE_LIMITED` | 429 | Too many requests |
+| `VALIDATION_ERROR` | 400 | Invalid request payload |
+
+---
+
+## Features
+
+| Feature | Details |
+|---------|---------|
+| **Cryptographic Identity** | Ed25519 keypairs with SHA-256 fingerprints |
+| **7 Permission Scopes** | `read`, `write`, `execute`, `transact`, `communicate`, `delegate`, `elevate` |
+| **Immutable Audit Trail** | Append-only events with content hashing |
+| **Trust Scoring** | 5-factor algorithm producing a 0–100 score |
+| **Payload Signing** | Client-side Ed25519 via Web Crypto or Node.js crypto |
+| **Dual Runtime** | Node.js 18+ and modern browsers |
+| **Zero Dependencies** | Types bundled — nothing extra to install |
+| **ESM + CJS** | Dual module output for any bundler or runtime |
+
+---
+
 ## 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.
+This 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)
+VAIP defines 5 conformance levels, from basic identity to full cryptographic signing. The protocol is open-source under Apache 2.0 — anyone can implement it.
+
+Read the full specification: **[SPEC.md](https://github.com/Kzino/vorim-protocol/blob/main/SPEC.md)**
+
+---
 
 ## Requirements
 
-- Node.js 18+ or modern browser with Web Crypto API
-- TypeScript 5.0+ (optional, but recommended)
+- **Node.js** 18+ or modern browser with Web Crypto API
+- **TypeScript** 5.0+ (optional but recommended)
+
+---
+
+## Links
+
+- **Website:** [vorim.ai](https://vorim.ai)
+- **Protocol Spec:** [github.com/Kzino/vorim-protocol](https://github.com/Kzino/vorim-protocol)
+- **npm:** [@vorim/sdk](https://www.npmjs.com/package/@vorim/sdk)
+- **X:** [@vorim_ai_x](https://x.com/vorim_ai_x)
+- **Issues:** [GitHub Issues](https://github.com/Kzino/vorim-protocol/issues)
+
+---
 
 ## License
 
@@ -233,4 +406,4 @@ MIT — see [LICENSE](LICENSE) for details.
 
 ---
 
-Built by [Vorim AI](https://vorim.ai)
+Built by **[Vorim AI](https://vorim.ai)**

package/package.json

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