@glade-chat/glade.js 0.1.0

package/src/gateway/Gateway.js

@@ -0,0 +1,172 @@
+'use strict';
+
+import { io } from 'socket.io-client';
+import { GladeGatewayError } from '../errors/index.js';
+
+/**
+ * The realtime layer of glade.js: a thin wrapper around a Socket.IO client
+ * connection to the Glade gateway. It authenticates the handshake with the
+ * client's access token, transparently refreshes + reconnects when the token
+ * expires, and forwards every server dispatch to a single handler.
+ */
+export class Gateway {
+  /**
+   * @param {object} opts
+   * @param {string} opts.url Gateway origin.
+   * @param {() => (string | null)} opts.getToken Returns the current access token.
+   * @param {() => Promise<string | null>} opts.refresh Refreshes the token; returns the new one.
+   * @param {(event: string, data: any) => void} opts.onDispatch Receives every server event.
+   * @param {() => void} [opts.onConnect]
+   * @param {(reason: string) => void} [opts.onDisconnect]
+   * @param {(err: Error) => void} [opts.onError]
+   * @param {(msg: string) => void} [opts.debug]
+   * @param {object} [opts.ws] Extra socket.io-client options.
+   */
+  constructor(opts) {
+    this.url = opts.url;
+    this.getToken = opts.getToken;
+    this.refresh = opts.refresh;
+    this.onDispatch = opts.onDispatch;
+    this.onConnect = opts.onConnect ?? (() => {});
+    this.onDisconnect = opts.onDisconnect ?? (() => {});
+    this.onError = opts.onError ?? (() => {});
+    this._debug = opts.debug ?? null;
+    this.wsOptions = opts.ws ?? {};
+
+    /** @type {import('socket.io-client').Socket | null} */
+    this.socket = null;
+    /** @type {string | null} The socket id assigned on connect. */
+    this.id = null;
+    this._refreshingHandshake = false;
+    /** Consecutive handshake-refresh attempts, reset on a successful connect. */
+    this._handshakeRefreshAttempts = 0;
+    /** Cap on consecutive handshake refreshes to avoid a reconnect loop. */
+    this._maxHandshakeRefresh = opts.maxHandshakeRefresh ?? 5;
+  }
+
+  /** Whether the underlying socket is currently connected. */
+  get connected() {
+    return Boolean(this.socket?.connected);
+  }
+
+  /**
+   * Opens the gateway connection. Safe to call once; subsequent calls reconnect
+   * the existing socket.
+   */
+  connect() {
+    if (this.socket) {
+      if (!this.socket.connected) this.socket.connect();
+      return;
+    }
+
+    this.#debug(`Connecting to ${this.url}`);
+    this.socket = io(this.url, {
+      autoConnect: false,
+      withCredentials: true,
+      auth: (cb) => cb({ token: this.getToken() }),
+      ...this.wsOptions,
+    });
+
+    this.socket.on('connect', () => {
+      this.id = this.socket.id;
+      this._handshakeRefreshAttempts = 0;
+      this.#debug(`Connected (socket ${this.id})`);
+      this.onConnect();
+    });
+
+    this.socket.on('disconnect', (reason) => {
+      this.#debug(`Disconnected: ${reason}`);
+      this.onDisconnect(reason);
+    });
+
+    // If the handshake is rejected for an expired/invalid token, refresh once and
+    // reconnect; the auth callback re-reads the token on the next attempt.
+    this.socket.on('connect_error', async (err) => {
+      this.#debug(`connect_error: ${err.message}`);
+      const tokenError = err.message?.toLowerCase().includes('token');
+      const canRefresh =
+        tokenError &&
+        !this._refreshingHandshake &&
+        this._handshakeRefreshAttempts < this._maxHandshakeRefresh;
+      if (canRefresh) {
+        this._refreshingHandshake = true;
+        this._handshakeRefreshAttempts += 1;
+        try {
+          const fresh = await this.refresh();
+          if (fresh) this.socket.connect();
+          else this.onError(new GladeGatewayError(`Gateway auth failed: ${err.message}`));
+        } finally {
+          this._refreshingHandshake = false;
+        }
+      } else {
+        this.onError(new GladeGatewayError(err.message));
+      }
+    });
+
+    // Forward every server-sent event to the dispatch handler.
+    this.socket.onAny((event, ...args) => {
+      this.onDispatch(event, args.length <= 1 ? args[0] : args);
+    });
+
+    this.socket.connect();
+  }
+
+  /** Closes the gateway connection. */
+  disconnect() {
+    if (this.socket) {
+      this.socket.disconnect();
+      this.socket = null;
+      this.id = null;
+    }
+  }
+
+  /**
+   * Emits an event to the server without waiting for an acknowledgement.
+   * @param {string} event
+   * @param {...any} args
+   */
+  send(event, ...args) {
+    if (!this.socket) throw new GladeGatewayError('Gateway is not connected');
+    this.socket.emit(event, ...args);
+  }
+
+  /**
+   * Emits an event and resolves with the server's acknowledgement. Rejects with a
+   * {@link GladeGatewayError} when the ack reports `ok: false` (e.g. rate limited).
+   * @param {string} event
+   * @param {any} [payload]
+   * @param {number} [timeout=15000] ms before rejecting.
+   * @returns {Promise<any>}
+   */
+  request(event, payload, timeout = 15_000) {
+    return new Promise((resolve, reject) => {
+      if (!this.socket) return reject(new GladeGatewayError('Gateway is not connected'));
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        reject(new GladeGatewayError(`Gateway request "${event}" timed out`));
+      }, timeout);
+
+      const ack = (response) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (response && response.ok === false) {
+          reject(new GladeGatewayError(response.error || `"${event}" failed`, response.code));
+        } else {
+          resolve(response);
+        }
+      };
+
+      if (payload === undefined) this.socket.emit(event, ack);
+      else this.socket.emit(event, payload, ack);
+    });
+  }
+
+  #debug(msg) {
+    this._debug?.(`[Gateway] ${msg}`);
+  }
+}
+
+export default Gateway;

