@glade-chat/glade.js 0.1.0

package/src/structures/House.js

@@ -0,0 +1,171 @@
+'use strict';
+
+import { Base } from './Base.js';
+import { Routes } from '../rest/Routes.js';
+import { RoomManager } from '../managers/RoomManager.js';
+import { MemberManager } from '../managers/MemberManager.js';
+import { RoleManager } from '../managers/RoleManager.js';
+import { InviteManager } from '../managers/InviteManager.js';
+
+/**
+ * Represents a Glade House — a community, analogous to a server/guild. Holds the
+ * House's rooms, members, roles, and invites.
+ * @extends {Base}
+ */
+export class House extends Base {
+  constructor(client, data) {
+    super(client);
+    /** @type {string} The House id. */
+    this.id = data.id;
+
+    /** @type {RoomManager} Manager for the House's rooms (channels). */
+    this.rooms = new RoomManager(client, this);
+    /** @type {MemberManager} Manager for the House's members. */
+    this.members = new MemberManager(client, this);
+    /** @type {RoleManager} Manager for the House's roles. */
+    this.roles = new RoleManager(client, this);
+    /** @type {InviteManager} Manager for the House's invites. */
+    this.invites = new InviteManager(client, this);
+
+    this._patch(data);
+  }
+
+  _patch(data) {
+    if ('name' in data) {
+      /** @type {string} The House name. */
+      this.name = data.name;
+    }
+    if ('iconUrl' in data) {
+      /** @type {string | null} URL of the House icon. */
+      this.iconUrl = data.iconUrl ?? null;
+    }
+    if ('accent' in data) {
+      /** @type {string | null} The House accent color. */
+      this.accent = data.accent ?? null;
+    }
+    if ('ownerId' in data) {
+      /** @type {string} Id of the House owner. */
+      this.ownerId = data.ownerId;
+    }
+    if ('createdAt' in data) {
+      /** @type {string | null} ISO creation timestamp. */
+      this.createdAt = data.createdAt ?? null;
+    }
+    if (Array.isArray(data.rooms)) {
+      for (const room of data.rooms) this.rooms._add(room);
+    }
+    return data;
+  }
+
+  /** The owner of this House, if cached. */
+  get owner() {
+    return this.client.users.cache.get(this.ownerId) ?? null;
+  }
+
+  /** Whether the logged-in account owns this House. */
+  get isOwner() {
+    return this.client.user?.id === this.ownerId;
+  }
+
+  /**
+   * Edits this House.
+   * @param {{ name?: string, iconUrl?: string | null }} data
+   * @returns {Promise<House>}
+   */
+  async edit(data) {
+    const { house } = await this.client.rest.patch(Routes.house(this.id), data);
+    this._patch(house);
+    return this;
+  }
+
+  /** Sets the House name. */
+  setName(name) {
+    return this.edit({ name });
+  }
+
+  /** Sets the House icon URL (or null to clear). */
+  setIcon(iconUrl) {
+    return this.edit({ iconUrl });
+  }
+
+  /**
+   * Permanently deletes this House. Owner only.
+   * @returns {Promise<void>}
+   */
+  async delete() {
+    await this.client.rest.delete(Routes.house(this.id));
+    this.client.houses.cache.delete(this.id);
+  }
+
+  /**
+   * Leaves this House.
+   * @returns {Promise<void>}
+   */
+  async leave() {
+    await this.client.rest.post(Routes.houseLeave(this.id));
+    this.client.houses.cache.delete(this.id);
+  }
+
+  /**
+   * Creates a room (channel) in this House.
+   * @param {string} name
+   * @param {{ type?: 'text' | 'voice' | 'portal' }} [options]
+   * @returns {Promise<import('./Room.js').Room>}
+   */
+  createRoom(name, options = {}) {
+    return this.rooms.create(name, options);
+  }
+
+  /**
+   * Creates a role in this House.
+   * @param {object} data
+   * @returns {Promise<import('./Role.js').Role>}
+   */
+  createRole(data) {
+    return this.roles.create(data);
+  }
+
+  /**
+   * Creates an invite to this House.
+   * @param {{ expiresInMinutes?: number | null, maxUses?: number | null }} [options]
+   * @returns {Promise<import('./Invite.js').Invite>}
+   */
+  createInvite(options = {}) {
+    return this.invites.create(options);
+  }
+
+  /** Fetches and caches all members. */
+  fetchMembers() {
+    return this.members.fetch();
+  }
+
+  /** Fetches and caches all rooms. */
+  fetchRooms() {
+    return this.rooms.fetch();
+  }
+
+  /** Fetches and caches all roles. */
+  fetchRoles() {
+    return this.roles.fetch();
+  }
+
+  /** Fetches all active invites for this House. */
+  fetchInvites() {
+    return this.invites.fetch();
+  }
+
+  /**
+   * Fetches current voice-room occupancy for this House over the gateway.
+   * @returns {Promise<Array<{ roomId: string, users: Array<{ userId: string, muted: boolean, deafened: boolean }> }>>}
+   */
+  async fetchVoiceStates() {
+    const ack = await this.client.gateway.request('voice:sync', this.id);
+    return ack?.states ?? [];
+  }
+
+  toString() {
+    return this.name;
+  }
+}
+
+export default House;

