altohost-node

Official AltoHost server SDK for Node.js. Trigger events, authenticate channels, and query presence. Zero external dependencies (uses Node.js crypto).

Install

npm install @girardmedia/altohost-node

Quick Start

import AltoHost from '@girardmedia/altohost-node'

const altohost = new AltoHost({
  appId: process.env.ALTOHOST_APP_ID,
  key: process.env.ALTOHOST_KEY,
  secret: process.env.ALTOHOST_SECRET,
  host: process.env.ALTOHOST_HOST,  // e.g. 'ws.altohost.com'
  port: process.env.ALTOHOST_PORT,  // e.g. '6001'
  useTLS: false,
})

// Trigger an event
await altohost.trigger('chat-room', 'new-message', {
  user: 'alice',
  text: 'Hello, world!',
})

Trigger Events

// Single channel
await altohost.trigger('chat-room', 'new-message', { text: 'Hello' })

// Multiple channels
await altohost.trigger(['room-1', 'room-2'], 'announcement', { text: 'Server restart in 5 min' })

// Exclude the sender
await altohost.trigger('chat-room', 'new-message', { text: 'Hello' }, {
  socketId: '12345.67890', // sender's socket ID
})

Batch Trigger

Send multiple events in a single request.

await altohost.triggerBatch([
  { channel: 'user-1', event: 'notification', data: { type: 'follow' } },
  { channel: 'user-2', event: 'notification', data: { type: 'mention' } },
])

Channel Authentication

Authenticate private and presence channel subscriptions from your server.

// Express / Next.js API route
app.post('/api/altohost/auth', (req, res) => {
  const { socket_id, channel_name } = req.body

  // Private channel
  const auth = altohost.authenticateChannel(socket_id, channel_name)
  res.json(auth)
})

// Presence channel (include user data)
app.post('/api/altohost/auth', (req, res) => {
  const { socket_id, channel_name } = req.body

  const auth = altohost.authenticateChannel(socket_id, channel_name, {
    user_id: req.user.id,
    user_info: { name: req.user.name, avatar: req.user.avatar },
  })
  res.json(auth)
})

Channel Info

Query channel state from the server.

const info = await altohost.getChannelInfo('presence-room')
// { occupied: true, user_count: 5, subscription_count: 5 }

const members = await altohost.getPresenceMembers('presence-room')
// { users: [{ id: '1' }, { id: '2' }] }

Configuration

const altohost = new AltoHost({
  appId: 'your-app-id',    // Required
  key: 'your-app-key',     // Required
  secret: 'your-app-secret', // Required
  host: '127.0.0.1',       // Engine host (default: '127.0.0.1')
  port: 6001,              // Engine port (default: 6001)
  useTLS: false,            // Use HTTPS (default: false)
})

API Reference

| Method | Description | |--------|-------------| | trigger(channel, event, data, options?) | Trigger an event on one or more channels. | | triggerBatch(events) | Trigger multiple events in a single request. | | authenticateChannel(socketId, channel, userData?) | Authenticate a private or presence channel subscription. | | getChannelInfo(channel) | Get info about a channel (occupied, user count). | | getPresenceMembers(channel) | Get the list of users in a presence channel. |

License

MIT