aira-sdk 0.3.1 → 1.0.0

package/README.md

@@ -1,30 +1,20 @@
-# Aira TypeScript SDK
-
-**AI compliance infrastructure for AI agents.**
+# Aira TypeScript SDK — The authorization and audit layer for AI agents.
 
 [![npm version](https://img.shields.io/npm/v/aira-sdk.svg)](https://www.npmjs.com/package/aira-sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-Aira produces cryptographic receipts for every action your AI agent takes. Ed25519 signatures and RFC 3161 timestamps create tamper-proof, court-admissible proof of what happened, who authorized it, and which model made the decision. Built for EU AI Act, SR 11-7, and GDPR compliance.
-
----
-
-## Integration Matrix
-
-Drop Aira into your existing agent framework with one import:
+Drop Aira into your agent stack in one line. Define policies without changing code. Get cryptographic proof of every decision — for your auditors, your board, or a court. Not because regulation requires it. Because your agents are acting in production right now.
 
-| Framework | Import | Integration |
-|---|---|---|
-| **LangChain.js** | `import { AiraCallbackHandler } from "aira-sdk/extras/langchain"` | Callback handler |
-| **Vercel AI** | `import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai"` | Middleware |
-| **OpenAI Agents** | `import { AiraGuardrail } from "aira-sdk/extras/openai-agents"` | Guardrail |
-| **MCP** | `import { createServer } from "aira-sdk/extras/mcp"` | MCP Server |
-| **Webhooks** | `import { verifySignature } from "aira-sdk/extras/webhooks"` | Verification |
+```bash
+npm install aira-sdk
+```
 
-Or install the core SDK alone:
+Framework integrations use sub-imports — just make sure the peer dependency is installed:
 
 ```bash
-npm install aira-sdk
+npm install aira-sdk langchain      # for LangChain.js
+npm install aira-sdk ai             # for Vercel AI
+npm install aira-sdk @openai/agents # for OpenAI Agents
 ```
 
 ---
@@ -53,154 +43,13 @@ console.log(receipt.action_id);       // uuid — publicly verifiable
 
 ---
 
-## Framework Integrations
-
-### LangChain.js
-
-`AiraCallbackHandler` notarizes every tool call, chain completion, and LLM invocation with a cryptographic receipt. No changes to your chain logic.
-
-```typescript
-import { Aira } from "aira-sdk";
-import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
-
-const aira = new Aira({ apiKey: "aira_live_xxx" });
-const handler = new AiraCallbackHandler({ client: aira, agentId: "research-agent", modelId: "gpt-5.2" });
-
-// Every tool call and chain completion gets a signed receipt
-const result = await chain.invoke({ input: "Analyze Q1 revenue" }, { callbacks: [handler] });
-```
-
-### Vercel AI
-
-`AiraVercelMiddleware` wraps your Vercel AI `streamText` / `generateText` calls so every model invocation is notarized with a tamper-proof receipt.
-
-```typescript
-import { Aira } from "aira-sdk";
-import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai";
-
-const aira = new Aira({ apiKey: "aira_live_xxx" });
-const middleware = new AiraVercelMiddleware({ client: aira, agentId: "assistant-agent" });
-
-// Wrap your Vercel AI calls — receipts at invocation and completion
-const result = await middleware.wrapGenerateText({
-  model: openai("gpt-5.2"),
-  prompt: "Summarize the contract terms",
-});
-```
-
-### OpenAI Agents SDK
-
-`AiraGuardrail` wraps any tool function to automatically notarize both invocation and result with cryptographic proof.
-
-```typescript
-import { Aira } from "aira-sdk";
-import { AiraGuardrail } from "aira-sdk/extras/openai-agents";
-
-const aira = new Aira({ apiKey: "aira_live_xxx" });
-const guardrail = new AiraGuardrail({ client: aira, agentId: "assistant-agent" });
-
-// Wrap tools — every call and result gets a signed receipt
-const search = guardrail.wrapTool(searchTool, { toolName: "web_search" });
-const execute = guardrail.wrapTool(codeExecutor, { toolName: "code_exec" });
-```
-
----
-
-## MCP Server
-
-Expose Aira as an MCP tool server. Any MCP-compatible AI agent can notarize actions and verify receipts without SDK integration.
-
-```typescript
-import { createServer } from "aira-sdk/extras/mcp";
-
-const server = createServer({ apiKey: "aira_live_xxx" });
-server.listen(); // stdio transport
-```
-
-The server exposes three tools: `notarize_action`, `verify_action`, and `get_receipt` -- each producing cryptographically signed results.
-
-Add to your MCP client config:
-
-```json
-{
-  "mcpServers": {
-    "aira": {
-      "command": "npx",
-      "args": ["aira-sdk", "mcp"],
-      "env": { "AIRA_API_KEY": "aira_live_xxx" }
-    }
-  }
-}
-```
-
----
-
-## Session
-
-Pre-fill defaults for a block of related actions. Every `notarize()` call within the session inherits the agent identity, producing receipts that share a common provenance chain.
-
-```typescript
-const sess = aira.session("onboarding-agent", { modelId: "claude-sonnet-4-6" });
-
-await sess.notarize({ actionType: "identity_verified", details: "Verified customer ID #4521" });
-await sess.notarize({ actionType: "account_created", details: "Created account for customer #4521" });
-await sess.notarize({ actionType: "welcome_sent", details: "Sent welcome email to customer #4521" });
-```
-
----
-
-## Offline Mode
-
-Queue notarizations locally when connectivity is unavailable. Cryptographic receipts are generated server-side when you sync -- nothing is lost.
-
-```typescript
-const aira = new Aira({ apiKey: "aira_live_xxx", offline: true });
-
-// These queue locally — no network calls
-await aira.notarize({ actionType: "scan_completed", details: "Scanned document batch #77" });
-await aira.notarize({ actionType: "classification_done", details: "Classified 142 documents" });
-
-console.log(aira.pendingCount);  // 2
-
-// Flush to API when back online — receipts are generated for each action
-const results = await aira.sync();
-```
-
----
-
-## Webhook Verification
-
-Verify that incoming webhooks are authentic Aira events, not forged requests. HMAC-SHA256 signature verification ensures tamper-proof delivery.
-
-```typescript
-import { verifySignature, parseEvent } from "aira-sdk/extras/webhooks";
-
-// Verify the webhook signature (HMAC-SHA256)
-const isValid = verifySignature({
-  payload: request.body,
-  signature: request.headers["x-aira-signature"],
-  secret: "whsec_xxx",
-});
-
-if (isValid) {
-  const event = parseEvent(request.body);
-  console.log(event.eventType);    // "action.notarized"
-  console.log(event.data);         // Action data with cryptographic receipt
-  console.log(event.deliveryId);   // Unique delivery ID
-}
-```
-
-Supported event types: `action.notarized`, `action.authorized`, `agent.registered`, `agent.decommissioned`, `evidence.sealed`, `escrow.deposited`, `escrow.released`, `escrow.disputed`, `compliance.snapshot_created`, `case.complete`, `case.requires_human_review`.
-
----
-
 ## Core SDK Methods
 
 All 52 methods on `Aira`. Every write operation produces a cryptographic receipt.
 
 | Category | Method | Description |
 |---|---|---|
-| **Actions** | `notarize()` | Notarize an action -- returns Ed25519-signed receipt |
+| **Actions** | `notarize()` | Notarize an action -- returns Ed25519-signed receipt (supports `requireApproval`) |
 | | `getAction()` | Retrieve action details + receipt |
 | | `listActions()` | List actions with filters (type, agent, status) |
 | | `authorizeAction()` | Human co-signature on high-stakes action |
@@ -374,6 +223,224 @@ const handler = new AiraCallbackHandler(aira, "research-agent", {
 
 ---
 
+## Session
+
+Pre-fill defaults for a block of related actions. Every `notarize()` call within the session inherits the agent identity, producing receipts that share a common provenance chain.
+
+```typescript
+const sess = aira.session("onboarding-agent", { modelId: "claude-sonnet-4-6" });
+
+await sess.notarize({ actionType: "identity_verified", details: "Verified customer ID #4521" });
+await sess.notarize({ actionType: "account_created", details: "Created account for customer #4521" });
+await sess.notarize({ actionType: "welcome_sent", details: "Sent welcome email to customer #4521" });
+```
+
+---
+
+## Offline Mode
+
+Queue notarizations locally when connectivity is unavailable. Cryptographic receipts are generated server-side when you sync -- nothing is lost.
+
+```typescript
+const aira = new Aira({ apiKey: "aira_live_xxx", offline: true });
+
+// These queue locally — no network calls
+await aira.notarize({ actionType: "scan_completed", details: "Scanned document batch #77" });
+await aira.notarize({ actionType: "classification_done", details: "Classified 142 documents" });
+
+console.log(aira.pendingCount);  // 2
+
+// Flush to API when back online — receipts are generated for each action
+const results = await aira.sync();
+```
+
+---
+
+## Human Approval
+
+Hold high-stakes actions for human review before the cryptographic receipt is issued. Approvers receive an email with Approve/Deny buttons.
+
+```typescript
+const receipt = await aira.notarize({
+  actionType: "loan_decision",
+  details: "Approved €15,000 loan for Maria Schmidt",
+  agentId: "lending-agent",
+  requireApproval: true,
+  approvers: ["compliance@acme.com", "risk@acme.com"],
+});
+console.log(receipt.status);      // "pending_approval"
+console.log(receipt.receipt_id);  // undefined — no receipt until approved
+
+// Falls back to org default approvers (Settings → Approvers)
+const receipt2 = await aira.notarize({
+  actionType: "wire_transfer",
+  details: "Transfer $50,000 to vendor account",
+  agentId: "payments-agent",
+  requireApproval: true,
+});
+```
+
+The approver clicks "Approve" in the email → receipt is minted with Ed25519 signature + RFC 3161 timestamp → `action.approved` webhook fires.
+
+Configure default approvers in the [dashboard](https://app.airaproof.com/dashboard/settings/approvers) or via the `/approvers` API.
+
+### Automatic Policy Evaluation
+
+Org admins configure policies in the dashboard — your code doesn't change. Every `notarize()` call is automatically evaluated against active policies before the receipt is issued.
+
+Three evaluation modes:
+
+- **Rules**: Deterministic conditions — instant, no LLM call
+- **AI**: Single LLM evaluates action against a natural language policy (1-5s)
+- **Consensus**: Multiple LLMs evaluate independently — disagreement triggers human review (3-10s)
+
+```typescript
+// Your code stays the same — policies evaluate automatically
+const receipt = await aira.notarize({
+  actionType: "wire_transfer",
+  details: "Transfer $50,000 to vendor account",
+  agentId: "billing-agent",
+});
+
+// If a policy triggers "require_approval":
+console.log(receipt.status);             // "pending_approval"
+console.log(receipt.policy_evaluation);  // { policy_name: "Wire transfers need approval", decision: "require_approval", ... }
+
+// If a policy triggers "deny":
+import { AiraError } from "aira-sdk";
+try {
+  await aira.notarize({ actionType: "data_deletion", details: "Delete customer records" });
+} catch (e) {
+  if (e instanceof AiraError && e.code === "POLICY_DENIED") {
+    console.log(e.message);  // "Action denied by policy 'Block deletions': ..."
+  }
+}
+```
+
+Every policy evaluation produces a cryptographic receipt — proof the policy was checked. The SDK `requireApproval: true` override still works and skips policy evaluation entirely.
+
+Configure policies at [Settings → Policies](https://app.airaproof.com/dashboard/policies).
+
+---
+
+## Framework Integrations
+
+Drop Aira into your existing agent framework with one import:
+
+| Framework | Import | Integration |
+|---|---|---|
+| **LangChain.js** | `import { AiraCallbackHandler } from "aira-sdk/extras/langchain"` | Callback handler |
+| **Vercel AI** | `import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai"` | Middleware |
+| **OpenAI Agents** | `import { AiraGuardrail } from "aira-sdk/extras/openai-agents"` | Guardrail |
+| **MCP** | `import { createServer } from "aira-sdk/extras/mcp"` | MCP Server |
+| **Webhooks** | `import { verifySignature } from "aira-sdk/extras/webhooks"` | Verification |
+
+### LangChain.js
+
+`AiraCallbackHandler` notarizes every tool call, chain completion, and LLM invocation with a cryptographic receipt. No changes to your chain logic.
+
+```typescript
+import { Aira } from "aira-sdk";
+import { AiraCallbackHandler } from "aira-sdk/extras/langchain";
+
+const aira = new Aira({ apiKey: "aira_live_xxx" });
+const handler = new AiraCallbackHandler({ client: aira, agentId: "research-agent", modelId: "gpt-5.2" });
+
+// Every tool call and chain completion gets a signed receipt
+const result = await chain.invoke({ input: "Analyze Q1 revenue" }, { callbacks: [handler] });
+```
+
+### Vercel AI
+
+`AiraVercelMiddleware` wraps your Vercel AI `streamText` / `generateText` calls so every model invocation is notarized with a tamper-proof receipt.
+
+```typescript
+import { Aira } from "aira-sdk";
+import { AiraVercelMiddleware } from "aira-sdk/extras/vercel-ai";
+
+const aira = new Aira({ apiKey: "aira_live_xxx" });
+const middleware = new AiraVercelMiddleware({ client: aira, agentId: "assistant-agent" });
+
+// Wrap your Vercel AI calls — receipts at invocation and completion
+const result = await middleware.wrapGenerateText({
+  model: openai("gpt-5.2"),
+  prompt: "Summarize the contract terms",
+});
+```
+
+### OpenAI Agents SDK
+
+`AiraGuardrail` wraps any tool function to automatically notarize both invocation and result with cryptographic proof.
+
+```typescript
+import { Aira } from "aira-sdk";
+import { AiraGuardrail } from "aira-sdk/extras/openai-agents";
+
+const aira = new Aira({ apiKey: "aira_live_xxx" });
+const guardrail = new AiraGuardrail({ client: aira, agentId: "assistant-agent" });
+
+// Wrap tools — every call and result gets a signed receipt
+const search = guardrail.wrapTool(searchTool, { toolName: "web_search" });
+const execute = guardrail.wrapTool(codeExecutor, { toolName: "code_exec" });
+```
+
+---
+
+## MCP Server
+
+Expose Aira as an MCP tool server. Any MCP-compatible AI agent can notarize actions and verify receipts without SDK integration.
+
+```typescript
+import { createServer } from "aira-sdk/extras/mcp";
+
+const server = createServer({ apiKey: "aira_live_xxx" });
+server.listen(); // stdio transport
+```
+
+The server exposes three tools: `notarize_action`, `verify_action`, and `get_receipt` -- each producing cryptographically signed results.
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "aira": {
+      "command": "npx",
+      "args": ["aira-sdk", "mcp"],
+      "env": { "AIRA_API_KEY": "aira_live_xxx" }
+    }
+  }
+}
+```
+
+---
+
+## Webhook Verification
+
+Verify that incoming webhooks are authentic Aira events, not forged requests. HMAC-SHA256 signature verification ensures tamper-proof delivery.
+
+```typescript
+import { verifySignature, parseEvent } from "aira-sdk/extras/webhooks";
+
+// Verify the webhook signature (HMAC-SHA256)
+const isValid = verifySignature({
+  payload: request.body,
+  signature: request.headers["x-aira-signature"],
+  secret: "whsec_xxx",
+});
+
+if (isValid) {
+  const event = parseEvent(request.body);
+  console.log(event.eventType);    // "action.notarized"
+  console.log(event.data);         // Action data with cryptographic receipt
+  console.log(event.deliveryId);   // Unique delivery ID
+}
+```
+
+Supported event types: `action.notarized`, `action.authorized`, `agent.registered`, `agent.decommissioned`, `evidence.sealed`, `escrow.deposited`, `escrow.released`, `escrow.disputed`, `compliance.snapshot_created`, `case.complete`, `case.requires_human_review`.
+
+---
+
 ## Error Handling
 
 ```typescript

package/dist/client.d.ts

@@ -29,6 +29,8 @@ export declare class Aira {
         parentActionId?: string;
         storeDetails?: boolean;
         idempotencyKey?: string;
+        requireApproval?: boolean;
+        approvers?: string[];
     }): Promise<ActionReceipt>;
     getAction(actionId: string): Promise<ActionDetail>;
     listActions(params?: {

package/dist/client.js

@@ -10,7 +10,7 @@ const MAX_DETAILS_LENGTH = 50_000;
 function buildBody(obj) {
     return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined && v !== null));
 }
-function sanitizeDetails(text) {
+function truncateDetails(text) {
     return text.length > MAX_DETAILS_LENGTH ? text.slice(0, MAX_DETAILS_LENGTH) + "...[truncated]" : text;
 }
 class Aira {
@@ -69,9 +69,17 @@ class Aira {
         return this.request("POST", path, body);
     }
     put(path, body) {
+        if (this.queue) {
+            const qid = this.queue.enqueue("PUT", path, body);
+            return Promise.resolve({ _offline: true, _queue_id: qid });
+        }
         return this.request("PUT", path, body);
     }
     del(path) {
+        if (this.queue) {
+            const qid = this.queue.enqueue("DELETE", path, {});
+            return Promise.resolve({ _offline: true, _queue_id: qid });
+        }
         return this.request("DELETE", path);
     }
     paginated(data) {
@@ -82,7 +90,7 @@ class Aira {
     async notarize(params) {
         const body = buildBody({
             action_type: params.actionType,
-            details: sanitizeDetails(params.details),
+            details: truncateDetails(params.details),
             agent_id: params.agentId,
             agent_version: params.agentVersion,
             model_id: params.modelId,
@@ -91,6 +99,8 @@ class Aira {
             parent_action_id: params.parentActionId,
             store_details: params.storeDetails || undefined,
             idempotency_key: params.idempotencyKey,
+            require_approval: params.requireApproval || undefined,
+            approvers: params.approvers,
         });
         return this.post("/actions", body);
     }

package/dist/extras/mcp.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getTools = getTools;
 exports.handleToolCall = handleToolCall;
 exports.createServer = createServer;
+const types_1 = require("../types");
 /** MCP tool definitions exposed by the Aira server. */
 function getTools() {
     return [
@@ -138,7 +139,10 @@ async function handleToolCall(client, name, args) {
         return [{ type: "text", text: JSON.stringify({ error: `Unknown tool: ${name}` }) }];
     }
     catch (e) {
-        return [{ type: "text", text: JSON.stringify({ error: String(e) }) }];
+        if (e instanceof types_1.AiraError) {
+            return [{ type: "text", text: JSON.stringify({ error: e.message, code: e.code }) }];
+        }
+        return [{ type: "text", text: JSON.stringify({ error: "Internal error", code: "SDK_ERROR" }) }];
     }
 }
 /**

package/dist/session.d.ts

@@ -16,5 +16,7 @@ export declare class AiraSession {
         parentActionId?: string;
         storeDetails?: boolean;
         idempotencyKey?: string;
+        requireApproval?: boolean;
+        approvers?: string[];
     }): Promise<ActionReceipt>;
 }

package/dist/types.d.ts

@@ -1,15 +1,23 @@
 /** Cryptographic receipt from notarizing an action. */
 export interface ActionReceipt {
     action_id: string;
-    receipt_id: string;
-    payload_hash: string;
-    signature: string;
-    timestamp_token: string | null;
+    receipt_id?: string;
+    payload_hash?: string;
+    signature?: string;
+    timestamp_token?: string | null;
     created_at: string;
     request_id: string;
+    status?: string;
     action_type?: string;
     agent_id?: string | null;
     warnings?: string[] | null;
+    policy_evaluation?: {
+        policy_id: string;
+        policy_name: string;
+        decision: string;
+        reasoning: string | null;
+        confidence: number | null;
+    } | null;
 }
 /** Full action details including receipt and authorizations. */
 export interface ActionDetail {
@@ -63,6 +71,7 @@ export interface AgentVersion {
     changelog: string | null;
     status: string;
     published_at: string | null;
+    created_at: string;
 }
 /** Sealed evidence package. */
 export interface EvidencePackage {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aira-sdk",
-  "version": "0.3.1",
-  "description": "TypeScript SDK for Aira — legal infrastructure for AI agents",
+  "version": "1.0.0",
+  "description": "The authorization and audit layer for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {