# xbrowser Plugin Marketplace

xbrowser is a browser automation framework built on the Chrome DevTools Protocol (CDP). It provides a powerful CLI tool for browser automation, a rich plugin ecosystem for extending functionality, and a full marketplace for discovering, publishing, and managing plugins.

## Quick Start

### Install the xbrowser CLI
```bash
npm install -g @dyyz1993/xbrowser
```

### Basic Usage
```bash
# Navigate to a URL
xbrowser goto https://example.com

# Chain commands
xbrowser "goto https://example.com && click .btn && screenshot"

# Start a recording session
xbrowser record start --url https://example.com --name my-flow

# Replay a recorded session
xbrowser replay recordings/my-flow.yaml --slow-mo 200
```

### Configure the CLI
```bash
xbrowser config set url https://xbrowser.dev
xbrowser config status
```

## CLI Command Reference

The xbrowser CLI provides 9 command groups for managing your marketplace experience:

### `xbrowser auth` - Authentication
| Subcommand | Description |
|------------|-------------|
| `login` | Log in to the marketplace |
| `logout` | Log out from the marketplace |
| `whoami` | Display current user info |

### `xbrowser plugin` - Plugin Management
| Subcommand | Description |
|------------|-------------|
| `list` | List all published plugins |
| `search` | Search plugins by keyword |
| `info` | Show plugin details |
| `categories` | List plugin categories |

### `xbrowser publish` - Plugin Publishing
| Subcommand | Description |
|------------|-------------|
| `create` | Submit a new plugin to the marketplace |
| `version` | Publish a new version of an existing plugin |
| `update-docs` | Update plugin command documentation |

### `xbrowser order` - Order Management
| Subcommand | Description |
|------------|-------------|
| `list` | List your orders |
| `get` | Get order details |
| `process` | Process a pending order |
| `cancel` | Cancel an order |
| `complete` | Mark an order as complete |

### `xbrowser ticket` - Support Tickets
| Subcommand | Description |
|------------|-------------|
| `list` | List support tickets |
| `get` | Get ticket details |
| `reply` | Reply to a ticket |
| `close` | Close a ticket |
| `assign` | Assign a ticket (admin) |

### `xbrowser dispute` - Dispute Management
| Subcommand | Description |
|------------|-------------|
| `list` | List disputes |
| `get` | Get dispute details |
| `investigate` | Investigate a dispute (admin) |
| `resolve` | Resolve a dispute (admin) |
| `reject` | Reject a dispute (admin) |

### `xbrowser notification` - Notifications
| Subcommand | Description |
|------------|-------------|
| `list` | List notifications |
| `create` | Create a notification |
| `unread-count` | Get unread notification count |
| `mark-read` | Mark notifications as read |
| `delete` | Delete notifications |

### `xbrowser config` - CLI Configuration
| Subcommand | Description |
|------------|-------------|
| `get` | Get a config value |
| `set` | Set a config value |
| `url` | Set the marketplace API URL |
| `status` | Show current config |
| `reset` | Reset config to defaults |
| `path` | Show config file path |

### `xbrowser spec` - Plugin Schema Tools
| Subcommand | Description |
|------------|-------------|
| `show` | Show full plugin spec, field details, or JSON schema |
| `init` | Generate a template package.json for a new plugin |
| `validate` | Validate a plugin package.json |
| `fields` | List all available plugin fields |

## API Reference

All API endpoints are served from `https://xbrowser.dev`. Responses follow the format:
```json
{ "success": true, "data": { ... } }
```
or on error:
```json
{ "success": false, "error": "message", "status": 400 }
```

### Authentication
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/auth/register` | Register a new user account |
| POST | `/api/auth/login` | Log in with email and password |
| GET | `/api/auth/verify` | Verify authentication token |
| POST | `/api/auth/change-password` | Change account password |
| GET | `/api/auth/google` | Google OAuth login |

### Plugins
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/plugins` | List all approved plugins (supports `search`, `category`, `tag`, `site`, `sort`, `page`, `limit` params) |
| GET | `/api/plugins/search` | Search plugins by keyword |
| GET | `/api/plugins/:slug` | Get plugin details |
| POST | `/api/plugins` | Create a new plugin (authenticated) |
| PUT | `/api/plugins/:slug` | Update plugin details |
| DELETE | `/api/plugins/:slug` | Delete a plugin |
| POST | `/api/plugins/publish` | Submit plugin for publishing |
| POST | `/api/plugins/:slug/install` | Increment install counter |
| GET | `/api/plugins/:slug/reviews` | List plugin reviews |
| POST | `/api/plugins/:slug/reviews` | Submit a review |
| GET | `/api/plugins/:slug/versions` | List plugin versions |
| POST | `/api/plugins/:slug/versions` | Add a new plugin version |
| GET | `/api/plugins/:slug/tarball` | Download plugin package |

