Vibes SDK

## Vibes SDK Reference

You are building an HTML widget for It Just Vibes (itjustvibes.com). The Vibes SDK is auto-injected — do NOT add a script tag. Just use `window.vibes` (or just `vibes`).

### Setup

Wrap your startup code in `vibes.onReady`:

```js
vibes.onReady(async () => {
  const saved = await vibes.load("myKey");
  // your widget logic here
});
```

### State (Per-User Persistence)

Every user gets their own isolated state per widget. All methods return Promises.

| Method | Description |
|--------|-------------|
| `await vibes.save(key, value)` | Save JSON-serializable data |
| `await vibes.load(key)` | Load saved data (returns `null` if not found) |
| `await vibes.delete(key)` | Delete a saved key |
| `await vibes.listKeys()` | Get array of all saved key names |

**Key rules:**
- Keys are strings, max 64 characters, alphanumeric + dashes/underscores
- Values must be JSON-serializable (objects, arrays, strings, numbers, booleans)
- Max 100KB per value, 500KB per widget per user, 5MB per user total
- Max 100 keys per widget per user

### Fetch Proxy

Use direct `fetch()` for APIs with permissive CORS headers (`Access-Control-Allow-Origin: *`). Use `vibes.fetch` for APIs without CORS headers (the proxy handles cross-origin requests):

```js
const resp = await vibes.fetch("https://api.example.com/data", {
  method: "GET",         // GET, POST, PUT, DELETE
  headers: {},           // optional headers
  body: null,            // optional body (string)
  timeout: null          // optional timeout in ms
});
const data = await resp.json(); // or resp.text()
console.log(resp.status, resp.ok);
```

### Multiplayer (Shared State)

Real-time shared state across all users viewing the same widget.

```js
// Join a room (call once at startup)
await vibes.shared.join("lobby", { persistent: true });

// Set shared state (broadcasts to all users)
await vibes.shared.set("score", { player1: 10, player2: 7 });

// Read shared state (synchronous, returns last known value)
const score = vibes.shared.get("score");

// Listen for changes to a specific key
vibes.shared.onChange("score", (newValue) => {
  console.log("Score updated:", newValue);
});

// Listen for any shared state change
vibes.shared.onAny((key, value) => {
  console.log(key, "changed to", value);
});

// Get number of connected users
const count = await vibes.shared.getUserCount();

// Leave room
vibes.shared.leave();

// Clear all shared state for this room
await vibes.shared.clear();
```

**Shared state options:**
- `{ persistent: true }` — state survives page reloads (stored server-side)
- Default room name is "__default__" if omitted

### Agent-Accessible State (vibes.ai.*)

State written with the standard `vibes.save` / `vibes.load` methods is private to each user and is **NOT readable by AI agents**. To share state with an AI agent (via the MCP connector), use the `vibes.ai` sub-namespace:

| Method | Description |
|--------|-------------|
| `await vibes.ai.setState(key, value)` | Write agent-readable state. Key is stored internally as `ai/<key>`. |
| `await vibes.ai.getState(key)` | Read agent-readable state. Returns `null` if key absent. |
| `await vibes.ai.listKeys()` | List all agent-readable keys (without the `ai/` prefix). |

**Important rules:**
- Regular `vibes.save()` / `vibes.setState()` is **NOT agent-accessible** — use `vibes.ai.*` for state you want agents to read.
- The widget **owner** must enable agent access in **Manage → Agent tab** before any agent can read or write `vibes.ai.*` state.
- Keys are auto-prefixed to `ai/` internally; you supply just the short key (e.g. `'context'`).

```js
vibes.onReady(async () => {
  // Write state an AI agent can later read
  await vibes.ai.setState('context', { currentLevel: 3, score: 1500 });

  // Read it back (same auto-prefix applies)
  const ctx = await vibes.ai.getState('context');

  // List all agent-accessible keys for this widget
  const keys = await vibes.ai.listKeys(); // e.g. ['context']
});
```

### Rules

1. **Do NOT use localStorage, sessionStorage, or window.storage** — they are blocked or undefined in the sandbox. Use `vibes.save`/`vibes.load` instead.
2. **Do NOT add a script tag to import the SDK** — it is auto-injected.
3. **Wrap startup code in `vibes.onReady()`** — the SDK may not be ready immediately.
4. **Await all SDK calls** — every method (except `vibes.shared.get`) returns a Promise.
5. **Do NOT import external JS libraries via script tags** — they will be blocked. Include library code inline or use a CDN link in a `<link>` tag for CSS only.
6. **Keep total code under 80KB** — that is the default widget size limit (your account limit may be higher).

### Rate Limits

| Operation | Limit |
|-----------|-------|
| Writes (save + delete combined) | 30/min |
| Reads (load) | 60/min |
| List keys | 30/min |
| Fetch proxy | Rate limited per widget |

### Error Handling

All SDK methods can reject. Wrap in try/catch:

```js
try {
  await vibes.save("key", value);
} catch (err) {
  console.error("Save failed:", err.message);
}
```

Fetch proxy errors include `err.code`: `"RATE_LIMITED"`, `"BLOCKED"`, `"FETCH_ERROR"`.

### Data Export

Export rows of data as CSV or Excel directly from your widget.

```js
// Register dataset for the platform's "Export data" button
// AND optionally trigger an immediate download
vibes.exportData(rows, { filename: 'results.csv' })

// rows: Array of arrays (each inner array is one row; first row = headers)
// options.filename: sets the download filename and format (csv or xlsx)
// options.directDownload: false to only register without downloading (default: true)
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `filename` | string | `'data.csv'` | Download filename; extension determines format (`.csv` or `.xlsx`) |
| `directDownload` | boolean | `true` | Trigger immediate browser download in addition to registering the dataset |

**Notes:**
- First call registers the dataset so the widget chrome shows an "Export data" button
- Use `.csv` extension for CSV, `.xlsx` for Excel
- CSV injection safety is automatic (formula-starting cells prefixed with `'`)
- Data stays in the browser — no server round-trip