@valiron/sdk 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @valiron/sdk
 
-Official TypeScript SDK for **Valiron** - Trust Infrastructure for AI Agent Systems
+Official TypeScript SDK for **Valiron** — Trust Infrastructure for AI Agent Systems
 
 Valiron verifies AI agent trustworthiness using on-chain reputation (ERC-8004) and behavioral analysis. This SDK provides routing decisions based on agent trust scores, enabling you to protect infrastructure while maintaining service availability for verified agents.
 
@@ -16,213 +16,157 @@ pnpm add @valiron/sdk
 
 ## Getting Started
 
-1. **Initialize the SDK:**
-
 ```typescript
 import { ValironSDK } from '@valiron/sdk';
 
-// Simple initialization (uses default production endpoint)
 const valiron = new ValironSDK();
 
-// Or with custom configuration
-const valiron = new ValironSDK({
-  endpoint: 'https://valiron-edge-proxy.onrender.com', // default
-  timeout: 5000,  // optional
-  debug: false    // optional
-});
-```
-
-> **Note:** API key authentication is not yet enforced. The `apiKey` field is
-> reserved for future use when authentication is implemented.
-
-2. **Check agent trust before processing requests:**
-
-```typescript
-const decision = await valiron.checkAgent('417');
-
-if (decision.route === 'prod') {
-  return handleRequest();
-} else {
-  return denyRequest();
+// Quick routing check
+const route = await valiron.checkAgent('25459');
+if (route === 'prod') {
+  // Allow full production access
 }
+
+// Or get the full trust profile
+const profile = await valiron.getAgentProfile('25459');
+console.log(profile.routing.finalRoute);          // 'prod'
+console.log(profile.localReputation?.tier);        // 'AAA'
+console.log(profile.onchainReputation.averageScore); // 92.5
 ```
 
+> **Note:** API key authentication is not yet enforced. The `apiKey` config
+> field is reserved for future use.
+
 ## Core Concepts
 
 ### Route Decisions
 
 The SDK returns one of four routing decisions:
 
-- **`prod`** - Full access (trust tiers: AAA to BAA)
-- **`prod_throttled`** - Rate-limited access (trust tiers: BA to B)
-- **`sandbox`** - Agent under evaluation (temporary state)
-- **`sandbox_only`** - Access denied (trust tiers: CAA to C)
+| Route | Meaning | Trust Tiers |
+|-------|---------|-------------|
+| `prod` | Full access | AAA – BAA |
+| `prod_throttled` | Rate-limited access | BA – B |
+| `sandbox` | Agent under evaluation | Temporary |
+| `sandbox_only` | Access denied | CAA – C |
 
 ### Trust Evaluation
 
 Valiron evaluates agents using:
 
-1. **On-chain Reputation** - ERC-8004 feedback submitted by other organizations
-2. **Behavioral Analysis** - Sandbox evaluation of rate-limit compliance, error rates, and request patterns
-3. **Credit Rating** - Moody's-style scoring system (AAA to C tiers)
+1. **On-chain Reputation** — ERC-8004 feedback submitted by other organizations
+2. **Behavioral Analysis** — Sandbox evaluation of rate-limit compliance, error rates, and request patterns
+3. **Credit Rating** — Moody's-style scoring system (AAA to C)
 
 ### Architecture
 
 ```
-Request → SDK.checkAgent() → Valiron API → Route Decision → Application
+Request → SDK.checkAgent() → Valiron Operator API → Route Decision → Your App
 ```
 
-The SDK queries Valiron's trust infrastructure, which evaluates on-chain reputation and behavioral metrics to return a routing decision. Your application implements access control based on this decision.
-
 ## API Reference
 
 ### Constructor
 
 ```typescript
-new ValironSDK(config: ValironConfig)
+new ValironSDK(config?: ValironConfig)
 ```
 
-**Config Options:**
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | — | API key (reserved for future use) |
+| `endpoint` | `string` | `https://valiron-edge-proxy.onrender.com` | API endpoint URL |
+| `timeout` | `number` | `5000` | Request timeout (ms) |
+| `debug` | `boolean` | `false` | Enable debug logging |
 