package/src/structures/Invite.js

@@ -0,0 +1,83 @@
+'use strict';
+
+import { Base } from './Base.js';
+import { Routes } from '../rest/Routes.js';
+
+/**
+ * Represents an invite to a House. Depending on where it came from, some fields
+ * may be absent (e.g. a previewed invite has no `id`, so it cannot be revoked).
+ * @extends {Base}
+ */
+export class Invite extends Base {
+  constructor(client, data) {
+    super(client);
+    this._patch(data);
+  }
+
+  _patch(data) {
+    if ('id' in data) {
+      /** @type {string | undefined} The invite id (present when listed/created). */
+      this.id = data.id;
+    }
+    if ('code' in data) {
+      /** @type {string} The invite code. */
+      this.code = data.code;
+    }
+    if ('uses' in data) {
+      /** @type {number | undefined} How many times the invite has been used. */
+      this.uses = data.uses;
+    }
+    if ('maxUses' in data) {
+      /** @type {number | null | undefined} Maximum uses, or null for unlimited. */
+      this.maxUses = data.maxUses ?? null;
+    }
+    if ('expiresAt' in data) {
+      /** @type {string | null} ISO expiry timestamp, or null if it never expires. */
+      this.expiresAt = data.expiresAt ?? null;
+    }
+    if ('createdAt' in data) {
+      /** @type {string | undefined} ISO creation timestamp. */
+      this.createdAt = data.createdAt;
+    }
+    if (data.house) {
+      /** @type {{ id: string, name: string, iconUrl: string | null, accent: string | null } | undefined} Partial House info from a preview. */
+      this.house = data.house;
+      this.houseId = data.house.id;
+    }
+    // From listing: `creator { handle, displayName }`. From preview: `inviter { handle, displayName }`.
+    if (data.creator || data.inviter) {
+      /** @type {{ handle: string, displayName: string }} The user who created the invite. */
+      this.inviter = data.creator ?? data.inviter;
+    }
+    return data;
+  }
+
+  /** Whether the invite has expired (based on `expiresAt`). */
+  get expired() {
+    return this.expiresAt ? Date.parse(this.expiresAt) < Date.now() : false;
+  }
+
+  /**
+   * Redeems this invite for the logged-in account, joining the House.
+   * @returns {Promise<import('./House.js').House>}
+   */
+  redeem() {
+    return this.client.redeemInvite(this.code);
+  }
+
+  /**
+   * Revokes (deletes) this invite. Requires the invite `id` (present on listed or
+   * freshly-created invites).
+   * @returns {Promise<void>}
+   */
+  async delete() {
+    if (!this.id) throw new Error('This invite has no id and cannot be revoked');
+    await this.client.rest.delete(Routes.inviteRevoke(this.id));
+  }
+
+  toString() {
+    return this.code;
+  }
+}
+
+export default Invite;