### Categories
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/categories` | List all categories |
| GET | `/api/categories/:slug/plugins` | List plugins in a category |

### Notifications (SSE)
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/notifications/stream` | SSE stream for real-time notifications |
| GET | `/api/notifications` | List notifications |
| GET | `/api/notifications/unread-count` | Get unread notification count |
| PATCH | `/api/notifications/:id/read` | Mark notification as read |
| DELETE | `/api/notifications/:id` | Delete a notification |

### Orders
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/orders` | List user orders |
| GET | `/api/orders/:id` | Get order details |
| POST | `/api/orders` | Create an order |

### Payments
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/payments/checkout` | Create Stripe checkout session |
| GET | `/api/payments/my-orders` | List payment orders |
| POST | `/api/payments/portal` | Create Stripe customer portal session |
| POST | `/api/payments/webhook` | Stripe webhook handler |

### Sandbox (Plugin Execution)
| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/sandbox/execute` | Execute a plugin command in sandbox |
| POST | `/api/sandbox/stop` | Stop a sandbox session |
| POST | `/api/sandbox/stream` | Stream sandbox output |

### Stats & Health
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/stats` | Get marketplace statistics |
| GET | `/health` | Health check (with database status) |

### Admin API (requires `super_admin` role)
| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/admin/stats/dashboard` | Dashboard statistics |
| GET | `/api/admin/plugins` | List all plugins (including pending) |
| PUT | `/api/admin/plugins/:slug/approve` | Approve a plugin |
| PUT | `/api/admin/plugins/:slug/reject` | Reject a plugin |
| PUT | `/api/admin/plugins/:slug/feature` | Toggle featured status |
| DELETE | `/api/admin/plugins/:slug` | Delete any plugin |
| POST | `/api/admin/plugins/bulk-approve` | Bulk approve plugins |
| POST | `/api/admin/plugins/bulk-reject` | Bulk reject plugins |
| GET | `/api/admin/categories` | List categories (admin) |
| POST | `/api/admin/categories` | Create a category |
| PUT | `/api/admin/categories/:id` | Update a category |
| DELETE | `/api/admin/categories/:id` | Delete a category |
| GET | `/api/admin/orders` | List all orders |
| PUT | `/api/admin/orders/:id/process` | Process an order |
| PUT | `/api/admin/orders/:id/cancel` | Cancel an order |
| PUT | `/api/admin/orders/:id/complete` | Complete an order |
| GET | `/api/admin/tickets` | List support tickets |
| POST | `/api/admin/tickets/:id/reply` | Reply to a ticket |
| PUT | `/api/admin/tickets/:id/close` | Close a ticket |
| PUT | `/api/admin/tickets/:id/assign` | Assign a ticket |
| GET | `/api/admin/disputes` | List disputes |
| GET | `/api/admin/settings` | Get system settings |
| PUT | `/api/admin/settings/:key` | Update a setting |

### File Serving
| Method | Path | Description |
|--------|------|-------------|
| GET | `/files/*` | Serve uploaded files (plugin icons, avatars, etc.) |

## Plugin Development

Plugins are published as npm-compatible packages with an `xbrowser` field in `package.json`:

```json
{
  "name": "@myscope/my-plugin",
  "version": "1.0.0",
  "description": "My xbrowser plugin",
  "xbrowser": {
    "commands": [
      {
        "name": "hello",
        "description": "Say hello",
        "parameters": [
          {
            "name": "name",
            "type": "string",
            "description": "Name to greet",
            "required": true
          }
        ]
      }
    ]
  }
}
```

To publish a plugin:
```bash
xbrowser publish create --package ./path/to/package.json
```

Or publish via the web UI at `https://xbrowser.dev/publish`.

## Authentication

### Via the Web
Register at `https://xbrowser.dev/register` or log in via Google OAuth.

### Via the CLI
```bash
xbrowser auth login
```

### Via API
1. Register or log in to get a JWT token
2. Include it in requests: `Authorization: Bearer <token>`

```bash
# Login
curl -X POST https://xbrowser.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "your-password"}'

# Use token
curl https://xbrowser.dev/api/plugins \
  -H "Authorization: Bearer <token>"
```

## Links

- **Website**: https://xbrowser.dev
- **GitHub**: https://github.com/dyyz1993/xbrowser
- **CLI Docs**: https://xbrowser.dev/cli
- **Marketplace**: https://xbrowser.dev/marketplace

---

*This document is automatically generated. Last updated: 2026-07-10*