-| Option | Type | Required | Default | Description |
-|--------|------|----------|---------|-------------|
-| `apiKey` | string | No | - | API key (reserved for future use) |
-| `endpoint` | string | No | `https://valiron-edge-proxy.onrender.com` | API endpoint URL |
-| `timeout` | number | No | `5000` | Request timeout (ms) |
-| `debug` | boolean | No | `false` | Enable debug logging |
-
-### Methods
-
-#### `checkAgent(agentId: string): Promise<RoutingResponse>`
+---
 
-Check routing decision for an ERC-8004 agent.
+### `checkAgent(agentId): Promise<RouteDecision>`
 
-**Returns:**
-```typescript
-{
-  route: 'prod' | 'prod_throttled' | 'sandbox' | 'sandbox_only',
-  reason: string,
-  explanation: string,
-  onChainData?: {
-    feedbackCount: number,
-    averageScore: number,
-    agentId: string
-  },
-  localReputation?: {
-    score: number,
-    tier: MoodysRating,
-    riskLevel: 'GREEN' | 'YELLOW' | 'RED',
-    graduated: boolean
-  }
-}
-```
+Quick routing check — returns just the route decision string.
 
-**Example:**
 ```typescript
-const decision = await valiron.checkAgent('417');
-console.log(decision.route); // 'prod'
-console.log(decision.localReputation?.tier); // 'AAA'
+const route = await valiron.checkAgent('25459');
+// route: 'prod' | 'prod_throttled' | 'sandbox' | 'sandbox_only'
 ```
 
 ---
 
-#### `checkWallet(wallet: string): Promise<RoutingResponse>`
+### `getAgentProfile(agentId): Promise<AgentProfile>`
 
-Check routing decision for a wallet address (legacy method).
+Full trust profile combining on-chain identity, reputation, behavioral data, and routing.
 
-**Example:**
 ```typescript
-const decision = await valiron.checkWallet('0x742d35Cc...');
+const profile = await valiron.getAgentProfile('25459');
 ```
 
----
+**Response shape:**
 
-#### `getAgentProfile(agentId: string): Promise<AgentProfile>`
-
-Get complete trust profile for an agent.
-
-**Returns:**
 ```typescript
 {
   agentId: string,
   identity: {
+    agentId: string,
     wallet: string,
+    tokenUri: string,
     name: string,
-    description: string,
     image: string,
-    endpoints: string[]
+    description: string,
+    endpoints: Record<string, string>,
+    trustModels: string[],
   },
   onchainReputation: {
-    count: number,
+    count: string,
     averageScore: number,
-    feedbackEntries: FeedbackEntry[]
+    feedbackEntries: FeedbackEntry[],
+    totalFeedback: number,
   },
   localReputation: {
+    exists: boolean,
     score: number,
     tier: MoodysRating,
     riskLevel: 'GREEN' | 'YELLOW' | 'RED',
-    metrics: BehavioralMetrics
-  },
+    graduated: boolean,
+    metrics: BehavioralMetrics,
+  } | null,
   routing: {
     finalRoute: RouteDecision,
-    decision: string,
-    reasons: string[]
-  }
+    decision: string,       // human-readable explanation
+    reasons: string[],      // array of reasoning steps
+    signals: {
+      onchain: { feedbackCount, averageScore, threshold },
+      local:   { exists, graduated, tier, riskLevel, score },
+    },
+  },
+  timestamp: string,
 }
 ```
 
-**Example:**
-```typescript
-const profile = await valiron.getAgentProfile('417');
-console.log(`Score: ${profile.localReputation.score}/100`);
-console.log(`Tier: ${profile.localReputation.tier}`);
-console.log(`On-chain feedback: ${profile.onchainReputation.count} entries`);
-```
-
 ---
 
-#### `submitFeedback(params: SubmitFeedbackParams): Promise<{ success: boolean; txHash?: string }>`
+### `getWalletProfile(wallet): Promise<WalletProfile>`
 
