@agentvisa/widget 0.2.2 → 0.2.3

package/README.md

@@ -1,16 +1,12 @@
 # @agentvisa/widget
 
-Lightweight JavaScript/TypeScript widget for **AgentVisa** verification.
+Server-side middleware for **AgentVisa** verification — protect your Express or Next.js API routes so only AI agents backed by a verified human can access them.
 
-Drop-in verification for websites that need to confirm a real human has approved an AI agent's action.
+When an unverified agent hits a protected route, the middleware returns a `302` redirect (or `401`) pointing the agent to [agentvisa.ai/for-agents](https://agentvisa.ai/for-agents), where it prompts the human to sign up. Verified agents pass straight through.
 
-## Features
-
-- Works with both **Basic** and **Pro** tiers
-- Unified response shape for all plans
-- Zero runtime dependencies
-- < 5KB gzipped
-- TypeScript support
+> **Which package should I use?**
+> - **`@agentvisa/widget`** (this package) — use when you want the full viral redirect loop: unverified AI agents are redirected to AgentVisa to get verified, then come back. Also works as a plain `block` or `passthrough` gate. Supports Express and Next.js.
+> - **[`@agentvisa/verify`](https://www.npmjs.com/package/@agentvisa/verify)** — use when you just want to verify a token and get a result back. Simpler API, no redirect, no growth loop. Works with any Node.js framework.
 
 ## Installation
 
@@ -18,77 +14,134 @@ Drop-in verification for websites that need to confirm a real human has approved
 npm install @agentvisa/widget
 ```
 
-Or via CDN:
+## Quick start — Express
 
-```html
-<script src="https://cdn.agentvisa.ai/widget.js"></script>
-```
+```ts
+import express from 'express';
+import { agentVisa } from '@agentvisa/widget/express';
 
-## Usage
+const app = express();
 
-### Basic Usage (Recommended)
+app.use('/api', agentVisa({
+  widgetId: process.env.AV_WIDGET_ID!,
+  apiKey:   process.env.AV_API_KEY!,
+}));
+
+app.post('/api/order', (req, res) => {
+  // Only reaches here if the agent is verified
+  console.log(req.agentVisa.result.plan);  // "basic" | "pro"
+  res.json({ ok: true });
+});
+```
+
+## Quick start — Next.js
 
 ```ts
-import { AgentVisa } from "@agentvisa/widget";
+// middleware.ts (project root)
+import { withAgentVisa } from '@agentvisa/widget/next';
 
-const result = await AgentVisa.verify({
-  widgetId: "widget_abc123",
-  plan: "basic"
+export default withAgentVisa({
+  widgetId: process.env.AV_WIDGET_ID!,
+  apiKey:   process.env.AV_API_KEY!,
 });
 
-console.log(result.valid);     // true | false
-console.log(result.reason);    // "ok" | "expired" | "invalid" ...
-console.log(result.plan);      // "basic" | "pro"
+export const config = {
+  matcher: ['/api/:path*'],
+};
 ```
 
-### Instance Usage
+## How agents send their token
+
+Agents use the [AgentVisa MCP server](https://www.npmjs.com/package/@agentvisa/mcp) (`@agentvisa/mcp`) to exchange their permanent token for a short-lived `tmp_xxx` token, then send it in one of two ways:
+
+**Standard mode:**
+```
+X-AgentVisa-Token: tmp_xxxxxxxxxxxxxxxxxxxx
+```
+
+**Web Bot Auth mode** (RFC 9421 — token bound in the signature):
+```
+AgentVisa-Assertion: tmp_xxxxxxxxxxxxxxxxxxxx
+Signature-Input: sig1=("@method" "@path" "host" "agentvisa-assertion");keyid="key-1";created=1234567890
+Signature: sig1=:base64sig:
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `widgetId` | `string` | **required** | Your `wgt_xxx` widget ID |
+| `apiKey` | `string` | **required** | Your `wk_xxx` API key — **server-side only** |
+| `onUnverified` | `'redirect' \| 'block' \| 'passthrough'` | `'redirect'` | What to do when an agent is unverified |
+| `redirectUrl` | `string` | `'https://agentvisa.ai/for-agents'` | Where to redirect unverified AI agents |
+| `timeoutMs` | `number` | `5000` | Timeout for the `/v1/verify` API call |
+
+### `onUnverified` modes
+
+- **`'redirect'`** (default) — AI agents get a `302` to `/for-agents` with instructions. Human browsers and bot scrapers get a plain `401`. This is the viral growth mode: unverified agents send their human to sign up, then come back verified.
+- **`'block'`** — All unverified requests get `401`. Quiet hard gate.
+- **`'passthrough'`** — Attach the result to `req.agentVisa` (Express) or response headers (Next.js) and continue. Use this for soft-gating or analytics.
+
+## Express — reading the result
+
+On verified requests, `req.agentVisa` is populated:
 
 ```ts
-const visa = new AgentVisa({
-  widgetId: "widget_abc123",
-  plan: "pro"
+app.post('/api/action', (req, res) => {
+  const av = req.agentVisa!;
+  console.log(av.verified);          // true
+  console.log(av.result.plan);       // "basic" | "pro"
+  console.log(av.result.valid);      // true
+  console.log(av.result.verified_at); // ISO timestamp
+  console.log(av.result.web_bot_auth_bound); // true if RFC 9421 bound (Pro)
 });
-
-const result = await visa.verify();
 ```
 
-### Browser (UMD)
+In `'passthrough'` mode, unverified requests also reach your handler:
 
-```html
-<script src="https://cdn.agentvisa.ai/widget.js"></script>
-<script>
-  const result = await AgentVisa.verify({
-    widgetId: "widget_abc123",
-    plan: "basic"
-  });
-</script>
+```ts
+app.use(agentVisa({ widgetId, apiKey, onUnverified: 'passthrough' }));
+
+app.get('/api/data', (req, res) => {
+  if (!req.agentVisa?.verified) {
+    return res.json({ data: publicData, premium: null });
+  }
+  res.json({ data: publicData, premium: premiumData });
+});
 ```
 
-## Response Shape
+## Next.js — reading the result
 
-The widget always returns the unified response:
+On the edge or in a route handler, read the forwarded headers:
+
+```ts
+// app/api/route.ts
+export async function POST(request: Request) {
+  const verified = request.headers.get('x-agentvisa-verified') === 'true';
+  const reason   = request.headers.get('x-agentvisa-reason');
+
+  if (!verified) {
+    return Response.json({ error: reason }, { status: 401 });
+  }
+  // Proceed
+}
+```
+
+## Response shape from `/v1/verify`
 
 ```json
 {
   "valid": true,
   "reason": "ok",
   "plan": "basic",
-  "widget_id": "widget_abc123",
-  "human_name": null,
-  "email": null,
-  "phone": null,
-  "verified_at": null,
-  "expires_at": null
+  "widget_id": "wgt_abc123",
+  "verified_at": "2026-06-22T10:00:00Z",
+  "expires_at": "2026-06-23T10:00:00Z",
+  "domain_verified": true
 }
 ```
 
-## Configuration
-
-| Option       | Type               | Default                  | Description                     |
-|--------------|--------------------|--------------------------|---------------------------------|
-| `widgetId`   | `string`           | **required**             | Your AgentVisa widget ID        |
-| `plan`       | `"basic" \| "pro"` | `"basic"`                | Verification tier               |
-| `apiBaseUrl` | `string`           | `"https://api.agentvisa.ai"` | Backend API base URL        |
+Pro plan additionally returns `age_over_18`, `age_over_21`, `multiple_agents_authorized`, `web_bot_auth_bound`, and AVS-style attribute confirmations. Raw PII (name, email, phone) is never returned.
 
 ## Development
 
@@ -98,17 +151,10 @@ npm run build
 ```
 
 Build output is in `dist/`:
-
-- `widget.js` — UMD bundle (browser)
-- `widget.esm.js` — ESM bundle
-- `index.d.ts` — TypeScript definitions
-
-## Examples
-
-See the `examples/` folder:
-
-- `basic.html` — Basic tier demo
-- `pro.html` — Pro tier demo with richer data
+- `dist/express/index.js` — Express middleware
+- `dist/next/index.js` — Next.js middleware
+- `dist/core.js` — Shared verification logic
+- TypeScript declarations alongside each `.js` file
 
 ## Contributing
 
@@ -120,4 +166,4 @@ See [SECURITY.md](SECURITY.md).
 
 ## License
 
-MIT © [AgentVisa](https://agentvisa.ai)
+MIT © [AgentVisa](https://agentvisa.ai)

package/dist/index.d.ts

@@ -22,9 +22,6 @@ interface VerificationResult {
     verified_at: string | null;
     expires_at: string | null;
     domain_verified?: boolean;
-    human_name?: string | null;
-    email?: string | null;
-    phone?: string | null;
     age_over_18?: "y" | "n" | "null";
     age_over_21?: "y" | "n" | "null";
     gov_id_pic_validation?: "y" | "n" | "null";

package/dist/widget.esm.js

@@ -24,9 +24,6 @@ async function verifyToken(options) {
             reason: "network_error",
             plan,
             widget_id: widgetId,
-            human_name: null,
-            email: null,
-            phone: null,
             verified_at: null,
             expires_at: null,
         };

package/dist/widget.js

@@ -30,9 +30,6 @@
                 reason: "network_error",
                 plan,
                 widget_id: widgetId,
-                human_name: null,
-                email: null,
-                phone: null,
                 verified_at: null,
                 expires_at: null,
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentvisa/widget",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "AgentVisa widget + server middleware for Express and Next.js",
   "keywords": [
     "agentvisa",