@stoatx/client 0.1.0 → 0.2.0

package/README.md

@@ -1,11 +1,11 @@
 # @stoatx/client
 
-A high-performance, fully-typed, and memory-efficient client library for the Revolt API. Built from the ground up for the Stoatx ecosystem.
+A high-performance, fully-typed, and memory-efficient client library for the Stoat API. Built from the ground up for the Stoatx ecosystem.
 
 [![npm version](https://img.shields.io/npm/v/@stoatx/client.svg?style=flat-square)](https://www.npmjs.com/package/@stoatx/client)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
 
-`@stoatx/client` provides a robust object-oriented wrapper around Revolt's REST and WebSocket APIs. It features an intelligent caching system, automatic memory sweeping, and strict event typings to make building bots as frictionless as possible.
+`@stoatx/client` provides a robust object-oriented wrapper around Stoat's REST and WebSocket APIs. It features an intelligent caching system, automatic memory sweeping, and strict event typings to make building bots as frictionless as possible.
 
 ## Features
 
@@ -102,7 +102,7 @@ if (channel && channel.isText()) {
 ## Building Command Handlers
 
 While you can use `@stoatx/client` directly, it truly shines when paired with a command handler. Because the events are strictly typed using generics, you can easily build type-safe event registries.
-We recommend using the Stoatx Handler for a seamless experience, but you can also create your own custom command handler leveraging the client's event system.
+We recommend using the `Stoatx` for a seamless experience, but you can also create your own custom command handler leveraging the client's event system.
 
 ```typescript
 // Example of event listening

package/dist/index.cjs

@@ -53,6 +53,7 @@ __export(index_exports, {
   Server: () => Server,
   ServerChannelManager: () => ServerChannelManager,
   ServerManager: () => ServerManager,
+  StoatAPIError: () => StoatAPIError,
   SweeperManager: () => SweeperManager,
   TextChannel: () => TextChannel,
   UnknownChannel: () => UnknownChannel,
@@ -174,7 +175,6 @@ var Message = class extends Base {
     this.channelId = data.channel;
     const timestamp = (0, import_ulid.decodeTime)(this.id);
     if (timestamp) {
-      console.log(timestamp);
       this.createdAt = new Date(timestamp);
     }
     if (data.attachments) {
@@ -450,7 +450,7 @@ var GatewayManager = class {
         if (payload.users) {
           for (const rawUser of payload.users) {
             this.client.users._add(rawUser);
-            if (rawUser.relation === "User" && !this.client.user) {
+            if (rawUser.relationship === "User" && !this.client.user) {
               this.client.user = new ClientUser(this.client, rawUser);
             }
           }
@@ -617,7 +617,8 @@ var GatewayManager = class {
   }
   reconnect() {
     if (!this.token) {
-      return this.client.emit("error", new Error("RECONNECT_FAILED: No token available."));
+      this.client.emit("error", new Error("RECONNECT_FAILED: No token available."));
+      return;
     }
     let waitTime = Math.pow(2, this.reconnectAttempts) * 1e3;
     const jitter = waitTime * 0.2 * Math.random();
@@ -651,6 +652,46 @@ var AsyncBucket = class {
   resetAt = 0;
   queue = Promise.resolve();
 };
+var StoatAPIError = class _StoatAPIError extends Error {
+  statusCode;
+  apiType;
+  location;
+  rawData;
+  method;
+  path;
+  constructor(statusCode, data, method, path) {
+    let errorMessage = "Unknown API Error";
+    let type = "Unknown";
+    let location = "Unknown";
+    if (typeof data === "object" && data !== null) {
+      if ("type" in data || "location" in data) {
+        type = String(data.type || type);
+        location = String(data.location || location);
+        errorMessage = `Type: ${type} (Location: ${location})`;
+      } else if ("message" in data) {
+        errorMessage = String(data.message);
+      } else {
+        try {
+          errorMessage = JSON.stringify(data);
+        } catch {
+          errorMessage = "Unparseable Error Object";
+        }
+      }
+    } else if (typeof data === "string" && data.trim() !== "") {
+      errorMessage = data;
+    }
+    const routeInfo = method && path ? ` on ${method.toUpperCase()} ${path}` : "";
+    super(`${errorMessage}${routeInfo}`);
+    this.name = `StoatAPIError[${statusCode}]`;
+    this.statusCode = statusCode;
+    this.apiType = type;
+    this.location = location;
+    this.rawData = data;
+    this.method = method;
+    this.path = path;
+    Object.setPrototypeOf(this, _StoatAPIError.prototype);
+  }
+};
 var RESTManager = class {
   constructor(client) {
     this.client = client;
@@ -710,22 +751,23 @@ var RESTManager = class {
       bucket.remaining = Number(remainingHeader);
       bucket.resetAt = Date.now() + Number(resetAfterHeader);
     }
+    const textBody = await response.body.text();
+    let data;
+    try {
+      data = JSON.parse(textBody);
+    } catch {
+      data = textBody;
+    }
     if (response.statusCode === 429) {
-      const data2 = await response.body.json();
-      const retryMs = data2.retry_after || Number(resetAfterHeader) || 5e3;
+      const retryMs = typeof data === "object" && data?.retry_after ? data.retry_after : Number(resetAfterHeader) || 5e3;
       this.client.emit("debug", `Hit 429 on [${method}:${endpoint}]. Retrying in ${retryMs}ms.`);
       bucket.remaining = 0;
       bucket.resetAt = Date.now() + retryMs;
       await sleep(retryMs);
       return this.execute(method, endpoint, body, bucket);
     }
-    const data = await response.body.json();
     if (response.statusCode >= 400) {
-      let errorMessage = "Unknown Error";
-      if (typeof data === "object" && data !== null && "message" in data) {
-        errorMessage = String(data.message);
-      }
-      throw new Error(`[Stoat API Error ${response.statusCode}]: ${errorMessage}`);
+      throw new StoatAPIError(response.statusCode, data, method, endpoint);
     }
     return data;
   }
@@ -745,7 +787,14 @@ var RESTManager = class {
       body: formData
     });
     if (!response.ok) {
-      throw new Error(`Upload failed: ${response.status} ${response.statusText}`);
+      let errData;
+      const errText = await response.text();
+      try {
+        errData = JSON.parse(errText);
+      } catch {
+        errData = errText;
+      }
+      throw new StoatAPIError(response.status, errData, "POST", "/attachments");
     }
     const data = await response.json();
     return data.id;
@@ -845,11 +894,17 @@ var util2 = __toESM(require("util"), 1);
 
 // src/managers/BaseManager.ts
 var BaseManager = class {
+  cache;
+  client;
   constructor(client, limit = Infinity) {
     this.client = client;
     this.cache = new Collection(limit);
+    Object.defineProperty(this, "client", {
+      value: client,
+      enumerable: false,
+      writable: false
+    });
   }
-  cache;
   /**
    * Transforms raw data into a Structure, patches if existing, and saves to cache.
    * @internal
@@ -1558,16 +1613,28 @@ var MemberRoleManager = class {
   }
 };
 
+// src/utils/Constants.ts
+var StoatCDN = "https://cdn.stoatusercontent.com";
+
 // src/structures/Member.ts
 var Member = class extends Base {
+  // The server ID the member is in
   serverId;
+  // The nickname the member has in the server, if any.
   nickname = null;
+  // The avatar the member has in the server, if any.
   avatar = null;
-  roleIds = [];
+  /** @internal */
+  _roles = [];
+  // The date the member joined the server
   joinedAt;
+  // The date the member's timeout expires, or null if not timed out
   timeout = null;
+  // Whatever the user can talk in Voice Chat
   canPublish = false;
+  // Whatever the user can hear in Voice Chat
   canRecieve = false;
+  // Member roles manager
   roles;
   constructor(client, data) {
     super(client, { _id: data.user._id });
@@ -1579,11 +1646,17 @@ var Member = class extends Base {
   _patch(data) {
     if (data.nickname !== void 0) this.nickname = data.nickname;
     if (data.avatar !== void 0) this.avatar = data.avatar;
-    if (data.roles !== void 0) this.roleIds = data.roles;
+    if (data.roles !== void 0) this._roles = data.roles;
     if (data.timeout !== void 0) this.timeout = data.timeout ? new Date(data.timeout) : null;
     if (data.can_publish !== void 0) this.canPublish = data.canPublish;
     if (data.can_recieve !== void 0) this.canRecieve = data.canRecieve;
   }
+  /**
+   * Get member role IDs
+   */
+  get roleIds() {
+    return this._roles;
+  }
   /** Gets the global User object for this member */
   get user() {
     return this.client.users.cache.get(this.id);
@@ -1592,18 +1665,12 @@ var Member = class extends Base {
   get server() {
     return this.client.servers.cache.get(this.serverId);
   }
-  /** Resolves the array of role strings into actual Role objects */
-  get roleObjects() {
-    const server = this.server;
-    if (!server) return [];
-    return this.roleIds.map((id) => server.roles.cache.get(id)).filter((role) => role !== void 0);
-  }
   /** Calculates the member's total permissions using BigInt */
   get permissions() {
     const server = this.server;
     if (!server) return 0n;
     let totalPerms = server.defaultPermissions ?? 0n;
-    for (const role of this.roleObjects) {
+    for (const role of this.roles.cache.values()) {
       totalPerms |= BigInt(role.permissions);
     }
     if (server.ownerId === this.id) {
@@ -1611,40 +1678,76 @@ var Member = class extends Base {
     }
     return totalPerms;
   }
-  /** Checks if the member has a specific permission */
-  hasPermission(permission) {
-    return Permissions.has(this.permissions, permission);
+  /** Get avatar URL for this member, or null if they don't have one.
+   * @example
+   * // Get a member's avatar URL
+   * const avatarURL = member.avatarURL;
+   * console.log(avatarURL); // https://cdn.stoat.chat/attachments/avatars/1234567890/avatar.png
+   */
+  get avatarURL() {
+    if (!this.avatar) return null;
+    return `${StoatCDN}/attachments/avatars/${this.avatar.id}/${this.avatar.filename}`;
   }
   /**
-   * Edits this member's nickname, avatar, roles, or timeout.
+   * Ban this member from the server.
+   * @param options The options for this ban
+   * @example
+   * // Ban a member with a reason and delete their messages from the last hour
+   * await member.ban({ reason: "Spamming", deleteMessageSeconds: 3600 });
    */
-  async edit(options) {
+  async ban(options) {
     let server = this.server;
     if (!server) server = await this.client.servers.fetch(this.serverId);
-    return await server.members.edit(this.id, options);
+    await server.members.ban(this.id, options);
   }
   /**
-   * Kicks this member from the server.
+   * Creates a DM channel between the client's user and this member.
+   * @param force If true, forces the creation of a new DM channel even if one already exists.
+   * @returns A promise that resolves to the created DMChannel object.
+   * @throws {Error} If the API request fails.
+   * @example
+   * // Create a DM with this member
+   * const dm = await member.createDM();
+   * console.log(`DM channel ID: ${dm.id}`);
    */
-  async kick() {
+  async createDM(force = false) {
+    await this.client.users.createDM(this.id, { force });
+  }
+  /**
+   * Timeout this member for a specified duration.
+   * @param duration The duration of the timeout in milliseconds.
+   * @example
+   * // Timeout a member for 10 minutes (600,000 milliseconds)
+   * await member.setTimeout(600000);
+   */
+  async setTimeout(duration) {
     let server = this.server;
     if (!server) server = await this.client.servers.fetch(this.serverId);
-    await server.members.kick(this.id);
+    await server.members.setTimeout(this.id, duration);
+  }
+  /** Checks if the member has a specific permission */
+  hasPermission(permission) {
+    return Permissions.has(this.permissions, permission);
   }
   /**
-   * Bans this member from the server.
-   * @param options The options for this ban
+   * Edit this member.
+   * @param options The options to edit the member with (nickname, roles, timeout, etc.)
+   * @returns A promise that resolves to the updated Member.
    */
-  async ban(options) {
+  async edit(options) {
     let server = this.server;
     if (!server) server = await this.client.servers.fetch(this.serverId);
-    await server.members.ban(this.id, options);
+    return await server.members.edit(this.id, options);
   }
-  async unban() {
-    let server = this.client.servers.cache.get(this.serverId);
+  /**
+   * Kick this member from the server.
+   */
+  async kick() {
+    let server = this.server;
     if (!server) server = await this.client.servers.fetch(this.serverId);
-    await server.members.unban(this.id);
+    await server.members.kick(this.id);
   }
+  /** @internal */
   [util4.inspect.custom](depth, options, inspect10) {
     const { client, serverId, ...props } = this;
     return `${this.constructor.name} ${inspect10(
@@ -1682,24 +1785,48 @@ var MemberManager = class extends BaseManager {
     }
     return new Member(this.client, data);
   }
+  /**
+   * Resolve a string or mention to Member
+   * @param member The MemberResolvable to resolve
+   * @returns The resolved Member or undefined if not found
+   */
   resolve(member) {
     if (member instanceof Member) return member;
     if (member instanceof User) return this.cache.get(member.id);
     if (typeof member === "string") return this.cache.get(member.replace(/[<@>]/g, ""));
     return void 0;
   }
+  /**
+   * Resolve a Member to their ID string.
+   * @param member The MemberResolvable to resolve
+   * @returns The resolved ID string
+   * @throws {TypeError} If the provided resolvable is invalid
+   */
   resolveId(member) {
     if (typeof member === "string") return member.replace(/[<@>]/g, "");
     if ("id" in member) return member.id;
     throw new TypeError("Invalid MemberResolvable provided.");
   }
-  async fetch(member, force = true) {
+  /**
+   * Fetches a member from the server, or returns the cached version if available and not forced.
+   * @param member The MemberResolvable to fetch
+   * @param force Whether to bypass the cache and fetch fresh data from the API
+   * @returns A promise that resolves to the fetched Member
+   * @throws {Error} If the API request fails or the member is not found
+   * @example
+   * // Fetch a member by ID, using cache if available
+   * const member = await server.members.fetch("1234567890");
+   *
+   * // Fetch a member by mention, bypassing cache
+   * const member = await server.members.fetch("<@1234567890>", true);
+   */
+  async fetch(member, force = false) {
     if (!force) {
       const cached = this.resolve(member);
       if (cached) return cached;
     }
     const id = this.resolveId(member);
-    const data = await this.client.rest.get(`/channels/${id}`);
+    const data = await this.client.rest.get(`/servers/${this.server.id}/members/${id}`);
     return this._add(data);
   }
   /**
@@ -1739,6 +1866,14 @@ var MemberManager = class extends BaseManager {
    * Edits a member in the server.
    * @param member The MemberResolvable to edit.
    * @param options The fields to update (nickname, roles, timeout, etc.).
+   * @returns A promise that resolves to the updated Member.
+   * @throws {Error} If the API request fails or the member is not found.
+   * @example
+   * // Change a member's nickname and add a role
+   * const updatedMember = await server.members.edit("1234567890", {
+   *   nickname: "New Nickname",
+   *   roles: ["roleId1", "roleId2"],
+   * });
    */
   async edit(member, options) {
     const id = this.resolveId(member);
@@ -1765,6 +1900,9 @@ var MemberManager = class extends BaseManager {
   /**
    * Kicks a member from the server.
    * @param member The MemberResolvable to kick.
+   * @example
+   * // Kick a member by ID
+   * await server.members.kick("1234567890");
    */
   async kick(member) {
     const id = this.resolveId(member);
@@ -1775,6 +1913,9 @@ var MemberManager = class extends BaseManager {
    * Bans a member from the server.
    * @param member The MemberResolvable to ban.
    * @param options The ban options
+   * @example
+   * // Ban a member by ID
+   * await server.members.ban("1234567890", { reason: "Spamming", deleteMessageSeconds: 3600 });
    */
   async ban(member, options) {
     const id = this.resolveId(member);
@@ -1787,11 +1928,26 @@ var MemberManager = class extends BaseManager {
   /**
    * Unbans a user from the server
    * @param member The MemberResolvable to unban
+   * @example
+   * // Unban a member by ID
+   * await server.members.unban("1234567890");
    */
   async unban(member) {
     const id = this.resolveId(member);
     await this.client.rest.delete(`/servers/${this.server.id}/bans/${id}`);
   }
+  /**
+   * Timeouts a member in the server for a specified duration.
+   * @param member The MemberResolvable to timeout
+   * @param duration The duration of the timeout in milliseconds
+   * @example
+   * // Timeout a member for 10 minutes
+   * await server.members.setTimeout("1234567890", 10 * 60 * 1000);
+   */
+  async setTimeout(member, duration) {
+    const id = this.resolveId(member);
+    await this.edit(id, { timeout: new Date(Date.now() + duration).toISOString() });
+  }
   [util5.inspect.custom]() {
     return this.cache;
   }
@@ -2156,7 +2312,7 @@ var RoleManager = class extends BaseManager {
    * console.log("Role deleted successfully.");
    *
    * // Delete a role using a Role object
-   * const role = await server.roles.fetch("01JE2MM759J5D7CHJF084R7MJ2");
+   * const role = await server.roles.fetch("01JE2MM759J5D7CHJF084R7");
    * await server.roles.delete(role);
    * console.log("Role deleted successfully.");
    *
@@ -2644,6 +2800,38 @@ var UserManager = class extends BaseManager {
     const data = await this.client.rest.patch(`/users/@me`, payload);
     return this._add(data);
   }
+  /**
+   * The DM between the client's user and a user
+   *
+   * @param {string} userId The user id
+   * @returns {?DMChannel}
+   * @private
+   */
+  dmChannel(userId) {
+    return this.client.channels.cache.find((channel) => channel.isDM() && channel.recipients.includes(userId)) ?? null;
+  }
+  /**
+   * Creates a DM channel between the client's user and another user.
+   * @param user The UserResolvable to create a DM with.
+   * @param options Additional options for DM creation.
+   * @param options.force If true, forces the creation of a new DM channel even if one already exists.
+   * @returns A promise that resolves to the created DMChannel object.
+   * @throws {TypeError} If an invalid UserResolvable is provided.
+   * @throws {Error} If the API request fails.
+   * @example
+   * // Create a DM with a user by ID
+   * const dm = await client.users.createDM("1234567890");
+   * console.log(`DM channel ID: ${dm.id}`);
+   */
+  async createDM(user, { force = false } = {}) {
+    const id = this.resolveId(user);
+    if (!force) {
+      const dmChannel = this.dmChannel(id);
+      if (dmChannel) return dmChannel;
+    }
+    const data = await this.client.rest.get(`/users/${id}/dm`);
+    return this.client.channels._add(data);
+  }
 };
 
 // src/managers/SweepManager.ts
@@ -2790,6 +2978,7 @@ var EmbedBuilder = class {
   Server,
   ServerChannelManager,
   ServerManager,
+  StoatAPIError,
   SweeperManager,
   TextChannel,
   UnknownChannel,
@@ -2798,3 +2987,4 @@ var EmbedBuilder = class {
   UserPresence,
   UserRelationship
 });
+//# sourceMappingURL=index.cjs.map