package/src/gateway/handleDispatch.js

@@ -0,0 +1,259 @@
+'use strict';
+
+import { Events, GatewayDispatch } from '../util/Constants.js';
+import { VoiceState } from '../structures/VoiceState.js';
+
+/**
+ * Translates a raw gateway event into cache mutations and client-facing events.
+ * Invoked for every server dispatch by the {@link Gateway}.
+ *
+ * @param {import('../client/Client.js').Client} client
+ * @param {string} event Raw Socket.IO event name.
+ * @param {any} data Event payload.
+ */
+export function handleDispatch(client, event, data) {
+  // Surface every raw event for power users / debugging.
+  client.emit(Events.Raw, event, data);
+
+  switch (event) {
+    case GatewayDispatch.Ready: {
+      client.ready = true;
+      // The server only auto-joins user/house/DM channels — explicitly subscribe
+      // to each cached room so we receive room messages, typing, and reactions.
+      client._subscribeCachedRooms();
+      client.emit(Events.Ready, client);
+      break;
+    }
+
+    case GatewayDispatch.MessageNew: {
+      const message = client._cacheMessage(data);
+      client.emit(Events.MessageCreate, message);
+      break;
+    }
+
+    case GatewayDispatch.MessageUpdated: {
+      const existing = findCachedMessage(client, data);
+      const old = existing ? existing._clone() : null;
+      const message = client._cacheMessage(data);
+      client.emit(Events.MessageUpdate, old, message);
+      break;
+    }
+
+    case GatewayDispatch.MessageDeleted: {
+      const existing = findCachedMessage(client, data);
+      removeCachedMessage(client, data);
+      client.emit(Events.MessageDelete, existing ?? data);
+      break;
+    }
+
+    case GatewayDispatch.MessagePinned: {
+      const existing = findCachedMessage(client, { id: data.messageId, roomId: data.roomId });
+      if (existing) existing.pinned = data.pinned;
+      client.emit(Events.MessagePinUpdate, {
+        roomId: data.roomId,
+        messageId: data.messageId,
+        pinned: data.pinned,
+        message: existing ?? null,
+      });
+      break;
+    }
+
+    case GatewayDispatch.ReactionUpdated: {
+      const existing = findCachedMessage(client, {
+        id: data.messageId,
+        roomId: data.roomId,
+        dmChannelId: data.dmChannelId,
+      });
+      if (existing) existing._patch({ reactions: data.reactions });
+      client.emit(Events.MessageReactionUpdate, {
+        messageId: data.messageId,
+        roomId: data.roomId ?? null,
+        dmChannelId: data.dmChannelId ?? null,
+        reactions: existing ? existing.reactions : data.reactions,
+        message: existing ?? null,
+      });
+      break;
+    }
+
+    case GatewayDispatch.Mention: {
+      const message = client._cacheMessage(data.message);
+      client.emit(Events.Mention, {
+        houseId: data.houseId,
+        roomId: data.roomId,
+        message,
+      });
+      break;
+    }
+
+    case GatewayDispatch.DmIncoming: {
+      // The message also arrives via `message:new` (the socket is in the DM room),
+      // so we only ensure the channel/message are cached here — no duplicate event.
+      client._cacheMessage(data.message);
+      break;
+    }
+
+    case GatewayDispatch.Typing: {
+      const user = client.users.cache.get(data.userId) ?? null;
+      client.emit(Events.TypingStart, {
+        userId: data.userId,
+        handle: data.handle,
+        user,
+        roomId: data.roomId ?? null,
+        dmChannelId: data.dmChannelId ?? null,
+        typing: data.typing,
+      });
+      break;
+    }
+
+    case GatewayDispatch.PresenceUpdate: {
+      const user = client.users.cache.get(data.userId);
+      if (user) user.status = data.status;
+      // Reflect on cached House members too.
+      for (const house of client.houses.cache.values()) {
+        const member = house.members.cache.get(data.userId);
+        if (member) member.status = data.status;
+      }
+      client.emit(Events.PresenceUpdate, { userId: data.userId, status: data.status, user: user ?? null });
+      break;
+    }
+
+    case GatewayDispatch.RoomCreated: {
+      const house = client.houses.cache.get(data.houseId);
+      const room = house ? house.rooms._add(data) : null;
+      client.emit(Events.RoomCreate, room ?? data);
+      break;
+    }
+
+    case GatewayDispatch.RoomUpdated: {
+      if (data.id) {
+        const existing = client.channels.cache.get(data.id);
+        const old = existing ? existing._clone() : null;
+        const house = client.houses.cache.get(data.houseId ?? existing?.houseId);
+        const room = house ? house.rooms._add(data) : existing;
+        client.emit(Events.RoomUpdate, old, room ?? data);
+      } else {
+        // Override-only update: just a houseId hint to refetch.
+        client.emit(Events.RoomUpdate, null, data);
+      }
+      break;
+    }
+
+    case GatewayDispatch.RoomDeleted: {
+      const existing = client.channels.cache.get(data.roomId) ?? null;
+      const house = client.houses.cache.get(data.houseId);
+      house?.rooms.cache.delete(data.roomId);
+      client.channels.cache.delete(data.roomId);
+      client.emit(Events.RoomDelete, existing ?? data);
+      break;
+    }
+
+    case GatewayDispatch.RoomReordered: {
+      client.emit(Events.RoomsReorder, { houseId: data.houseId });
+      break;
+    }
+
+    case GatewayDispatch.HouseUpdated: {
+      client.emit(Events.HouseUpdate, { houseId: data.houseId, house: client.houses.cache.get(data.houseId) ?? null });
+      break;
+    }
+
+    case GatewayDispatch.HouseDeleted: {
+      const house = client.houses.cache.get(data.houseId) ?? null;
+      client.houses.cache.delete(data.houseId);
+      client.emit(Events.HouseDelete, house ?? data);
+      break;
+    }
+
+    case GatewayDispatch.RolesUpdated: {
+      client.emit(Events.RolesUpdate, { houseId: data.houseId });
+      break;
+    }
+
+    case GatewayDispatch.MembersUpdated: {
+      client.emit(Events.MembersUpdate, { houseId: data.houseId });
+      break;
+    }
+
+    case GatewayDispatch.MemberJoined: {
+      client.emit(Events.MemberJoin, { houseId: data.houseId, userId: data.userId });
+      break;
+    }
+
+    case GatewayDispatch.FriendRequest: {
+      const user = data.user ? client.users._add(data.user) : null;
+      client.emit(Events.FriendRequest, { id: data.id, user });
+      break;
+    }
+
+    case GatewayDispatch.FriendAccepted: {
+      const user = data.user ? client.users._add(data.user) : null;
+      if (user) client.friends.cache.set(user.id, user);
+      client.emit(Events.FriendAccepted, { user });
+      break;
+    }
+
+    case GatewayDispatch.FriendRemoved: {
+      client.friends.cache.delete(data.userId);
+      client.emit(Events.FriendRemoved, { userId: data.userId });
+      break;
+    }
+
+    case GatewayDispatch.SessionRevoked: {
+      client.emit(Events.SessionRevoked, { sessionId: data.sessionId });
+      break;
+    }
+
+    case GatewayDispatch.VoicePeerJoined: {
+      client.emit(Events.VoicePeerJoin, new VoiceState(client, data));
+      break;
+    }
+
+    case GatewayDispatch.VoicePeerLeft: {
+      client.emit(Events.VoicePeerLeave, { socketId: data.socketId });
+      break;
+    }
+
+    case GatewayDispatch.VoicePeerState: {
+      client.emit(Events.VoicePeerUpdate, new VoiceState(client, data));
+      break;
+    }
+
+    case GatewayDispatch.VoiceRoomState: {
+      client.emit(Events.VoiceRoomState, {
+        roomId: data.roomId,
+        users: (data.users ?? []).map((u) => new VoiceState(client, { ...u, roomId: data.roomId })),
+      });
+      break;
+    }
+
+    case GatewayDispatch.VoiceSignal: {
+      client.emit(Events.VoiceSignal, data);
+      break;
+    }
+
+    default:
+      // Unknown event — already surfaced via the `raw` event above.
+      break;
+  }
+}
+
+/** Finds a cached message in its owning channel, if both are cached. */
+function findCachedMessage(client, ref) {
+  if (ref.roomId) {
+    const room = client.channels.cache.get(ref.roomId);
+    if (room) return room.messages.cache.get(ref.id) ?? null;
+  }
+  if (ref.dmChannelId) {
+    const dm = client.dms.cache.get(ref.dmChannelId);
+    if (dm) return dm.messages.cache.get(ref.id) ?? null;
+  }
+  return null;
+}
+
+/** Removes a cached message from its owning channel. */
+function removeCachedMessage(client, ref) {
+  if (ref.roomId) client.channels.cache.get(ref.roomId)?.messages.cache.delete(ref.id);
+  if (ref.dmChannelId) client.dms.cache.get(ref.dmChannelId)?.messages.cache.delete(ref.id);
+}
+
+export default handleDispatch;

