@stardust-sh/client

Stardust client SDK. Today it ships the realtime API — broadcast and presence over a single WebSocket connection. The realtime surface mirrors Supabase Realtime so existing UI patterns (channel.on('broadcast', ...), channel.track(...), presenceState()) port across with minimal change.

import { RealtimeClient } from '@stardust-sh/client'

const client = new RealtimeClient({
  url: 'ws://localhost:3333/socket',
  token: sessionTokenOrOrgToken,
})

const channel = client
  .channel(`room:${roomId}`)
  .on('broadcast', { event: 'message' }, ({ payload }) => {
    console.log('new message', payload)
  })
  .on('presence', { event: 'sync' }, () => {
    const state = channel.presenceState<{ username: string }>()
    const online = Object.values(state).flat()
    console.log('online users', online)
  })
  .subscribe(async (status) => {
    if (status === 'SUBSCRIBED') {
      await channel.track({ username: 'ada' })
    }
  })

// Send a broadcast.
await channel.send({ type: 'broadcast', event: 'message', payload: { text: 'hi' } })

// Leave the room.
await channel.unsubscribe()

Options

new RealtimeClient(options):

| Option | Type | Default | Description | | --------------------- | ------------------------------------------ | ------- | -------------------------------------------------------- | | url | string | — | WebSocket endpoint, e.g. ws://localhost:3333/socket. | | token | string \| () => string \| Promise<string> | — | Stardust session or organization access token. | | params | Record<string, string> | {} | Extra query params merged into the connect URL. | | heartbeatIntervalMs | number | 30_000| Phoenix heartbeat interval. |

client.channel(topic, config?):

| Path | Type | Default | Description | | ----------------------------- | --------- | ---------------- | -------------------------------------------------------------------- | | config.broadcast.self | boolean | false | Echo broadcasts back to the sender. | | config.presence.key | string | random UUID | Stable per-connection presence key. | | config.presence.enabled | boolean | true | Disable presence wiring on this channel. |