# VEXOR AI Coding Agent Setup Guide

Welcome, Agent. You have been asked to connect this workspace to **VEXOR Video Infrastructure**.

Follow these instructions strictly:
1. **Preserve existing files, dependencies, and configurations.**
2. **Never expose or hardcode secrets.** Always store API keys in environment variables (e.g., `.env.local` or `.env`).
3. **Verify connectivity using read-only operations** before performing any mutations.

---

## 1. What is VEXOR?
VEXOR is an end-to-end video infrastructure platform providing:
- Fast, resumable video uploads (Tus 1.0 & direct storage upload).
- Adaptive HLS ladder packaging (240p to 1080p, AES-128 encryption).
- Cloud storage connections (AWS S3, Cloudflare R2, Google Cloud Storage, Azure Blob, Oracle Cloud).
- Multi-currency billing (ETB via Telebirr, USD via Polar).
- Remote Model Context Protocol (MCP) server for autonomous agents.

---

## 2. Option A: Setup via Model Context Protocol (MCP)

If you are running in Cursor, Claude Desktop, Windsurf, or an MCP-compatible environment, register the remote VEXOR MCP Server:

### MCP Configuration
Add the following block to your MCP configuration file (`.cursor/mcp.json`, `claude_desktop_config.json`, or environment settings):

```json
{
  "mcpServers": {
    "vexor": {
      "url": "https://vexor-video.vercel.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ${VEXOR_API_KEY}"
      }
    }
  }
}
```

### Available MCP Tools (Read-Only & Safe)
- `get_usage`: Check current wallet balance, currency (ETB/USD), and storage usage.
- `list_assets`: Inspect existing video assets, states (`uploading`, `uploaded`, `transcoding`, `ready`, `failed`), and durations.
- `get_asset`: Inspect safe metadata and adaptive HLS stream information for a specific video asset.
- `list_storage_connections`: View connected S3/R2/GCS/Azure buckets and health status.
- `test_storage_connection`: Non-destructively verify connectivity to a connected cloud storage bucket.
- `get_storage_setup_guide`: Retrieve provider-specific IAM policies and connection instructions.

---

## 3. Option B: Setup via Official SDKs

### TypeScript / Node.js
1. Install the SDK:
```bash
npm install @vexor-video/sdk
```

2. Add credentials to `.env.local` or `.env`:
```env
VEXOR_API_KEY=vx_live_your_api_key_here
```

3. Read-only verification snippet:
```typescript
import { Vexor } from '@vexor-video/sdk';

const vexor = new Vexor({
  apiKey: process.env.VEXOR_API_KEY,
});

async function verifyConnection() {
  const assets = await vexor.assets.list({ limit: 5 });
  console.log(`Connected to VEXOR! Found ${assets.length} assets.`);
}

verifyConnection().catch(console.error);
```

---

### Python
1. Install the package:
```bash
pip install vexor
```

2. Add credentials to `.env`:
```env
VEXOR_API_KEY=vx_live_your_api_key_here
```

3. Read-only verification snippet:
```python
import os
from vexor import Vexor

client = Vexor(api_key=os.environ.get("VEXOR_API_KEY"))

try:
    assets = client.assets.list(limit=5)
    print(f"Connected to VEXOR! Found {len(assets)} assets.")
except Exception as e:
    print(f"Verification failed: {e}")
```

---

## 4. Web Player Integration (React / Next.js / HTML)

To embed the high-performance adaptive HLS player in client apps:
```bash
npm install @vexor-video/player
```

```tsx
import { VexorPlayer } from '@vexor-video/player';
import '@vexor-video/player/dist/index.css';

export function VideoPlayer({ assetId }: { assetId: string }) {
  return (
    <VexorPlayer
      src={`https://vexor-api-ves7.onrender.com/v1/assets/${assetId}/hls/master.m3u8`}
      controls
      autoPlay={false}
    />
  );
}
```

---

## 5. Security & Verification Rules for Coding Agents
- **API Keys**: Inform the user to obtain an API key from the VEXOR Console at `https://vexor-video.vercel.app/settings/api-keys`.
- **Validation**: Test the API key using a read-only request (`list_assets` or `get_usage`). Never trigger billable transcoding jobs during onboarding.
- **Reporting**: Report back to the developer with the account currency, active assets, and available storage connections.
