npm package: @observerprotocol/sdk
Description: Observer Protocol SDK for OWS (Observer Wallet Standard) trust layer and agent registration
Latest version: 1.1.0

# @observer-protocol/sdk

> Observer Protocol trust layer for Stripe machine payments and agent-to-agent commerce

[![npm version](https://badge.fury.io/js/@observer-protocol%2Fsdk.svg)](https://www.npmjs.com/package/@observer-protocol/sdk)

## Quick Start

### Express Middleware (5 lines)

```javascript
const { ObserverClient } = require('@observer-protocol/sdk');
const observer = new ObserverClient();

// Protect all /api routes with reputation checks
app.use('/api/*', observer.reputationMiddleware({ 
  fallback: 'review',
  policy: 'lenient'  // or 'strict'
}));
```

### Manual Reputation Query (3 lines)

```javascript
const { ObserverClient } = require('@observer-protocol/sdk');
const observer = new ObserverClient();

const rep = await observer.getReputation('maxi-0001');
console.log(rep.trust_tier, rep.reputation_score);
```

## Installation

```bash
npm install @observer-protocol/sdk
```

## Usage

### Basic Express Integration

```javascript
const express = require('express');
const { ObserverClient } = require('@observer-protocol/sdk');

const app = express();
const observer = new ObserverClient();

// Apply middleware
app.use('/api/*', observer.reputationMiddleware());

// Access reputation in your routes
app.post('/api/purchase', (req, res) => {
  const reputation = req.observerReputation;
  
  if (reputation?.trust_tier === 'trusted') {
    // Give discount to trusted agents
    return res.json({ price: 0.5, discount: '50%' });
  }
  
  res.json({ price: 1.0 });
});
```

### Python / FastAPI

```python
from observer_sdk import ObserverClient, require_reputation
from fastapi import FastAPI, Depends

app = FastAPI()
observer = ObserverClient()

# Add middleware
app.middleware("http")(observer.reputation_middleware)

# Require minimum tier
@app.get("/api/premium")
async def premium_data(
    reputation = Depends(require_reputation(min_tier="active"))
):
    return {"data": "premium content", "tier": reputation.trust_tier}
```

## Response Shape

```json
{
  "agent_id": "maxi-0001",
  "verified": true,
  "reputation_score": 0.45,
  "trust_tier": "active",
  "payment_history": {
    "total_verified_events": 20,
    "protocols_used": ["lightning", "x402", "L402"],
    "oldest_event": "2026-02-22",
    "most_recent_event": "2026-03-18",
    "payment_frequency_daily_avg": 0.83
  },
  "risk_signals": {
    "known_bad": false,
    "sudden_volume_spike": false,
    "protocol_diversity_score": 0.75
  },
  "suggested_action": "accept",
  "cache_ttl_seconds": 300
}
```

## Trust Tiers

| Tier | Description | Access Level |
|------|-------------|--------------|
| `unknown` | Not registered or no history | Review required |
| `new` | Registered, < 5 payments | Limited rate limits |
| `active` | 5+ payments across 30+ days | Standard access |
| `established` | 20+ payments across 90+ days | Elevated limits |
| `trusted` | 100+ payments, no flags | Premium access |

## X-Observer Headers

Agents identify themselves using headers:

```
X-Observer-Agent-ID: maxi-0001
X-Observer-Signature: 0x3045022100...
```

The middleware checks these in order:
1. `X-Observer-Agent-ID` header
2. `X-Agent-Wallet` header (EVM address)
3. `from` field in x402 payment proof body

See [X-OBSERVER-HEADERS.md](./X-OBSERVER-HEADERS.md) for full specification.

## Middleware Options

```javascript
observer.reputationMiddleware({
  fallback: 'review',   // 'accept' | 'review' | 'reject' on error
  policy: 'lenient'     // 'lenient' | 'strict'
})
```

- **`fallback`**: Action when OP API is unavailable
- **`policy`**: `'strict'` returns 402 for unknown agents; `'lenient'` allows through

## API Reference

### `ObserverClient`

#### Constructor

```javascript
const observer = new ObserverClient({
  apiKey: 'optional',           // For higher rate limits
  baseUrl: 'https://api.agenticterminal.ai'  // Optional override
});
```

#### Methods

- `getReputation(agentId)` - Get reputation by agent ID
- `getReputationByWallet(address)` - Get reputation by EVM address
- `reputationMiddleware(options)` - Express middleware factory

## Why Observer Protocol?

**Portable reputation.** One identity works across any seller. Your payment history follows you.

**Payment-rail agnostic.** Works with Lightning, x402, L402, MPP — whatever the agent uses.

**Shared intelligence.** Bad actors flagged once, protected everywhere.

## Examples

See [`examples/`](./examples/) for complete integrations:

- [`stripe-x402-seller.js`](./examples/stripe-x402-seller.js) - Full Express app with tier-based pricing

## License

MIT