@glade-chat/glade.js 0.1.0

package/src/util/Constants.js

@@ -0,0 +1,183 @@
+'use strict';
+
+/**
+ * Default {@link Client} options. The backend URLs default to the public Glade
+ * service; override `rest`/`gateway` to target a self-hosted deployment.
+ */
+export const DefaultOptions = {
+  /** Base origin of the REST API, without the version segment. */
+  rest: 'https://api.glade.chat',
+  /** Origin of the Socket.IO gateway. */
+  gateway: 'https://ws.glade.chat',
+  /** API version path segment. */
+  version: 'v1',
+  /** Whether the REST client should auto-refresh the access token on a 401. */
+  autoRefresh: true,
+  /**
+   * How many ms before the access token's expiry to proactively refresh it.
+   * Keeps a long-running gateway connection authenticated.
+   */
+  refreshSkewMs: 60_000,
+  /** Whether to cache structures received from REST and the gateway. */
+  cache: true,
+  /**
+   * Auto-subscribe to a House room's realtime events by emitting `room:join`.
+   * The server only auto-joins user/house/DM channels on connect, so without this
+   * the client receives no text-room message/typing/reaction events.
+   */
+  autoSubscribeRooms: true,
+  /** Socket.IO client options merged into the gateway connection. */
+  ws: {
+    transports: ['websocket', 'polling'],
+  },
+  /** When true, the client emits verbose `debug` events. */
+  debug: false,
+};
+
+/**
+ * Client-facing event names (camelCase), emitted by {@link Client}.
+ * @enum {string}
+ */
+export const Events = {
+  Ready: 'ready',
+  Debug: 'debug',
+  Error: 'error',
+  Warn: 'warn',
+  Raw: 'raw',
+
+  Connecting: 'connecting',
+  Reconnecting: 'reconnecting',
+  Disconnect: 'disconnect',
+
+  MessageCreate: 'messageCreate',
+  MessageUpdate: 'messageUpdate',
+  MessageDelete: 'messageDelete',
+  MessagePinUpdate: 'messagePinUpdate',
+  MessageReactionUpdate: 'messageReactionUpdate',
+
+  TypingStart: 'typingStart',
+  PresenceUpdate: 'presenceUpdate',
+  Mention: 'mention',
+
+  RoomCreate: 'roomCreate',
+  RoomUpdate: 'roomUpdate',
+  RoomDelete: 'roomDelete',
+  RoomsReorder: 'roomsReorder',
+
+  HouseUpdate: 'houseUpdate',
+  HouseDelete: 'houseDelete',
+  MemberJoin: 'memberJoin',
+  MembersUpdate: 'membersUpdate',
+  RolesUpdate: 'rolesUpdate',
+
+  FriendRequest: 'friendRequest',
+  FriendAccepted: 'friendAccepted',
+  FriendRemoved: 'friendRemoved',
+
+  VoicePeerJoin: 'voicePeerJoin',
+  VoicePeerLeave: 'voicePeerLeave',
+  VoicePeerUpdate: 'voicePeerUpdate',
+  VoiceRoomState: 'voiceRoomState',
+  VoiceSignal: 'voiceSignal',
+
+  SessionRevoked: 'sessionRevoked',
+};
+
+/**
+ * Raw Socket.IO event names the server dispatches to the client (server → client).
+ * @enum {string}
+ */
+export const GatewayDispatch = {
+  Ready: 'ready',
+  MessageNew: 'message:new',
+  MessageUpdated: 'message:updated',
+  MessageDeleted: 'message:deleted',
+  MessagePinned: 'message:pinned',
+  ReactionUpdated: 'reaction:updated',
+  Mention: 'mention',
+  DmIncoming: 'dm:incoming',
+  Typing: 'typing',
+  PresenceUpdate: 'presence:update',
+  RoomCreated: 'room:created',
+  RoomUpdated: 'room:updated',
+  RoomDeleted: 'room:deleted',
+  RoomReordered: 'room:reordered',
+  HouseUpdated: 'house:updated',
+  HouseDeleted: 'house:deleted',
+  RolesUpdated: 'roles:updated',
+  MembersUpdated: 'members:updated',
+  MemberJoined: 'member:joined',
+  FriendRequest: 'friend:request',
+  FriendAccepted: 'friend:accepted',
+  FriendRemoved: 'friend:removed',
+  SessionRevoked: 'session:revoked',
+  VoicePeerJoined: 'voice:peer-joined',
+  VoicePeerLeft: 'voice:peer-left',
+  VoicePeerState: 'voice:peer-state',
+  VoiceRoomState: 'voice:room-state',
+  VoiceSignal: 'voice:signal',
+};
+
+/**
+ * Raw Socket.IO event names the client emits to the server (client → server).
+ * @enum {string}
+ */
+export const GatewayCommand = {
+  RoomJoin: 'room:join',
+  RoomLeave: 'room:leave',
+  MessageSend: 'message:send',
+  MessageEdit: 'message:edit',
+  MessageDelete: 'message:delete',
+  ReactionToggle: 'reaction:toggle',
+  TypingStart: 'typing:start',
+  TypingStop: 'typing:stop',
+  PresenceSet: 'presence:set',
+  VoiceJoin: 'voice:join',
+  VoiceLeave: 'voice:leave',
+  VoiceSync: 'voice:sync',
+  VoiceSignal: 'voice:signal',
+  VoiceState: 'voice:state',
+};
+
+/**
+ * Room (channel) types.
+ * @enum {string}
+ */
+export const RoomTypes = {
+  Text: 'text',
+  Voice: 'voice',
+  Portal: 'portal',
+};
+
+/**
+ * Presence statuses a user can hold.
+ * @enum {string}
+ */
+export const PresenceStatus = {
+  Online: 'online',
+  Idle: 'idle',
+  DnD: 'dnd',
+  Offline: 'offline',
+};
+
+/** Statuses a user may manually set (offline is implicit). */
+export const SettableStatus = [
+  PresenceStatus.Online,
+  PresenceStatus.Idle,
+  PresenceStatus.DnD,
+];
+
+/**
+ * Friendship statuses returned by the friends API.
+ * @enum {string}
+ */
+export const FriendStatus = {
+  Self: 'self',
+  None: 'none',
+  Friends: 'friends',
+  Incoming: 'incoming',
+  Outgoing: 'outgoing',
+};
+
+/** Name of the httpOnly refresh-token cookie the backend sets. */
+export const REFRESH_COOKIE = 'glade_rt';

