Quickstart

npm install @zokai/client
# or
yarn add @zokai/client
# or
pnpm add @zokai/client

npm install @zokai/server

pip install zokai

go get github.com/zokai/zokai-go

Browser                   Your Server                 Zokai
  │                            │                          │
  │── subscribe('private-x') ──▶                          │
  │                            │                          │
  │◀── GET /auth/zokai ────────│ (your auth endpoint)     │
  │                            │── sign token ────────▶   │
  │                            │◀─ token ──────────────   │
  │                            │                          │
  │── zok:auth(token) ─────────────────────────────────▶  │
  │◀── zok:auth_success ───────────────────────────────   │
  │◀── zok:subscribed ─────────────────────────────────   │

{
  "event":   "new-order",
  "channel": "orders",
  "data": {
    "id":     "ORD-1042",
    "total":  89.00,
    "status": "confirmed"
  }
}

const ch = client.subscribe('presence-chat');

// Fires when the subscription succeeds — contains the current member list
ch.on('zokai:subscription_succeeded', ({ members }) => {
  console.log('Online now:', members);
});

// Member joined
ch.on('zokai:member_added', ({ id, info }) => {
  console.log(info.name, 'joined');
});

// Member left
ch.on('zokai:member_removed', ({ id }) => {
  console.log(id, 'left');
});

npm install @zokai/client

import Zokai from '@zokai/client';

const client = new Zokai({
  appKey:     'YOUR_APP_KEY',        // required
  authEndpoint: '/api/zokai/auth',  // required for private/presence channels
  cluster:    'us-east-1',          // optional, default: nearest
});

// Connection lifecycle events
client.on('connected',    () => console.log('Connected'));
client.on('disconnected', () => console.log('Disconnected — reconnecting…'));
client.on('error',        (err) => console.error('Error', err));

// Public channel — no auth required
const feed = client.subscribe('live-feed');

// Private channel — token fetched from your authEndpoint
const inbox = client.subscribe('private-user.1234.inbox');

// Unsubscribe when done
client.unsubscribe('live-feed');

const ch = client.subscribe('orders');

// Bind a specific event
ch.on('order-created', (data) => {
  console.log('New order:', data.id);
});

// Bind all events on the channel
ch.onAll((eventName, data) => {
  console.log(eventName, data);
});

// Remove a listener
const handler = (data) => { /* ... */ };
ch.on('order-created', handler);
ch.off('order-created', handler);

const room = client.subscribe('presence-chat.room.42');

// Once subscribed, you get the full member list
room.on('zokai:subscription_succeeded', ({ count, members }) => {
  renderUserList(members);
});

// Live updates
room.on('zokai:member_added',   ({ id, info }) => addUser(id, info));
room.on('zokai:member_removed', ({ id })       => removeUser(id));

// Access current members at any time
console.log(room.members);

// Express route — POST /api/zokai/auth
app.post('/api/zokai/auth', requireLogin, (req, res) => {
  const { channel, socket_id } = req.body;

  // Authorize: only allow users to access their own inbox
  if (channel !== `private-user.${req.user.id}.inbox`) {
    return res.status(403).json({ error: 'Forbidden' });
  }

  const token = zokai.auth({ channel, socket_id, userId: req.user.id });
  res.json({ token });
});

import Zokai from '@zokai/server';

const zokai = new Zokai({
  appKey:    process.env.ZOKAI_KEY,
  appSecret: process.env.ZOKAI_SECRET,
});

// Single channel
await zokai.publish('orders', 'order-created', {
  id: 'ORD-1042', total: 89.00,
});

// Multiple channels at once
await zokai.publish(['orders', 'analytics'], 'order-created', { id: 'ORD-1042' });

// Use in your auth endpoint to sign channel tokens
const token = zokai.auth({
  channel:  'private-user.1234.inbox',
  socketId: req.body.socket_id,
  userId:   'user-1234',
  userInfo: { name: 'Jane Doe' },  // shown in presence member list
});

import zokai, os

client = zokai.Client(
    key=os.environ["ZOKAI_KEY"],
    secret=os.environ["ZOKAI_SECRET"],
)

# Publish an event
client.publish(
    channel="orders",
    event="order-created",
    data={"id": "ORD-1042", "total": 89.00},
)

# Generate an auth token (for Flask/Django auth endpoints)
token = client.auth(
    channel="private-user.1234.inbox",
    socket_id=request.form["socket_id"],
    user_id="user-1234",
)

import zokai "github.com/zokai/zokai-go"

client := zokai.New(zokai.Config{
    Key:    os.Getenv("ZOKAI_KEY"),
    Secret: os.Getenv("ZOKAI_SECRET"),
})

// Publish an event
err := client.Publish(ctx, zokai.Event{
    Channel: "orders",
    Name:    "order-created",
    Data:    map[string]any{"id": "ORD-1042", "total": 89.00},
})

// Generate a channel auth token
token, err := client.Auth(ctx, zokai.AuthParams{
    Channel:  "private-user.1234.inbox",
    SocketID: r.FormValue("socket_id"),
    UserID:   "user-1234",
})

curl https://api.zokai.io/v1/apps/YOUR_APP_KEY/events \
  -u YOUR_APP_KEY:YOUR_APP_SECRET \
  -H "Content-Type: application/json" \
  -d '{"channel":"orders","event":"order-created","data":{"id":"ORD-1042"}}'

{
  "channel": "orders",
  "event":   "order-created",
  "data": {
    "id":     "ORD-1042",
    "total":  89.00,
    "status": "confirmed"
  }
}

{ "ok": true, "delivered_to": 24 }

{
  "ok":    false,
  "error": "Channel name is required",
  "code":  400
}