@glade-chat/glade.js 0.1.0

package/src/structures/Role.js

@@ -0,0 +1,107 @@
+'use strict';
+
+import { Base } from './Base.js';
+import { Routes } from '../rest/Routes.js';
+import { PermissionsBitField } from '../util/Permissions.js';
+
+/**
+ * Represents a role in a House.
+ * @extends {Base}
+ */
+export class Role extends Base {
+  constructor(client, data) {
+    super(client);
+    /** @type {string} The role id. */
+    this.id = data.id;
+    this._patch(data);
+  }
+
+  _patch(data) {
+    if ('houseId' in data) {
+      /** @type {string} Id of the House this role belongs to. */
+      this.houseId = data.houseId;
+    }
+    if ('name' in data) {
+      /** @type {string} The role name. */
+      this.name = data.name;
+    }
+    if ('color' in data) {
+      /** @type {string | null} The role color. */
+      this.color = data.color ?? null;
+    }
+    if ('permissions' in data) {
+      /** @type {PermissionsBitField} The role's permission bitfield. */
+      this.permissions = new PermissionsBitField(data.permissions ?? 0);
+    }
+    if ('position' in data) {
+      /** @type {number} The role's sort position. */
+      this.position = data.position ?? 0;
+    }
+    if ('isDefault' in data) {
+      /** @type {boolean} Whether this is the `@everyone` role. */
+      this.isDefault = Boolean(data.isDefault);
+    }
+    if ('hoist' in data) {
+      /** @type {boolean} Whether members with this role show in their own list section. */
+      this.hoist = Boolean(data.hoist);
+    }
+    return data;
+  }
+
+  /** The House this role belongs to, if cached. */
+  get house() {
+    return this.client.houses.cache.get(this.houseId) ?? null;
+  }
+
+  /**
+   * Edits this role.
+   * @param {{ name?: string, color?: string | null, permissions?: import('../util/Permissions.js').PermissionResolvable, hoist?: boolean }} data
+   * @returns {Promise<Role>}
+   */
+  async edit(data) {
+    const body = { ...data };
+    if (data.permissions !== undefined) body.permissions = PermissionsBitField.resolve(data.permissions);
+    const { role } = await this.client.rest.patch(Routes.role(this.id), body);
+    this._patch(role);
+    return this;
+  }
+
+  /** Sets the role name. */
+  setName(name) {
+    return this.edit({ name });
+  }
+
+  /** Sets the role color. */
+  setColor(color) {
+    return this.edit({ color });
+  }
+
+  /**
+   * Sets the role's permissions.
+   * @param {import('../util/Permissions.js').PermissionResolvable} permissions
+   * @returns {Promise<Role>}
+   */
+  setPermissions(permissions) {
+    return this.edit({ permissions });
+  }
+
+  /** Sets whether the role is hoisted. */
+  setHoist(hoist) {
+    return this.edit({ hoist });
+  }
+
+  /**
+   * Deletes this role.
+   * @returns {Promise<void>}
+   */
+  async delete() {
+    await this.client.rest.delete(Routes.role(this.id));
+    this.house?.roles.cache.delete(this.id);
+  }
+
+  toString() {
+    return this.name;
+  }
+}
+
+export default Role;

package/src/structures/Room.js