package/src/structures/Member.js

@@ -0,0 +1,148 @@
+'use strict';
+
+import { Base } from './Base.js';
+import { Routes } from '../rest/Routes.js';
+import { Collection } from '../util/Collection.js';
+import { PermissionsBitField, ALL_PERMISSIONS, PermissionFlags } from '../util/Permissions.js';
+import { resolveId } from '../util/Util.js';
+
+/**
+ * Represents a member of a House — a user plus their House-specific data (roles,
+ * nickname, presence). The member id equals the underlying user id.
+ * @extends {Base}
+ */
+export class Member extends Base {
+  /**
+   * @param {import('../client/Client.js').Client} client
+   * @param {import('./House.js').House} house
+   * @param {any} data
+   */
+  constructor(client, house, data) {
+    super(client);
+    /** @type {string} The member (and user) id. */
+    this.id = data.id;
+    /** @type {string} Id of the House this membership belongs to. */
+    this.houseId = house.id;
+    this._patch(data);
+  }
+
+  _patch(data) {
+    // Keep the underlying user in the global cache fresh.
+    if ('handle' in data || 'displayName' in data) this.client.users._add(data);
+    if ('nickname' in data) {
+      /**
+       * The member's House nickname, if any.
+       * @type {string | null}
+       * @remarks The current backend members endpoint does not serialize nicknames,
+       * so this is typically `null`; {@link Member#displayName} falls back to the user's.
+       */
+      this.nickname = data.nickname ?? null;
+    } else if (this.nickname === undefined) {
+      this.nickname = null;
+    }
+    if ('roleIds' in data) {
+      /** @type {string[]} Ids of the roles assigned to this member. */
+      this.roleIds = data.roleIds ?? [];
+    } else if (!this.roleIds) {
+      this.roleIds = [];
+    }
+    if ('status' in data) {
+      /** @type {string} The member's current presence status. */
+      this.status = data.status ?? 'offline';
+    }
+    return data;
+  }
+
+  /** The underlying {@link User}, from the user cache. */
+  get user() {
+    return this.client.users.cache.get(this.id) ?? null;
+  }
+
+  /** The House this member belongs to, if cached. */
+  get house() {
+    return this.client.houses.cache.get(this.houseId) ?? null;
+  }
+
+  /** The member's effective display name (nickname falls back to the user's). */
+  get displayName() {
+    return this.nickname ?? this.user?.displayName ?? null;
+  }
+
+  /** Whether this member owns the House. */
+  get isOwner() {
+    return this.house?.ownerId === this.id;
+  }
+
+  /**
+   * The roles assigned to this member (including `@everyone`), resolved from the
+   * House role cache.
+   * @returns {Collection<string, import('./Role.js').Role>}
+   */
+  get roles() {
+    const collection = new Collection();
+    const house = this.house;
+    if (!house) return collection;
+    const everyone = house.roles.cache.find((r) => r.isDefault);
+    if (everyone) collection.set(everyone.id, everyone);
+    for (const id of this.roleIds) {
+      const role = house.roles.cache.get(id);
+      if (role) collection.set(role.id, role);
+    }
+    return collection;
+  }
+
+  /**
+   * The member's computed House-wide permissions. Requires the House's roles to be
+   * cached for non-owners; owners and Administrators resolve to all permissions.
+   * @returns {PermissionsBitField}
+   */
+  get permissions() {
+    if (this.isOwner) return new PermissionsBitField(ALL_PERMISSIONS);
+    let bits = 0;
+    for (const role of this.roles.values()) bits |= role.permissions.bitfield;
+    if (bits & PermissionFlags.Administrator) bits = ALL_PERMISSIONS;
+    return new PermissionsBitField(bits);
+  }
+
+  /**
+   * Replaces this member's (non-default) roles. Requires `ManageRoles`.
+   * @param {Array<string | import('./Role.js').Role>} roles
+   * @returns {Promise<Member>}
+   */
+  async setRoles(roles) {
+    const roleIds = roles.map(resolveId);
+    const result = await this.client.rest.put(
+      Routes.memberRoles(this.houseId, this.id),
+      { roleIds },
+    );
+    this.roleIds = result.roleIds ?? roleIds;
+    return this;
+  }
+
+  /**
+   * Adds one or more roles to this member.
+   * @param {...(string | import('./Role.js').Role)} roles
+   * @returns {Promise<Member>}
+   */
+  addRole(...roles) {
+    const next = new Set(this.roleIds);
+    for (const role of roles) next.add(resolveId(role));
+    return this.setRoles([...next]);
+  }
+
+  /**
+   * Removes one or more roles from this member.
+   * @param {...(string | import('./Role.js').Role)} roles
+   * @returns {Promise<Member>}
+   */
+  removeRole(...roles) {
+    const remove = new Set(roles.map(resolveId));
+    return this.setRoles(this.roleIds.filter((id) => !remove.has(id)));
+  }
+
+  toString() {
+    return this.displayName ?? this.id;
+  }
+}
+
+export default Member;