package/src/index.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * glade.js — a Node.js library for the Glade (glade.chat) API and realtime gateway.
+ * @module glade.js
+ */
+
+// --- Core ---
+export { Client } from './client/Client.js';
+export { REST } from './rest/REST.js';
+export { Gateway } from './gateway/Gateway.js';
+export { Routes } from './rest/Routes.js';
+
+// --- Structures ---
+export { Base } from './structures/Base.js';
+export { User } from './structures/User.js';
+export { ClientUser } from './structures/ClientUser.js';
+export { House } from './structures/House.js';
+export { Room, TextRoom, VoiceRoom, PortalRoom, createRoom } from './structures/Room.js';
+export { Message } from './structures/Message.js';
+export { Member } from './structures/Member.js';
+export { Role } from './structures/Role.js';
+export { DMChannel } from './structures/DMChannel.js';
+export { Invite } from './structures/Invite.js';
+export { ReactionGroup } from './structures/ReactionGroup.js';
+export { VoiceState } from './structures/VoiceState.js';
+
+// --- Managers ---
+export { CachedManager } from './managers/CachedManager.js';
+export { HouseManager } from './managers/HouseManager.js';
+export { ChannelManager } from './managers/ChannelManager.js';
+export { RoomManager } from './managers/RoomManager.js';
+export { UserManager } from './managers/UserManager.js';
+export { MessageManager } from './managers/MessageManager.js';
+export { MemberManager } from './managers/MemberManager.js';
+export { RoleManager } from './managers/RoleManager.js';
+export { DMManager } from './managers/DMManager.js';
+export { FriendManager } from './managers/FriendManager.js';
+export { InviteManager } from './managers/InviteManager.js';
+
+// --- Utilities ---
+export { Collection } from './util/Collection.js';
+export {
+  PermissionsBitField,
+  PermissionFlags,
+  ALL_PERMISSIONS,
+  DEFAULT_EVERYONE,
+  CHANNEL_OVERRIDABLE,
+} from './util/Permissions.js';
+export {
+  Events,
+  GatewayDispatch,
+  GatewayCommand,
+  RoomTypes,
+  PresenceStatus,
+  FriendStatus,
+  DefaultOptions,
+  REFRESH_COOKIE,
+} from './util/Constants.js';
+export * from './util/Util.js';
+
+// --- Errors ---
+export { GladeError, GladeAPIError, GladeGatewayError } from './errors/index.js';
+
+/** The installed glade.js version. */
+export const version = '0.1.0';

