altohost-js

Official AltoHost client SDK for real-time WebSocket communication. Zero dependencies.

Install

npm install @girardmedia/altohost-js

Quick Start

import AltoHost from '@girardmedia/altohost-js'

const client = new AltoHost('YOUR_APP_KEY', {
  wsHost: 'ws.altohost.com',
  forceTLS: true,
})

// Subscribe to a channel
const channel = client.subscribe('chat-room')

// Listen for events
channel.on('new-message', (data) => {
  console.log('Message received:', data)
})

// Unsubscribe
channel.off('new-message')
client.unsubscribe('chat-room')

Private Channels

Private channels require server-side authentication. The SDK automatically sends auth requests to your authEndpoint.

const client = new AltoHost('YOUR_APP_KEY', {
  wsHost: 'ws.altohost.com',
  authEndpoint: '/api/altohost/auth',
  forceTLS: true,
})

const privateChannel = client.subscribe('private-user-123')
privateChannel.on('notification', (data) => {
  console.log('Private notification:', data)
})

Presence Channels

Track who is online in real time.

const presence = client.subscribe('presence-room')

presence.on('subscription_succeeded', () => {
  console.log('Members online:', presence.members.count)
  presence.members.each((member) => {
    console.log(member.id, member.info)
  })
})

presence.on('member_added', (member) => {
  console.log('Joined:', member.id)
})

presence.on('member_removed', (member) => {
  console.log('Left:', member.id)
})

Client Events

Send events directly from the client on private/presence channels.

const channel = client.subscribe('private-chat')
channel.trigger('client-typing', { user: 'alice' })

Configuration

const client = new AltoHost('APP_KEY', {
  wsHost: 'ws.altohost.com',   // Required: WebSocket host
  wsPort: 80,                   // WebSocket port (default: 80)
  wssPort: 443,                 // Secure WebSocket port (default: 443)
  forceTLS: true,               // Use wss:// (default: true)
  authEndpoint: '/api/altohost/auth', // Auth endpoint for private/presence channels
  authHeaders: {},              // Custom headers for auth requests
})

API Reference

AltoHost (default export)

| Method | Description | |--------|-------------| | subscribe(channel) | Subscribe to a channel. Returns Channel, PrivateChannel, or PresenceChannel. | | unsubscribe(channel) | Unsubscribe from a channel. | | channel(name) | Get an existing channel by name. | | disconnect() | Close the WebSocket connection. | | bind(event, callback) / on(event, callback) | Listen for global events. | | socketId | Current socket ID (read-only). | | state | Connection state (read-only). |

Channel

| Method | Description | |--------|-------------| | bind(event, callback) / on(event, callback) | Listen for an event. | | unbind(event, callback?) / off(event, callback?) | Remove listener(s). | | name | Channel name (read-only). | | subscribed | Whether the channel is subscribed (read-only). |

PresenceChannel (extends PrivateChannel)

| Property | Description | |----------|-------------| | members.count | Number of members online. | | members.each(callback) | Iterate over all members. | | members.get(id) | Get a member by ID. | | members.me | The current user's member object. |

License

MIT