package/src/structures/Message.js

@@ -0,0 +1,176 @@
+'use strict';
+
+import { Base } from './Base.js';
+import { Routes } from '../rest/Routes.js';
+import { ReactionGroup } from './ReactionGroup.js';
+
+/**
+ * Represents a message in a room or DM channel.
+ * @extends {Base}
+ */
+export class Message extends Base {
+  constructor(client, data) {
+    super(client);
+    /** @type {string} The message id. */
+    this.id = data.id;
+    this._patch(data);
+  }
+
+  _patch(data) {
+    if ('roomId' in data) {
+      /** @type {string | null} Id of the room this message was sent in, if any. */
+      this.roomId = data.roomId ?? null;
+    }
+    if ('dmChannelId' in data) {
+      /** @type {string | null} Id of the DM channel this message was sent in, if any. */
+      this.dmChannelId = data.dmChannelId ?? null;
+    }
+    if ('houseId' in data) {
+      /** @type {string | null} Id of the House the room belongs to (null for DMs). */
+      this.houseId = data.houseId ?? null;
+    }
+    if ('content' in data) {
+      /** @type {string} The message content (may be E2E ciphertext). */
+      this.content = data.content;
+    }
+    if ('clientNonce' in data) {
+      /** @type {string | null} The client nonce echoed back for optimistic dedupe. */
+      this.clientNonce = data.clientNonce ?? null;
+    }
+    if ('pinned' in data) {
+      /** @type {boolean} Whether the message is pinned. */
+      this.pinned = Boolean(data.pinned);
+    }
+    if ('createdAt' in data) {
+      /** @type {string} ISO timestamp of when the message was sent. */
+      this.createdAt = data.createdAt;
+    }
+    if ('editedAt' in data) {
+      /** @type {string | null} ISO timestamp of the last edit, if edited. */
+      this.editedAt = data.editedAt ?? null;
+    }
+    if (data.author) {
+      /** @type {string} Id of the message author. */
+      this.authorId = data.author.id;
+      // Cache/merge the author as a User.
+      this.client.users._add(data.author);
+    }
+    if (Array.isArray(data.reactions)) {
+      /** @type {ReactionGroup[]} Aggregated reactions on this message. */
+      this.reactions = data.reactions.map((r) => new ReactionGroup(this.client, this, r));
+    } else if (!this.reactions) {
+      this.reactions = [];
+    }
+    return data;
+  }
+
+  /** The author of this message, resolved from the user cache. */
+  get author() {
+    return this.client.users.cache.get(this.authorId) ?? null;
+  }
+
+  /** The channel (room or DM) this message belongs to, if cached. */
+  get channel() {
+    if (this.roomId) return this.client.channels.cache.get(this.roomId) ?? null;
+    if (this.dmChannelId) return this.client.dms.cache.get(this.dmChannelId) ?? null;
+    return null;
+  }
+
+  /** The room this message belongs to, if any and cached. */
+  get room() {
+    return this.roomId ? (this.client.channels.cache.get(this.roomId) ?? null) : null;
+  }
+
+  /** Millisecond timestamp of when the message was created. */
+  get createdTimestamp() {
+    return this.createdAt ? Date.parse(this.createdAt) : null;
+  }
+
+  /** Whether the message was edited. */
+  get edited() {
+    return this.editedAt != null;
+  }
+
+  /**
+   * Sends a message to the same channel this message is in.
+   * @param {string | import('../managers/MessageManager.js').MessagePayload} content
+   * @returns {Promise<Message>}
+   */
+  reply(content) {
+    const target = this.roomId ? { roomId: this.roomId } : { dmChannelId: this.dmChannelId };
+    return this.client._sendMessage(target, content);
+  }
+
+  /**
+   * Edits this message (author only). Emits over the gateway; the updated content
+   * is also delivered via `messageUpdate`.
+   * @param {string} content
+   * @returns {Promise<Message>}
+   */
+  async edit(content) {
+    await this.client.gateway.request('message:edit', { messageId: this.id, content });
+    this.content = content;
+    this.editedAt = new Date().toISOString();
+    return this;
+  }
+
+  /**
+   * Deletes this message.
+   * @returns {Promise<Message>}
+   */
+  async delete() {
+    await this.client.gateway.request('message:delete', { messageId: this.id });
+    return this;
+  }
+
+  /**
+   * Pins this message (room messages only). Requires `ManageMessages`.
+   * @returns {Promise<Message>}
+   */
+  async pin() {
+    return this.#setPinned(true);
+  }
+
+  /**
+   * Unpins this message.
+   * @returns {Promise<Message>}
+   */
+  async unpin() {
+    return this.#setPinned(false);
+  }
+
+  async #setPinned(pinned) {
+    if (!this.roomId) throw new Error('Only room messages can be pinned');
+    const { message } = await this.client.rest.post(Routes.roomPin(this.roomId, this.id), {
+      pinned,
+    });
+    this._patch(message);
+    return this;
+  }
+
+  /**
+   * Adds a reaction from the client user.
+   * @param {string} emoji
+   * @returns {Promise<Message>}
+   */
+  async react(emoji) {
+    await this.client.gateway.request('reaction:toggle', { messageId: this.id, emoji, add: true });
+    return this;
+  }
+
+  /**
+   * Removes the client user's reaction.
+   * @param {string} emoji
+   * @returns {Promise<Message>}
+   */
+  async unreact(emoji) {
+    await this.client.gateway.request('reaction:toggle', { messageId: this.id, emoji, add: false });
+    return this;
+  }
+
+  toString() {
+    return this.content;
+  }
+}
+
+export default Message;

