# SocketFlare

Pusher-protocol-compatible realtime messaging. You publish events over HTTP;
subscribed WebSocket clients receive them. Drop-in replacement for Pusher —
change the host in your existing pusher-js / pusher-server code and you're done.
Every official Pusher SDK in every language works.

## Hosts

- Publish API (server → SocketFlare): https://api.socketflare.com
- WebSocket (client ↔ SocketFlare):   wss://ws.socketflare.com
- Dashboard / account management:      https://socketflare.com

## Credentials

Every app has three values:

- APP_ID       — opaque identifier, used in the publish URL path
- APP_KEY      — public, used by WebSocket clients and HMAC signing
- APP_SECRET   — private, used by the server to HMAC-sign publishes

Create apps via the dashboard OR programmatically via the /v1 API below.

## Management API (/v1)

Base URL: https://api.socketflare.com/v1

Auth: `Authorization: Bearer sf_acct_<hex>`. Create an account API key in
the dashboard at https://socketflare.com/dashboard?tab=settings (Security
section). The same key can be used by CLIs, CI pipelines, and AI coding
agents — no dashboard interaction required after the initial key issuance.

### Create an app
```bash
curl -X POST https://api.socketflare.com/v1/apps \
  -H "Authorization: Bearer sf_acct_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "my-realtime-app"}'
```
Response:
```json
{
  "id": "uuid",
  "name": "my-realtime-app",
  "app_key": "sf_...",
  "app_secret": "...",
  "publish_url": "https://api.socketflare.com/apps/<id>/events",
  "websocket_url": "wss://ws.socketflare.com/app/sf_..."
}
```

### Other endpoints
- `GET    /v1/apps`                       — list all apps on the account
- `GET    /v1/apps/:id`                   — get one app
- `DELETE /v1/apps/:id`                   — delete
- `POST   /v1/apps/:id/rotate_secret`      — rotate the secret
- `GET    /v1/apps/:id/usage`              — current-period usage + limits
- `GET    /v1/account`                    — plan + limits for the account

## Server-side publish (Node.js)

```js
import Pusher from "pusher";
const sf = new Pusher({
  appId:  process.env.APP_ID,
  key:    process.env.APP_KEY,
  secret: process.env.APP_SECRET,
  host:   "api.socketflare.com",
  port:   443,
  useTLS: true,
});
await sf.trigger("orders", "order-updated", { id: 42 });
```

## Client-side subscribe (Browser / React Native)

```js
import Pusher from "pusher-js";
const sf = new Pusher(APP_KEY, {
  wsHost: "ws.socketflare.com",
  wsPort: 443, wssPort: 443, forceTLS: true,
  enabledTransports: ["ws", "wss"],
  cluster: "edge",
});
sf.subscribe("orders").bind("order-updated", (data) => console.log(data));
```

## Laravel

`.env`:
```
BROADCAST_DRIVER=pusher
PUSHER_APP_ID=your-app-id
PUSHER_APP_KEY=your-app-key
PUSHER_APP_SECRET=your-app-secret
PUSHER_APP_CLUSTER=edge
PUSHER_HOST=api.socketflare.com
PUSHER_PORT=443
PUSHER_SCHEME=https
```

Everything else in `config/broadcasting.php` stays at Laravel defaults.
Laravel Echo on the frontend:
```js
window.Echo = new Echo({
  broadcaster: "pusher",
  key: import.meta.env.VITE_PUSHER_APP_KEY,
  cluster: "edge",
  wsHost: "ws.socketflare.com",
  wsPort: 443, wssPort: 443, forceTLS: true,
  enabledTransports: ["ws", "wss"],
});
```

## Python / Django / Flask

```python
import pusher
sf = pusher.Pusher(
  app_id=APP_ID, key=APP_KEY, secret=APP_SECRET,
  cluster="edge", host="api.socketflare.com", port=443, ssl=True,
)
sf.trigger("orders", "order-updated", {"id": 42})
```

## Ruby / Rails, Go, Java, .NET, Elixir