package/src/managers/CachedManager.js

@@ -0,0 +1,95 @@
+'use strict';
+
+import { Collection } from '../util/Collection.js';
+import { resolveId } from '../util/Util.js';
+
+/**
+ * Base class for all managers. Holds a {@link Collection} cache of structures and
+ * provides shared add/resolve helpers. Subclasses set {@link CachedManager#holds}
+ * and may override {@link CachedManager#_create} for structures needing extra
+ * constructor context.
+ * @abstract
+ */
+export class CachedManager {
+  /**
+   * @param {import('../client/Client.js').Client} client
+   * @param {Function} holds The structure class this manager caches.
+   */
+  constructor(client, holds) {
+    /**
+     * @type {import('../client/Client.js').Client}
+     * @readonly
+     */
+    Object.defineProperty(this, 'client', { value: client });
+    /**
+     * The structure class this manager holds.
+     * @type {Function}
+     */
+    Object.defineProperty(this, 'holds', { value: holds });
+    /**
+     * The cache of structures, keyed by id.
+     * @type {Collection<string, any>}
+     */
+    this.cache = new Collection();
+  }
+
+  /**
+   * Instantiates a new structure from raw data. Override when the structure needs
+   * more than `(client, data)`.
+   * @param {any} data
+   * @returns {any}
+   * @protected
+   */
+  _create(data) {
+    return new this.holds(this.client, data);
+  }
+
+  /**
+   * Adds raw data to the cache, patching an existing entry if present.
+   * @param {any} data
+   * @param {boolean} [cache=true] Whether to store the result in the cache.
+   * @returns {any} The cached/created structure.
+   * @protected
+   */
+  _add(data, cache = true) {
+    const id = data.id;
+    const existing = id != null ? this.cache.get(id) : undefined;
+    if (existing) {
+      existing._patch(data);
+      return existing;
+    }
+    const entry = this._create(data);
+    if (cache && this.client.options.cache && entry.id != null) {
+      this.cache.set(entry.id, entry);
+    }
+    return entry;
+  }
+
+  /**
+   * Resolves a value to a cached structure.
+   * @param {string | { id: string }} idOrInstance
+   * @returns {any | null}
+   */
+  resolve(idOrInstance) {
+    if (idOrInstance instanceof this.holds) return idOrInstance;
+    if (typeof idOrInstance === 'string') return this.cache.get(idOrInstance) ?? null;
+    if (idOrInstance?.id) return this.cache.get(idOrInstance.id) ?? null;
+    return null;
+  }
+
+  /**
+   * Resolves a value to an id.
+   * @param {string | { id: string }} idOrInstance
+   * @returns {string}
+   */
+  resolveId(idOrInstance) {
+    return resolveId(idOrInstance);
+  }
+
+  /** Iterates the cache values. */
+  [Symbol.iterator]() {
+    return this.cache.values();
+  }
+}
+
+export default CachedManager;