-Submit feedback about an agent's behavior. Valiron handles IPFS storage and on-chain submission automatically.
-
-**Parameters:**
-```typescript
-{
-  agentId: string,
-  score: number,        // 0-100
-  outcome: 'success' | 'failure',
-  metadata?: {          // Custom metadata
-    [key: string]: any
-  }
-}
-```
+Reverse-lookup a wallet address to get its trust profile.
 
-**Example:**
 ```typescript
-await valiron.submitFeedback({
-  agentId: '417',
-  score: 95,
-  outcome: 'success',
-  metadata: {
-    taskType: 'data_processing',
-    duration: 2340,
-    recordsProcessed: 10000
-  }
-});
+const profile = await valiron.getWalletProfile('0x52ce…');
+console.log(profile.routing.finalRoute);
 ```
 
 ---
 
-#### `triggerSandboxTest(params: SandboxTestParams): Promise<{ success: boolean; message: string }>`
+### `triggerSandboxTest(agentId): Promise<SandboxResult>`
 
-Manually trigger sandbox testing for an agent.
+Run real sandbox tests against an agent and compute a Valiron score.
 
-**Example:**
 ```typescript
-await valiron.triggerSandboxTest({
-  agentId: '417',
-  behaviorType: 'good'
-});
+const result = await valiron.triggerSandboxTest('25459');
+console.log(result.valironScore); // 95
+console.log(result.tier);         // 'AAA'
+console.log(result.riskLevel);    // 'GREEN'
+console.log(result.mode);         // 'endpoint-probe' | 'sandbox-relay'
+console.log(result.testSummary);
+// { totalRequests, successCount, rateLimitCount, errorCount, avgLatencyMs }
 ```
 
 ---
