@glade-chat/glade.js 0.1.0

package/src/rest/REST.js

@@ -0,0 +1,250 @@
+'use strict';
+
+import { GladeAPIError } from '../errors/index.js';
+import { Routes } from './Routes.js';
+import { makeQuery, trimTrailingSlash } from '../util/Util.js';
+import { REFRESH_COOKIE } from '../util/Constants.js';
+
+/** Credential endpoints where a 401 means "bad credentials", not "expired session". */
+const AUTH_ENDPOINTS = /^\/auth\/(login|register|forgot|reset|logout|refresh)/;
+
+/**
+ * The HTTP layer of glade.js. Talks to the Glade REST API, attaching the bearer
+ * access token, persisting the `glade_rt` refresh cookie, and transparently
+ * refreshing an expired access token on a 401 (single-flight, retried once).
+ */
+export class REST {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.base] REST origin without the version segment.
+   * @param {string} [options.version] API version segment, e.g. `v1`.
+   * @param {boolean} [options.autoRefresh] Refresh + retry on 401.
+   * @param {(token: string) => void} [options.onToken] Called whenever a fresh access token is obtained.
+   * @param {(msg: string) => void} [options.debug] Debug sink.
+   */
+  constructor(options = {}) {
+    /** @type {string} The REST origin (without the version segment). */
+    this.base = trimTrailingSlash(options.base ?? 'https://api.glade.chat');
+    /** @type {string} */
+    this.version = options.version ?? 'v1';
+    /** @type {boolean} */
+    this.autoRefresh = options.autoRefresh ?? true;
+    /** @type {((token: string) => void) | null} */
+    this.onToken = options.onToken ?? null;
+    /** @type {((msg: string) => void) | null} */
+    this._debug = options.debug ?? null;
+
+    /** @type {string | null} The current access token. */
+    this.token = null;
+    /** @type {string | null} The raw `glade_rt` refresh cookie value. */
+    this.refreshCookie = null;
+    /** @type {Promise<string | null> | null} In-flight refresh, for single-flight. */
+    this._refreshing = null;
+  }
+
+  /** The fully-qualified base, i.e. `<base>/<version>`. */
+  get apiBase() {
+    return `${this.base}/${this.version}`;
+  }
+
+  /**
+   * Sets the access token used for the `Authorization` header.
+   * @param {string | null} token
+   * @returns {this}
+   */
+  setToken(token) {
+    this.token = token ?? null;
+    return this;
+  }
+
+  /**
+   * Sets the refresh cookie value directly (e.g. when resuming a saved session).
+   * @param {string | null} value
+   * @returns {this}
+   */
+  setRefreshToken(value) {
+    this.refreshCookie = value ?? null;
+    return this;
+  }
+
+  /**
+   * Performs a REST request.
+   * @template T
+   * @param {object} opts
+   * @param {string} opts.method HTTP method.
+   * @param {string} opts.path Path relative to the version prefix (use {@link Routes}).
+   * @param {any} [opts.body] JSON body.
+   * @param {Record<string, any>} [opts.query] Query parameters.
+   * @param {Record<string, string>} [opts.headers] Extra headers.
+   * @param {boolean} [opts.auth=true] Attach the bearer token.
+   * @param {boolean} [opts.sendCookie=false] Attach the refresh cookie.
+   * @param {BodyInit} [opts.rawBody] Pre-built body (e.g. FormData); bypasses JSON.
+   * @param {boolean} [opts._retry] Internal: marks a post-refresh retry.
+   * @returns {Promise<T>}
+   */
+  async request(opts) {
+    const {
+      method = 'GET',
+      path,
+      body,
+      query,
+      headers = {},
+      auth = true,
+      sendCookie = false,
+      rawBody,
+      _retry = false,
+    } = opts;
+
+    const url = `${this.apiBase}${path}${makeQuery(query)}`;
+    const finalHeaders = { Accept: 'application/json', ...headers };
+
+    if (auth && this.token) finalHeaders.Authorization = `Bearer ${this.token}`;
+    if (sendCookie && this.refreshCookie) {
+      finalHeaders.Cookie = `${REFRESH_COOKIE}=${this.refreshCookie}`;
+    }
+
+    let payload = rawBody;
+    if (rawBody === undefined && body !== undefined) {
+      finalHeaders['Content-Type'] = 'application/json';
+      payload = JSON.stringify(body);
+    }
+
+    this.#debug(`${method} ${path}`);
+    const res = await fetch(url, { method, headers: finalHeaders, body: payload });
+
+    this.#captureCookies(res);
+
+    // Refresh-and-retry on an expired access token.
+    if (
+      res.status === 401 &&
+      this.autoRefresh &&
+      auth &&
+      !_retry &&
+      !AUTH_ENDPOINTS.test(path)
+    ) {
+      const fresh = await this.refresh();
+      if (fresh) return this.request({ ...opts, _retry: true });
+    }
+
+    if (res.status === 204) return /** @type {T} */ (undefined);
+
+    let data = null;
+    const text = await res.text();
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = text;
+      }
+    }
+
+    if (!res.ok) {
+      const message = (data && data.error) || res.statusText || 'Request failed';
+      throw new GladeAPIError({
+        status: res.status,
+        message,
+        method,
+        path,
+        details: data && data.details,
+      });
+    }
+
+    return /** @type {T} */ (data);
+  }
+
+  /** Convenience helpers. */
+  get(path, opts = {}) {
+    return this.request({ ...opts, method: 'GET', path });
+  }
+  post(path, body, opts = {}) {
+    return this.request({ ...opts, method: 'POST', path, body });
+  }
+  patch(path, body, opts = {}) {
+    return this.request({ ...opts, method: 'PATCH', path, body });
+  }
+  put(path, body, opts = {}) {
+    return this.request({ ...opts, method: 'PUT', path, body });
+  }
+  delete(path, opts = {}) {
+    return this.request({ ...opts, method: 'DELETE', path });
+  }
+
+  /**
+   * Exchanges the stored refresh cookie for a new access token. Single-flight:
+   * concurrent callers share one in-flight request.
+   * @returns {Promise<string | null>} The new access token, or null on failure.
+   */
+  refresh() {
+    // Bot/user tokens have no refresh cookie — there is nothing to exchange.
+    if (!this.refreshCookie) return Promise.resolve(null);
+    if (this._refreshing) return this._refreshing;
+    this._refreshing = (async () => {
+      try {
+        const data = await this.request({
+          method: 'POST',
+          path: Routes.refresh(),
+          auth: false,
+          sendCookie: true,
+        });
+        const token = data?.accessToken ?? null;
+        if (token) {
+          this.token = token;
+          this.onToken?.(token);
+          this.#debug('Access token refreshed');
+        }
+        return token;
+      } catch (err) {
+        this.#debug(`Refresh failed: ${err.message}`);
+        return null;
+      } finally {
+        this._refreshing = null;
+      }
+    })();
+    return this._refreshing;
+  }
+
+  /**
+   * Uploads a file via multipart/form-data to `/uploads`.
+   * @param {Buffer | Uint8Array | Blob} file File contents.
+   * @param {object} [opts]
+   * @param {string} [opts.name] File name.
+   * @param {string} [opts.contentType] MIME type.
+   * @param {'avatar' | 'attachment'} [opts.kind] Upload bucket; `avatar` for avatars/banners.
+   * @returns {Promise<{ url: string, name: string, size: number, contentType: string }>}
+   */
+  async upload(file, opts = {}) {
+    const form = new FormData();
+    const blob =
+      file instanceof Blob
+        ? file
+        : new Blob([file], { type: opts.contentType || 'application/octet-stream' });
+    form.append('file', blob, opts.name || 'file');
+    return this.request({
+      method: 'POST',
+      path: Routes.uploads(),
+      query: opts.kind ? { kind: opts.kind } : undefined,
+      rawBody: form,
+    });
+  }
+
+  /** Reads `Set-Cookie` headers and stores the refresh cookie value. */
+  #captureCookies(res) {
+    let cookies = [];
+    if (typeof res.headers.getSetCookie === 'function') {
+      cookies = res.headers.getSetCookie();
+    } else {
+      const raw = res.headers.get('set-cookie');
+      if (raw) cookies = [raw];
+    }
+    for (const cookie of cookies) {
+      const match = cookie.match(new RegExp(`${REFRESH_COOKIE}=([^;]+)`));
+      if (match) this.refreshCookie = match[1];
+    }
+  }
+
+  #debug(msg) {
+    this._debug?.(`[REST] ${msg}`);
+  }
+}
+
+export default REST;