package/src/managers/ChannelManager.js

@@ -0,0 +1,40 @@
+'use strict';
+
+import { CachedManager } from './CachedManager.js';
+import { Room } from '../structures/Room.js';
+
+/**
+ * The client-wide cache of rooms (channels) across every House the client is in.
+ * Rooms are added here by each House's {@link RoomManager}. There is no single-room
+ * REST endpoint, so {@link ChannelManager#fetch} resolves a room by fetching its
+ * House's rooms when necessary.
+ * @extends {CachedManager}
+ */
+export class ChannelManager extends CachedManager {
+  constructor(client) {
+    super(client, Room);
+  }
+
+  /**
+   * Resolves a room by id from the cache, fetching its House's rooms if needed.
+   * @param {string} id
+   * @param {{ force?: boolean }} [options]
+   * @returns {Promise<Room | null>}
+   */
+  async fetch(id, { force = false } = {}) {
+    if (!force && this.cache.has(id)) return this.cache.get(id);
+    // Find which cached House owns it, then refresh that House's rooms.
+    const cached = this.cache.get(id);
+    const houseId = cached?.houseId;
+    if (houseId) {
+      const house = this.client.houses.cache.get(houseId);
+      if (house) {
+        await house.rooms.fetch();
+        return this.cache.get(id) ?? null;
+      }
+    }
+    return this.cache.get(id) ?? null;
+  }
+}
+
+export default ChannelManager;