@@ -0,0 +1,264 @@
+'use strict';
+
+import { Base } from './Base.js';
+import { Routes } from '../rest/Routes.js';
+import { MessageManager } from '../managers/MessageManager.js';
+import { PermissionsBitField } from '../util/Permissions.js';
+import { RoomTypes } from '../util/Constants.js';
+import { resolveId } from '../util/Util.js';
+
+/**
+ * Base class for a Glade room (channel) inside a House.
+ * @extends {Base}
+ */
+export class Room extends Base {
+  constructor(client, data) {
+    super(client);
+    /** @type {string} The room id. */
+    this.id = data.id;
+    /** @type {MessageManager} Cache + helpers for this room's messages. */
+    this.messages = new MessageManager(client, this);
+    this._patch(data);
+  }
+
+  _patch(data) {
+    if ('houseId' in data) {
+      /** @type {string} Id of the House this room belongs to. */
+      this.houseId = data.houseId;
+    }
+    if ('name' in data) {
+      /** @type {string} The room name. */
+      this.name = data.name;
+    }
+    if ('type' in data) {
+      /** @type {string} The room type: text | voice | portal. */
+      this.type = data.type;
+    }
+    if ('topic' in data) {
+      /** @type {string | null} The room topic. */
+      this.topic = data.topic ?? null;
+    }
+    if ('position' in data) {
+      /** @type {number} The room's sort position. */
+      this.position = data.position ?? 0;
+    }
+    if ('createdAt' in data) {
+      /** @type {string | null} ISO creation timestamp. */
+      this.createdAt = data.createdAt ?? null;
+    }
+    return data;
+  }
+
+  /** Whether this is a text room. */
+  isText() {
+    return this.type === RoomTypes.Text;
+  }
+  /** Whether this is a voice room. */
+  isVoice() {
+    return this.type === RoomTypes.Voice;
+  }
+  /** Whether this is a portal room. */
+  isPortal() {
+    return this.type === RoomTypes.Portal;
+  }
+
+  /** The House this room belongs to, if cached. */
+  get house() {
+    return this.client.houses.cache.get(this.houseId) ?? null;
+  }
+
+  /**
+   * Sends a message to this room.
+   * @param {string | import('../managers/MessageManager.js').MessagePayload} content
+   * @returns {Promise<import('./Message.js').Message>}
+   */
+  send(content) {
+    return this.client._sendMessage({ roomId: this.id }, content);
+  }
+
+  /**
+   * Subscribes the gateway connection to this room so it receives the room's
+   * realtime events (`messageCreate`, typing, reactions, pins, …). The client
+   * auto-subscribes cached rooms on ready unless `autoSubscribeRooms` is disabled.
+   * @returns {this}
+   */
+  subscribe() {
+    this.client.gateway.send('room:join', this.id);
+    return this;
+  }
+
+  /**
+   * Unsubscribes the gateway connection from this room's realtime events.
+   * @returns {this}
+   */
+  unsubscribe() {
+    this.client.gateway.send('room:leave', this.id);
+    return this;
+  }
+
+  /** Broadcasts a "typing…" indicator to the room. */
+  sendTyping() {
+    this.client.gateway.send('typing:start', { roomId: this.id });
+    return this;
+  }
+
+  /** Stops the "typing…" indicator. */
+  stopTyping() {
+    this.client.gateway.send('typing:stop', { roomId: this.id });
+    return this;
+  }
+
+  /**
+   * Fetches a page of messages.
+   * @param {{ cursor?: string, limit?: number }} [options]
+   * @returns {Promise<{ messages: import('./Message.js').Message[], nextCursor: string | null }>}
+   */
+  fetchMessages(options) {
+    return this.messages.fetch(options);
+  }
+
+  /** Fetches this room's pinned messages. */
+  fetchPins() {
+    return this.messages.fetchPins();
+  }
+
+  /**
+   * Edits this room.
+   * @param {{ name?: string, topic?: string | null }} data
+   * @returns {Promise<Room>}
+   */
+  async edit(data) {
+    const { room } = await this.client.rest.patch(Routes.room(this.id), data);
+    this._patch(room);
+    return this;
+  }
+
+  /** Sets the room name. */
+  setName(name) {
+    return this.edit({ name });
+  }
+
+  /** Sets the room topic (or null to clear). */
+  setTopic(topic) {
+    return this.edit({ topic });
+  }
+
+  /**
+   * Clones this room's settings into a new room (messages are not copied).
+   * @returns {Promise<Room>}
+   */
+  async clone() {
+    const { room } = await this.client.rest.post(Routes.roomClone(this.id));
+    return this.house ? this.house.rooms._add(room) : new Room(this.client, room);
+  }
+
+  /**
+   * Deletes this room.
+   * @returns {Promise<void>}
+   */
+  async delete() {
+    await this.client.rest.delete(Routes.room(this.id));
+    this.house?.rooms.cache.delete(this.id);
+    this.client.channels.cache.delete(this.id);
+  }
+
+  /**
+   * Lists this room's per-role permission overrides.
+   * @returns {Promise<Array<{ id: string, roomId: string, roleId: string, allow: number, deny: number }>>}
+   */
+  async fetchPermissionOverrides() {
+    const { permissions } = await this.client.rest.get(Routes.roomPermissions(this.id));
+    return permissions;
+  }
+
+  /**
+   * Sets (or clears) a role's permission override on this room. Pass `allow: 0, deny: 0` to clear.
+   * @param {string | import('./Role.js').Role} role
+   * @param {{ allow?: import('../util/Permissions.js').PermissionResolvable, deny?: import('../util/Permissions.js').PermissionResolvable }} options
+   * @returns {Promise<void>}
+   */
+  async setPermissionOverride(role, { allow = 0, deny = 0 } = {}) {
+    await this.client.rest.put(Routes.roomPermission(this.id, resolveId(role)), {
+      allow: PermissionsBitField.resolve(allow),
+      deny: PermissionsBitField.resolve(deny),
+    });
+  }
+
+  toString() {
+    return this.name;
+  }
+}
+
+/**
+ * A text room.
+ * @extends {Room}
+ */
+export class TextRoom extends Room {}
+
+/**
+ * A portal room.
+ * @extends {Room}
+ */
+export class PortalRoom extends Room {}
+
+/**
+ * A voice room. Adds WebRTC-mesh signaling helpers; actual audio transport is up
+ * to the consumer (the gateway only relays SDP/ICE between peers).
+ * @extends {Room}
+ */
+export class VoiceRoom extends Room {
+  /**
+   * Joins this voice room. Resolves with the current peers, so the caller can
+   * begin WebRTC negotiation. Listen for `voicePeerJoin` / `voiceSignal` etc.
+   * @returns {Promise<{ selfSocketId: string, participants: Array<{ socketId: string, userId: string, muted: boolean }> }>}
+   */
+  async join() {
+    const ack = await this.client.gateway.request('voice:join', this.id);
+    return { selfSocketId: ack.selfSocketId, participants: ack.participants ?? [] };
+  }
+
+  /** Leaves this voice room. */
+  leave() {
+    this.client.gateway.send('voice:leave', this.id);
+    return this;
+  }
+
+  /**
+   * Updates the client's mute/deafen state within this voice room.
+   * @param {{ muted: boolean, deafened?: boolean }} state
+   */
+  setVoiceState(state) {
+    this.client.gateway.send('voice:state', { roomId: this.id, ...state });
+    return this;
+  }
+
+  /**
+   * Relays a WebRTC signaling payload (SDP offer/answer or ICE candidate) to a peer.
+   * @param {string} toSocketId
+   * @param {any} data
+   */
+  signal(toSocketId, data) {
+    this.client.gateway.send('voice:signal', { toSocketId, data });
+    return this;
+  }
+}
+
+/**
+ * Instantiates the correct {@link Room} subclass for the given raw data.
+ * @param {import('../client/Client.js').Client} client
+ * @param {any} data
+ * @returns {Room}
+ */
+export function createRoom(client, data) {
+  switch (data.type) {
+    case RoomTypes.Voice:
+      return new VoiceRoom(client, data);
+    case RoomTypes.Portal:
+      return new PortalRoom(client, data);
+    case RoomTypes.Text:
+    default:
+      return new TextRoom(client, data);
+  }
+}
+
+export default Room;

