npm package: @girardmedia/altohost-js
Description: AltoHost real-time WebSocket client — channels, presence, and client events
Author: AltoHost
Latest version: 1.1.0

# altohost-js

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

## Install

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

## Quick Start

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

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

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

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

## Configuration

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