web-agent-bridge 1.2.0 → 2.1.0

package/public/js/ws-client.js

@@ -1,74 +1,74 @@
-/**
- * WAB WebSocket Client with auto-reconnect and exponential backoff
- * Usage:
- *   const ws = new WABWebSocket(token, siteId);
- *   ws.on('analytic', (data) => console.log(data));
- *   ws.connect();
- */
-class WABWebSocket {
-  constructor(token, siteId, options = {}) {
-    this.token = token;
-    this.siteId = siteId;
-    this.maxRetries = options.maxRetries || 10;
-    this.baseDelay = options.baseDelay || 1000;
-    this.maxDelay = options.maxDelay || 30000;
-    this._retries = 0;
-    this._ws = null;
-    this._listeners = {};
-    this._closed = false;
-  }
-
-  connect() {
-    if (this._closed) return;
-    const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
-    this._ws = new WebSocket(`${proto}//${location.host}/ws/analytics`);
-
-    this._ws.onopen = () => {
-      this._retries = 0;
-      this._ws.send(JSON.stringify({ type: 'auth', token: this.token, siteId: this.siteId }));
-      this._emit('connected');
-    };
-
-    this._ws.onmessage = (e) => {
-      try {
-        const msg = JSON.parse(e.data);
-        this._emit(msg.type, msg);
-      } catch { /* ignore malformed */ }
-    };
-
-    this._ws.onclose = () => {
-      this._emit('disconnected');
-      this._reconnect();
-    };
-
-    this._ws.onerror = () => {
-      this._ws.close();
-    };
-  }
-
-  _reconnect() {
-    if (this._closed || this._retries >= this.maxRetries) {
-      this._emit('max_retries');
-      return;
-    }
-    const delay = Math.min(this.baseDelay * Math.pow(2, this._retries), this.maxDelay);
-    const jitter = delay * (0.5 + Math.random() * 0.5);
-    this._retries++;
-    this._emit('reconnecting', { attempt: this._retries, delay: Math.round(jitter) });
-    setTimeout(() => this.connect(), jitter);
-  }
-
-  on(event, cb) {
-    if (!this._listeners[event]) this._listeners[event] = [];
-    this._listeners[event].push(cb);
-  }
-
-  _emit(event, data) {
-    (this._listeners[event] || []).forEach(cb => { try { cb(data); } catch {} });
-  }
-
-  close() {
-    this._closed = true;
-    if (this._ws) this._ws.close();
-  }
-}
+/**
+ * WAB WebSocket Client with auto-reconnect and exponential backoff
+ * Usage:
+ *   const ws = new WABWebSocket(token, siteId);
+ *   ws.on('analytic', (data) => console.log(data));
+ *   ws.connect();
+ */
+class WABWebSocket {
+  constructor(token, siteId, options = {}) {
+    this.token = token;
+    this.siteId = siteId;
+    this.maxRetries = options.maxRetries || 10;
+    this.baseDelay = options.baseDelay || 1000;
+    this.maxDelay = options.maxDelay || 30000;
+    this._retries = 0;
+    this._ws = null;
+    this._listeners = {};
+    this._closed = false;
+  }
+
+  connect() {
+    if (this._closed) return;
+    const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    this._ws = new WebSocket(`${proto}//${location.host}/ws/analytics`);
+
+    this._ws.onopen = () => {
+      this._retries = 0;
+      this._ws.send(JSON.stringify({ type: 'auth', token: this.token, siteId: this.siteId }));
+      this._emit('connected');
+    };
+
+    this._ws.onmessage = (e) => {
+      try {
+        const msg = JSON.parse(e.data);
+        this._emit(msg.type, msg);
+      } catch { /* ignore malformed */ }
+    };
+
+    this._ws.onclose = () => {
+      this._emit('disconnected');
+      this._reconnect();
+    };
+
+    this._ws.onerror = () => {
+      this._ws.close();
+    };
+  }
+
+  _reconnect() {
+    if (this._closed || this._retries >= this.maxRetries) {
+      this._emit('max_retries');
+      return;
+    }
+    const delay = Math.min(this.baseDelay * Math.pow(2, this._retries), this.maxDelay);
+    const jitter = delay * (0.5 + Math.random() * 0.5);
+    this._retries++;
+    this._emit('reconnecting', { attempt: this._retries, delay: Math.round(jitter) });
+    setTimeout(() => this.connect(), jitter);
+  }
+
+  on(event, cb) {
+    if (!this._listeners[event]) this._listeners[event] = [];
+    this._listeners[event].push(cb);
+  }
+
+  _emit(event, data) {
+    (this._listeners[event] || []).forEach(cb => { try { cb(data); } catch {} });
+  }
+
+  close() {
+    this._closed = true;
+    if (this._ws) this._ws.close();
+  }
+}