package/src/structures/User.js

@@ -0,0 +1,113 @@
+'use strict';
+
+import { Base } from './Base.js';
+
+/**
+ * Represents a Glade user. Built from the backend's "public user" shape; message
+ * authors carry a reduced set of fields (id, handle, displayName, avatarUrl, bot).
+ * @extends {Base}
+ */
+export class User extends Base {
+  constructor(client, data) {
+    super(client);
+    /** @type {string} The user's unique id. */
+    this.id = data.id;
+    this._patch(data);
+  }
+
+  _patch(data) {
+    if ('handle' in data) {
+      /** @type {string} The user's unique @handle. */
+      this.handle = data.handle;
+    }
+    if ('displayName' in data) {
+      /** @type {string} The user's chosen display name. */
+      this.displayName = data.displayName;
+    }
+    if ('avatarUrl' in data) {
+      /** @type {string | null} URL of the user's avatar, if set. */
+      this.avatarUrl = data.avatarUrl ?? null;
+    }
+    if ('bannerUrl' in data) {
+      /** @type {string | null} URL of the user's profile banner, if set. */
+      this.bannerUrl = data.bannerUrl ?? null;
+    }
+    if ('bio' in data) {
+      /** @type {string | null} The user's bio. */
+      this.bio = data.bio ?? null;
+    }
+    if ('status' in data) {
+      /** @type {string} The user's presence status (online | idle | dnd | offline). */
+      this.status = data.status ?? 'offline';
+    }
+    // The profile endpoint (GET /users/:id) carries the authoritative *live*
+    // presence under `presence`, alongside the stored `status` — prefer it.
+    if ('presence' in data) {
+      this.status = data.presence ?? this.status ?? 'offline';
+    }
+    if ('isBot' in data) {
+      /** @type {boolean} Whether this account is a bot. */
+      this.bot = Boolean(data.isBot);
+    }
+    if ('badges' in data) {
+      /** @type {string[]} Cosmetic badge ids granted to the user. */
+      this.badges = data.badges ?? [];
+    }
+    if ('publicKey' in data) {
+      /** @type {string | null} The user's E2E identity public key (base64 SPKI). */
+      this.publicKey = data.publicKey ?? null;
+    }
+    if ('twoFactorEnabled' in data) {
+      /** @type {boolean} Whether the user has two-factor enabled. */
+      this.twoFactorEnabled = Boolean(data.twoFactorEnabled);
+    }
+    if ('createdAt' in data) {
+      /**
+       * ISO timestamp of when the account was created.
+       * @type {string | null}
+       * @remarks Only the profile endpoint (`users.fetch(id)`) returns this; the
+       * self/auth payloads omit it, so `client.user.createdAt` may be `null`.
+       */
+      this.createdAt = data.createdAt ?? null;
+    }
+    return data;
+  }
+
+  /** The `@handle` form, suitable for mentions in message content. */
+  get tag() {
+    return `@${this.handle}`;
+  }
+
+  /**
+   * Opens (or fetches the existing) DM channel with this user.
+   * @returns {Promise<import('./DMChannel.js').DMChannel>}
+   */
+  createDM() {
+    return this.client.dms.create(this.id);
+  }
+
+  /**
+   * Sends a direct message to this user, opening a DM channel if necessary.
+   * @param {string | import('../managers/MessageManager.js').MessagePayload} content
+   * @returns {Promise<import('./Message.js').Message>}
+   */
+  async send(content) {
+    const dm = await this.createDM();
+    return dm.send(content);
+  }
+
+  /**
+   * Re-fetches this user's full profile from the API.
+   * @returns {Promise<User>}
+   */
+  fetch() {
+    return this.client.users.fetch(this.id, { force: true });
+  }
+
+  /** Mentions the user (`@handle`). */
+  toString() {
+    return this.tag;
+  }
+}
+
+export default User;

