@stoatx/client 0.6.4 → 0.7.0

package/README.md

@@ -5,127 +5,17 @@ A high-performance, fully-typed, and memory-efficient client library for the Sto
 [![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 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
 
 - **Strictly Typed:** 100% TypeScript with highly accurate generic types for events and structures.
 - **Smart Caching:** Built on a unified `BaseManager` architecture that guarantees reference stability (no duplicate objects in memory).
 - **Automatic Memory Management:** Includes a built-in `SweeperManager` to prevent memory leaks in long-running applications.
 - **Extensible:** Designed to seamlessly integrate with higher-level command frameworks like the Stoatx Handler.
+- **Self-hosting support:** Natively supports custom Stoat instances via root API discovery.
 - **Modern Node:** Pure ESM and CommonJS support built with `tsup`.
 
-## Installation
-
-```bash
-# Using pnpm (Recommended)
-pnpm add @stoatx/client
-
-# Using npm
-npm install @stoatx/client
-
-# Using yarn
-yarn add @stoatx/client
-```
-
-## Quick Start
-
-```typescript
-import { Client } from "@stoatx/client";
-
-// Initialize the client
-const client = new Client({
-  sweepers: {
-    messages: {
-      lifetime: 3600000, // 1 hour
-      interval: 600000, // 10 minutes
-    },
-  },
-});
-
-// Listen to events
-client.on("ready", async () => {
-  const me = await client.users.fetchMe();
-  console.log(`Logged in successfully as ${me.username}!`);
-});
-
-client.on("messageCreate", async (message) => {
-  if (message.author.bot) return;
-
-  if (message.content === "!ping") {
-    await message.channel.send("Pong! 🏓");
-  }
-});
-
-// Connect to Stoat
-client.login("YOUR_BOT_TOKEN");
-```
-
-##️ Architecture & Managers
-
-`@stoatx/client` organizes data using a predictable **Manager** hierarchy. Managers handle fetching, caching, and editing structures.
-
-### Global Managers
-
-Accessible directly on the `client`, managing data across the entire bot:
-
-- `client.users` (Fetches and caches users)
-- `client.servers` (Fetches and caches servers)
-- `client.channels` (The global cache for all channel types)
-
-### Scoped Managers
-
-Accessible on specific structures (like `Server` or `Channel`), managing localized data:
-
-- `server.members` (Manages members within a specific server)
-- `server.roles` (Manages roles for a server)
-- `server.channels` (A virtual manager filtering the global channel cache)
-- `channel.messages` (Manages messages within a specific channel)
-
-### Example: Editing a Server and Sending a Message
-
-```typescript
-// Fetch a server and edit its name
-const server = await client.servers.fetch("SERVER_ID");
-await server.edit({ name: "My Awesome Server" });
-
-// Find a specific channel and send an embed
-const channel = server.channels.cache.get("CHANNEL_ID");
-if (channel && channel.isText()) {
-  await channel.send({
-    content: "Welcome to the new server!",
-    embeds: [{ title: "Update", description: "Name changed successfully." }],
-  });
-}
-```
-
-## 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` 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
-import type { ClientEvents } from "@stoatx/client";
-
-function registerEvent<K ClientEvents extends keyof>(
-  client: Client,
-  event: K,
-  handler: (...args: ClientEvents[K]) => void
-) {
-  client.on(event, handler);
-}
-```
-
-## Contributing
-
-Contributions are welcome! If you're using this library and find a bug or want to add a feature from the Revolt API, feel free to open a Pull Request.
-
-1. Clone the repository.
-2. Run `pnpm install`.
-3. Make your changes in `packages/client`.
-4. Run `pnpm build` to ensure `tsup` compiles your changes correctly.
+For installation instructions, guides, and API references, visit the **[Stoatx Documentation](https://stoatx-ts.github.io/stoatx/)**.
 
 ## License
 
-MIT © [Stoatx / Stoatx Team]
+MIT © [Stoatx / Stoatx Team]

package/dist/index.cjs

@@ -829,6 +829,7 @@ var GatewayManager = class {
     this.client = client;
   }
   ws = null;
+  wsURL = "";
   pingInterval = null;
   token = null;
   reconnectAttempts = 0;
@@ -843,7 +844,7 @@ var GatewayManager = class {
       this.ws.removeAllListeners();
       this.ws = null;
     }
-    const baseUrl = "wss://stoat.chat/events";
+    const baseUrl = this.wsURL ?? "wss://events.stoat.chat";
     const url = `${baseUrl}?version=1&format=json&token=${this.token}`;
     this.ws = new import_ws.default(url);
     this.ws.on("open", () => {
@@ -863,6 +864,9 @@ var GatewayManager = class {
       this.client.emit("error", error);
     });
   }
+  setGatewayUrl(url) {
+    this.wsURL = url;
+  }
   handleMessage(rawData) {
     const payload = JSON.parse(rawData.toString());
     const eventType = payload.type;
@@ -1359,12 +1363,19 @@ var RESTManager = class {
       }
     }, 3e5).unref();
   }
-  baseURL = "https://stoat.chat/api";
+  baseURL = "";
+  cdnURL = "";
   token = null;
   buckets = /* @__PURE__ */ new Map();
   setToken(token) {
     this.token = token;
   }
+  setBaseURL(baseURL) {
+    this.baseURL = baseURL.replace(/\/+$/, "");
+  }
+  setCDNURL(cdnURL) {
+    this.cdnURL = cdnURL.replace(/\/+$/, "");
+  }
   /**
    * Generates a local identifier for the bucket based on method and path.
    */
@@ -1456,7 +1467,7 @@ var RESTManager = class {
    */
   async uploadFile(tag, fileBuffer, filename) {
     if (!this.token) throw new Error("REST_NOT_READY: No token available.");
-    const url = `https://cdn.stoatusercontent.com/${tag}`;
+    const url = `${this.cdnURL}/${tag}`;
     const formData = new FormData();
     formData.append("file", new Blob([fileBuffer]), filename);
     const response = await fetch(url, {
@@ -3852,6 +3863,50 @@ var Emoji = class extends Base {
     if (data.animated !== void 0) this.animated = data.animated;
     if (data.nsfw !== void 0) this.nsfw = data.nsfw;
   }
+  /**
+   * Fetch this emoji from the API or resolves it from the local cache.
+   * @param force Whether to skip the cache check and force a direct API request. Defaults to false.
+   * @returns A promise that resolves to the fetched {@link Emoji} object.
+   * @throws {Error} If the API request fails or if the emoji is detached.
+   * @example
+   * // Force fetch emoji to update its data
+   * await emoji.fetch(true);
+   */
+  async fetch(force) {
+    const server = this.client.servers.cache.get(this.parent.type === "Server" ? this.parent.id : "");
+    if (!server) throw new Error("No server registered in EmojiManager");
+    if (this.parent.type === "Detached") throw new Error("Cannot fetch a detached emoji");
+    return await server.emojis.fetch(this, force);
+  }
+  /**
+   * Deletes this emoji from the server.
+   * @returns A promise that resolves when the emoji has been deleted.
+   * @throws {Error} If the API request fails or if the emoji is detached.
+   * @example
+   * // Delete an emoji from the server
+   * await emoji.delete();
+   */
+  async delete() {
+    const server = this.client.servers.cache.get(this.parent.type === "Server" ? this.parent.id : "");
+    if (!server) throw new Error("No server registered in EmojiManager");
+    if (this.parent.type === "Detached") throw new Error("Emoji is already detached");
+    await server.emojis.delete(this);
+  }
+  /**
+   * Edits this emoji's properties.
+   * @param options The options to edit the emoji with.
+   * @returns A promise that resolves to the edited {@link Emoji} object.
+   * @throws {Error} If the API request fails or if the emoji is detached.
+   * @example
+   * // Edit an emoji's name
+   * await emoji.edit({ name: "new_name" });
+   */
+  async edit(options) {
+    const server = this.client.servers.cache.get(this.parent.type === "Server" ? this.parent.id : "");
+    if (!server) throw new Error("No server registered in EmojiManager");
+    if (this.parent.type === "Detached") throw new Error("Cannot edit a detached emoji");
+    return await server.emojis.edit(this, options);
+  }
 };
 
 // src/managers/EmojiManager.ts
@@ -3865,7 +3920,7 @@ var EmojiManager = class extends BaseManager {
    * Tell BaseManager how to find the ID for Emojis
    */
   extractId(data) {
-    return data._id ?? data.id;
+    return data._id;
   }
   /**
    * Tell BaseManager how to build an Emoji
@@ -3873,10 +3928,104 @@ var EmojiManager = class extends BaseManager {
   construct(data) {
     return new Emoji(this.client, data);
   }
-  async fetch(id) {
+  /**
+   * Fetch an Emoji from the API or resolves it from the local cache.
+   * @param emoji The ID, mention, or {@link Emoji} object to fetch
+   * @param force Whether to skip the cache check and force a direct API request. Defaults to false.
+   * @returns A promise that resolves to the fetched {@link Emoji} object.
+   * @throws {TypeError} If an invalid {@link EmojiResolvable} is provided.
+   * @throws {Error} If the API request fails.
+   * @example
+   * // Fetch a channel, bypassing cache
+   * const channel = await client.channels.fetch("01H...", true);
+   */
+  async fetch(emoji, force = false) {
+    if (!force) {
+      const cached = this.resolve(emoji);
+      if (cached) return cached;
+    }
+    const id = this.resolveId(emoji);
     const data = await this.client.rest.get(`/custom/emoji/${id}`);
     return this._add(data);
   }
+  /**
+   * Resolves a {@link EmojiResolvable} to a {@link Emoji} object from the cache.
+   * @param emoji The {@link EmojiResolvable} to resolve.
+   * @returns The resolved {@link Emoji} object, or undefined if not found.
+   */
+  resolve(emoji) {
+    if (emoji instanceof Emoji) return emoji;
+    if (typeof emoji === "string") {
+      const id = emoji.replace(/[<:>]/g, "");
+      return this.cache.get(id);
+    }
+    return void 0;
+  }
+  /**
+   * Extracts ID from a {@link EmojiResolvable}.
+   * @param emoji The {@link EmojiResolvable} to extract the ID from.
+   * @returns The extracted {@link Emoji} ID.
+   * @throws {TypeError} If an invalid type is provided.
+   */
+  resolveId(emoji) {
+    if (emoji instanceof Emoji) return emoji.id;
+    if (typeof emoji === "string") {
+      return emoji.replace(/:/g, "");
+    }
+    throw new Error("Invalid EmojiResolvable");
+  }
+  /**
+   * Create a new emoji
+   * @param options The options for creating the emoji
+   * @returns A promise that resolves to the created {@link Emoji} object.
+   * @throws {Error} If no server is registered in the {@link EmojiManager} or if the emoji attachment cannot be resolved.
+   * @example
+   * const emoji = await client.emojis.create(server, { emoji: "path/to/emoji.png", name: "myEmoji" });
+   */
+  async crate(options) {
+    if (!this.server) throw new Error("No server registered in EmojiManager");
+    const resolvedId = await resolveAttachment(this.client.rest, options.emoji, "emojis");
+    if (!resolvedId) throw new Error("Failed to resolve emoji attachment");
+    const payload = {
+      name: options.name,
+      parent: {
+        type: "Server",
+        id: this.server.id
+      }
+    };
+    if (options.nsfw) payload.nsfw = options.nsfw;
+    const data = await this.client.rest.put(`/custom/emoji/${resolvedId}`, payload);
+    return this._add(data);
+  }
+  /**
+   * Delete an emoji
+   * @param emoji The {@link EmojiResolvable} to delete
+   * @throws {Error} If no server is registered in the {@link EmojiManager}.
+   * @example
+   * await client.emojis.delete(emoji);
+   */
+  async delete(emoji) {
+    const id = this.resolveId(emoji);
+    await this.client.rest.delete(`/custom/emoji/${id}`);
+    this.cache.delete(id);
+  }
+  /**
+   * Edit an emoji
+   * @param emoji The {@link EmojiResolvable} to edit
+   * @param options The options to edit the emoji with
+   * @returns A promise that resolves to the edited {@link Emoji} object.
+   * @throws {Error} If no server is registered in the {@link EmojiManager}.
+   * @example
+   * const editedEmoji = await client.emojis.edit(emoji, { name: "newName" });
+   */
+  async edit(emoji, options) {
+    const id = this.resolveId(emoji);
+    const payload = {
+      name: options.name
+    };
+    const data = await this.client.rest.patch(`/custom/emoji/${id}`, payload);
+    return this._add(data);
+  }
   [util11.inspect.custom]() {
     return this.cache;
   }
@@ -4282,6 +4431,15 @@ var SweeperManager = class {
 
 // src/client/Client.ts
 var Client = class extends import_events2.EventEmitter {
+  rest;
+  gateway;
+  channels;
+  servers;
+  users;
+  sweepers;
+  emojis;
+  user = null;
+  options;
   constructor(options = {}) {
     super({ captureRejections: true });
     this.options = options;
@@ -4293,23 +4451,40 @@ var Client = class extends import_events2.EventEmitter {
     this.emojis = new EmojiManager(this, void 0, options.cacheLimits?.emojis);
     this.sweepers = new SweeperManager(this, options.sweepers ?? {});
   }
-  rest;
-  gateway;
-  channels;
-  servers;
-  users;
-  sweepers;
-  emojis;
-  user = null;
   /**
    * Connects the bot to the Stoat Gateway
    */
   async login(token) {
     if (!token) throw new Error("A valid token must be provided.");
-    this.sweepers.start();
+    const rootApiUrl = this.options.apiURL ?? "https://api.stoat.chat";
+    this.rest.setBaseURL(rootApiUrl);
     this.rest.setToken(token);
+    const configData = await this.fetchConfig(rootApiUrl);
+    const finalWsUrl = this.options.overrides?.wsURL ?? configData.ws;
+    if (!finalWsUrl) {
+      throw new Error(
+        `[Stoat Misconfiguration] The server at '${rootApiUrl}' is running, but it has no WebSocket URL configured. The server administrator needs to set their gateway config, or you must bypass it using 'options.overrides.wsURL'.`
+      );
+    }
+    this.gateway.setGatewayUrl(finalWsUrl);
+    const finalCdnUrl = this.options.overrides?.cdnURL ?? configData.features.autumn.url;
+    if (!finalCdnUrl) {
+      throw new Error(
+        `[Stoat Misconfiguration] The server at '${rootApiUrl}' is running, but it has no CDN URL configured. The server administrator needs to set their cdn config, or you must bypass it using 'options.overrides.cdnURL'.`
+      );
+    }
+    this.rest.setCDNURL(finalCdnUrl);
+    this.sweepers.start();
     return this.gateway.connect(token);
   }
+  async fetchConfig(baseURL) {
+    try {
+      const response = await fetch(baseURL);
+      return await response.json();
+    } catch (error) {
+      throw new Error(`Failed to fetch ${baseURL}, make sure the instance is running.`);
+    }
+  }
   [/* @__PURE__ */ Symbol.for("nodejs.rejection")](error) {
     this.emit("error", error);
   }