package/src/rest/Routes.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * Builders for every Glade REST endpoint. Each returns a path *relative to the
+ * version prefix*, e.g. `Routes.login()` → `/auth/login`, which the
+ * {@link REST} client expands to `<base>/<version>/auth/login`.
+ */
+export const Routes = {
+  // --- Auth ---
+  register: () => '/auth/register',
+  login: () => '/auth/login',
+  loginTwoFactor: () => '/auth/login/2fa',
+  twoFactorSetup: () => '/auth/2fa/setup',
+  twoFactorEnable: () => '/auth/2fa/enable',
+  twoFactorDisable: () => '/auth/2fa/disable',
+  refresh: () => '/auth/refresh',
+  logout: () => '/auth/logout',
+  tokens: () => '/auth/tokens',
+  tokensReset: () => '/auth/tokens/reset',
+  sessions: () => '/auth/sessions',
+  session: (id) => `/auth/sessions/${id}`,
+  authMe: () => '/auth/me',
+  forgotPassword: () => '/auth/forgot',
+  resetPassword: () => '/auth/reset',
+
+  // --- Users ---
+  me: () => '/users/me',
+  userSearch: () => '/users',
+  user: (id) => `/users/${id}`,
+
+  // --- Houses ---
+  houses: () => '/houses',
+  house: (houseId) => `/houses/${houseId}`,
+  houseLeave: (houseId) => `/houses/${houseId}/leave`,
+  houseMembers: (houseId) => `/houses/${houseId}/members`,
+  memberRoles: (houseId, userId) => `/houses/${houseId}/members/${userId}/roles`,
+
+  // --- Roles ---
+  houseRoles: (houseId) => `/houses/${houseId}/roles`,
+  houseRolesReorder: (houseId) => `/houses/${houseId}/roles/reorder`,
+  role: (roleId) => `/roles/${roleId}`,
+
+  // --- Rooms (channels) ---
+  houseRooms: (houseId) => `/houses/${houseId}/rooms`,
+  houseRoomsReorder: (houseId) => `/houses/${houseId}/rooms/reorder`,
+  room: (roomId) => `/rooms/${roomId}`,
+  roomClone: (roomId) => `/rooms/${roomId}/clone`,
+  roomMessages: (roomId) => `/rooms/${roomId}/messages`,
+  roomPins: (roomId) => `/rooms/${roomId}/pins`,
+  roomPin: (roomId, messageId) => `/rooms/${roomId}/messages/${messageId}/pin`,
+  roomPermissions: (roomId) => `/rooms/${roomId}/permissions`,
+  roomPermission: (roomId, roleId) => `/rooms/${roomId}/permissions/${roleId}`,
+
+  // --- E2E house keys ---
+  houseKeysSelf: (houseId) => `/houses/${houseId}/keys/self`,
+  houseKeysMembers: (houseId) => `/houses/${houseId}/keys/members`,
+  houseKeys: (houseId) => `/houses/${houseId}/keys`,
+
+  // --- DMs ---
+  dms: () => '/dms',
+  dmMessages: (dmId) => `/dms/${dmId}/messages`,
+
+  // --- Invites ---
+  houseInvites: (houseId) => `/houses/${houseId}/invites`,
+  invite: (code) => `/invites/${code}`,
+  inviteRedeem: (code) => `/invites/${code}/redeem`,
+  inviteRevoke: (id) => `/invites/${id}`,
+
+  // --- Friends ---
+  friends: () => '/friends',
+  friendsPending: () => '/friends/pending',
+  friendAccept: (id) => `/friends/${id}/accept`,
+  friendDecline: (id) => `/friends/${id}/decline`,
+  friendRemove: (userId) => `/friends/${userId}`,
+
+  // --- Uploads ---
+  uploads: () => '/uploads',
+
+  // --- Billing ---
+  subscription: () => '/billing/subscription',
+  checkout: () => '/billing/checkout',
+  portal: () => '/billing/portal',
+};
+
+export default Routes;