package/src/structures/VoiceState.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/**
+ * A lightweight snapshot of a user's state inside a voice room, as reported by the
+ * gateway's voice occupancy / peer events.
+ */
+export class VoiceState {
+  /**
+   * @param {import('../client/Client.js').Client} client
+   * @param {{ userId: string, muted?: boolean, deafened?: boolean, socketId?: string, roomId?: string }} data
+   */
+  constructor(client, data) {
+    Object.defineProperty(this, 'client', { value: client });
+    /** @type {string} Id of the user this state describes. */
+    this.userId = data.userId;
+    /** @type {string | null} Id of the voice room, if known. */
+    this.roomId = data.roomId ?? null;
+    /** @type {string | null} The peer's socket id, for per-peer events. */
+    this.socketId = data.socketId ?? null;
+    /** @type {boolean} Whether the user is muted. */
+    this.muted = Boolean(data.muted);
+    /** @type {boolean} Whether the user is deafened. */
+    this.deafened = Boolean(data.deafened);
+  }
+
+  /** The {@link User} this state belongs to, if cached. */
+  get user() {
+    return this.client.users.cache.get(this.userId) ?? null;
+  }
+
+  toJSON() {
+    return {
+      userId: this.userId,
+      roomId: this.roomId,
+      socketId: this.socketId,
+      muted: this.muted,
+      deafened: this.deafened,
+    };
+  }
+}
+
+export default VoiceState;

package/src/util/Collection.js