package/src/util/Permissions.js

@@ -0,0 +1,148 @@
+'use strict';
+
+/**
+ * Glade House permission flags. These mirror the bitfield stored in
+ * `Role.permissions` and the allow/deny masks on per-room overrides server-side.
+ * @enum {number}
+ */
+export const PermissionFlags = {
+  /** Grants every permission and bypasses channel overrides. */
+  Administrator: 1 << 0,
+  /** Edit the House name / icon. */
+  ManageHouse: 1 << 1,
+  /** Create, edit, delete and assign roles. */
+  ManageRoles: 1 << 2,
+  /** Create, edit, delete and clone rooms, and set channel overrides. */
+  ManageChannels: 1 << 3,
+  /** Remove members from the House. */
+  KickMembers: 1 << 4,
+  /** Pin and delete other members' messages. */
+  ManageMessages: 1 << 5,
+  /** View rooms. */
+  ViewChannels: 1 << 6,
+  /** Send messages in rooms. */
+  SendMessages: 1 << 7,
+  /** Connect to voice rooms. */
+  Connect: 1 << 8,
+};
+
+/** Every permission OR'd together. */
+export const ALL_PERMISSIONS = Object.values(PermissionFlags).reduce((a, b) => a | b, 0);
+
+/** Permissions granted to the default `@everyone` role by the backend. */
+export const DEFAULT_EVERYONE =
+  PermissionFlags.ViewChannels | PermissionFlags.SendMessages | PermissionFlags.Connect;
+
+/** Permissions a per-room override is allowed to toggle. */
+export const CHANNEL_OVERRIDABLE =
+  PermissionFlags.ViewChannels |
+  PermissionFlags.SendMessages |
+  PermissionFlags.Connect |
+  PermissionFlags.ManageMessages;
+
+/**
+ * A wrapper around a Glade permission bitfield, offering ergonomic checks and edits.
+ * Accepts flag names (keys of {@link PermissionFlags}), raw numbers, or other
+ * `PermissionsBitField` instances anywhere a resolvable is expected.
+ */
+export class PermissionsBitField {
+  /**
+   * @param {PermissionResolvable} [bits=0]
+   */
+  constructor(bits = 0) {
+    /** @type {number} The raw bitfield. */
+    this.bitfield = PermissionsBitField.resolve(bits);
+  }
+
+  /**
+   * Resolves a permission-like value into a raw number.
+   * @param {PermissionResolvable} bits
+   * @returns {number}
+   */
+  static resolve(bits = 0) {
+    if (typeof bits === 'number') return bits;
+    if (bits instanceof PermissionsBitField) return bits.bitfield;
+    if (typeof bits === 'string') {
+      const flag = PermissionFlags[bits];
+      if (flag === undefined) throw new RangeError(`Unknown permission flag: ${bits}`);
+      return flag;
+    }
+    if (Array.isArray(bits)) {
+      return bits.map((b) => PermissionsBitField.resolve(b)).reduce((a, b) => a | b, 0);
+    }
+    throw new TypeError(`Cannot resolve permissions from: ${typeof bits}`);
+  }
+
+  /**
+   * Whether the bitfield holds all of the given permissions. The `Administrator`
+   * flag short-circuits to `true`, matching the server's `has()` semantics.
+   * @param {PermissionResolvable} permission
+   * @param {boolean} [checkAdmin=true]
+   * @returns {boolean}
+   */
+  has(permission, checkAdmin = true) {
+    if (checkAdmin && (this.bitfield & PermissionFlags.Administrator) !== 0) return true;
+    const bit = PermissionsBitField.resolve(permission);
+    return (this.bitfield & bit) === bit;
+  }
+
+  /**
+   * Returns whether any of the given permission bits are present.
+   * @param {PermissionResolvable} permission
+   * @returns {boolean}
+   */
+  any(permission) {
+    const bit = PermissionsBitField.resolve(permission);
+    return (this.bitfield & bit) !== 0;
+  }
+
+  /**
+   * Adds permissions, returning this for chaining.
+   * @param {...PermissionResolvable} bits
+   * @returns {this}
+   */
+  add(...bits) {
+    for (const b of bits) this.bitfield |= PermissionsBitField.resolve(b);
+    return this;
+  }
+
+  /**
+   * Removes permissions, returning this for chaining.
+   * @param {...PermissionResolvable} bits
+   * @returns {this}
+   */
+  remove(...bits) {
+    for (const b of bits) this.bitfield &= ~PermissionsBitField.resolve(b);
+    return this;
+  }
+
+  /**
+   * The flag names currently set in this bitfield.
+   * @returns {string[]}
+   */
+  toArray() {
+    return Object.keys(PermissionFlags).filter(
+      (name) => (this.bitfield & PermissionFlags[name]) === PermissionFlags[name],
+    );
+  }
+
+  /** @returns {number} */
+  valueOf() {
+    return this.bitfield;
+  }
+
+  /** @returns {string[]} */
+  toJSON() {
+    return this.toArray();
+  }
+}
+
+PermissionsBitField.Flags = PermissionFlags;
+PermissionsBitField.All = ALL_PERMISSIONS;
+PermissionsBitField.DefaultEveryone = DEFAULT_EVERYONE;
+
+/**
+ * @typedef {keyof typeof PermissionFlags | number | PermissionsBitField | Array<keyof typeof PermissionFlags | number | PermissionsBitField>} PermissionResolvable
+ */
+
+export default PermissionsBitField;