package/src/structures/Base.js

@@ -0,0 +1,70 @@
+'use strict';
+
+/**
+ * The base class every cached Glade structure extends. Holds a non-enumerable
+ * reference to the owning {@link Client} so structures can perform actions.
+ * @abstract
+ */
+export class Base {
+  /**
+   * @param {import('../client/Client.js').Client} client
+   */
+  constructor(client) {
+    /**
+     * The client that instantiated this structure.
+     * @type {import('../client/Client.js').Client}
+     * @readonly
+     */
+    Object.defineProperty(this, 'client', { value: client });
+  }
+
+  /**
+   * Applies raw API data onto this structure. Subclasses override and call super.
+   * @param {any} data
+   * @returns {any} The same data, for convenience.
+   * @protected
+   */
+  _patch(data) {
+    return data;
+  }
+
+  /**
+   * Returns a shallow clone of this structure (used for "old" copies in update events).
+   * @returns {this}
+   * @protected
+   */
+  _clone() {
+    return Object.assign(Object.create(this), this);
+  }
+
+  /**
+   * Snapshots this structure (the "old" copy), patches this instance in place with
+   * the new data, and returns the old snapshot — handy for `*Update` events.
+   * @param {any} data
+   * @returns {this} The pre-patch snapshot.
+   * @protected
+   */
+  _update(data) {
+    const old = this._clone();
+    this._patch(data);
+    return old;
+  }
+
+  /**
+   * @returns {string | undefined}
+   */
+  valueOf() {
+    return this.id;
+  }
+
+  toJSON() {
+    const out = {};
+    for (const [key, value] of Object.entries(this)) {
+      if (value && typeof value === 'object' && 'cache' in value) continue; // skip managers
+      out[key] = value?.toJSON ? value.toJSON() : value;
+    }
+    return out;
+  }
+}
+
+export default Base;

