npm package: @girardmedia/altohost-node
Description: AltoHost server SDK — trigger events, authenticate channels, and query presence
Author: AltoHost
Latest version: 1.4.0

# altohost-node

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

## Install

```bash
npm install @girardmedia/altohost-node
```

## Quick Start

```js
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

```js
// 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.

```js
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.

```js
// 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.

```js
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

```js
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