package/src/util/Util.js

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * Generates a short, unlikely-to-collide nonce used to correlate an optimistically
+ * sent message with its `message:new` echo from the gateway.
+ * @returns {string}
+ */
+export function generateNonce() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * Decodes the payload of a JWT without verifying its signature. Used only to read
+ * the access token's `exp` so the client can refresh proactively.
+ * @param {string} token
+ * @returns {Record<string, any> | null}
+ */
+export function decodeJwt(token) {
+  try {
+    const part = token.split('.')[1];
+    if (!part) return null;
+    const json = Buffer.from(part.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8');
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Builds a query string (with leading `?`) from an object, skipping
+ * `undefined`/`null` values. Returns `''` when there is nothing to encode.
+ * @param {Record<string, any>} [query]
+ * @returns {string}
+ */
+export function makeQuery(query) {
+  if (!query) return '';
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    params.append(key, String(value));
+  }
+  const str = params.toString();
+  return str ? `?${str}` : '';
+}
+
+/**
+ * Trims any trailing slashes from a URL/origin.
+ * @param {string} url
+ * @returns {string}
+ */
+export function trimTrailingSlash(url) {
+  return String(url).replace(/\/+$/, '');
+}
+
+/**
+ * Resolves something to its id: accepts a raw id string or any object with an `id`.
+ * @param {string | { id: string }} value
+ * @returns {string}
+ */
+export function resolveId(value) {
+  return typeof value === 'string' ? value : value?.id;
+}