package/src/structures/ClientUser.js

@@ -0,0 +1,142 @@
+'use strict';
+
+import { User } from './User.js';
+import { Routes } from '../rest/Routes.js';
+import { SettableStatus } from '../util/Constants.js';
+
+/**
+ * Represents the currently logged-in account. Adds methods for editing the
+ * profile, managing presence, and inspecting connected sessions.
+ * @extends {User}
+ */
+export class ClientUser extends User {
+  /**
+   * Updates the live presence broadcast to other users (via the gateway).
+   * @param {'online' | 'idle' | 'dnd'} status
+   * @returns {this}
+   */
+  setPresence(status) {
+    if (!SettableStatus.includes(status)) {
+      throw new RangeError(`Status must be one of ${SettableStatus.join(', ')}`);
+    }
+    this.client.gateway.send('presence:set', status);
+    this.status = status;
+    return this;
+  }
+
+  /**
+   * Edits the account profile.
+   * @param {object} data
+   * @param {string} [data.displayName]
+   * @param {string | null} [data.avatarUrl]
+   * @param {string | null} [data.bannerUrl]
+   * @param {string} [data.bio]
+   * @param {'online' | 'idle' | 'dnd'} [data.status]
+   * @param {string} [data.publicKey]
+   * @param {string} [data.currentPassword]
+   * @param {string} [data.newPassword]
+   * @returns {Promise<this>}
+   */
+  async edit(data) {
+    const { user } = await this.client.rest.patch(Routes.me(), data);
+    this._patch(user);
+    return this;
+  }
+
+  /**
+   * Sets both the persisted preferred status and the live presence.
+   * @param {'online' | 'idle' | 'dnd'} status
+   * @returns {Promise<this>}
+   */
+  async setStatus(status) {
+    await this.edit({ status });
+    if (this.client.gateway.connected) this.setPresence(status);
+    return this;
+  }
+
+  /**
+   * Sets the display name.
+   * @param {string} displayName
+   * @returns {Promise<this>}
+   */
+  setDisplayName(displayName) {
+    return this.edit({ displayName });
+  }
+
+  /**
+   * Sets the bio.
+   * @param {string} bio
+   * @returns {Promise<this>}
+   */
+  setBio(bio) {
+    return this.edit({ bio });
+  }
+
+  /**
+   * Sets the avatar. Accepts an existing URL string, or raw file data which is
+   * uploaded first.
+   * @param {string | Buffer | Uint8Array | Blob | null} avatar
+   * @param {{ name?: string, contentType?: string }} [fileOptions]
+   * @returns {Promise<this>}
+   */
+  async setAvatar(avatar, fileOptions = {}) {
+    const avatarUrl = await this.#resolveImage(avatar, fileOptions);
+    return this.edit({ avatarUrl });
+  }
+
+  /**
+   * Sets the profile banner. Accepts a URL string or raw file data.
+   * @param {string | Buffer | Uint8Array | Blob | null} banner
+   * @param {{ name?: string, contentType?: string }} [fileOptions]
+   * @returns {Promise<this>}
+   */
+  async setBanner(banner, fileOptions = {}) {
+    const bannerUrl = await this.#resolveImage(banner, fileOptions);
+    return this.edit({ bannerUrl });
+  }
+
+  /**
+   * Sets the E2E identity public key.
+   * @param {string} publicKey
+   * @returns {Promise<this>}
+   */
+  setPublicKey(publicKey) {
+    return this.edit({ publicKey });
+  }
+
+  /**
+   * Changes the account password.
+   * @param {string} currentPassword
+   * @param {string} newPassword
+   * @returns {Promise<this>}
+   */
+  setPassword(currentPassword, newPassword) {
+    return this.edit({ currentPassword, newPassword });
+  }
+
+  /**
+   * Lists the account's connected device sessions.
+   * @returns {Promise<Array<{ id: string, userAgent: string | null, location: string | null, createdAt: string, lastSeenAt: string, current: boolean }>>}
+   */
+  async fetchSessions() {
+    const { sessions } = await this.client.rest.get(Routes.sessions());
+    return sessions;
+  }
+
+  /**
+   * Revokes (signs out) a connected session.
+   * @param {string} sessionId
+   * @returns {Promise<void>}
+   */
+  async revokeSession(sessionId) {
+    await this.client.rest.delete(Routes.session(sessionId));
+  }
+
+  async #resolveImage(image, fileOptions) {
+    if (image === null || typeof image === 'string') return image;
+    const { url } = await this.client.rest.upload(image, { ...fileOptions, kind: 'avatar' });
+    return url;
+  }
+}
+
+export default ClientUser;