@@ -232,216 +176,77 @@ await valiron.triggerSandboxTest({
 ### Express.js Middleware
 
 ```typescript
-import { ValironSDK } from '@valiron/sdk';
 import express from 'express';
+import { ValironSDK } from '@valiron/sdk';
 
 const app = express();
-const valiron = new ValironSDK({ apiKey: process.env.VALIRON_API_KEY! });
-
-async function valironMiddleware(req, res, next) {
-  const agentId = req.headers['x-agent-id'];
-  
-  const decision = await valiron.checkAgent(agentId);
-  
-  if (decision.route === 'prod' || decision.route === 'prod_throttled') {
+const valiron = new ValironSDK();
+
+app.use('/api/protected/*', async (req, res, next) => {
+  const agentId = req.headers['x-agent-id'] as string;
+  if (!agentId) return res.status(400).json({ error: 'Missing x-agent-id' });
+
+  const profile = await valiron.getAgentProfile(agentId);
+  const { finalRoute } = profile.routing;
+
+  if (finalRoute === 'prod' || finalRoute === 'prod_throttled') {
+    (req as any).valironProfile = profile;
     return next();
   }
-  
+
   return res.status(403).json({
-    error: 'Access denied',
-    reason: decision.reason
+    error: finalRoute === 'sandbox' ? 'Agent under evaluation' : 'Access denied',
+    message: profile.routing.decision,
   });
-}
-
-app.use('/api/protected/*', valironMiddleware);
+});
 ```
 
 ### Next.js Middleware
 
 ```typescript
-// middleware.ts
 import { NextRequest, NextResponse } from 'next/server';
 import { ValironSDK } from '@valiron/sdk';
 
-const valiron = new ValironSDK({ apiKey: process.env.VALIRON_API_KEY! });
+const valiron = new ValironSDK();
 
 export async function middleware(request: NextRequest) {
   const agentId = request.headers.get('x-agent-id');
-  const decision = await valiron.checkAgent(agentId!);
-  
-  if (decision.route === 'prod' || decision.route === 'prod_throttled') {
-    return NextResponse.next();
+  if (!agentId) {
+    return NextResponse.json({ error: 'Missing x-agent-id' }, { status: 400 });
   }
-  
-  return NextResponse.json(
-    { error: 'Access denied' },
-    { status: 403 }
-  );
-}
-
-export const config = {
-  matcher: '/api/protected/:path*'
-};
-```
 
-### Simple API Gateway
-
-```typescript
-import { ValironSDK } from '@valiron/sdk';
+  const route = await valiron.checkAgent(agentId);
 
-const valiron = new ValironSDK({ apiKey: 'vln_xxx' });
-
-async function handleRequest(agentId: string) {
-  const decision = await valiron.checkAgent(agentId);
-  
-  switch (decision.route) {
-    case 'prod':
-      return processRequest({ rateLimit: null });
-    
-    case 'prod_throttled':
-      return processRequest({ rateLimit: '100/hour' });
-    
-    case 'sandbox':
-      return { error: 'Agent under evaluation', retryAfter: 30 };
-    
-    case 'sandbox_only':
-      return { error: 'Access denied', reason: decision.reason };
+  if (route === 'prod' || route === 'prod_throttled') {
+    return NextResponse.next();
   }
-}
-```
-
-### Integration with x402 Payment APIs
-
-Valiron integrates with **x402** payment-gated APIs (e.g., [Orthogonal](https://www.orth.sh/)). Verify trust before processing payments to prevent malicious agents from accessing paid endpoints.
-
-#### Server-Side: Validate Trust + Payment
-
-```typescript
-import { ValironSDK } from '@valiron/sdk';
-import { privateKeyToAccount } from 'viem/accounts';
-import { getAddress } from 'viem';
-import { exact } from 'x402/schemes'; // Real x402 package
-
-const valiron = new ValironSDK();
 
-async function trustThenPayment(req, res, next) {
-  const agentId = req.headers['x-agent-id'];
-  const paymentHeader = req.headers['x-payment'];
-  
-  // Step 1: Verify trust before payment
-  const { route, localReputation } = await valiron.checkAgent(agentId);
-  
-  if (route === 'sandbox_only') {
-    return res.status(403).json({
-      error: 'Agent banned',
-      reason: 'Failed behavioral trust requirements'
-    });
-  }
-  
-  if (route === 'sandbox') {
-    return res.status(403).json({
-      error: 'Agent under evaluation',
-      retryAfter: 30
-    });
-  }
-  
-  // Step 2: Verify payment (trusted agents only)
-  if (!paymentHeader) {
-    // Dynamic pricing based on trust tier
-    const pricing = {
-      'AAA': 5, 'AA': 5, 'A': 8, 'BAA': 10,
-      'BA': 25, 'B': 50, 'CAA': 100, 'CA': 100, 'C': 100
-    };
-    
-    return res.status(402).json({
-      error: 'Payment Required',
-      accepts: [{
-        scheme: 'exact',
-        network: 'base',
-        maxAmountRequired: pricing[localReputation?.tier || 'B'],
-        asset: '0x...',
-        payTo: '0x...',
-        // ... x402 payment requirements
-      }]
-    });
-  }
-  
-  // Verify payment (use x402 library)
-  const valid = await exact.evm.verifyPayment(paymentHeader);
-  if (!valid) {
-    return res.status(402).json({ error: 'Invalid payment' });
-  }
-  
-  // Step 3: Apply trust-based rate limits
-  req.rateLimit = route === 'prod' ? 1000 : 100; // requests/hour
-  next();
+  return NextResponse.json({ error: 'Access denied' }, { status: 403 });
 }
 
-app.get('/api/premium/weather', trustThenPayment, handler);
+export const config = { matcher: '/api/protected/:path*' };
 ```
 
-#### Client-Side: Make Trusted Payments
+### x402 Payment Integration
 
-```typescript
-import { ValironSDK } from '@valiron/sdk';
-import { exact } from 'x402/schemes';
-import { privateKeyToAccount } from 'viem/accounts';
+Valiron integrates with x402 payment-gated APIs (e.g., [Orthogonal](https://www.orth.sh/)). Verify trust before processing payments to prevent malicious agents from accessing paid endpoints.
 
-const valiron = new ValironSDK();
-const account = privateKeyToAccount(process.env.PRIVATE_KEY);
+```typescript
+const profile = await valiron.getAgentProfile(agentId);
 
-async function fetchPaidAPI(agentId: string, url: string) {
-  // Optional: Verify own trust status
-  const { route } = await valiron.checkAgent(agentId);
-  if (route === 'sandbox_only') {
-    throw new Error('Agent access denied');
-  }
-  
-  // Get payment requirements
-  const res = await fetch(url);
-  const { accepts } = await res.json();
-  
-  // Create x402 payment header
-  const paymentHeader = await exact.evm.createPaymentHeader(
-    account,
-    1,
-    accepts[0]
-  );
-  
-  // Retry with payment
-  const data = await fetch(url, {
-    headers: { 'X-PAYMENT': paymentHeader }
-  }).then(r => r.json());
-  
-  return data;
+if (profile.routing.finalRoute === 'sandbox_only') {
+  return res.status(403).json({ error: 'Agent banned' });
 }
-```
 
-**Trust + Payment Benefits:**
-- Reject untrusted agents before payment verification
-- Implement dynamic pricing based on trust tier
-- Reduce transaction overhead by filtering banned agents
-- Mitigate DDoS attacks from paid malicious requests
+// Trust-based pricing — better agents pay less
+const pricing = { AAA: 5, AA: 5, A: 8, BAA: 10, BA: 25, B: 50 };
+const tier = profile.localReputation?.tier || 'B';
+const price = pricing[tier] || 50;
 
-**Compatible with:**
-- [Orthogonal](https://www.orth.sh/) x402 API marketplace
-- Any HTTP 402 Payment Required API
-
-See [examples/x402-integration.ts](examples/x402-integration.ts) for complete implementation.
-
-## TypeScript Types
-
-The SDK is fully typed. Import types as needed:
-
-```typescript
-import {
-  ValironSDK,
-  RouteDecision,
-  MoodysRating,
-  AgentProfile,
-  RoutingResponse,
-  ValironError
-} from '@valiron/sdk';
+// Return x402 payment challenge
+return res.status(402).json({
+  accepts: [{ scheme: 'exact', maxAmountRequired: price, payTo: '0x…' }],
+});
 ```
 
 ## Moody's Credit Rating Tiers
@@ -458,29 +263,43 @@ import {
 | CA | 20-34 | Extremely speculative | Sandbox only |
 | C | 0-19 | Default risk | Sandbox only |
 
+## TypeScript Types
+
+The SDK is fully typed. Import types as needed:
+
+```typescript
+import {
+  ValironSDK,
+  RouteDecision,
+  MoodysRating,
+  RiskLevel,
+  AgentProfile,
+  WalletProfile,
+  SandboxResult,
+  AgentIdentity,
+  OnchainReputation,
+  LocalReputation,
+  RoutingExplanation,
+  BehavioralMetrics,
+  FeedbackEntry,
+  ValironError,
+  ValironClient,
+} from '@valiron/sdk';
+```
+
 ## Error Handling
 
 ```typescript
 import { ValironError } from '@valiron/sdk';
 
 try {
-  const decision = await valiron.checkAgent('123');
+  const profile = await valiron.getAgentProfile('123');
 } catch (error) {
   if (error instanceof ValironError) {
-    console.error('Code:', error.code);
-    console.error('Message:', error.message);
-    console.error('Status:', error.statusCode);
-    
     switch (error.code) {
-      case 'TIMEOUT_ERROR':
-        // Handle timeout
-        break;
-      case 'NETWORK_ERROR':
-        // Handle network issues
-        break;
-      case 'API_ERROR':
-        // Handle API errors
-        break;
+      case 'TIMEOUT_ERROR':  // Request timed out
+      case 'NETWORK_ERROR':  // Could not reach API
+      case 'API_ERROR':      // Non-2xx response (check error.statusCode)
     }
   }
 }
@@ -492,7 +311,7 @@ try {
 
 ## Support
 
-- **Email**: founders@valiron.io
+- **Email**: founders@valiron.co
 
 ## License