@stoatx/client 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -18,6 +18,18 @@ declare class GatewayManager {
     disconnect(): void;
 }
 
+/**
+ * Custom Error class for Stoat API failures
+ */
+declare class StoatAPIError extends Error {
+    statusCode: number;
+    apiType: string;
+    location: string;
+    rawData: any;
+    method?: string | undefined;
+    path?: string | undefined;
+    constructor(statusCode: number, data: any, method?: string, path?: string);
+}
 declare class RESTManager {
     private client;
     private baseURL;
@@ -205,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
@@ -252,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.
@@ -272,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>;
 }
 
@@ -344,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;
@@ -848,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.");
      *
@@ -1045,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;
@@ -1057,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;
 }
 
@@ -1255,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>;
 }
 
 /**
@@ -1335,4 +1460,4 @@ declare class UnknownChannel extends BaseChannel {
     constructor(client: Client, data: any);
 }
 
-export { Attachment, type AttachmentMetadata, Base, BaseChannel, type BotInformation, type Categories, type ChannelCreateOptions, type ChannelEditOptions, ChannelManager, type ChannelResolvable, type ChannelRolePermissionOptions, ChannelType, Client, type ClientEvents, type ClientOptions, ClientUser, Collection, DMChannel, EmbedBuilder, type FetchMembersOptions, GatewayManager, type Interaction, type Masquerade, Member, type MemberBanOptions, type MemberEditOptions, MemberManager, type MemberResolvable, Message, type MessageFetchOptions, MessageManager, type MessageOptions, type MessageResolvable, PermissionFlags, type PermissionResolvable, type PermissionString, Permissions, RESTManager, type ReplyIntent, Role, type RoleCreateOptions, type RoleEditOptions, RoleManager, type RolePermissionOptions, type RoleResolvable, Server, ServerChannelManager, type ServerEditOptions, ServerManager, SweeperManager, type SweeperOptions, TextChannel, type TextEmbedData, UnknownChannel, User, type UserEditOptions, UserManager, UserPresence, type UserProfile, UserRelationship, type UserResolvable, type UserStatus };
+export { Attachment, type AttachmentMetadata, Base, BaseChannel, type BotInformation, type Categories, type ChannelCreateOptions, type ChannelEditOptions, ChannelManager, type ChannelResolvable, type ChannelRolePermissionOptions, ChannelType, Client, type ClientEvents, type ClientOptions, ClientUser, Collection, DMChannel, EmbedBuilder, type FetchMembersOptions, GatewayManager, type Interaction, type Masquerade, Member, type MemberBanOptions, type MemberEditOptions, MemberManager, type MemberResolvable, Message, type MessageFetchOptions, MessageManager, type MessageOptions, type MessageResolvable, PermissionFlags, type PermissionResolvable, type PermissionString, Permissions, RESTManager, type ReplyIntent, Role, type RoleCreateOptions, type RoleEditOptions, RoleManager, type RolePermissionOptions, type RoleResolvable, Server, ServerChannelManager, type ServerEditOptions, ServerManager, StoatAPIError, SweeperManager, type SweeperOptions, TextChannel, type TextEmbedData, UnknownChannel, User, type UserEditOptions, UserManager, UserPresence, type UserProfile, UserRelationship, type UserResolvable, type UserStatus };

package/dist/index.d.ts

@@ -18,6 +18,18 @@ declare class GatewayManager {
     disconnect(): void;
 }
 
+/**
+ * Custom Error class for Stoat API failures
+ */
+declare class StoatAPIError extends Error {
+    statusCode: number;
+    apiType: string;
+    location: string;
+    rawData: any;
+    method?: string | undefined;
+    path?: string | undefined;
+    constructor(statusCode: number, data: any, method?: string, path?: string);
+}
 declare class RESTManager {
     private client;
     private baseURL;
@@ -205,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
@@ -252,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.
@@ -272,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>;
 }
 
@@ -344,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;
@@ -848,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.");
      *
@@ -1045,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;
@@ -1057,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;
 }
 
@@ -1255,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>;
 }
 
 /**
@@ -1335,4 +1460,4 @@ declare class UnknownChannel extends BaseChannel {
     constructor(client: Client, data: any);
 }
 
-export { Attachment, type AttachmentMetadata, Base, BaseChannel, type BotInformation, type Categories, type ChannelCreateOptions, type ChannelEditOptions, ChannelManager, type ChannelResolvable, type ChannelRolePermissionOptions, ChannelType, Client, type ClientEvents, type ClientOptions, ClientUser, Collection, DMChannel, EmbedBuilder, type FetchMembersOptions, GatewayManager, type Interaction, type Masquerade, Member, type MemberBanOptions, type MemberEditOptions, MemberManager, type MemberResolvable, Message, type MessageFetchOptions, MessageManager, type MessageOptions, type MessageResolvable, PermissionFlags, type PermissionResolvable, type PermissionString, Permissions, RESTManager, type ReplyIntent, Role, type RoleCreateOptions, type RoleEditOptions, RoleManager, type RolePermissionOptions, type RoleResolvable, Server, ServerChannelManager, type ServerEditOptions, ServerManager, SweeperManager, type SweeperOptions, TextChannel, type TextEmbedData, UnknownChannel, User, type UserEditOptions, UserManager, UserPresence, type UserProfile, UserRelationship, type UserResolvable, type UserStatus };
+export { Attachment, type AttachmentMetadata, Base, BaseChannel, type BotInformation, type Categories, type ChannelCreateOptions, type ChannelEditOptions, ChannelManager, type ChannelResolvable, type ChannelRolePermissionOptions, ChannelType, Client, type ClientEvents, type ClientOptions, ClientUser, Collection, DMChannel, EmbedBuilder, type FetchMembersOptions, GatewayManager, type Interaction, type Masquerade, Member, type MemberBanOptions, type MemberEditOptions, MemberManager, type MemberResolvable, Message, type MessageFetchOptions, MessageManager, type MessageOptions, type MessageResolvable, PermissionFlags, type PermissionResolvable, type PermissionString, Permissions, RESTManager, type ReplyIntent, Role, type RoleCreateOptions, type RoleEditOptions, RoleManager, type RolePermissionOptions, type RoleResolvable, Server, ServerChannelManager, type ServerEditOptions, ServerManager, StoatAPIError, SweeperManager, type SweeperOptions, TextChannel, type TextEmbedData, UnknownChannel, User, type UserEditOptions, UserManager, UserPresence, type UserProfile, UserRelationship, type UserResolvable, type UserStatus };