pingerchips-js 2.1.0 → 3.0.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "pingerchips-js",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "Pingerchips JavaScript client SDK for real-time WebSocket connections",
   "main": "index.js",
   "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test test/*.test.js"
   },
   "keywords": [
     "pingerchips",
@@ -18,6 +18,7 @@
   "author": "Pingerchips",
   "license": "MIT",
   "dependencies": {
+    "@msgpack/msgpack": "^3.1.2",
     "phoenix": "^1.7.0"
   },
   "repository": {

package/spaces.js

@@ -0,0 +1,414 @@
+import { Pingerchips } from "./index.js";
+
+// ---------------------------------------------------------------------------
+// PingerchipsSpaces — entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Usage:
+ *   const spaces = new PingerchipsSpaces('pk_live_...', { endpoint: 'wss://...' });
+ *   await spaces.connect();
+ *   const space = await spaces.get('doc-abc123', { clientId: 'user-42', profile: { name: 'Alice' } });
+ *
+ *   space.cursors.set({ x: 124, y: 88 });
+ *   space.cursors.subscribe('update', ({ member, position }) => renderCursor(member, position));
+ *
+ *   await space.enter({ name: 'Alice', color: '#FF0099' });
+ *   space.members.subscribe('enter', (member) => addAvatar(member));
+ *
+ *   space.locations.set({ elementId: 'heading-2' });
+ *   space.locations.subscribe('update', ({ member, location }) => showIndicator(member, location));
+ *
+ *   const lock = await space.locks.acquire('block-3');
+ *   await space.locks.release('block-3');
+ *
+ *   await space.leave();
+ */
+export class PingerchipsSpaces {
+  constructor(appKey, options = {}) {
+    if (!appKey) throw new Error("appKey required");
+    this.appKey = appKey;
+    this._options = options;
+    this._realtime =
+      options.realtime || new Pingerchips(appKey, { endpoint: options.endpoint });
+    this._spaces = {};
+  }
+
+  /**
+   * Waits until the socket is connected.
+   * @returns {Promise<void>}
+   */
+  connect() {
+    return new Promise((resolve) => {
+      if (this._realtime.socket?.isConnected()) return resolve();
+      this._realtime.socket.onOpen(() => resolve());
+    });
+  }
+
+  /**
+   * Join or retrieve a named Space.
+   *
+   * @param {string} spaceId     - Unique space name, e.g. "doc-abc123"
+   * @param {{ clientId: string, profile?: object, throttle?: number }} options
+   * @returns {Promise<Space>}
+   */
+  async get(spaceId, { clientId, profile = {}, throttle = 33 } = {}) {
+    if (!clientId) throw new Error("clientId required");
+    const key = spaceId;
+    if (this._spaces[key]) return this._spaces[key];
+
+    const topic = `app:${this.appKey}:room:ephemeral-${spaceId}`;
+    const channel = this._realtime.socket.channel(topic, {});
+
+    const space = new Space(channel, spaceId, clientId, profile, throttle);
+    await space._join();
+    this._spaces[key] = space;
+    return space;
+  }
+
+  /**
+   * Leave and clean up a space.
+   * @param {string} spaceId
+   */
+  leave(spaceId) {
+    const space = this._spaces[spaceId];
+    if (space) {
+      space._leave();
+      delete this._spaces[spaceId];
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Space
+// ---------------------------------------------------------------------------
+
+class Space {
+  constructor(channel, spaceId, clientId, profile, throttle) {
+    this._channel = channel;
+    this.spaceId = spaceId;
+    this.clientId = clientId;
+    this.profile = profile;
+    this._throttleMs = throttle;
+
+    this.cursors   = new Cursors(this);
+    this.members   = new Members(this);
+    this.locations = new Locations(this);
+    this.locks     = new Locks(this);
+
+    // Wire up server events to sub-APIs
+    channel.on("presence:state", (payload) => {
+      this.members._handleState(payload.members || []);
+    });
+    channel.on("presence:join", (payload) => {
+      this.members._handleJoin(payload);
+    });
+    channel.on("presence:leave", (payload) => {
+      this.members._handleLeave(payload);
+    });
+    channel.on("cursor", (payload) => {
+      this.cursors._handleUpdate(payload);
+    });
+    channel.on("location", (payload) => {
+      this.locations._handleUpdate(payload);
+    });
+    channel.on("lock:update", (payload) => {
+      this.locks._handleUpdate(payload);
+    });
+  }
+
+  _join() {
+    return new Promise((resolve, reject) => {
+      this._channel
+        .join()
+        .receive("ok", () => resolve())
+        .receive("error", (err) => reject(new Error(`Space join failed: ${JSON.stringify(err)}`)));
+    });
+  }
+
+  /**
+   * Enter the space with a member profile. Broadcasts presence to all members.
+   * @param {object} profile  - Arbitrary member metadata: { name, color, avatar, ... }
+   */
+  async enter(profile = {}) {
+    this.profile = { ...this.profile, ...profile };
+    this._channel.push("presence:update", { profile: this.profile, client_id: this.clientId });
+  }
+
+  /**
+   * Leave the space. Releases all held locks and removes presence.
+   */
+  async leave() {
+    this._channel.push("presence:leave", { client_id: this.clientId });
+    this._leave();
+  }
+
+  _leave() {
+    this._channel.leave();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Cursors
+// ---------------------------------------------------------------------------
+
+class Cursors {
+  constructor(space) {
+    this._space = space;
+    this._handlers = [];
+    this._throttleTimer = null;
+    this._pendingPosition = null;
+  }
+
+  /**
+   * Publish the current cursor position. Client-side throttled.
+   * @param {{ x: number, y: number, [extra: string]: any }} position
+   */
+  set(position) {
+    this._pendingPosition = position;
+    if (this._throttleTimer) return;
+    this._throttleTimer = setTimeout(() => {
+      this._throttleTimer = null;
+      if (this._pendingPosition) {
+        this._space._channel.push("cursor", {
+          client_id: this._space.clientId,
+          position: this._pendingPosition,
+        });
+        this._pendingPosition = null;
+      }
+    }, this._space._throttleMs);
+  }
+
+  /**
+   * Subscribe to cursor updates from all other members.
+   * @param {'update'} event
+   * @param {function} handler  - ({ member: { clientId, profile }, position }) => void
+   * @returns {() => void}  unsubscribe function
+   */
+  subscribe(event, handler) {
+    if (event !== "update") return () => {};
+    this._handlers.push(handler);
+    return () => {
+      this._handlers = this._handlers.filter((h) => h !== handler);
+    };
+  }
+
+  _handleUpdate({ client_id, position }) {
+    if (client_id === this._space.clientId) return; // skip own events
+    const member = this._space.members.get(client_id);
+    for (const h of this._handlers) h({ member, position });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Members
+// ---------------------------------------------------------------------------
+
+class Members {
+  constructor(space) {
+    this._space = space;
+    this._members = {}; // clientId → member object
+    this._handlers = { enter: [], leave: [], update: [] };
+  }
+
+  /**
+   * Get the current member list.
+   * @returns {object[]}
+   */
+  getAll() {
+    return Object.values(this._members);
+  }
+
+  /**
+   * Get a member by clientId.
+   * @param {string} clientId
+   * @returns {object|undefined}
+   */
+  get(clientId) {
+    return this._members[clientId];
+  }
+
+  /**
+   * Subscribe to member lifecycle events.
+   * @param {'enter'|'leave'|'update'} event
+   * @param {function} handler
+   * @returns {() => void}  unsubscribe function
+   */
+  subscribe(event, handler) {
+    if (!this._handlers[event]) return () => {};
+    this._handlers[event].push(handler);
+    return () => {
+      this._handlers[event] = this._handlers[event].filter((h) => h !== handler);
+    };
+  }
+
+  _handleState(members) {
+    this._members = {};
+    for (const m of members) {
+      this._members[m.client_id || m.id] = _normaliseMember(m);
+    }
+  }
+
+  _handleJoin(payload) {
+    const member = _normaliseMember(payload);
+    const isUpdate = !!this._members[member.clientId];
+    this._members[member.clientId] = member;
+    const event = isUpdate ? "update" : "enter";
+    for (const h of this._handlers[event] || []) h(member);
+  }
+
+  _handleLeave(payload) {
+    const clientId = payload.client_id || payload.id;
+    const member = this._members[clientId];
+    delete this._members[clientId];
+    if (member) {
+      for (const h of this._handlers.leave) h(member);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Locations
+// ---------------------------------------------------------------------------
+
+class Locations {
+  constructor(space) {
+    this._space = space;
+    this._handlers = [];
+    this._current = null;
+  }
+
+  /**
+   * Set the current member's location (what they're looking at).
+   * @param {object} location  - e.g. { elementId: 'heading-2', range: { start: 4, end: 12 } }
+   */
+  set(location) {
+    this._current = location;
+    this._space._channel.push("location", {
+      client_id: this._space.clientId,
+      location,
+    });
+  }
+
+  /**
+   * Subscribe to location updates from other members.
+   * @param {'update'} event
+   * @param {function} handler  - ({ member, currentLocation, previousLocation }) => void
+   * @returns {() => void}
+   */
+  subscribe(event, handler) {
+    if (event !== "update") return () => {};
+    this._handlers.push(handler);
+    return () => {
+      this._handlers = this._handlers.filter((h) => h !== handler);
+    };
+  }
+
+  _handleUpdate({ client_id, location }) {
+    if (client_id === this._space.clientId) return;
+    const member = this._space.members.get(client_id);
+    const previous = member?._location ?? null;
+    if (member) member._location = location;
+    for (const h of this._handlers) h({ member, currentLocation: location, previousLocation: previous });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Locks
+// ---------------------------------------------------------------------------
+
+class Locks {
+  constructor(space) {
+    this._space = space;
+    this._locks = {}; // lockId → { id, status, holder }
+    this._handlers = [];
+  }
+
+  /**
+   * Acquire a named lock.
+   * @param {string} lockId
+   * @returns {Promise<{ id: string, status: 'locked'|'pending' }>}
+   */
+  acquire(lockId) {
+    return new Promise((resolve, reject) => {
+      this._space._channel
+        .push("lock:acquire", { id: lockId })
+        .receive("ok", (resp) => {
+          this._locks[lockId] = { id: lockId, status: resp.status, holder: this._space.clientId };
+          resolve({ id: lockId, status: resp.status });
+        })
+        .receive("error", (err) => {
+          reject(new Error(err.reason || "lock held by another member"));
+        });
+    });
+  }
+
+  /**
+   * Release a named lock.
+   * @param {string} lockId
+   * @returns {Promise<void>}
+   */
+  release(lockId) {
+    return new Promise((resolve) => {
+      this._space._channel
+        .push("lock:release", { id: lockId })
+        .receive("ok", () => {
+          delete this._locks[lockId];
+          resolve();
+        })
+        .receive("error", () => resolve()); // no-op if not held
+    });
+  }
+
+  /**
+   * Get all currently known locks.
+   * @returns {object[]}
+   */
+  getAll() {
+    return Object.values(this._locks);
+  }
+
+  /**
+   * Get a single lock by id.
+   * @param {string} lockId
+   * @returns {object|undefined}
+   */
+  get(lockId) {
+    return this._locks[lockId];
+  }
+
+  /**
+   * Subscribe to lock state changes.
+   * @param {'update'} event
+   * @param {function} handler  - ({ id, status, member }) => void
+   * @returns {() => void}
+   */
+  subscribe(event, handler) {
+    if (event !== "update") return () => {};
+    this._handlers.push(handler);
+    return () => {
+      this._handlers = this._handlers.filter((h) => h !== handler);
+    };
+  }
+
+  _handleUpdate({ id, status, holder }) {
+    this._locks[id] = { id, status, holder };
+    if (status === "unlocked") delete this._locks[id];
+    const member = holder ? this._space.members.get(holder) : null;
+    for (const h of this._handlers) h({ id, status, member });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function _normaliseMember(raw) {
+  return {
+    clientId: raw.client_id || raw.id,
+    profile:  raw.profile || {},
+    joinedAt: raw.joined_at || null,
+  };
+}
+
+export default PingerchipsSpaces;