@jusi/light-im-sdk 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Shao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# @jusi/light-im-sdk
+
+TypeScript SDK for [jusi-light-im](https://github.com/John-Shao/jusi-light-im) — a lightweight self-hosted IM service designed to complement [we-meet](https://github.com/John-Shao/we-meet) and similar real-time collaboration apps.
+
+## Install
+
+```bash
+npm install @jusi/light-im-sdk
+```
+
+Supports modern browsers + Node 18+ (ESM and CJS bundles ship side-by-side).
+
+## Usage
+
+```ts
+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](https://github.com/John-Shao/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](https://github.com/John-Shao/jusi-light-im/blob/main/LICENSE) © 2026 John Shao

package/dist/index.cjs

@@ -0,0 +1,608 @@
+'use strict';
+
+// src/types.ts
+var FrameType = {
+  Echo: "echo",
+  System: "system",
+  Msg: "msg",
+  Ack: "ack",
+  Read: "read"
+};
+
+// src/errors.ts
+var IMError = class extends Error {
+  constructor(message, cause) {
+    super(message, cause !== void 0 ? { cause } : void 0);
+    this.name = "IMError";
+  }
+};
+var AuthError = class extends IMError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = "AuthError";
+  }
+};
+var NetworkError = class extends IMError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = "NetworkError";
+  }
+};
+var ProtocolError = class extends IMError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = "ProtocolError";
+  }
+};
+var TimeoutError = class extends IMError {
+  constructor(message, cause) {
+    super(message, cause);
+    this.name = "TimeoutError";
+  }
+};
+
+// src/events.ts
+var Emitter = class {
+  listeners = /* @__PURE__ */ new Set();
+  on(cb) {
+    this.listeners.add(cb);
+    return () => {
+      this.listeners.delete(cb);
+    };
+  }
+  emit(event) {
+    for (const cb of this.listeners) {
+      try {
+        cb(event);
+      } catch (e) {
+        console.error("[jusi-light-im-sdk] listener threw", e);
+      }
+    }
+  }
+  clear() {
+    this.listeners.clear();
+  }
+  get size() {
+    return this.listeners.size;
+  }
+};
+
+// src/backoff.ts
+var Backoff = class _Backoff {
+  attempt = 0;
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  static create(opts = {}) {
+    return new _Backoff({
+      baseMs: opts.baseMs ?? 1e3,
+      maxMs: opts.maxMs ?? 3e4,
+      factor: opts.factor ?? 2,
+      jitter: opts.jitter ?? 0.3,
+      random: opts.random ?? Math.random
+    });
+  }
+  /**
+   * Compute the next delay (in ms) and increment the internal attempt counter.
+   *
+   * Caller is responsible for sleeping; this method just returns the number.
+   */
+  next() {
+    const exp = this.opts.baseMs * Math.pow(this.opts.factor, this.attempt);
+    const raw = Math.min(exp, this.opts.maxMs);
+    this.attempt += 1;
+    if (this.opts.jitter <= 0) return raw;
+    const lo = 1 - this.opts.jitter;
+    const span = this.opts.jitter * 2;
+    const factor = lo + this.opts.random() * span;
+    return Math.max(0, Math.round(raw * factor));
+  }
+  /** Reset attempts to 0; the next call to next() yields baseMs again. */
+  reset() {
+    this.attempt = 0;
+  }
+  /** Number of times next() has been called since the last reset. */
+  get attempts() {
+    return this.attempt;
+  }
+};
+
+// src/rest.ts
+var RestClient = class {
+  baseURL;
+  tokenProvider;
+  fetchImpl;
+  cachedToken = null;
+  constructor(opts) {
+    if (!opts.baseURL) throw new Error("RestClient: baseURL required");
+    if (!opts.tokenProvider) throw new Error("RestClient: tokenProvider required");
+    this.baseURL = opts.baseURL.replace(/\/$/, "");
+    this.tokenProvider = opts.tokenProvider;
+    this.fetchImpl = opts.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  }
+  /** Drop the cached token; next request will call tokenProvider again. */
+  invalidateToken() {
+    this.cachedToken = null;
+  }
+  // ---- public endpoints ----
+  async listConversations() {
+    return this.request("GET", "/v1/conversations");
+  }
+  async listMessages(cid, opts = {}) {
+    if (!cid) throw new Error("listMessages: cid required");
+    const params = new URLSearchParams({ cid });
+    if (opts.beforeSeq !== void 0) params.set("before_seq", String(opts.beforeSeq));
+    if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+    return this.request("GET", `/v1/messages?${params.toString()}`);
+  }
+  async markRead(cid, seq) {
+    if (!cid) throw new Error("markRead: cid required");
+    if (!Number.isFinite(seq) || seq <= 0) throw new Error("markRead: positive seq required");
+    await this.request("POST", "/v1/read", { cid, seq });
+  }
+  // ---- internals ----
+  async getToken() {
+    if (this.cachedToken) return this.cachedToken;
+    try {
+      const t = await this.tokenProvider();
+      if (!t) throw new Error("tokenProvider returned empty token");
+      this.cachedToken = t;
+      return t;
+    } catch (e) {
+      throw new AuthError("tokenProvider failed", e);
+    }
+  }
+  async request(method, path, body) {
+    const url = this.baseURL + path;
+    const res = await this.doFetch(url, method, body, await this.getToken());
+    if (res.status === 401) {
+      this.invalidateToken();
+      const fresh = await this.getToken();
+      const res2 = await this.doFetch(url, method, body, fresh);
+      if (res2.status === 401) {
+        throw new AuthError("unauthorized after token refresh");
+      }
+      return this.parseBody(res2);
+    }
+    return this.parseBody(res);
+  }
+  async doFetch(url, method, body, token) {
+    const headers = {
+      Authorization: `Bearer ${token}`
+    };
+    let payload;
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      payload = JSON.stringify(body);
+    }
+    try {
+      return await this.fetchImpl(url, { method, headers, body: payload });
+    } catch (e) {
+      throw new NetworkError(`${method} ${url} failed`, e);
+    }
+  }
+  async parseBody(res) {
+    if (res.status === 204) {
+      return void 0;
+    }
+    if (res.status >= 500) {
+      throw new NetworkError(`${res.status} ${res.statusText}`);
+    }
+    if (res.status >= 400) {
+      const detail = await res.text().catch(() => "");
+      throw new ProtocolError(`${res.status} ${res.statusText}: ${detail}`);
+    }
+    try {
+      return await res.json();
+    } catch (e) {
+      throw new ProtocolError("response not valid JSON", e);
+    }
+  }
+};
+
+// src/ws.ts
+var DEFAULT_ACK_TIMEOUT_MS = 1e4;
+var WsClient = class {
+  baseURL;
+  wsFactory;
+  ackTimeoutMs;
+  ws = null;
+  pendingAcks = /* @__PURE__ */ new Map();
+  idCounter = 0;
+  openEmit = new Emitter();
+  closeEmit = new Emitter();
+  frameEmit = new Emitter();
+  errorEmit = new Emitter();
+  constructor(opts) {
+    if (!opts.url) throw new Error("WsClient: url required");
+    this.baseURL = opts.url;
+    this.wsFactory = opts.wsFactory ?? ((u) => new WebSocket(u));
+    this.ackTimeoutMs = opts.ackTimeoutMs ?? DEFAULT_ACK_TIMEOUT_MS;
+  }
+  /** True when the underlying socket is OPEN. */
+  get isOpen() {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+  /**
+   * Open a WebSocket with the given token appended as ?token=. Resolves when the
+   * native onopen fires; rejects on transport error (does NOT wait for the
+   * server-side "connected" system frame — that's Client's higher-level concern).
+   */
+  connect(token) {
+    return new Promise((resolve, reject) => {
+      const sep = this.baseURL.includes("?") ? "&" : "?";
+      const url = this.baseURL + sep + "token=" + encodeURIComponent(token);
+      let ws;
+      try {
+        ws = this.wsFactory(url);
+      } catch (e) {
+        reject(new NetworkError("WebSocket constructor threw", e));
+        return;
+      }
+      this.ws = ws;
+      let settled = false;
+      const settle = (err) => {
+        if (settled) return;
+        settled = true;
+        if (err) reject(err);
+        else resolve();
+      };
+      ws.onopen = () => {
+        this.openEmit.emit();
+        settle();
+      };
+      ws.onmessage = (e) => this.handleMessage(e.data);
+      ws.onerror = (_e) => {
+        const err = new NetworkError("ws error event");
+        this.errorEmit.emit(err);
+        settle(err);
+      };
+      ws.onclose = (e) => {
+        this.failPendingAcks(new NetworkError("connection closed"));
+        this.closeEmit.emit({ code: e.code, reason: e.reason });
+        settle(new NetworkError(`closed before open (code ${e.code})`));
+      };
+    });
+  }
+  /** Send any frame. Throws NetworkError if the socket is not open. */
+  send(frame) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new NetworkError("send: ws not open");
+    }
+    let serialised;
+    try {
+      serialised = JSON.stringify(frame);
+    } catch (e) {
+      throw new ProtocolError("frame not JSON-serialisable", e);
+    }
+    this.ws.send(serialised);
+  }
+  /**
+   * Send a TypeMsg frame and resolve when the matching ack arrives (matched on
+   * client_msg_id). Rejects with TimeoutError if no ack within ackTimeoutMs, or
+   * with NetworkError if the connection drops first.
+   */
+  sendMsg(payload) {
+    const cmid = payload.client_msg_id ?? this.generateClientMsgId();
+    const out = { ...payload, client_msg_id: cmid };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingAcks.delete(cmid);
+        reject(new TimeoutError(`ack timeout for ${cmid}`));
+      }, this.ackTimeoutMs);
+      this.pendingAcks.set(cmid, { resolve, reject, timer });
+      try {
+        this.send({ type: FrameType.Msg, payload: out });
+      } catch (e) {
+        clearTimeout(timer);
+        this.pendingAcks.delete(cmid);
+        reject(e);
+      }
+    });
+  }
+  /** Close the socket and reject any pending acks. Idempotent. */
+  disconnect(code = 1e3, reason = "client disconnect") {
+    this.failPendingAcks(new IMError("disconnected"));
+    if (this.ws && this.ws.readyState !== WebSocket.CLOSED) {
+      try {
+        this.ws.close(code, reason);
+      } catch {
+      }
+    }
+    this.ws = null;
+  }
+  // ---- subscriptions ----
+  onOpen(cb) {
+    return this.openEmit.on(cb);
+  }
+  onClose(cb) {
+    return this.closeEmit.on(cb);
+  }
+  onFrame(cb) {
+    return this.frameEmit.on(cb);
+  }
+  onError(cb) {
+    return this.errorEmit.on(cb);
+  }
+  // ---- internals ----
+  handleMessage(data) {
+    let raw;
+    if (typeof data === "string") {
+      raw = data;
+    } else if (data instanceof ArrayBuffer) {
+      raw = new TextDecoder().decode(new Uint8Array(data));
+    } else {
+      this.errorEmit.emit(new ProtocolError("unsupported ws data type"));
+      return;
+    }
+    let frame;
+    try {
+      frame = JSON.parse(raw);
+    } catch (e) {
+      this.errorEmit.emit(new ProtocolError("bad json frame", e));
+      return;
+    }
+    if (frame.type === FrameType.Ack && frame.payload) {
+      const ack = frame.payload;
+      const cmid = ack.client_msg_id;
+      if (cmid && this.pendingAcks.has(cmid)) {
+        const p = this.pendingAcks.get(cmid);
+        clearTimeout(p.timer);
+        this.pendingAcks.delete(cmid);
+        p.resolve(ack);
+        return;
+      }
+    }
+    this.frameEmit.emit(frame);
+  }
+  failPendingAcks(err) {
+    for (const [, p] of this.pendingAcks) {
+      clearTimeout(p.timer);
+      p.reject(err);
+    }
+    this.pendingAcks.clear();
+  }
+  generateClientMsgId() {
+    try {
+      const g = globalThis;
+      if (g.crypto && typeof g.crypto.randomUUID === "function") {
+        return g.crypto.randomUUID();
+      }
+    } catch {
+    }
+    this.idCounter += 1;
+    return "cm-" + this.idCounter.toString(36);
+  }
+};
+
+// src/client.ts
+var Client = class {
+  opts;
+  rest;
+  wsURL;
+  backoff;
+  stateEmit = new Emitter();
+  msgEmit = new Emitter();
+  readEmit = new Emitter();
+  systemEmit = new Emitter();
+  state_ = "disconnected";
+  ws = null;
+  currentToken = null;
+  reconnectTimer = null;
+  explicitlyDisconnected = false;
+  constructor(opts) {
+    if (!opts.baseURL) throw new Error("Client: baseURL required");
+    if (!opts.tokenProvider) throw new Error("Client: tokenProvider required");
+    this.opts = opts;
+    this.rest = new RestClient({
+      baseURL: opts.baseURL,
+      tokenProvider: opts.tokenProvider,
+      fetch: opts.fetch
+    });
+    this.wsURL = opts.wsURL ?? this.deriveWsURL(opts.baseURL);
+    this.backoff = Backoff.create(opts.backoff);
+    if (opts.onStateChange) this.stateEmit.on(opts.onStateChange);
+  }
+  // ---- public API ----
+  get state() {
+    return this.state_;
+  }
+  async connect() {
+    this.explicitlyDisconnected = false;
+    if (this.state_ === "connected" || this.state_ === "connecting") return;
+    await this.openOnce(
+      /*allowRefresh=*/
+      true
+    );
+  }
+  disconnect() {
+    this.explicitlyDisconnected = true;
+    this.cancelReconnect();
+    if (this.ws) {
+      this.ws.disconnect();
+      this.ws = null;
+    }
+    this.transitionTo("disconnected");
+  }
+  async sendText(cid, body, opts = {}) {
+    if (!cid || !body) throw new Error("sendText: cid and body required");
+    if (!this.ws || !this.ws.isOpen) {
+      throw new NetworkError("sendText: not connected");
+    }
+    return this.ws.sendMsg({
+      cid,
+      body,
+      content_type: opts.contentType,
+      client_msg_id: opts.clientMsgId
+    });
+  }
+  async loadHistory(cid, opts = {}) {
+    return this.rest.listMessages(cid, opts);
+  }
+  async markRead(cid, seq) {
+    if (this.ws && this.ws.isOpen) {
+      const payload = { cid, seq };
+      this.ws.send({ type: FrameType.Read, payload });
+      return;
+    }
+    await this.rest.markRead(cid, seq);
+  }
+  async listConversations() {
+    return this.rest.listConversations();
+  }
+  // ---- event subscriptions ----
+  onMessage(cb) {
+    return this.msgEmit.on(cb);
+  }
+  onRead(cb) {
+    return this.readEmit.on(cb);
+  }
+  onSystem(cb) {
+    return this.systemEmit.on(cb);
+  }
+  onStateChange(cb) {
+    return this.stateEmit.on(cb);
+  }
+  // ---- internals ----
+  deriveWsURL(baseURL) {
+    const trimmed = baseURL.replace(/\/$/, "");
+    return trimmed.replace(/^http/, "ws") + "/v1/ws";
+  }
+  transitionTo(next) {
+    if (this.state_ === next) return;
+    this.state_ = next;
+    this.stateEmit.emit(next);
+  }
+  async fetchToken(forceRefresh) {
+    if (this.currentToken && !forceRefresh) return this.currentToken;
+    let tok;
+    try {
+      tok = await this.opts.tokenProvider();
+    } catch (e) {
+      throw new AuthError("tokenProvider failed", e);
+    }
+    if (!tok) throw new AuthError("tokenProvider returned empty token");
+    this.currentToken = tok;
+    return tok;
+  }
+  /**
+   * Try to open one WebSocket. On 401-style failure, retries once with a fresh token
+   * (when allowRefresh is true). Updates state.
+   */
+  async openOnce(allowRefresh) {
+    this.transitionTo("connecting");
+    let token;
+    try {
+      token = await this.fetchToken(false);
+    } catch (e) {
+      this.transitionTo("auth_failed");
+      throw e;
+    }
+    try {
+      await this.openWith(token);
+      this.backoff.reset();
+      this.transitionTo("connected");
+    } catch (e) {
+      if (allowRefresh && this.looksLikeAuthFailure(e)) {
+        try {
+          token = await this.fetchToken(true);
+        } catch (refreshErr) {
+          this.transitionTo("auth_failed");
+          throw refreshErr;
+        }
+        try {
+          await this.openWith(token);
+          this.backoff.reset();
+          this.transitionTo("connected");
+          return;
+        } catch (e2) {
+          this.transitionTo("auth_failed");
+          throw e2;
+        }
+      }
+      throw e;
+    }
+  }
+  looksLikeAuthFailure(e) {
+    if (e instanceof NetworkError && /code 1008|1006/.test(e.message)) return true;
+    if (e instanceof AuthError) return true;
+    return false;
+  }
+  openWith(token) {
+    const ws = new WsClient({
+      url: this.wsURL,
+      wsFactory: this.opts.wsFactory,
+      ackTimeoutMs: this.opts.ackTimeoutMs
+    });
+    this.ws = ws;
+    ws.onFrame((f) => this.dispatchFrame(f));
+    ws.onClose((info) => this.handleClose(info));
+    return ws.connect(token);
+  }
+  dispatchFrame(f) {
+    switch (f.type) {
+      case FrameType.Msg:
+        if (f.payload) this.msgEmit.emit(f.payload);
+        break;
+      case FrameType.Read:
+        if (f.payload) this.readEmit.emit(f.payload);
+        break;
+      case FrameType.System:
+        if (f.payload) this.systemEmit.emit(f.payload);
+        break;
+    }
+  }
+  handleClose(_info) {
+    if (this.explicitlyDisconnected) {
+      return;
+    }
+    this.ws = null;
+    if (this.state_ === "auth_failed") {
+      return;
+    }
+    this.transitionTo("reconnecting");
+    this.scheduleReconnect();
+  }
+  scheduleReconnect() {
+    this.cancelReconnect();
+    const delay = this.backoff.next();
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      void this.tryReconnect();
+    }, delay);
+  }
+  async tryReconnect() {
+    if (this.explicitlyDisconnected) return;
+    try {
+      await this.openOnce(
+        /*allowRefresh=*/
+        true
+      );
+    } catch (e) {
+      if (this.state_ === "auth_failed" || this.explicitlyDisconnected) return;
+      this.transitionTo("reconnecting");
+      this.scheduleReconnect();
+    }
+  }
+  cancelReconnect() {
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+};
+
+exports.AuthError = AuthError;
+exports.Backoff = Backoff;
+exports.Client = Client;
+exports.Emitter = Emitter;
+exports.FrameType = FrameType;
+exports.IMError = IMError;
+exports.NetworkError = NetworkError;
+exports.ProtocolError = ProtocolError;
+exports.RestClient = RestClient;
+exports.TimeoutError = TimeoutError;
+exports.WsClient = WsClient;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map