All official Pusher server libraries work. Set `host = "api.socketflare.com"`
and `port = 443` (or equivalent) in the library's config. See
https://socketflare.com/docs for language-specific snippets.

## HTTP publish (no SDK)

If you don't want an SDK, sign the request manually with HMAC-SHA256:

```js
const body = JSON.stringify({
  name: "order-updated",
  channels: ["orders"],
  data: JSON.stringify({ id: 42 }),
});
const ts  = Math.floor(Date.now() / 1000);
const md5 = crypto.createHash("md5").update(body).digest("hex");
const params = new URLSearchParams({
  auth_key: APP_KEY, auth_timestamp: ts, auth_version: "1.0", body_md5: md5,
});
const path   = `/apps/${APP_ID}/events`;
const sorted = [...params].sort(([a],[b]) => a.localeCompare(b))
  .map(([k,v]) => k+"="+v).join("&");
const toSign = `POST\n${path}\n${sorted}`;
params.set("auth_signature",
  crypto.createHmac("sha256", APP_SECRET).update(toSign).digest("hex"));
await fetch(`https://api.socketflare.com${path}?${params}`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body,
});
```

## Pricing tiers (per-month)

| Tier     | Price  | API calls | Msg/sec | Concurrent | Total conns | Apps  |
|----------|--------|-----------|---------|------------|-------------|-------|
| Free     | $0     | 1K        | 5       | 10         | 2K          | 3     |
| Starter  | $19    | 2M        | 100     | 20K        | 4M          | 100   |
| Growth   | $59    | 10M       | 500     | 50K        | 10M         | 250   |
| Pro      | $129   | 40M       | 2,000   | 100K       | 30M         | 500   |
| Business | $299   | 100M      | 5,000   | 200K       | 80M         | 1,000 |
| Scale    | $699   | 200M      | 10,000  | 500K       | 200M        | 5,000 |

All tiers: unlimited channels, unlimited message delivery, free idle
connections, HMAC + JWT auth, global edge network (300+ PoPs), Pusher
SDK compatible.

## Common errors

- 401  HMAC signature missing / expired / invalid
- 401  Bearer token invalid (on /v1 routes)
- 402  Plan app-count limit reached
- 404  App not found (or not owned by the calling account)
- 429  Per-second rate limit OR monthly quota exceeded
- 429  /v1 management API rate limit (60 req / 10s per IP/token)

## AI agents — CLI + MCP

SocketFlare ships first-class tools for agent communication:

### CLI (`@socketflare/cli`)
```bash
npm i -g @socketflare/cli
socketflare login
socketflare apps create my-bot

# Two CLIs talking (terminal chat over a private channel):
socketflare pipe room-42        # in terminal A
socketflare pipe room-42        # in terminal B

# Run any program as a network-callable agent:
socketflare agent serve bob --exec "claude --print"

# Ask that agent (request/response over a SocketFlare channel):
socketflare agent ask bob "summarize this..."
```

### MCP server (`@socketflare/mcp`)
For Claude Desktop / Cursor / Continue. Add to your MCP config:
```json
{
  "mcpServers": {
    "socketflare": {
      "command": "npx",
      "args": ["-y", "@socketflare/mcp"],
      "env": {
        "SOCKETFLARE_TOKEN": "sf_acct_...",
        "SOCKETFLARE_APP_ID": "...",
        "SOCKETFLARE_APP_KEY": "sf_...",
        "SOCKETFLARE_APP_SECRET": "..."
      }
    }
  }
}
```
Tools: `sf_publish`, `sf_subscribe`, `sf_ask_agent`, `sf_list_apps`,
`sf_create_app`, `sf_app_usage`.

### Agent protocol (works with any Pusher SDK)
Convention layered on private channels — no server-side support needed.
- Agent listens on  `private-agent.<name>`
- Caller listens on `private-reply.<random>`
- Request: event `agent.request`, data `{id, msg, reply_to, from, ts}`
- Reply:   event `agent.reply`,   data `{id, msg, ts}` on the reply_to channel

## Further reading

Full docs:   https://socketflare.com/docs
AI/agents:   https://socketflare.com/docs#ai-overview
Status:      https://socketflare.com/status