@stoatx/client 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -26,8 +26,8 @@ declare class StoatAPIError extends Error {
     apiType: string;
     location: string;
     rawData: any;
-    method?: string;
-    path?: string;
+    method?: string | undefined;
+    path?: string | undefined;
     constructor(statusCode: number, data: any, method?: string, path?: string);
 }
 declare class RESTManager {
@@ -217,9 +217,9 @@ declare class Collection<K, V> extends Map<K, V> {
  * @template Holds The type of the Structure this manager holds
  */
 declare abstract class BaseManager<K, Holds> {
-    client: Client;
     cache: Collection<K, Holds>;
-    constructor(client: Client, limit?: number);
+    protected readonly client: Client;
+    protected constructor(client: Client, limit?: number);
     /**
      * Defines how to extract the unique ID from a raw API payload.
      * @internal
@@ -264,8 +264,32 @@ declare class MemberManager extends BaseManager<string, Member> {
      * @internal
      */
     protected construct(data: any): Member;
+    /**
+     * Resolve a string or mention to Member
+     * @param member The MemberResolvable to resolve
+     * @returns The resolved Member or undefined if not found
+     */
     resolve(member: MemberResolvable): Member | undefined;
+    /**
+     * 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: MemberResolvable): string;
+    /**
+     * 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);
+     */
     fetch(member: MemberResolvable, force?: boolean): Promise<Member>;
     /**
      * Fetches multiple members from the server.
@@ -284,24 +308,50 @@ declare class MemberManager extends BaseManager<string, Member> {
      * 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"],
+     * });
      */
     edit(member: MemberResolvable, options: MemberEditOptions): Promise<Member>;
     /**
      * Kicks a member from the server.
      * @param member The MemberResolvable to kick.
+     * @example
+     * // Kick a member by ID
+     * await server.members.kick("1234567890");
      */
     kick(member: MemberResolvable): Promise<void>;
     /**
      * 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 });
      */
     ban(member: MemberResolvable, options?: MemberBanOptions): Promise<void>;
     /**
      * Unbans a user from the server
      * @param member The MemberResolvable to unban
+     * @example
+     * // Unban a member by ID
+     * await server.members.unban("1234567890");
      */
     unban(member: MemberResolvable): Promise<void>;
+    /**
+     * 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);
+     */
+    setTimeout(member: MemberResolvable, duration: number): Promise<void>;
     [util.inspect.custom](): Collection<string, Member>;
 }
 
@@ -356,7 +406,7 @@ declare class Permissions {
 
 declare class DMChannel extends BaseChannel {
     active: boolean;
-    recipients: DMChannel[];
+    recipients: string[];
     lastMessageId: string | null;
     constructor(client: any, data: any);
     _patch(data: any): void;
@@ -860,7 +910,7 @@ declare class RoleManager extends BaseManager<string, Role> {
      * 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.");
      *
@@ -1057,11 +1107,17 @@ declare class MemberRoleManager {
     set(roles: RoleResolvable[]): Promise<Member>;
 }
 
+/**
+ * Represents a member of a server on Stoat
+ *
+ * @extends {Base}
+ */
 declare class Member extends Base {
     serverId: string;
     nickname: string | null;
-    avatar: string | null;
-    roleIds: string[];
+    avatar: Attachment | null;
+    /** @internal */
+    private _roles;
     joinedAt: Date;
     timeout: Date | null;
     canPublish: boolean;
@@ -1069,30 +1125,63 @@ declare class Member extends Base {
     roles: MemberRoleManager;
     constructor(client: Client, data: any);
     _patch(data: any): void;
+    /**
+     * Get member role IDs
+     */
+    get roleIds(): string[];
     /** Gets the global User object for this member */
     get user(): User | undefined;
     /** Gets the Server object this member belongs to */
     get server(): Server | undefined;
-    /** Resolves the array of role strings into actual Role objects */
-    get roleObjects(): Role[];
     /** Calculates the member's total permissions using BigInt */
     get permissions(): bigint;
+    /** 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(): string | null;
+    /**
+     * 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 });
+     */
+    ban(options?: MemberBanOptions): Promise<void>;
+    /**
+     * 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}`);
+     */
+    createDM(force?: boolean): Promise<void>;
+    /**
+     * 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);
+     */
+    setTimeout(duration: number): Promise<void>;
     /** Checks if the member has a specific permission */
     hasPermission(permission: PermissionResolvable): boolean;
     /**
-     * Edits this member's nickname, avatar, roles, or timeout.
+     * 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.
      */
     edit(options: MemberEditOptions): Promise<this>;
     /**
-     * Kicks this member from the server.
+     * Kick this member from the server.
      */
     kick(): Promise<void>;
-    /**
-     * Bans this member from the server.
-     * @param options The options for this ban
-     */
-    ban(options?: MemberBanOptions): Promise<void>;
-    unban(): Promise<void>;
+    /** @internal */
     [util.inspect.custom](depth: number, options: util.InspectOptions, inspect: typeof util.inspect): string;
 }
 
@@ -1267,6 +1356,30 @@ declare class UserManager extends BaseManager<string, User> {
      * await client.users.editMe({ avatar: null, displayName: null });
      */
     editMe(options: UserEditOptions): Promise<User>;
+    /**
+     * The DM between the client's user and a user
+     *
+     * @param {string} userId The user id
+     * @returns {?DMChannel}
+     * @private
+     */
+    dmChannel(userId: string): DMChannel | 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}`);
+     */
+    createDM(user: UserResolvable, { force }?: {
+        force?: boolean | undefined;
+    }): Promise<DMChannel>;
 }
 
 /**

package/dist/index.d.ts

@@ -26,8 +26,8 @@ declare class StoatAPIError extends Error {
     apiType: string;
     location: string;
     rawData: any;
-    method?: string;
-    path?: string;
+    method?: string | undefined;
+    path?: string | undefined;
     constructor(statusCode: number, data: any, method?: string, path?: string);
 }
 declare class RESTManager {
@@ -217,9 +217,9 @@ declare class Collection<K, V> extends Map<K, V> {
  * @template Holds The type of the Structure this manager holds
  */
 declare abstract class BaseManager<K, Holds> {
-    client: Client;
     cache: Collection<K, Holds>;
-    constructor(client: Client, limit?: number);
+    protected readonly client: Client;
+    protected constructor(client: Client, limit?: number);
     /**
      * Defines how to extract the unique ID from a raw API payload.
      * @internal
@@ -264,8 +264,32 @@ declare class MemberManager extends BaseManager<string, Member> {
      * @internal
      */
     protected construct(data: any): Member;
+    /**
+     * Resolve a string or mention to Member
+     * @param member The MemberResolvable to resolve
+     * @returns The resolved Member or undefined if not found
+     */
     resolve(member: MemberResolvable): Member | undefined;
+    /**
+     * 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: MemberResolvable): string;
+    /**
+     * 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);
+     */
     fetch(member: MemberResolvable, force?: boolean): Promise<Member>;
     /**
      * Fetches multiple members from the server.
@@ -284,24 +308,50 @@ declare class MemberManager extends BaseManager<string, Member> {
      * 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"],
+     * });
      */
     edit(member: MemberResolvable, options: MemberEditOptions): Promise<Member>;
     /**
      * Kicks a member from the server.
      * @param member The MemberResolvable to kick.
+     * @example
+     * // Kick a member by ID
+     * await server.members.kick("1234567890");
      */
     kick(member: MemberResolvable): Promise<void>;
     /**
      * 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 });
      */
     ban(member: MemberResolvable, options?: MemberBanOptions): Promise<void>;
     /**
      * Unbans a user from the server
      * @param member The MemberResolvable to unban
+     * @example
+     * // Unban a member by ID
+     * await server.members.unban("1234567890");
      */
     unban(member: MemberResolvable): Promise<void>;
+    /**
+     * 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);
+     */
+    setTimeout(member: MemberResolvable, duration: number): Promise<void>;
     [util.inspect.custom](): Collection<string, Member>;
 }
 
@@ -356,7 +406,7 @@ declare class Permissions {
 
 declare class DMChannel extends BaseChannel {
     active: boolean;
-    recipients: DMChannel[];
+    recipients: string[];
     lastMessageId: string | null;
     constructor(client: any, data: any);
     _patch(data: any): void;
@@ -860,7 +910,7 @@ declare class RoleManager extends BaseManager<string, Role> {
      * 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.");
      *
@@ -1057,11 +1107,17 @@ declare class MemberRoleManager {
     set(roles: RoleResolvable[]): Promise<Member>;
 }
 
+/**
+ * Represents a member of a server on Stoat
+ *
+ * @extends {Base}
+ */
 declare class Member extends Base {
     serverId: string;
     nickname: string | null;
-    avatar: string | null;
-    roleIds: string[];
+    avatar: Attachment | null;
+    /** @internal */
+    private _roles;
     joinedAt: Date;
     timeout: Date | null;
     canPublish: boolean;
@@ -1069,30 +1125,63 @@ declare class Member extends Base {
     roles: MemberRoleManager;
     constructor(client: Client, data: any);
     _patch(data: any): void;
+    /**
+     * Get member role IDs
+     */
+    get roleIds(): string[];
     /** Gets the global User object for this member */
     get user(): User | undefined;
     /** Gets the Server object this member belongs to */
     get server(): Server | undefined;
-    /** Resolves the array of role strings into actual Role objects */
-    get roleObjects(): Role[];
     /** Calculates the member's total permissions using BigInt */
     get permissions(): bigint;
+    /** 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(): string | null;
+    /**
+     * 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 });
+     */
+    ban(options?: MemberBanOptions): Promise<void>;
+    /**
+     * 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}`);
+     */
+    createDM(force?: boolean): Promise<void>;
+    /**
+     * 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);
+     */
+    setTimeout(duration: number): Promise<void>;
     /** Checks if the member has a specific permission */
     hasPermission(permission: PermissionResolvable): boolean;
     /**
-     * Edits this member's nickname, avatar, roles, or timeout.
+     * 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.
      */
     edit(options: MemberEditOptions): Promise<this>;
     /**
-     * Kicks this member from the server.
+     * Kick this member from the server.
      */
     kick(): Promise<void>;
-    /**
-     * Bans this member from the server.
-     * @param options The options for this ban
-     */
-    ban(options?: MemberBanOptions): Promise<void>;
-    unban(): Promise<void>;
+    /** @internal */
     [util.inspect.custom](depth: number, options: util.InspectOptions, inspect: typeof util.inspect): string;
 }
 
@@ -1267,6 +1356,30 @@ declare class UserManager extends BaseManager<string, User> {
      * await client.users.editMe({ avatar: null, displayName: null });
      */
     editMe(options: UserEditOptions): Promise<User>;
+    /**
+     * The DM between the client's user and a user
+     *
+     * @param {string} userId The user id
+     * @returns {?DMChannel}
+     * @private
+     */
+    dmChannel(userId: string): DMChannel | 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}`);
+     */
+    createDM(user: UserResolvable, { force }?: {
+        force?: boolean | undefined;
+    }): Promise<DMChannel>;
 }
 
 /**