package/src/managers/DMManager.js

@@ -0,0 +1,43 @@
+'use strict';
+
+import { CachedManager } from './CachedManager.js';
+import { DMChannel } from '../structures/DMChannel.js';
+import { Routes } from '../rest/Routes.js';
+import { resolveId } from '../util/Util.js';
+
+/**
+ * Manages the client's direct-message channels.
+ * @extends {CachedManager}
+ */
+export class DMManager extends CachedManager {
+  constructor(client) {
+    super(client, DMChannel);
+  }
+
+  /**
+   * Fetches all of the client's DM channels.
+   * @returns {Promise<import('../util/Collection.js').Collection<string, DMChannel>>}
+   */
+  async fetch() {
+    const { dms } = await this.client.rest.get(Routes.dms());
+    for (const dm of dms) this._add(dm);
+    return this.cache;
+  }
+
+  /**
+   * Opens (or returns the existing) DM channel with a user.
+   * @param {string | import('../structures/User.js').User} user
+   * @returns {Promise<DMChannel>}
+   */
+  async create(user) {
+    const userId = resolveId(user);
+    const { dm } = await this.client.rest.post(Routes.dms(), { userId });
+    const channel = this._add({ id: dm.id });
+    // The REST response only carries the channel id; remember the recipient.
+    if (!channel.participantIds.includes(userId)) channel.participantIds.push(userId);
+    if (typeof user === 'object') this.client.users._add(user);
+    return channel;
+  }
+}
+
+export default DMManager;