# OddSockets — Real-Time WebSocket Channels for AI Agents
# https://oddsockets.com | CLI: npm install -g oddsockets
# Version: 1.0.0

## Quick Start (30 seconds)

npm install -g oddsockets
oddsockets signup my-app --local
oddsockets publish my-channel "Hello!"
oddsockets subscribe my-channel

## Instant Signup (one call, instant key)

POST /api/agent-signup/instant
Content-Type: application/json

{"slug": "my-app", "email": "optional@example.com", "platform": "claude"}

→ Returns: apiKey, userId, token, paymentUrl, quickstart code
→ Key works immediately on free tier (100 MAU, 50 conn, 10K msg/day, 10 channels)

## CLI Commands

oddsockets signup <app> [--email x] [--local]   Sign up, get instant API key
oddsockets login --key KEY [--local]             Save existing API key
oddsockets logout [--local]                      Clear config
oddsockets me                                    Account info + plan
oddsockets status                                Cluster health + platform stats

oddsockets publish <channel> "message"           Publish to channel
oddsockets publish <channel> --file data.json    Publish from file
oddsockets subscribe <channel>                   Live tail (Ctrl+C to stop)
oddsockets history <channel> [--limit 10]        Message history
oddsockets presence <channel>                    Who's in the channel

oddsockets channels                              List channels
oddsockets channel create <name>                 Create channel
oddsockets channel delete <name>                 Delete channel

oddsockets keys                                  List API keys
oddsockets key create "name"                     Create new key
oddsockets key revoke <id>                       Revoke key

Every command supports --json for machine-readable output.

## Config Priority

1. --key flag
2. ODDSOCKETS_API_KEY env var
3. .oddsockets/config.json (project-local)
4. ~/.oddsockets/config.json (global)

## REST API (raw HTTP fallback)

All endpoints require: Authorization: Bearer YOUR_API_KEY

### Channels & Messaging
POST   /api/channels/publish        {"channel":"x","data":{"text":"hello"}}
GET    /api/channels/:name/history  ?limit=10
GET    /api/channels/:name/presence
POST   /api/channels                {"name":"my-channel"}
GET    /api/channels
DELETE /api/channels/:name

### API Keys
GET    /saas/api/v1/sdk/apikeys/list
POST   /saas/api/v1/sdk/apikeys/management/create    {"name":"x","permissions":["publish","subscribe"]}
DELETE /saas/api/v1/sdk/apikeys/management/delete     ?apiKeyId=x

### Account
GET    /saas/api/v1/sdk/auth/user-profile
GET    /saas/api/v1/sdk/apikeys/usage-stats
GET    /health
GET    /api/public/stats

## SDKs (19 languages)

npm install @oddsocketsai/nodejs-sdk       # Node.js
npm install @oddsocketsai/javascript-sdk   # Browser
pip install oddsocketsai-python-sdk        # Python
go get github.com/jyswee/oddsockets-go-sdk # Go
cargo add oddsockets                       # Rust (0.1.0-beta.1)
+ Java, Kotlin, C#, Swift, Flutter, PHP, React Native, Ruby, Elixir, Svelte, C, C++, Unity, Unreal

## SDK Usage Pattern

const OddSockets = require('@oddsocketsai/nodejs-sdk');
const client = new OddSockets({ apiKey: 'YOUR_KEY' });

const ch = client.channel('my-channel');
await ch.subscribe(msg => console.log(msg));
await ch.publish({ text: 'Hello!' });
await ch.presence();
await ch.history(10);

## Free Tier Limits

- 100 MAU (monthly active users)
- 50 concurrent connections
- 500 connections/day
- 10,000 messages/day
- 100 messages/minute
- 10 channels max
- 100MB storage
- 24h message history retention

## Architecture

Client → Manager (manager1.oddsockets.tyga.network) → Worker assignment → WebSocket channel
Manager handles discovery + load balancing. Workers handle pub/sub + presence + history.
19 SDKs wrap this transparently — just provide API key and call channel methods.

## Infrastructure

Manager: https://manager1.oddsockets.tyga.network
Worker 1: wss://worker1-1.oddsockets.tyga.network
Worker 2: wss://worker1-2.oddsockets.tyga.network
Docs: https://docs.oddsockets.com
Dashboard: https://oddsockets.com/developer-dashboard

## Support

GitHub: https://github.com/jyswee
Email: support@oddsockets.com