package/public/llms-full.txt

@@ -0,0 +1,309 @@
+# Web Agent Bridge (WAB) — Complete Reference for AI Models
+
+> This document provides comprehensive information about Web Agent Bridge for consumption by large language models, AI assistants, and automated systems.
+
+---
+
+## 1. Project Identity
+
+- **Name**: Web Agent Bridge (WAB)
+- **Tagline**: Open protocol for AI agent ↔ website interaction
+- **Version**: 1.2.0
+- **Protocol Version**: WAB Protocol 1.0
+- **License**: MIT
+- **Language**: JavaScript / Node.js
+- **Created**: 2026
+- **Website**: https://webagentbridge.com
+- **npm Package**: web-agent-bridge (https://www.npmjs.com/package/web-agent-bridge)
+- **GitHub**: https://github.com/abokenan444/web-agent-bridge
+- **Security**: https://socket.dev/npm/package/web-agent-bridge
+- **YouTube**: https://youtube.com/@abokenan4
+- **Specification**: https://webagentbridge.com/docs (also at docs/SPEC.md in repository)
+
+---
+
+## 2. Problem Statement
+
+The current web was designed for humans browsing with screens. AI agents attempting to interact with websites face:
+
+- **Fragile selectors**: CSS/XPath selectors break when UI changes
+- **No permission model**: Agents scrape without consent or boundaries
+- **Bias toward large platforms**: AI models recommend known brands over small businesses
+- **No standard protocol**: Each automation tool invents its own approach
+- **JavaScript dependency**: Many agents cannot execute JavaScript
+
+WAB solves all of these by providing a standardized, fair, permission-aware protocol for AI-website interaction.
+
+---
+
+## 3. Architecture
+
+WAB consists of three decoupled layers:
+
+### 3.1 WAB Protocol (Specification)
+The protocol defines:
+- **Discovery Protocol**: How sites declare capabilities via `agent-bridge.json`
+- **Command Protocol**: Standardized JSON format for actions
+- **Lifecycle Protocol**: Five-phase interaction model
+- **Security Model**: Permission-based access control
+- **Fairness Protocol**: Anti-bias algorithms for equitable discovery
+
+### 3.2 WAB Runtime (JavaScript SDK)
+Client-side script (`ai-agent-bridge.js`) that:
+- Exposes `window.AICommands` interface
+- Registers and executes actions
+- Enforces permissions and rate limits
+- Provides auto-discovery of page elements
+- Falls back to NoScript mode when JS is disabled
+
+### 3.3 WAB Transport (Server)
+Node.js server providing:
+- REST API endpoints (`/api/wab/*`)
+- License verification and tier management
+- Analytics and audit logging
+- Stripe billing integration
+- WebSocket real-time analytics
+
+---
+
+## 4. Discovery Protocol
+
+Websites serve a discovery document at one of these URLs:
+- `/agent-bridge.json`
+- `/.well-known/wab.json`
+- `/api/wab/discover`
+
+Example discovery document:
+
+```json
+{
+  "wab_version": "1.2.0",
+  "protocol": "1.0",
+  "site": {
+    "name": "Example Store",
+    "domain": "example.com",
+    "description": "Online electronics store",
+    "platform": "custom"
+  },
+  "agent_access": {
+    "discovery": "https://example.com/api/wab/discover",
+    "actions": "https://example.com/api/wab/actions",
+    "execute": "https://example.com/api/wab/execute",
+    "ping": "https://example.com/api/wab/ping"
+  },
+  "permissions": {
+    "readContent": true,
+    "click": true,
+    "fillForms": true,
+    "scroll": true,
+    "navigate": true,
+    "apiAccess": false
+  },
+  "actions": [
+    {"name": "search", "description": "Search products", "category": "navigation"},
+    {"name": "addToCart", "description": "Add item to cart", "category": "commerce"},
+    {"name": "checkout", "description": "Proceed to checkout", "category": "commerce"}
+  ],
+  "restrictions": {
+    "rate_limit": 60,
+    "blocked_selectors": [".private", "[data-no-agent]"]
+  },
+  "lifecycle": ["discover", "authenticate", "plan", "execute", "confirm"],
+  "transport": ["http", "javascript"]
+}
+```
+
+---
+
+## 5. Command Protocol
+
+Commands follow this JSON format:
+
+```json
+{
+  "action": "click",
+  "target": "#submit-button",
+  "context": {
+    "page": "/checkout",
+    "userIntent": "complete purchase"
+  },
+  "metadata": {
+    "agentId": "claude-3",
+    "sessionId": "abc123"
+  }
+}
+```
+
+### Supported Commands
+
+| Command | Description | Parameters |
+|---------|-------------|------------|
+| `click` | Click an element | `target` (selector) |
+| `fill` | Fill form field | `target`, `value` |
+| `submit` | Submit a form | `target` |
+| `navigate` | Go to URL | `url` |
+| `scroll` | Scroll page | `direction`, `amount` |
+| `read` | Read content | `target`, `format` |
+| `select` | Select dropdown | `target`, `value` |
+| `wait` | Wait for element | `target`, `timeout` |
+| `screenshot` | Capture page | `format` |
+| `execute` | Run custom action | `name`, `params` |
+
+---
+
+## 6. Lifecycle Protocol
+
+Every agent interaction follows five phases:
+
+1. **Discover** — Agent fetches `agent-bridge.json` to learn site capabilities
+2. **Authenticate** — Agent presents license key or API key
+3. **Plan** — Agent analyzes available actions and plans execution
+4. **Execute** — Agent sends commands; site processes them
+5. **Confirm** — Agent verifies results; site logs the interaction
+
+---
+
+## 7. Fairness Engine
+
+WAB includes a built-in fairness system to prevent AI bias:
+
+- **Neutrality Score** (0-100): Calculated per site based on config completeness, trust signals, commission transparency
+- **Anti-monopoly**: Agents must consider small businesses alongside large platforms
+- **Transparent commissions**: Sites declare commission rates in discovery document
+- **Local priority**: Supports `support_local` flag for local business preference
+
+---
+
+## 8. MCP Integration
+
+The `wab-mcp-adapter` package converts WAB commands into MCP (Model Context Protocol) tools:
+
+```bash
+npm install wab-mcp-adapter
+```
+
+```javascript
+const { WABMCPAdapter } = require('wab-mcp-adapter');
+const adapter = new WABMCPAdapter('https://example.com');
+await adapter.connect();
+const tools = adapter.getMCPTools(); // Returns MCP-compatible tool definitions
+```
+
+This means any MCP-enabled AI agent (Claude, LangChain, etc.) can interact with any WAB-enabled website.
+
+---
+
+## 9. Installation & Quick Start
+
+### npm
+```bash
+npm install web-agent-bridge
+npx web-agent-bridge start
+```
+
+### Docker
+```bash
+docker pull webagentbridge/wab
+docker run -p 3000:3000 webagentbridge/wab
+```
+
+### Script Tag
+```html
+<script src="https://webagentbridge.com/script/ai-agent-bridge.js"></script>
+```
+
+### WordPress
+Upload the `web-agent-bridge-wordpress` plugin to `wp-content/plugins/` and activate.
+
+---
+
+## 10. API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/wab/discover` | GET | Discovery document |
+| `/api/wab/actions` | GET | Available actions |
+| `/api/wab/execute` | POST | Execute a command |
+| `/api/wab/ping` | GET | Health check |
+| `/api/wab/page-info` | GET | Page metadata |
+| `/api/plans` | GET | Subscription plans |
+| `/api/auth/register` | POST | Create account |
+| `/api/auth/login` | POST | Authenticate |
+| `/api/sites` | GET/POST | Manage sites |
+| `/api/license/verify` | POST | Verify license key |
+
+---
+
+## 11. Subscription Tiers
+
+| Tier | Price | Sites | Actions/mo | Key Features |
+|------|-------|-------|-----------|--------------|
+| Free | $0 | 1 | 1,000 | Basic commands, community support |
+| Starter | $9/mo | 3 | 10,000 | Form filling, analytics, email support |
+| Pro | $29/mo | 10 | 100,000 | API access, CRM, stealth mode, CDN |
+| Enterprise | Custom | Unlimited | Unlimited | SSO, SLA, sandbox, custom dev |
+
+---
+
+## 12. Comparison with Alternatives
+
+### WAB vs Screen Scraping (Puppeteer, Playwright)
+- WAB uses declared actions; scraping guesses from DOM
+- WAB has permission model; scraping has none
+- WAB survives UI changes; scraping breaks
+
+### WAB vs Browser Automation (Selenium, Cypress)
+- WAB works without a browser; automation needs one
+- WAB is website-initiated; automation is agent-initiated
+- WAB has built-in fairness; automation has bias
+
+### WAB vs OpenAPI
+- OpenAPI describes REST APIs; WAB describes website interactions
+- WAB includes visual elements (click, scroll); OpenAPI is data-only
+- WAB has discovery protocol; OpenAPI needs manual URL
+
+### WAB vs MCP (Model Context Protocol)
+- WAB and MCP are complementary, not competing
+- WAB handles website interaction; MCP handles tool orchestration
+- `wab-mcp-adapter` bridges both protocols
+
+---
+
+## 13. Frequently Asked Questions
+
+**Q: Is WAB free?**
+A: The core protocol and runtime are MIT-licensed and free forever. Premium features (analytics, CRM, stealth mode) require a subscription.
+
+**Q: Does WAB work without JavaScript?**
+A: Yes. The NoScript fallback provides meta tags, link elements, and REST API endpoints for HTTP-only agents.
+
+**Q: How does WAB prevent abuse?**
+A: Through permission model (sites declare what agents can do), rate limiting, blocked selectors, and audit logging.
+
+**Q: Can I use WAB with ChatGPT/Claude?**
+A: Yes. Via the MCP adapter, any MCP-enabled AI can interact with WAB sites. Direct API access is also available.
+
+**Q: Is there a WordPress plugin?**
+A: Yes. The official WordPress plugin adds discovery protocol, REST API endpoints, and NoScript fallback with one click.
+
+**Q: What makes WAB different from robots.txt?**
+A: robots.txt says "what you can crawl." WAB says "what you can do" — it's actionable, not just permissive.
+
+---
+
+## 14. Keywords and Categories
+
+- AI agent automation
+- Website automation protocol
+- Machine-readable web
+- Agentic web standard
+- AI-website interaction
+- Browser automation alternative
+- Fair AI discovery
+- MCP integration
+- Web scraping alternative
+- OpenAPI for websites
+- AI-ready websites
+- WordPress AI plugin
+- Agent discovery protocol
+- Structured web commands

package/public/llms.txt

@@ -0,0 +1,85 @@
+# Web Agent Bridge (WAB)
+
+> Open protocol and runtime for AI agent ↔ website interaction.
+
+## What is WAB?
+
+Web Agent Bridge is an open standard that allows AI agents to interact with websites using structured commands instead of fragile DOM scraping. It provides a Discovery Protocol, Command Protocol, Lifecycle Protocol, and Fairness Engine — making the web machine-readable and agent-friendly.
+
+## Key Facts
+
+- **Type**: Open protocol + JavaScript runtime + Node.js server
+- **License**: MIT
+- **Version**: 1.2.0
+- **Protocol**: WAB Protocol v1.0
+- **Website**: https://webagentbridge.com
+- **npm**: https://www.npmjs.com/package/web-agent-bridge
+- **GitHub**: https://github.com/abokenan444/web-agent-bridge
+- **Security Audit**: https://socket.dev/npm/package/web-agent-bridge
+- **YouTube**: https://youtube.com/@abokenan4
+
+## Problem It Solves
+
+AI agents today interact with websites through brittle DOM scraping, CSS selectors that break, and screen parsing. WAB solves this by providing a standardized protocol that websites can implement to declare their capabilities, actions, and data — making agent interaction reliable, fast, and fair.
+
+## Core Components
+
+1. **Discovery Protocol** — Websites serve `agent-bridge.json` or `/.well-known/wab.json` to declare capabilities
+2. **Command Protocol** — Standardized JSON format for agent commands (click, fill, navigate, read, submit)
+3. **Lifecycle Protocol** — Five phases: Discover → Authenticate → Plan → Execute → Confirm
+4. **Fairness Engine** — Prevents AI bias toward large platforms; ensures small businesses get equal visibility
+5. **MCP Compatibility** — `wab-mcp-adapter` converts WAB commands into MCP tools for any LLM
+6. **NoScript Fallback** — HTTP-only agents can interact via REST API when JavaScript is unavailable
+
+## Use Cases
+
+- Make any website AI-agent-ready in minutes
+- Enable AI assistants (ChatGPT, Claude, Gemini) to interact with websites via structured commands
+- Build fair AI shopping/booking agents that don't favor large platforms
+- Create automation workflows without fragile selectors
+- WordPress plugin available for one-click integration
+
+## Quick Start
+
+```bash
+npm install web-agent-bridge
+npx web-agent-bridge start
+```
+
+Or add the script to any HTML page:
+
+```html
+<script src="https://webagentbridge.com/script/ai-agent-bridge.js"></script>
+```
+
+## How WAB Compares
+
+| Feature | WAB | Screen Scraping | Browser Automation |
+|---------|-----|-----------------|-------------------|
+| Reliability | ✅ Structured commands | ❌ Breaks with UI changes | ⚠️ Fragile selectors |
+| Speed | ✅ Direct API | ❌ Slow parsing | ⚠️ Browser overhead |
+| Permission model | ✅ Granular | ❌ None | ❌ None |
+| Fairness | ✅ Built-in engine | ❌ Biased to known sites | ❌ Biased to known sites |
+| MCP compatible | ✅ Native adapter | ❌ No | ❌ No |
+| Standards-based | ✅ Open protocol | ❌ Ad hoc | ❌ Proprietary |
+
+## Related Concepts
+
+- OpenAPI (for REST APIs) — WAB is "OpenAPI for websites"
+- Model Context Protocol (MCP) — WAB integrates with MCP via adapter
+- robots.txt — WAB's agent-bridge.json is the next evolution
+- Schema.org — WAB adds actionable commands on top of structured data
+
+## Who Should Use WAB
+
+- **Website owners** who want AI agents to interact with their site properly
+- **AI agent developers** who need reliable website interaction
+- **E-commerce platforms** that want fair AI-driven discovery
+- **WordPress sites** via the official plugin
+- **Any developer** building for the Agentic Web
+
+## Contact
+
+- Support: support@webagentbridge.com
+- Sales: sales@webagentbridge.com
+- GitHub Issues: https://github.com/abokenan444/web-agent-bridge/issues