package/src/structures/DMChannel.js

@@ -0,0 +1,85 @@
+'use strict';
+
+import { Base } from './Base.js';
+import { MessageManager } from '../managers/MessageManager.js';
+
+/**
+ * Represents a direct-message channel between the client user and one or more
+ * other users.
+ * @extends {Base}
+ */
+export class DMChannel extends Base {
+  constructor(client, data) {
+    super(client);
+    /** @type {string} The DM channel id. */
+    this.id = data.id;
+    /** @type {MessageManager} Cache + helpers for this channel's messages. */
+    this.messages = new MessageManager(client, this);
+    /** @type {string[]} Ids of the other participants. */
+    this.participantIds = [];
+    this._patch(data);
+  }
+
+  _patch(data) {
+    if (Array.isArray(data.participants)) {
+      this.participantIds = data.participants.map((p) => {
+        this.client.users._add(p);
+        return p.id;
+      });
+    }
+    return data;
+  }
+
+  /** The other participants in this DM, resolved from the user cache. */
+  get participants() {
+    return this.participantIds
+      .map((id) => this.client.users.cache.get(id))
+      .filter((u) => Boolean(u));
+  }
+
+  /** The primary recipient (first other participant). */
+  get recipient() {
+    return this.participants[0] ?? null;
+  }
+
+  /** This DM channel is always a DM (not a room). */
+  isDM() {
+    return true;
+  }
+
+  /**
+   * Sends a message to this DM channel.
+   * @param {string | import('../managers/MessageManager.js').MessagePayload} content
+   * @returns {Promise<import('./Message.js').Message>}
+   */
+  send(content) {
+    return this.client._sendMessage({ dmChannelId: this.id }, content);
+  }
+
+  /** Broadcasts a "typing…" indicator to the DM. */
+  sendTyping() {
+    this.client.gateway.send('typing:start', { dmChannelId: this.id });
+    return this;
+  }
+
+  /** Stops the "typing…" indicator. */
+  stopTyping() {
+    this.client.gateway.send('typing:stop', { dmChannelId: 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);
+  }
+
+  toString() {
+    return this.recipient ? this.recipient.toString() : this.id;
+  }
+}
+
+export default DMChannel;