# 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

## Signup (create app, 7-day free trial)

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

{"slug": "my-app", "name": "My App", "email": "optional@example.com", "category": "messaging", "platform": "claude"}

→ Returns your app + activation details. Activate with the 7-day free trial
  (card required, cancel anytime before day 7 and you pay nothing).
→ Plans: Starter $29/mo, Pro $99/mo, Scale $299/mo, Enterprise custom — all paid
  tiers start with the 7-day free trial.

## CLI Commands

oddsockets signup <app> [--email x] [--local]   Sign up, start 7-day free trial
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)

On a package registry:

npm install oddsockets-nodejs              # Node.js
npm install oddsockets-js                  # Browser
npm install oddsockets-react-native        # React Native
npm install oddsockets-svelte              # Svelte
pip install oddsockets                     # Python
go get github.com/jyswee/oddsockets-go-sdk # Go

Not on a language registry yet — clone or vendor from GitHub
(github.com/jyswee/oddsockets-LANG-sdk): rust, java, kotlin, csharp, swift,
flutter, php, ruby, elixir, c, cpp, unity, unrealengine.

## SDK Usage Pattern

const OddSockets = require('oddsockets-nodejs');
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);

## Plans

There is no free tier. Every plan starts with a 7-day free trial.

- Starter $29/mo — 5M messages/mo, 200 peak connections, 3,000 req/min, $2.50 per extra million
- Pro $99/mo — 25M messages/mo, 1,000 peak connections, 12,000 req/min, $1.60 per extra million
- Scale $299/mo — 100M messages/mo, 5,000 peak connections, 60,000 req/min, $1.00 per extra million
- Enterprise — contact sales; unlimited, dedicated infrastructure, 99.999% SLA

Monthly active users are unlimited on every plan.
Live catalogue: GET https://oddsockets.com/saas/api/v1/sdk/billing/subscription-plans/api-key

Agents signing up via /api/agent-signup get a key that works immediately under
preActivation caps (10,000 messages, 25 channels, 25 connections). Add a card
within 48 hours to start the 7-day trial — otherwise the key locks (data kept).

## How it works

Give an SDK an API key and call channel methods. The SDK resolves a cluster
endpoint for you, holds a persistent connection, and reconnects and
resubscribes automatically if that endpoint goes away. Subscribers on any
endpoint receive every message published to a channel. Do not hardcode an
endpoint — let the SDK resolve one.

## Links

Docs: https://docs.oddsockets.com
Dashboard: https://oddsockets.com/developer-dashboard
API base: https://oddsockets.com

## Support

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