@x402sentinel/x402 0.1.4 → 0.2.0

package/README.md

@@ -22,6 +22,92 @@
 
 **One line to add. Zero config to start.**
 
+## Quick Start
+
+```bash
+npm install @x402sentinel/x402
+```
+
+```typescript
+import { sentinel } from "@x402sentinel/x402";
+
+const fetch = sentinel(globalThis.fetch);
+
+// That's it. Every x402 payment is now tracked.
+// View your data: sentinel.valeocash.com
+```
+
+### With options (optional)
+
+```typescript
+const fetch = sentinel(globalThis.fetch, {
+  agentId: "my-agent",
+  apiKey: "your-api-key",  // from sentinel.valeocash.com/dashboard/settings
+});
+```
+
+---
+
+## Framework Packages
+
+One-liner integrations for popular frameworks:
+
+| Package | Install |
+|---------|---------|
+| **Express** | `npm install @x402sentinel/express` |
+| **Next.js** | `npm install @x402sentinel/next` |
+| **LangChain** | `npm install @x402sentinel/langchain` |
+| **Vercel AI SDK** | `npm install @x402sentinel/vercel-ai` |
+
+### Express
+
+```typescript
+import express from "express";
+import { sentinelMiddleware } from "@x402sentinel/express";
+
+const app = express();
+app.use(sentinelMiddleware());
+
+app.get("/data", async (req, res) => {
+  const data = await req.sentinelFetch("https://api.example.com/paid");
+  res.json(await data.json());
+});
+```
+
+### Next.js
+
+```typescript
+// app/api/data/route.ts
+import { withSentinel } from "@x402sentinel/next";
+
+export const GET = withSentinel(async (req, sentinelFetch) => {
+  const res = await sentinelFetch("https://api.example.com/paid");
+  return Response.json(await res.json());
+});
+```
+
+### LangChain
+
+```typescript
+import { SentinelX402Tool } from "@x402sentinel/langchain";
+
+const tools = [new SentinelX402Tool({ agentId: "research-agent" })];
+```
+
+### Vercel AI SDK
+
+```typescript
+import { sentinelX402Tool } from "@x402sentinel/vercel-ai";
+
+const result = await generateText({
+  model: openai("gpt-4"),
+  tools: { x402: sentinelX402Tool({ agentId: "my-agent" }) },
+  prompt: "Fetch the latest weather data",
+});
+```
+
+---
+
 ## The Problem
 
 AI agents are spending real money autonomously. The [x402 protocol](https://github.com/coinbase/x402) enables internet-native payments, but provides no built-in audit trail, budget controls, or compliance tooling.
@@ -34,7 +120,27 @@ Sentinel fixes this with a single line of code.
 
 ---
 
-## Quick Start
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Budget Enforcement** | Per-call, hourly, daily, and lifetime spend limits. Blocks before payment. |
+| **Spike Detection** | Flags payments that exceed N x the rolling average |
+| **Audit Trails** | Every payment logged with agent ID, team, endpoint, tx hash, timing |
+| **Cryptographic Receipts** | HMAC-SHA256 signed proof for every payment |
+| **Endpoint Filtering** | Allowlist/blocklist URL patterns |
+| **Approval Workflows** | Require human approval above a threshold |
+| **Storage Backends** | In-memory (default), JSONL file, or remote API |
+| **Dashboard Queries** | Query spend by agent, team, endpoint, time range |
+| **CSV/JSON Export** | Export audit data for compliance reviews |
+| **Zero Config** | Works with no API key. Claim your data later. |
+| **Drop-in Wrapper** | One line change. Remove Sentinel, code works identically. |
+
+---
+
+## Advanced Configuration
+
+For full control, use `wrapWithSentinel` directly:
 
 ### Before (plain x402)
 
@@ -54,67 +160,34 @@ const response = await fetchWithPayment("https://api.example.com/paid");
 ```ts
 import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
 import { registerExactEvmScheme } from "@x402/evm/exact/client";
-import { wrapWithSentinel, standardPolicy } from "@x402sentinel/x402"; // <-- add
+import { wrapWithSentinel, standardPolicy } from "@x402sentinel/x402";
 
 const client = new x402Client();
 registerExactEvmScheme(client, { signer });
 const fetchWithPayment = wrapFetchWithPayment(fetch, client);
 
-const secureFetch = wrapWithSentinel(fetchWithPayment, {   // <-- wrap
+const secureFetch = wrapWithSentinel(fetchWithPayment, {
   agentId: "agent-weather-001",
   budget: standardPolicy(),
 });
 
-const response = await secureFetch("https://api.example.com/paid"); // same API
+const response = await secureFetch("https://api.example.com/paid");
 ```
 
-That's it. Same `fetch` interface. Budget enforcement + audit trail included.
-
-### Install
-
-```bash
-npm install @x402sentinel/x402
-# or
-pnpm add @x402sentinel/x402
-```
-
----
-
-## Features
-
-| Feature | Description |
-|---------|-------------|
-| **Budget Enforcement** | Per-call, hourly, daily, and lifetime spend limits. Blocks before payment. |
-| **Spike Detection** | Flags payments that exceed N× the rolling average |
-| **Audit Trails** | Every payment logged with agent ID, team, endpoint, tx hash, timing |
-| **Endpoint Filtering** | Allowlist/blocklist URL patterns |
-| **Approval Workflows** | Require human approval above a threshold |
-| **Storage Backends** | In-memory (default), JSONL file, or remote API |
-| **Dashboard Queries** | Query spend by agent, team, endpoint, time range |
-| **CSV/JSON Export** | Export audit data for compliance reviews |
-| **Zero Dependencies** | No runtime deps beyond x402 peer deps |
-| **Drop-in Wrapper** | One line change. Remove Sentinel, code works identically. |
-
----
-
-## Configuration
+### Full Configuration
 
 ```ts
 const secureFetch = wrapWithSentinel(fetchWithPayment, {
-  // Required
   agentId: "agent-weather-001",
-
-  // Optional identity
   team: "data-ops",
   humanSponsor: "alice@company.com",
 
-  // Budget policy
   budget: {
-    maxPerCall: "1.00",      // max USDC per single payment
-    maxPerHour: "25.00",     // hourly rolling cap
-    maxPerDay: "200.00",     // daily rolling cap
-    maxTotal: "10000.00",    // lifetime cap
-    spikeThreshold: 3.0,     // flag if > 3× rolling average
+    maxPerCall: "1.00",
+    maxPerHour: "25.00",
+    maxPerDay: "200.00",
+    maxTotal: "10000.00",
+    spikeThreshold: 3.0,
     allowedEndpoints: ["https://api.trusted.com/*"],
     blockedEndpoints: ["https://api.sketchy.com/*"],
     requireApproval: {
@@ -123,10 +196,9 @@ const secureFetch = wrapWithSentinel(fetchWithPayment, {
     },
   },
 
-  // Audit settings
   audit: {
     enabled: true,
-    storage: new MemoryStorage(),  // or FileStorage, ApiStorage
+    storage: new MemoryStorage(),
     redactFields: ["secret_key"],
     enrichment: {
       staticTags: ["production"],
@@ -136,14 +208,12 @@ const secureFetch = wrapWithSentinel(fetchWithPayment, {
     },
   },
 
-  // Lifecycle hooks
   hooks: {
     afterPayment: async (record) => { /* log to DataDog */ },
     onBudgetExceeded: async (violation) => { /* page on-call */ },
     onAnomaly: async (anomaly) => { /* alert Slack */ },
   },
 
-  // Custom metadata on every record
   metadata: { environment: "production", cost_center: "ENG-2024" },
 });
 ```
@@ -192,9 +262,8 @@ try {
 } catch (err) {
   if (err instanceof SentinelBudgetError) {
     console.log(err.message);
-    // "Budget exceeded: $2.50 spent of $5.00 hourly limit on agent-weather-001"
-    console.log(err.violation.type);   // "hourly"
-    console.log(err.violation.limit);  // "5.00"
+    console.log(err.violation.type);
+    console.log(err.violation.limit);
   }
 }
 ```
@@ -207,12 +276,12 @@ Every payment produces an `AuditRecord` with:
 
 ```ts
 {
-  id: "a1b2c3d4e5f6g7h8",    // deterministic hash
+  id: "a1b2c3d4e5f6g7h8",
   agent_id: "agent-weather-001",
   team: "data-ops",
   human_sponsor: "alice@company.com",
-  amount: "0.50",              // human-readable USDC
-  amount_raw: "500000",        // base units
+  amount: "0.50",
+  amount_raw: "500000",
   asset: "USDC",
   network: "eip155:8453",
   tx_hash: "0xabc...",
@@ -239,7 +308,7 @@ const memory = new MemoryStorage(10_000);
 // JSONL file — persistent, append-only
 const file = new FileStorage(".valeo/audit.jsonl");
 
-// Remote API — batched writes to api.valeo.money
+// Remote API — batched writes to sentinel.valeocash.com
 const api = new ApiStorage({ apiKey: "val_..." });
 ```
 
@@ -258,7 +327,7 @@ const records = await logger.query({
 });
 
 const summary = await logger.summarize({ team: "data-ops" });
-console.log(summary.total_spend);  // "$1,234.56"
+console.log(summary.total_spend);
 
 const csv = await logger.exportCSV();
 ```
@@ -272,17 +341,8 @@ import { SentinelDashboard } from "@x402sentinel/x402/dashboard";
 
 const dashboard = new SentinelDashboard({ storage: myStorage });
 
-// Spend reports
-const report = await dashboard.getSpend({
-  agentId: "bot-1",
-  range: "last_day",
-});
-console.log(report.totalSpend, report.count);
-
-// Agent summaries
+const report = await dashboard.getSpend({ agentId: "bot-1", range: "last_day" });
 const agents = await dashboard.getAgents();
-
-// Alerts (violations + anomalies)
 const alerts = await dashboard.getAlerts();
 ```
 
@@ -290,23 +350,15 @@ Dashboard queries run locally against your storage backend. No remote API requir
 
 ---
 
-## Integration Guide
-
-Sentinel wraps **any** x402-compatible fetch. It works with:
-
-- `@x402/fetch` + `x402Client` (current)
-- `x402-fetch` + viem wallet (legacy)
-- Any function with the `fetch` signature that handles x402 internally
+## API Reference
 
-The wrapper never touches the response body. It reads only headers (`PAYMENT-RESPONSE`, `PAYMENT-REQUIRED`) for audit data.
+### `sentinel(fetch, options?): typeof fetch`
 
----
-
-## API Reference
+Zero-config wrapper. Works with no API key. Call `sentinel(globalThis.fetch)` and every x402 payment is tracked.
 
 ### `wrapWithSentinel(fetch, config): typeof fetch`
 
-Wraps an x402 fetch function with Sentinel instrumentation. Returns a drop-in replacement.
+Full-config wrapper with budget enforcement, audit trails, hooks, and metadata.
 
 ### `BudgetManager`
 
@@ -353,11 +405,16 @@ Sentinel is an SDK + Dashboard + API + Docs in a single monorepo:
 
 ```
 ├── /                      SDK (@x402sentinel/x402)
+├── packages/              Framework integrations
+│   ├── express/           @x402sentinel/express
+│   ├── next/              @x402sentinel/next
+│   ├── langchain/         @x402sentinel/langchain
+│   └── vercel-ai/         @x402sentinel/vercel-ai
 ├── app/                   Next.js 15 application
 │   ├── /login             API key authentication
 │   ├── /dashboard         Real-time analytics dashboard
 │   ├── /docs              Full documentation site
-│   └── /api/v1/*          REST API (18 endpoints)
+│   └── /api/v1/*          REST API (20+ endpoints)
 ├── Dockerfile             Production Docker image
 └── docker-compose.yml     One-command deployment
 ```
@@ -397,7 +454,7 @@ Login with demo API key: `sk_sentinel_demo_000`
 - Escrow and pre-commitment flows
 - Treasury management integration
 - On-chain agent identity verification
-- Real-time dashboard at [app.valeo.money](https://app.valeo.money)
+- Real-time dashboard at [sentinel.valeocash.com](https://sentinel.valeocash.com)
 
 ---
 

package/dist/index.cjs

@@ -924,76 +924,6 @@ function wrapWithSentinel(fetchWithPayment, config) {
   };
   return sentinelFetch;
 }
-var FileStorage = class {
-  filePath;
-  buffer = [];
-  flushThreshold;
-  flushTimer = null;
-  constructor(filePath = ".valeo/audit.jsonl", flushThreshold = 100) {
-    this.filePath = filePath;
-    this.flushThreshold = flushThreshold;
-    this.ensureDir();
-    this.startAutoFlush();
-  }
-  async write(record) {
-    this.buffer.push(record);
-    if (this.buffer.length >= this.flushThreshold) {
-      await this.flush();
-    }
-  }
-  async query(query) {
-    await this.flush();
-    const all = this.readAll();
-    let results = all.filter((r) => matchesQuery(r, query));
-    const offset = query.offset ?? 0;
-    const limit = query.limit ?? results.length;
-    return results.slice(offset, offset + limit);
-  }
-  async summarize(query) {
-    await this.flush();
-    const records = this.readAll().filter((r) => matchesQuery(r, query));
-    return buildSummary(records, query);
-  }
-  async count(query) {
-    await this.flush();
-    return this.readAll().filter((r) => matchesQuery(r, query)).length;
-  }
-  async getById(id) {
-    await this.flush();
-    return this.readAll().find((r) => r.id === id) ?? null;
-  }
-  /** Write buffered records to disk */
-  async flush() {
-    if (this.buffer.length === 0) return;
-    const lines = this.buffer.map((r) => JSON.stringify(r)).join("\n") + "\n";
-    fs.appendFileSync(this.filePath, lines, "utf-8");
-    this.buffer = [];
-  }
-  /** Stop the auto-flush timer (for clean shutdown) */
-  destroy() {
-    if (this.flushTimer) {
-      clearInterval(this.flushTimer);
-      this.flushTimer = null;
-    }
-  }
-  readAll() {
-    if (!fs.existsSync(this.filePath)) return [];
-    const content = fs.readFileSync(this.filePath, "utf-8");
-    return content.split("\n").filter((line) => line.trim().length > 0).map((line) => JSON.parse(line));
-  }
-  ensureDir() {
-    const dir = path.dirname(this.filePath);
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true });
-    }
-  }
-  startAutoFlush() {
-    this.flushTimer = setInterval(() => {
-      void this.flush();
-    }, 5e3);
-    this.flushTimer.unref();
-  }
-};
 
 // src/audit/storage/api.ts
 var ApiStorage = class {
@@ -1115,6 +1045,115 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+// src/sentinel.ts
+function sentinel(fetchFn, options) {
+  const agentId = options?.agentId || `agent-${Date.now().toString(36)}`;
+  const apiKey = options?.apiKey || "anonymous";
+  const baseUrl = options?.baseUrl || "https://sentinel.valeocash.com";
+  const wrapped = wrapWithSentinel(fetchFn, {
+    agentId,
+    budget: {
+      maxPerCall: "10.00",
+      maxPerHour: "100.00",
+      maxPerDay: "1000.00"
+    },
+    audit: {
+      storage: new ApiStorage({
+        baseUrl: `${baseUrl}/api/v1`,
+        apiKey
+      })
+    }
+  });
+  if (apiKey === "anonymous") {
+    let hasLoggedOnce = false;
+    const sentinelFetch = async (input, init) => {
+      const response = await wrapped(input, init);
+      if (!hasLoggedOnce && (response.headers.has("payment-response") || response.headers.has("x-payment-response"))) {
+        hasLoggedOnce = true;
+        console.log(`
+\u2713 Payment tracked by Sentinel
+  Agent: ${agentId}
+  View: ${baseUrl}/agent/${agentId}
+  Claim your data: ${baseUrl}/claim
+`);
+      }
+      return response;
+    };
+    return sentinelFetch;
+  }
+  return wrapped;
+}
+var FileStorage = class {
+  filePath;
+  buffer = [];
+  flushThreshold;
+  flushTimer = null;
+  constructor(filePath = ".valeo/audit.jsonl", flushThreshold = 100) {
+    this.filePath = filePath;
+    this.flushThreshold = flushThreshold;
+    this.ensureDir();
+    this.startAutoFlush();
+  }
+  async write(record) {
+    this.buffer.push(record);
+    if (this.buffer.length >= this.flushThreshold) {
+      await this.flush();
+    }
+  }
+  async query(query) {
+    await this.flush();
+    const all = this.readAll();
+    let results = all.filter((r) => matchesQuery(r, query));
+    const offset = query.offset ?? 0;
+    const limit = query.limit ?? results.length;
+    return results.slice(offset, offset + limit);
+  }
+  async summarize(query) {
+    await this.flush();
+    const records = this.readAll().filter((r) => matchesQuery(r, query));
+    return buildSummary(records, query);
+  }
+  async count(query) {
+    await this.flush();
+    return this.readAll().filter((r) => matchesQuery(r, query)).length;
+  }
+  async getById(id) {
+    await this.flush();
+    return this.readAll().find((r) => r.id === id) ?? null;
+  }
+  /** Write buffered records to disk */
+  async flush() {
+    if (this.buffer.length === 0) return;
+    const lines = this.buffer.map((r) => JSON.stringify(r)).join("\n") + "\n";
+    fs.appendFileSync(this.filePath, lines, "utf-8");
+    this.buffer = [];
+  }
+  /** Stop the auto-flush timer (for clean shutdown) */
+  destroy() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+  readAll() {
+    if (!fs.existsSync(this.filePath)) return [];
+    const content = fs.readFileSync(this.filePath, "utf-8");
+    return content.split("\n").filter((line) => line.trim().length > 0).map((line) => JSON.parse(line));
+  }
+  ensureDir() {
+    const dir = path.dirname(this.filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+  startAutoFlush() {
+    this.flushTimer = setInterval(() => {
+      void this.flush();
+    }, 5e3);
+    this.flushTimer.unref();
+  }
+};
+
 exports.ApiStorage = ApiStorage;
 exports.AuditLogger = AuditLogger;
 exports.BudgetManager = BudgetManager;
@@ -1127,6 +1166,7 @@ exports.SentinelError = SentinelError;
 exports.conservativePolicy = conservativePolicy;
 exports.customPolicy = customPolicy;
 exports.liberalPolicy = liberalPolicy;
+exports.sentinel = sentinel;
 exports.standardPolicy = standardPolicy;
 exports.unlimitedPolicy = unlimitedPolicy;
 exports.validateConfig = validateConfig;