@@ -0,0 +1,167 @@
+'use strict';
+
+/**
+ * A `Map` with additional utility methods, used throughout glade.js to hold
+ * cached structures keyed by their id.
+ *
+ * @template K, V
+ * @extends {Map<K, V>}
+ */
+export class Collection extends Map {
+  /**
+   * Obtains the first value(s) in this collection.
+   * @param {number} [amount] How many values to return; negative counts from the end.
+   * @returns {V | V[] | undefined}
+   */
+  first(amount) {
+    if (amount === undefined) return this.values().next().value;
+    if (amount < 0) return this.last(amount * -1);
+    amount = Math.min(this.size, amount);
+    const iter = this.values();
+    return Array.from({ length: amount }, () => iter.next().value);
+  }
+
+  /**
+   * Obtains the last value(s) in this collection.
+   * @param {number} [amount]
+   * @returns {V | V[] | undefined}
+   */
+  last(amount) {
+    const arr = [...this.values()];
+    if (amount === undefined) return arr[arr.length - 1];
+    if (amount < 0) return this.first(amount * -1);
+    if (!amount) return [];
+    return arr.slice(-amount);
+  }
+
+  /**
+   * Returns a random value.
+   * @returns {V | undefined}
+   */
+  random() {
+    const arr = [...this.values()];
+    return arr[Math.floor(Math.random() * arr.length)];
+  }
+
+  /**
+   * Searches for a single item where the given function returns a truthy value.
+   * @param {(value: V, key: K, collection: this) => boolean} fn
+   * @returns {V | undefined}
+   */
+  find(fn) {
+    for (const [key, val] of this) if (fn(val, key, this)) return val;
+    return undefined;
+  }
+
+  /**
+   * Searches for the key of a single item where the given function returns a truthy value.
+   * @param {(value: V, key: K, collection: this) => boolean} fn
+   * @returns {K | undefined}
+   */
+  findKey(fn) {
+    for (const [key, val] of this) if (fn(val, key, this)) return key;
+    return undefined;
+  }
+
+  /**
+   * Identical to `Array.filter()` but returns a new Collection.
+   * @param {(value: V, key: K, collection: this) => boolean} fn
+   * @returns {Collection<K, V>}
+   */
+  filter(fn) {
+    const results = new this.constructor[Symbol.species]();
+    for (const [key, val] of this) if (fn(val, key, this)) results.set(key, val);
+    return results;
+  }
+
+  /**
+   * Maps each item to something else into an array, like `Array.map()`.
+   * @template T
+   * @param {(value: V, key: K, collection: this) => T} fn
+   * @returns {T[]}
+   */
+  map(fn) {
+    const out = [];
+    let i = 0;
+    for (const [key, val] of this) out[i++] = fn(val, key, this);
+    return out;
+  }
+
+  /**
+   * Checks if there exists an item that passes a test.
+   * @param {(value: V, key: K, collection: this) => boolean} fn
+   * @returns {boolean}
+   */
+  some(fn) {
+    for (const [key, val] of this) if (fn(val, key, this)) return true;
+    return false;
+  }
+
+  /**
+   * Checks if all items pass a test.
+   * @param {(value: V, key: K, collection: this) => boolean} fn
+   * @returns {boolean}
+   */
+  every(fn) {
+    for (const [key, val] of this) if (!fn(val, key, this)) return false;
+    return true;
+  }
+
+  /**
+   * Applies a function to produce a single value, like `Array.reduce()`.
+   * @template T
+   * @param {(accumulator: T, value: V, key: K, collection: this) => T} fn
+   * @param {T} [initial]
+   * @returns {T}
+   */
+  reduce(fn, initial) {
+    let accumulator = initial;
+    let first = accumulator === undefined;
+    for (const [key, val] of this) {
+      if (first) {
+        accumulator = val;
+        first = false;
+        continue;
+      }
+      accumulator = fn(accumulator, val, key, this);
+    }
+    if (first) throw new TypeError('Reduce of empty collection with no initial value');
+    return accumulator;
+  }
+
+  /**
+   * Identical to `Map.forEach()` but returns the collection for chaining.
+   * @param {(value: V, key: K, collection: this) => void} fn
+   * @returns {this}
+   */
+  each(fn) {
+    for (const [key, val] of this) fn(val, key, this);
+    return this;
+  }
+
+  /**
+   * Returns the items that pass the test as an array.
+   * @returns {V[]}
+   */
+  toArray() {
+    return [...this.values()];
+  }
+
+  /**
+   * Returns the keys as an array.
+   * @returns {K[]}
+   */
+  keyArray() {
+    return [...this.keys()];
+  }
+
+  /**
+   * Creates an identical shallow copy of this collection.
+   * @returns {Collection<K, V>}
+   */
+  clone() {
+    return new this.constructor[Symbol.species](this);
+  }
+}
+
+export default Collection;