@jusi/light-im-sdk

TypeScript SDK for jusi-light-im — a lightweight self-hosted IM service designed to complement we-meet and similar real-time collaboration apps.

Install

npm install @jusi/light-im-sdk

Supports modern browsers + Node 18+ (ESM and CJS bundles ship side-by-side).

Usage

import { Client } from '@jusi/light-im-sdk'

const client = new Client({
  baseURL: 'https://im.example.com',
  tokenProvider: () =>
    fetch('/api/im/token', { method: 'POST', credentials: 'include' })
      .then((r) => r.json())
      .then((d) => d.token),
})

await client.connect()
client.onMessage((m) => console.log('msg', m))
const ack = await client.sendText('cid-XYZ', 'hello')

const convs = await client.listConversations()
const { messages } = await client.loadHistory('cid-XYZ')
await client.markRead('cid-XYZ', ack.seq)

State machine:

disconnected → connecting → connected ⇄ reconnecting
                                ↓
                          auth_failed (terminal until explicit connect())

Companion server

This SDK targets jusi-light-im — a single Go binary you can host alongside any Postgres + Redis pair.

| Capability | API surface | |---|---| | REST | GET /v1/conversations, GET /v1/messages, POST /v1/read | | WebSocket | GET /v1/ws?token=<jwt> (text frames, JSON) | | Server-side admin | HMAC-signed /admin/* for bridge integrations |

The tokenProvider you pass to Client is expected to return a bearer JWT minted by the server's POST /admin/tokens/issue endpoint (typically called server-side from your host app).

Scripts

| Command | Purpose | |---|---| | npm run build | Bundle CJS + ESM + .d.ts to dist/ via tsup | | npm test | Unit tests via Vitest | | npm run typecheck | tsc --noEmit |

License

MIT © 2026 John Shao