package/src/structures/ReactionGroup.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/**
+ * An aggregated reaction on a {@link Message}: one emoji and the users who reacted
+ * with it. Mirrors the backend's `{ emoji, count, userIds }` shape.
+ */
+export class ReactionGroup {
+  /**
+   * @param {import('../client/Client.js').Client} client
+   * @param {import('./Message.js').Message} message
+   * @param {{ emoji: string, count: number, userIds: string[] }} data
+   */
+  constructor(client, message, data) {
+    Object.defineProperty(this, 'client', { value: client });
+    Object.defineProperty(this, 'message', { value: message });
+    /** @type {string} The reaction emoji. */
+    this.emoji = data.emoji;
+    /** @type {number} How many users reacted with this emoji. */
+    this.count = data.count;
+    /** @type {string[]} Ids of the users who reacted. */
+    this.userIds = data.userIds ?? [];
+  }
+
+  /** Whether the logged-in account reacted with this emoji. */
+  get me() {
+    const id = this.client.user?.id;
+    return id ? this.userIds.includes(id) : false;
+  }
+
+  /** The reacting users that are present in the user cache. */
+  get users() {
+    return this.userIds
+      .map((id) => this.client.users.cache.get(id))
+      .filter((u) => Boolean(u));
+  }
+
+  toJSON() {
+    return { emoji: this.emoji, count: this.count, userIds: this.userIds };
+  }
+}
+
+export default ReactionGroup;