vantiv.io 1.0.0

package/typings/index.d.ts

@@ -0,0 +1,3820 @@
+/// <reference lib="dom" />
+
+type Facing = "FrontRight" | "FrontLeft" | "BackRight" | "BackLeft"
+type Reactions = 'clap' | 'heart' | 'thumbs' | 'wave' | 'wink'
+type PaymentMethods = "bot_wallet_only" | "bot_wallet_priority" | "user_wallet_only"
+type EventType =
+    | 'SessionMetadata'
+    | 'ChatEvent'
+    | 'WhisperEvent'
+    | 'UserMovedEvent'
+    | 'UserJoinedEvent'
+    | 'UserLeftEvent'
+    | 'MessageEvent'
+    | 'TipReactionEvent'
+    | 'RoomModeratedEvent'
+    | 'ChannelEvent'
+    
+type Goldbars = 1 | 5 | 10 | 50 | 100 | 500 | 1000 | 5000 | 10000
+type ItemCategory =
+    | "bag"
+    | "blush"
+    | "body"
+    | "dress"
+    | "earrings"
+    | "emote"
+    | "eye"
+    | "eyebrow"
+    | "face_hair"
+    | "fishing_rod"
+    | "freckle"
+    | "glasses"
+    | "gloves"
+    | "hair_back"
+    | "hair_front"
+    | "handbag"
+    | "hat"
+    | "jacket"
+    | "lashes"
+    | "mole"
+    | "mouth"
+    | "necklace"
+    | "nose"
+    | "pants"
+    | "shirt"
+    | "shoes"
+    | "shorts"
+    | "skirt"
+    | "watch"
+    | "fullsuit"
+    | "sock"
+    | "tattoo"
+    | "rod"
+    | "aura";
+
+type Rarity =
+    | "common"
+    | "uncommon"
+    | "rare"
+    | "epic"
+    | "legendary"
+    | "none_";
+
+type ChannelListenerCallback = (message: ChannelMessage) => void | Promise<void>;
+
+type RoomInviteOptions = {
+    room_id: string;
+    world_id?: never;
+};
+
+type WorldInviteOptions = {
+    world_id: string;
+    room_id?: never;
+};
+
+type CooldownMetadata = Record<string, any>;
+
+type InviteOptions = RoomInviteOptions | WorldInviteOptions;
+
+/**
+ * Chat event filter function
+ * @param user - The user who sent the message
+ * @param message - The message content
+ * @returns boolean indicating if the event matches the filter
+ */
+type ChatFilter = (user: User, message: string) => boolean;
+
+/**
+ * Whisper event filter function  
+ * @param user - The user who sent the whisper
+ * @param message - The whisper content
+ * @returns boolean indicating if the event matches the filter
+ */
+type WhisperFilter = (user: User, message: string) => boolean;
+
+/**
+ * Direct message event filter function
+ * @param user - The user who sent the direct message
+ * @param message - The message content
+ * @param conversation - The conversation information
+ * @returns boolean indicating if the event matches the filter
+ */
+type DirectFilter = (user: User, message: string, conversation: Conversation) => boolean;
+
+/**
+ * Tip event filter function
+ * @param sender - The user who sent the tip
+ * @param receiver - The user who received the tip  
+ * @param currency - The tip currency information
+ * @returns boolean indicating if the event matches the filter
+ */
+type TipFilter = (sender: Sender, receiver: Receiver, currency: Currency) => boolean;
+
+/**
+ * Movement event filter function
+ * @param user - The user who moved
+ * @param position - The new position of the user
+ * @param anchor - The anchor position if user is sitting, null if standing
+ * @returns boolean indicating if the movement matches the filter
+ */
+type MovementFilter = (user: User, position: Position, anchor: AnchorPosition | null) => boolean;
+
+
+interface User {
+    id: string;
+    username: string;
+}
+
+interface Sender extends User { }
+interface Receiver extends User { }
+
+interface Position {
+    x: number;
+    y: number;
+    z: number;
+    facing: string;
+}
+
+interface AnchorPosition {
+    entity_id: string;
+    anchor_ix: number;
+}
+
+interface WalletResponse {
+    gold: number;
+    boost_tokens: number;
+    voice_tokens: number;
+}
+
+interface PermissionStats {
+    webapiSyncs: number;
+    fileSaves: number;
+    lastSync: number;
+    lastSave: number;
+    roles: number;
+    users: number;
+    webapiModerators: number;
+    webapiDesigners: number;
+}
+
+interface RoleObjectStructure {
+    [roleName: string]: string[]
+}
+
+interface GetRoomPrivilegeResponse {
+    moderator: boolean;
+    designer: boolean;
+}
+
+interface GetConversationsResponse {
+    id: string;
+    did_join: boolean;
+    unread_count: number;
+    last_message: string;
+    muted: boolean;
+    member_ids: string[];
+    name: string | null;
+    owner_id: string | null
+}
+
+interface Currency {
+    type: string;
+    amount: number
+}
+
+interface GetMessagesResponse {
+    message_id: string,
+    conversation_id: string,
+    createdAt: Date,
+    content: string,
+    sender_id: string,
+    category: string
+}
+
+interface ReadyEventMetadata {
+    connection_id: string
+    rate_limits: {
+        client: [number, number],
+        socials: [number, number]
+    }
+}
+
+interface ModerationAction {
+    type: string;
+    duration: number
+}
+
+interface BotInformation {
+    user: User;
+    room: {
+        id: string;
+        name: string;
+        owner_id: string;
+    };
+}
+
+interface ReadyEvent {
+    bot_id: string;
+    room: {
+        owner_id: string;
+        room_name: string;
+    }
+    metadata: ReadyEventMetadata
+}
+
+interface MetricData {
+    uptime: string;
+    connected: boolean;
+    room: string;
+    messages: number;
+    events: number;
+    errors: number;
+    cache: {
+        users: number;
+        memory: string;
+        active: number;
+        changes: number;
+    };
+    pendingReq: {
+        fireForget: number;
+        reqRes: number;
+    };
+}
+
+interface LoggerOptions {
+    showTimestamp?: boolean;
+    showMethodName?: boolean;
+    colors?: boolean;
+}
+
+interface Conversation {
+    id: `1_on_1:${string}:${string}`
+    is_new_conversation: boolean;
+}
+
+interface Outfit {
+    type: string;
+    amount: number;
+    id: string;
+    account_bound: boolean;
+    active_palette: number | null;
+}
+
+interface GetInventoryResponse extends Outfit { }
+
+interface GetUserOutfitResponse extends Outfit { }
+
+interface getUserAvatarResponse {
+    success: boolean,
+    width: number,
+    height: number,
+    size: number
+}
+
+interface ValidVoiceCheck {
+    secondsLeft: number,
+    autoSpeakersId: string[],
+    users: object
+}
+
+interface InvalidVoiceCheck {
+    message: string
+}
+
+interface CooldownInfo {
+    expiresAt: number;
+    duration: number;
+    metadata: CooldownMetadata;
+    remainingMs: number;
+    remainingSeconds: number;
+    progress: number;
+}
+
+interface GlobalCooldownInfo {
+    expiresAt: number;
+    duration: number;
+    setAt: number;
+    remainingMs: number;
+}
+
+interface GroupConfig {
+    defaultDuration: number;
+    maxConcurrent: number;
+    perUserLimit: number | null;
+    [key: string]: any;
+}
+
+interface CheckGroupResult {
+    allowed: boolean;
+    reason?: 'max_concurrent' | 'user_limit' | 'user_cooldown';
+    duration?: number;
+    remainingMs?: number;
+    remainingSeconds?: number;
+    message?: string;
+}
+
+interface StartGroupResult {
+    success: boolean;
+    actionId?: string;
+    startedAt?: number;
+    duration?: number;
+    allowed?: boolean;
+    reason?: 'max_concurrent' | 'user_limit' | 'user_cooldown';
+    message?: string;
+    remainingMs?: number;
+}
+
+interface AttemptResult {
+    success: boolean;
+    onCooldown: boolean;
+    executed?: boolean;
+    result?: any;
+    error?: Error;
+    cooldownSet?: boolean;
+    durationMs?: number;
+    remainingMs?: number;
+    remainingSeconds?: number;
+    data?: CooldownMetadata;
+}
+
+interface UserCooldown {
+    key: string;
+    remainingMs: number;
+    expiresAt: number;
+    metadata: CooldownMetadata;
+}
+
+interface CooldownMemoryUsage {
+    cooldowns: string;
+    globals: string;
+    groups: string;
+    total: string;
+}
+
+interface GroupStats {
+    active: number;
+    totalUsage: number;
+    config: GroupConfig;
+}
+
+interface CooldownManagerStats {
+    totalChecks: number;
+    blockedActions: number;
+    successfulActions: number;
+    averageCooldownTime: number;
+    activeCooldowns: number;
+    activeGlobals: number;
+    groups: Record<string, GroupStats>;
+    memoryUsage: CooldownMemoryUsage;
+}
+
+interface EventMap {
+    UserLeft: [user: User]
+    Ready: [session: ReadyEvent]
+    Chat: [user: User, message: string]
+    Whisper: [user: User, message: string]
+    UserJoined: [user: User, position: Position]
+    Voice: [users: VoiceUser[], secondsLeft: number, ended: boolean]
+    Channel: [senderId: string, message: string, tags: string[]]
+    Tip: [sender: Sender, receiver: Receiver, currency: Currency]
+    Direct: [user: User, message: string, conversation: Conversation]
+    Moderation: [moderator: User, target: User, action: ModerationAction]
+    Movement: [user: User, position: Position | null, anchor: AnchorPosition | null]
+}
+
+
+
+interface CachedUser {
+    position: Position;
+    anchor: AnchorPosition | null;
+    lastSeen: number;
+    username: string;
+}
+
+interface CachedPosition extends Position {
+    lastUpdated: number;
+}
+
+interface SpatialUser {
+    user: User;
+    position: CachedPosition;
+    anchor: {
+        entity_id: string;
+        anchor_ix: number;
+    } | null;
+    lastSeen: number;
+}
+
+interface VoiceUser {
+    user: User,
+    /**
+     * Either "muted" or "voice"
+     */
+    status: string
+}
+
+interface SpatialUserWithDistance extends SpatialUser {
+    distance: number;
+}
+
+interface RectangleCorners {
+    c1: { x: number; z: number };
+    c2: { x: number; z: number };
+    c3: { x: number; z: number };
+    c4: { x: number; z: number };
+}
+
+interface WebApiUser {
+    id: string;
+    username: string;
+    bio: string;
+    joinedAt: string;
+    lastOnline: string;
+    followers: number;
+    following: number;
+    friends: number;
+    currentRoom: string;
+    country: string;
+    crew: string;
+    voiceEnabled: boolean;
+    discordConnected: boolean;
+    avatar: string;
+    icon: string;
+}
+
+interface BasicRoom {
+    id: string;
+    name: string;
+    description: string | null;
+    category: string;
+    createdAt: string | null;
+    accessPolicy: string;
+    ownerId: string;
+    languages: string[];
+    isHomeRoom: boolean;
+    designerIds: string[];
+    moderatorIds: string[];
+}
+
+interface DetailedRoom extends BasicRoom {
+    connectedUsers: number;
+    thumbnail: string;
+    banner: string;
+    crewId: string;
+    bots: any[];
+}
+
+interface RoomsListResponse {
+    rooms: BasicRoom[];
+    pagination: {
+        total: number;
+        firstId: string;
+        lastId: string;
+        hasMore: boolean;
+    };
+}
+
+interface PostBody {
+    text: string;
+    inventory: PostInventory | null;
+}
+
+interface PostInventory {
+    items: PostItem[];
+}
+
+interface PostItem {
+    itemId: string;
+    activePalette: number | null;
+    accountBound: boolean;
+}
+
+interface PostComment {
+    id: string;
+    content: string;
+    postId: string;
+    authorId: string;
+    authorName: string;
+    likes: number;
+}
+
+interface PostListItem {
+    id: string;
+    authorId: string | null;
+    createdAt: string | null;
+    type: string | null;
+    visibility: string;
+    stats: {
+        comments: number;
+        likes: number;
+        reposts: number;
+    };
+    content: {
+        text: string;
+        hasBody: boolean;
+        caption: string | null;
+    };
+    fileKey: string | null;
+    featuredUserIds: string[];
+    inventory: PostInventory | null;
+    body: PostBody | null;
+}
+
+interface Post extends PostListItem {
+    comments: PostComment[];
+}
+
+interface PostsListResponse {
+    posts: PostListItem[];
+    pagination: {
+        total: number;
+        firstId: string;
+        lastId: string;
+        hasMore: boolean;
+    };
+}
+
+interface Affiliation {
+    id: string;
+    title: string;
+    type: string;
+    eventType: string | null;
+}
+
+interface OutfitItem {
+    itemId: string;
+    name: string;
+    rarity: string;
+    activePalette: number;
+    parts: number;
+    colors: OutfitItemColors | null;
+    linkedColors: string;
+}
+
+interface Seller {
+    userId: string;
+    username: string;
+    outfit: OutfitItem[];
+    lastConnectedAt: any | null;
+}
+
+
+interface StorefrontListings {
+    sellers: Seller[];
+    pages: number;
+    total: number;
+}
+
+interface OutfitItemColors {
+    linkedColors: string;
+}
+
+interface SkinPart {
+    bone: string;
+    slot: string;
+    imageFile: string;
+    attachmentName: string | null;
+    hasRemoteRenderLayer: boolean | null;
+}
+
+interface Item {
+    id: string;
+    name: string;
+    category: any | null;
+    colorLinkedCategories: any | null;
+    colorPalettes: any | null;
+    createdAt: any | null;
+    description: string | null;
+    pricing: {
+        gems: number | null;
+        pops: number | null;
+    };
+    properties: {
+        isPurchasable: boolean;
+        isTradable: boolean;
+    };
+    images: {
+        main: string | null;
+        icon: string | null;
+    };
+    links: {
+        linkIds: string[];
+        inspiredBy: any | null;
+    };
+    skinParts: {
+        front: SkinPart[];
+        back: SkinPart[];
+    };
+    metadata: {
+        dependentColors: any | null;
+        releaseDate: any | null;
+        keywords: any | null;
+    };
+}
+
+interface ItemsSearchResponse {
+    items: Item[];
+    pagination: {
+        total: number;
+        hasMore: boolean;
+        skip: number;
+    };
+}
+
+interface ItemDetail extends Item {
+    acquisition: {
+        cost: number | null;
+        amount: number | null;
+        currency: string | null;
+    };
+    metadata: {
+        dependentColors: any[];
+        releaseDate: any | null;
+        keywords: any | null;
+    };
+    relatedItems: {
+        items: Array<{
+            id: string;
+            name: string;
+        }>;
+    } | null;
+    affiliations: Affiliation[];
+    storefrontListings: StorefrontListings | null;
+}
+
+interface ItemsListResponse {
+    items: Item[];
+    pagination: {
+        total: number;
+        firstId: string;
+        lastId: string;
+        hasMore: boolean;
+    };
+}
+
+interface Grab {
+    id: string;
+    title: string;
+    description: string;
+    bannerImgUrl: string;
+    startsAt: any | null;
+    expiresAt: any | null;
+    rewards: GrabReward[];
+    costs: GrabCost[];
+    kompuRewards: GrabReward[];
+    limitedTimeKompu: LimitedKompu | null;
+    progressReward: ProgressReward | null;
+}
+
+interface GrabReward {
+    amount: number;
+    rewardId: string;
+    itemId: string | null;
+    accountBound: boolean;
+    metadata: any | null;
+    nfiMetadata: any | null;
+    itemNumber: number;
+    stackId: string;
+    nfiTemplateMetadata: any | null;
+    totalAmount: number | null;
+    bannerItem: boolean;
+    primaryImgUrl: string | null;
+    secondaryImgUrl: string | null;
+    isTradable: boolean;
+}
+
+interface GrabCost {
+    amount: number;
+    rewardId: string;
+    itemId: string | null;
+    accountBound: boolean;
+    metadata: any | null;
+    nfiMetadata: any | null;
+    itemNumber: number;
+    stackId: string;
+    nfiTemplateMetadata: any | null;
+    totalAmount: number | null;
+    bannerItem: boolean;
+}
+
+interface LimitedKompu {
+    expiresAt: any | null;
+    rewards: GrabReward[];
+}
+
+interface ProgressReward {
+    rewardsAt: number;
+    rewards: GrabReward[];
+}
+
+interface ItemsSearchParams {
+    /**
+     * Maximum number of items to return (default: 20, max: 100, min: 1)
+     */
+    limit?: number;
+
+    /**
+     * Number of items to skip (for pagination), default: 0
+     */
+    skip?: number;
+
+    /**
+     * Search query for item names
+     * @example 
+     * 'Fiery Creature Eyes'
+     */
+    query?: string;
+}
+
+interface RoomsParams {
+    /**
+     * Maximum number of rooms to return (default: 20, max: 100, min: 1)
+     */
+    limit?: number;
+
+    /**
+     * Sort order for the results
+     * - `asc`: Oldest rooms first
+     * - `desc`: Newest rooms first (default)
+     */
+    sort_order?: 'asc' | 'desc';
+
+    /**
+     * Filter rooms by owner user ID
+     * @example '68a7dd5eecae68acca580f41'
+     */
+    owner_id?: string;
+
+    /**
+     * Filter rooms by name (partial match)
+     */
+    room_name?: string;
+
+    /**
+     * Pagination cursor - get rooms created after this room ID
+     * Used for forward pagination
+     * @example '692505a6bf18ebcc157260ec'
+     */
+    starts_after?: string;
+
+    /**
+     * Pagination cursor - get rooms created before this room ID  
+     * Used for backward pagination
+     * @example '68a7dd5eecae68acca580f41'
+     */
+    ends_before?: string;
+}
+
+interface PostsParams {
+    /**
+     * Maximum number of posts to return (default: 20, max: 100, min: 1)
+     */
+    limit?: number;
+
+    /**
+     * Sort order for the results
+     * - `asc`: Oldest posts first
+     * - `desc`: Newest posts first (default)
+     */
+    sort_order?: 'asc' | 'desc';
+
+    /**
+     * Filter posts by author user ID
+     * @example '68a7dd5eecae68acca580f41'
+     */
+    author_id?: string;
+
+    /**
+     * Pagination cursor - get posts created after this post ID
+     * Used for forward pagination
+     * @example 'post_123456'
+     */
+    starts_after?: string;
+
+    /**
+     * Pagination cursor - get posts created before this post ID
+     * Used for backward pagination
+     * @example 'post_789012'
+     */
+    ends_before?: string;
+}
+
+interface ItemsParams {
+    /**
+     * Maximum number of items to return (default: 20, max: 100, min: 1)
+     */
+    limit?: number;
+
+    /**
+     * Sort order for the results
+     * - `asc`: Oldest items first
+     * - `desc`: Newest items first (default)
+     */
+    sort_order?: 'asc' | 'desc';
+
+    /**
+     * Filter items by rarity
+     * @example Rarity.RARE
+     * @example Rarity.EPIC
+     */
+    rarity?: Rarity;
+
+    /**
+     * Filter items by name (partial match)
+     * @example 
+     * 'Fiery Creature Eyes'
+     */
+    item_name?: string;
+
+    /**
+     * Filter items by category
+     * @example ItemCategory.SHIRT
+     * @example ItemCategory.HAT
+     */
+    category?: ItemCategory;
+
+    /**
+     * Pagination cursor - get items created after this item ID
+     * Used for forward pagination
+     * @example 'item_123456'
+     */
+    starts_after?: string;
+
+    /**
+     * Pagination cursor - get items created before this item ID
+     * Used for backward pagination
+     * @example 'item_789012'
+     */
+    ends_before?: string;
+}
+
+interface DanceEmote {
+    id: string;
+    name: string;
+    duration: number;
+}
+
+interface DancingPlayer {
+    id: string;
+    username: string;
+    position: any;
+    timeoutId: NodeJS.Timeout
+    emoteIndex: number;
+}
+
+interface DanceFloorCorners {
+    x: number;
+    y: number;
+    z: number;
+    x1: number;
+    z1: number;
+    y1: number;
+}
+
+interface DanceFloorConfig {
+    id: string;
+    corners: DanceFloorCorners;
+    emotes: DanceEmote[];
+    players: DancingPlayer[];
+    filePath?: string;
+    hasWatcher?: boolean
+}
+
+/**
+ * Represents a hidden channel message
+ * Used for bot-to-bot communication within the same room
+ */
+interface ChannelMessage {
+    /**
+     * Unique identifier for the message (UUID v4)
+     * @example "123e4567-e89b-12d3-a456-426614174000"
+     */
+    id: string;
+
+    /**
+     * The actual message content
+     * Can be any string data (JSON, plain text, etc.)
+     * @example "{\"username\":\"Player1\",\"action\":\"kicked\",\"reason\":\"spamming\"}"
+     * @example "Game started! Round 1"
+     */
+    message: string;
+
+    /**
+     * Normalized tags for categorization and filtering
+     * Tags are sorted alphabetically and in lowercase
+     * @example ["game", "start", "room-123"]
+     * @example ["moderation", "kick", "chat"]
+     */
+    tags: string[];
+
+    /**
+     * Unix timestamp in milliseconds when the message was stored locally
+     * @example 1703000000000
+     */
+    timestamp: number;
+
+    /**
+     * ID of the bot/user who sent the message
+     * @example "68a7dd5eecae68acca580f41"
+     */
+    senderId: string;
+
+    /**
+     * Whether this message was sent by the current bot instance
+     * - `true`: Message was sent by this bot
+     * - `false`: Message was received from another bot
+     */
+    sent: boolean;
+}
+
+/**
+ * Filter criteria for querying channel messages
+ */
+interface ChannelFilter {
+    /**
+     * Tags to filter messages by
+     * All specified tags must be present in the message
+     * @example ["game", "start"] - Only messages with BOTH "game" AND "start" tags
+     * @example ["moderation"] - Only messages with "moderation" tag
+     */
+    tags?: string | string[];
+
+    /**
+     * Start timestamp in milliseconds (inclusive)
+     * Only messages with timestamp >= since will be returned
+     * @default 0 (no lower bound)
+     * @example Date.now() - 3600000 // Last hour
+     */
+    since?: number;
+
+    /**
+     * End timestamp in milliseconds (inclusive)
+     * Only messages with timestamp <= until will be returned
+     * @default Date.now() (current time)
+     * @example Date.now() - 60000 // Up to 1 minute ago
+     */
+    until?: number;
+
+    /**
+     * Maximum number of messages to return
+     * @default 50
+     * @minimum 1
+     * @maximum 1000
+     * @example 10 - Return only 10 most recent messages
+     */
+    limit?: number;
+}
+
+/**
+ * Statistics about the channel system
+ */
+interface ChannelStats {
+    /**
+     * Total number of messages currently stored in history
+     * Older messages are automatically removed (max 500)
+     * @example 127
+     */
+    totalMessages: number;
+
+    /**
+     * Number of active listeners/subscriptions
+     * @example 3
+     */
+    listeners: number;
+}
+
+declare class RoleManager {
+    /**
+     * Create a new custom role
+     * @param roleName - Name of the role (any string)
+     * @returns True if created, false if already exists
+     */
+    createRole(roleName: string): boolean;
+
+    /**
+     * Add user to a role
+     * @param roleName - Role to add to
+     * @param userId - User ID to add
+     * @returns True if added, false if already in role
+     */
+    addToRole(roleName: string, userId: string): boolean;
+
+    /**
+     * Remove user from a role
+     * @param roleName - Role to remove from
+     * @param userId - User ID to remove
+     * @returns True if removed, false if not in role
+     */
+    removeFromRole(roleName: string, userId: string): boolean;
+
+    /**
+     * Check if user is in a role
+     * @param roleName - Role to check
+     * @param userId - User ID to check
+     * @returns True if user has the role
+     */
+    hasRole(roleName: string, userId: string): boolean;
+
+    /**
+     * Check if user is in any of the given roles
+     * @param roleNames - Array of roles to check
+     * @param userId - User ID to check
+     * @returns True if user has any of the roles
+     */
+    hasAnyRole(roleNames: string[], userId: string): boolean;
+
+    /**
+     * Get all roles a user is in
+     * @param userId - User ID to check
+     * @returns Array of role names
+     */
+    getUserRoles(userId: string): string[];
+
+    /**
+     * Get all users in a role
+     * @param roleName - Role to get users from
+     * @returns Array of user IDs
+     */
+    getUsersInRole(roleName: string): string[];
+
+    /**
+     * Get all role names
+     * @returns Array of all role names
+     */
+    getAllRoles(): string[];
+
+    /**
+     * Delete a role completely
+     * @param roleName - Role to delete
+     * @returns True if deleted
+     */
+    deleteRole(roleName: string): boolean;
+
+    /**
+     * Rename a role
+     * @param oldName - Current role name
+     * @param newName - New role name
+     * @returns True if renamed
+     */
+    renameRole(oldName: string, newName: string): boolean;
+
+    /**
+     * Check if user is owner (has 'owner' role)
+     * @param userId - User ID to check
+     * @returns True if user is owner
+     */
+    isOwner(userId: string): boolean;
+
+    /**
+     * Check if user is moderator (has 'moderator' role or from Web API)
+     * @param userId - User ID to check
+     * @returns True if user is moderator
+     */
+    isModerator(userId: string): boolean;
+
+    /**
+     * Check if user is designer (has 'designer' role or from Web API)
+     * @param userId - User ID to check
+     * @returns True if user is designer
+     */
+    isDesigner(userId: string): boolean;
+
+    /**
+     * Get all moderators (combined from role + Web API)
+     * @returns Array of all moderator user IDs
+     */
+    getAllModerators(): string[];
+
+    /**
+     * Get all designers (combined from role + Web API)
+     * @returns Array of all designer user IDs
+     */
+    getAllDesigners(): string[];
+
+    /**
+     * Force immediate sync with Web API and save to file
+     * @returns Promise that resolves when sync is complete
+     */
+    forceSync(): Promise<void>;
+
+    /**
+     * Export roles as JSON object
+     * @returns Object with role names as keys and user ID arrays as values
+     */
+    exportToObject(): RoleObjectStructure;
+
+    /**
+     * Import roles from JSON object
+     * @param obj - Object with role names as keys and user ID arrays as values
+     * @returns True if imported successfully
+     */
+    importFromObject(obj: RoleObjectStructure): boolean;
+
+    /**
+     * Clear all roles and Web API data
+     */
+    clearAll(): void;
+
+    /**
+     * Get sync statistics
+     */
+    getStats(): PermissionStats;
+}
+
+declare class CooldownManager {
+    /**
+     * The manager handles individual cooldowns, global cooldowns (affecting all users),
+     * and group-based cooldowns with rate limiting capabilities.
+     * 
+     * @example
+     * const cooldown = new CooldownManager();
+     * cooldown.startAutoCleanup(); // Optional: auto-clean expired cooldowns
+     */
+    constructor();
+
+    /**
+     * Sets a cooldown for a specific key. If the key is already on cooldown,
+     * returns false and doesn't override the existing cooldown.
+     * 
+     * @param key - Unique identifier for the cooldown. Common patterns:
+     *   - `user:{userId}:{command}` for user-specific command cooldowns
+     *   - `item:{itemId}:{userId}` for item usage cooldowns
+     *   - `action:{action}:{target}` for specific action cooldowns
+     * @param durationMs - Cooldown duration in milliseconds
+     * @param metadata - Optional metadata to store with the cooldown for later retrieval
+     * @returns `true` if cooldown was set successfully, `false` if key was already on cooldown
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Set a 5-second cooldown for a user's dance command
+     * const wasSet = cooldown.set(`user:${userId}:!dance`, 5000, {
+     *   command: 'dance',
+     *   timestamp: Date.now()
+     * });
+     * 
+     * @example
+     * // Prevent item spam - 30 seconds between using the same item
+     * cooldown.set(`item:teleport_scroll:${userId}`, 30000, {
+     *   itemName: 'Teleport Scroll',
+     *   usageCount: 1
+     * });
+     */
+    set(key: string, durationMs: number, metadata?: CooldownMetadata): boolean;
+
+    /**
+     * Checks if a key is currently on cooldown. Automatically cleans up
+     * expired cooldowns unless disabled.
+     * 
+     * @param key - The key to check for active cooldown
+     * @param autoCleanup - If `true` (default), automatically removes expired cooldowns
+     * @returns Cooldown information object if active, `null` if not on cooldown or expired
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * const cooldownInfo = cooldown.check(`user:${userId}:!dance`);
+     * if (cooldownInfo) {
+     *   // Still on cooldown
+     *   console.log(`Wait ${cooldownInfo.remainingSeconds} more seconds`);
+     *   console.log(`Progress: ${(cooldownInfo.progress * 100).toFixed(1)}% complete`);
+     * }
+     * 
+     * @example
+     * // Manual cleanup control
+     * const cooldownInfo = cooldown.check(key, false); // Don't auto-clean
+     * if (cooldownInfo && cooldownInfo.remainingMs < 100) {
+     *   // Almost expired, handle special case
+     * }
+     */
+    check(key: string, autoCleanup?: boolean): CooldownInfo | null;
+
+    /**
+     * Gets the remaining time in milliseconds for a cooldown.
+     * Returns 0 if the key is not on cooldown.
+     * 
+     * @param key - The key to check
+     * @returns Milliseconds remaining until cooldown expires, or 0 if no active cooldown
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * const remaining = cooldown.getRemaining(`user:${userId}:!dance`);
+     * if (remaining > 0) {
+     *   // Format and display to user
+     *   const seconds = Math.ceil(remaining / 1000);
+     *   bot.whisper.send(userId, `Please wait ${seconds} seconds`);
+     * }
+     */
+    getRemaining(key: string): number;
+
+    /**
+     * Attempts to execute an action if not on cooldown. If the key is not on cooldown,
+     * sets the cooldown and optionally executes the callback. If on cooldown,
+     * returns information about the remaining time without executing the callback.
+     * 
+     * @param key - The key to check and set cooldown for
+     * @param durationMs - Cooldown duration to set if successful
+     * @param callback - Optional function to execute if not on cooldown
+     * @returns Result object containing success status, remaining time (if on cooldown),
+     *          or execution result (if callback was executed)
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Basic usage with callback
+     * const result = cooldown.attempt(`user:${userId}:!dance`, 3000, () => {
+     *   // This only executes if not on cooldown
+     *   bot.player.emote('dance', userId);
+     *   return 'dance_started';
+     * });
+     * 
+     * if (!result.success) {
+     *   // On cooldown - inform user
+     *   bot.whisper.send(userId, `Wait ${result.remainingSeconds} seconds`);
+     * } else if (result.executed) {
+     *   // Callback was executed
+     *   console.log('Result:', result.result);
+     * }
+     * 
+     * @example
+     * // Without callback (just checks and sets)
+     * const result = cooldown.attempt(`user:${userId}:action`, 5000);
+     * if (result.success) {
+     *   // Not on cooldown, cooldown was set
+     *   // Proceed with action...
+     * }
+     */
+    attempt(key: string, durationMs: number, callback?: (() => any) | null): AttemptResult;
+
+    /**
+     * Removes an active cooldown for a specific key.
+     * 
+     * @param key - The key to remove cooldown for
+     * @returns `true` if cooldown existed and was removed, `false` if no cooldown existed
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Admin override - remove user's cooldown
+     * if (isAdmin(adminId)) {
+     *   const removed = cooldown.remove(`user:${targetUserId}:!dance`);
+     *   if (removed) {
+     *     bot.whisper.send(targetUserId, 'Your cooldown was cleared by admin');
+     *   }
+     * }
+     * 
+     * @example
+     * // Error recovery - remove stuck cooldown
+     * if (errorOccurred) {
+     *   cooldown.remove(`user:${userId}:!purchase`);
+     *   // Allow user to retry
+     * }
+     */
+    remove(key: string): boolean;
+
+    /**
+     * Clears all cooldowns, or only those matching a prefix.
+     * 
+     * @param prefix - Optional prefix to filter keys. If provided, only clears
+     *                cooldowns whose keys start with this prefix.
+     * @returns Number of cooldowns that were cleared
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Clear all cooldowns (server reset)
+     * const clearedAll = cooldown.clear();
+     * console.log(`Cleared ${clearedAll} cooldowns`);
+     * 
+     * @example
+     * // Clear only user-related cooldowns
+     * const clearedUsers = cooldown.clear('user:');
+     * 
+     * @example
+     * // Clear cooldowns for specific user
+     * const clearedUser = cooldown.clear(`user:${userId}:`);
+     * 
+     * @example
+     * // Clear daily cooldowns
+     * const clearedDaily = cooldown.clear('daily:');
+     */
+    clear(prefix?: string | null): number;
+
+    /**
+     * Sets a global cooldown that affects all users. Useful for system-wide
+     * events, maintenance, or world events.
+     * 
+     * @param action - Unique identifier for the global action
+     * @param durationMs - Duration in milliseconds
+     * @returns `true` if global cooldown was set, `false` if already active
+     * 
+     * @example
+     * // System maintenance
+     * cooldown.setGlobal('maintenance', 300000); // 5 minutes
+     * 
+     * @example
+     * // World boss spawn cooldown
+     * cooldown.setGlobal('world_boss_spawn', 3600000); // 1 hour
+     * 
+     * @example
+     * // Limited-time event
+     * cooldown.setGlobal('halloween_event', 604800000); // 7 days
+     */
+    setGlobal(action: string, durationMs: number): boolean;
+
+    /**
+     * Checks if a global cooldown is currently active.
+     * 
+     * @param action - The global action identifier
+     * @returns Global cooldown information if active, `null` if not active
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Check if system is in maintenance
+     * const maintenance = cooldown.checkGlobal('maintenance');
+     * if (maintenance) {
+     *   bot.message.send(`🛠️ Maintenance in progress for ${cooldown.formatTime(maintenance.remainingMs)}`);
+     *   return;
+     * }
+     * 
+     * @example
+     * // Check world boss availability
+     * const bossCooldown = cooldown.checkGlobal('world_boss_spawn');
+     * if (bossCooldown) {
+     *   const timeStr = cooldown.formatTime(bossCooldown.remainingMs);
+     *   bot.message.send(`The world boss will respawn in ${timeStr}`);
+     * } else {
+     *   // Spawn boss logic
+     * }
+     */
+    checkGlobal(action: string): GlobalCooldownInfo | null;
+
+    /**
+     * Creates a cooldown group for managing limited resources with
+     * configurable concurrency and per-user limits.
+     * 
+     * @param groupName - Unique name for the group
+     * @param config - Configuration object for the group
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Create a teleporter with max 3 concurrent users, 10s cooldown per user
+     * cooldown.createGroup('main_teleporter', {
+     *   defaultDuration: 10000,
+     *   maxConcurrent: 3,
+     *   perUserLimit: 1
+     * });
+     * 
+     * @example
+     * // Game table - only 1 game at a time, 5 minute games
+     * cooldown.createGroup('poker_table', {
+     *   defaultDuration: 300000,
+     *   maxConcurrent: 1,
+     *   perUserLimit: 1
+     * });
+     * 
+     * @example
+     * // Fishing spot - many can fish, but limited lines per user
+     * cooldown.createGroup('fishing_spot', {
+     *   defaultDuration: 30000,
+     *   maxConcurrent: 10,
+     *   perUserLimit: 3
+     * });
+     */
+    createGroup(groupName: string, config?: Partial<GroupConfig>): void;
+
+    /**
+     * Checks if a user can perform an action in a group, considering
+     * max concurrent limits and per-user limits.
+     * 
+     * @param groupName - The group to check
+     * @param userId - Optional user ID to check per-user limits
+     * @returns Object indicating if action is allowed and reason if not
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Check if user can teleport
+     * const check = cooldown.checkGroup('main_teleporter', userId);
+     * if (!check.allowed) {
+     *   switch (check.reason) {
+     *     case 'max_concurrent':
+     *       return 'Teleporter is busy! Wait for others to finish.';
+     *     case 'user_limit':
+     *       return 'You are already teleporting!';
+     *     case 'user_cooldown':
+     *       return `You just teleported! Wait ${check.remainingSeconds}s`;
+     *   }
+     * }
+     * 
+     * @example
+     * // Check resource availability without user context
+     * const resourceCheck = cooldown.checkGroup('mining_vein');
+     * if (!resourceCheck.allowed && resourceCheck.reason === 'max_concurrent') {
+     *   return 'This mining vein is fully occupied!';
+     * }
+     */
+    checkGroup(groupName: string, userId?: string | null): CheckGroupResult;
+
+    /**
+     * Starts an action in a group, consuming a slot and setting user cooldown.
+     * Returns detailed result including unique action ID for later ending.
+     * 
+     * @param groupName - The group to start action in
+     * @param actionId - Unique identifier for this specific action instance
+     * @param userId - Optional user ID for per-user tracking
+     * @returns Detailed result with success status and action information
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Start a teleport action
+     * const actionId = `teleport:${Date.now()}:${userId}`;
+     * const result = cooldown.startGroupAction('main_teleporter', actionId, userId);
+     * 
+     * if (!result.success) {
+     *   return result.message; // "Teleporter is busy!" etc.
+     * }
+     * 
+     * // Store actionId for later cleanup
+     * currentTeleports.set(userId, {
+     *   actionId: result.actionId,
+     *   startedAt: result.startedAt
+     * });
+     * 
+     * // When teleport completes
+     * cooldown.endGroupAction('main_teleporter', result.actionId);
+     * 
+     * @example
+     * // Start a game session
+     * const gameId = `chess:${Date.now()}:${player1}:${player2}`;
+     * const gameResult = cooldown.startGroupAction('chess_table', gameId, player1);
+     * // Note: Only first player consumes per-user limit
+     */
+    startGroupAction(groupName: string, actionId: string, userId?: string | null): StartGroupResult;
+
+    /**
+     * Ends an action in a group, freeing up the slot for others.
+     * 
+     * @param groupName - The group containing the action
+     * @param actionId - The unique action ID to end
+     * @returns `true` if action existed and was ended, `false` if not found
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // When teleport completes
+     * const actionId = currentTeleports.get(userId)?.actionId;
+     * if (actionId) {
+     *   const ended = cooldown.endGroupAction('main_teleporter', actionId);
+     *   if (ended) {
+     *     currentTeleports.delete(userId);
+     *     bot.whisper.send(userId, 'Teleport complete!');
+     *   }
+     * }
+     * 
+     * @example
+     * // Game completion
+     * function endGame(gameId: string) {
+     *   cooldown.endGroupAction('poker_table', gameId);
+     *   // Also remove user cooldowns if needed
+     *   cooldown.remove(`poker_cooldown:${player1}`);
+     *   cooldown.remove(`poker_cooldown:${player2}`);
+     * }
+     */
+    endGroupAction(groupName: string, actionId: string): boolean;
+
+    /**
+     * Gets all active cooldowns for a specific user. Useful for displaying
+     * user's current restrictions or detecting potential abuse.
+     * 
+     * @param userId - The user ID to get cooldowns for
+     * @returns Array of active cooldown objects for the user
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Display user's active cooldowns
+     * const userCooldowns = cooldown.getUserCooldowns(userId);
+     * if (userCooldowns.length > 0) {
+     *   const cooldownList = userCooldowns.map(c => 
+     *     `${c.metadata.command || 'Action'}: ${Math.ceil(c.remainingMs/1000)}s`
+     *   ).join('\n');
+     *   bot.whisper.send(userId, `Your active cooldowns:\n${cooldownList}`);
+     * }
+     * 
+     * @example
+     * // Detect potential abusers
+     * const userCooldowns = cooldown.getUserCooldowns(userId);
+     * if (userCooldowns.length > 15) {
+     *   bot.utils.logger.warn('High cooldown count', { userId, count: userCooldowns.length });
+     *   // Consider temporary restriction
+     * }
+     * 
+     * @example
+     * // Admin view of user restrictions
+     * function getUserStatus(userId: string) {
+     *   const cooldowns = cooldown.getUserCooldowns(userId);
+     *   return {
+     *     userId,
+     *     activeRestrictions: cooldowns.length,
+     *     restrictions: cooldowns.map(c => ({
+     *       type: c.key.split(':')[1],
+     *       remaining: cooldown.formatTime(c.remainingMs),
+     *       reason: c.metadata.reason
+     *     }))
+     *   };
+     * }
+     */
+    getUserCooldowns(userId: string): UserCooldown[];
+
+    /**
+     * Gets comprehensive usage statistics and current state of the cooldown manager.
+     * Useful for monitoring, debugging, and performance analysis.
+     * 
+     * @returns Statistics object containing usage metrics, current counts, and memory estimates
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Periodic monitoring
+     * setInterval(() => {
+     *   const stats = cooldown.getStats();
+     *   const successRate = (stats.successfulActions / stats.totalChecks * 100).toFixed(1);
+     *   
+     *   console.log(`
+     *   Cooldown Stats:
+     *   - Success Rate: ${successRate}%
+     *   - Active Cooldowns: ${stats.activeCooldowns}
+     *   - Memory Usage: ${stats.memoryUsage.total}
+     *   - Blocked Actions: ${stats.blockedActions}
+     *   `);
+     *   
+     *   // Check group status
+     *   for (const [groupName, groupStats] of Object.entries(stats.groups)) {
+     *     console.log(`${groupName}: ${groupStats.active}/${groupStats.config.maxConcurrent} active`);
+     *   }
+     * }, 60000); // Log every minute
+     * 
+     * @example
+     * // Dashboard endpoint
+     * function getSystemStatus() {
+     *   const stats = cooldown.getStats();
+     *   return {
+     *     uptime: Date.now() - startTime,
+     *     cooldownStats: stats,
+     *     health: stats.activeCooldowns < 1000 ? 'healthy' : 'warning'
+     *   };
+     * }
+     * 
+     * @example
+     * // Debugging high memory usage
+     * if (memoryIsHigh()) {
+     *   const stats = cooldown.getStats();
+     *   console.log('Memory breakdown:', stats.memoryUsage);
+     *   // Clear old cooldowns if memory is high
+     *   if (stats.activeCooldowns > 500) {
+     *     cooldown.clear('old:'); // Assuming you prefix old cooldowns
+     *   }
+     * }
+     */
+    getStats(): CooldownManagerStats;
+
+    /**
+     * Starts automatic background cleanup of expired cooldowns.
+     * Recommended for long-running applications to prevent memory buildup.
+     * 
+     * @param intervalMs - Cleanup interval in milliseconds (default: 60000 = 1 minute)
+     * @returns The interval ID that can be used to stop cleanup
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Start with default 1-minute interval
+     * cooldown.startAutoCleanup();
+     * 
+     * @example
+     * // More frequent cleanup for high-traffic bots
+     * cooldown.startAutoCleanup(30000); // Every 30 seconds
+     * 
+     * @example
+     * // Store interval for management
+     * const cleanupInterval = cooldown.startAutoCleanup(60000);
+     * 
+     * // Later, if needed
+     * clearInterval(cleanupInterval);
+     * // Or use stopAutoCleanup()
+     */
+    startAutoCleanup(intervalMs?: number): NodeJS.Timeout;
+
+    /**
+     * Stops the automatic cleanup interval if it's running.
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Graceful shutdown
+     * function shutdown() {
+     *   cooldown.stopAutoCleanup();
+     *   cooldown.destroy();
+     *   process.exit(0);
+     * }
+     * 
+     * @example
+     * // Temporary pause
+     * cooldown.stopAutoCleanup();
+     * // Do some maintenance...
+     * cooldown.startAutoCleanup(); // Resume
+     */
+    stopAutoCleanup(): void;
+
+    /**
+     * Completely destroys all cooldown data and stops auto-cleanup.
+     * Resets the manager to its initial empty state.
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Server reset
+     * function resetServer() {
+     *   cooldown.destroy();
+     *   console.log('All cooldowns cleared');
+     *   // Reinitialize if needed
+     *   cooldown.startAutoCleanup();
+     * }
+     * 
+     * @example
+     * // Testing - clean between tests
+     * beforeEach(() => {
+     *   cooldown.destroy();
+     * });
+     * 
+     * @example
+     * // Memory management
+     * if (memoryPressure > 0.9) { // 90% memory usage
+     *   cooldown.destroy();
+     *   // Recreate essential groups
+     *   cooldown.createGroup('essential_teleporter', {...});
+     * }
+     */
+    destroy(): void;
+
+    /**
+     * Static utility method to format milliseconds into a human-readable string.
+     * Automatically selects appropriate time units (ms, seconds, minutes, hours, days).
+     * 
+     * @param ms - Milliseconds to format
+     * @returns Formatted time string (e.g., "2m 5s", "1h 30m", "500ms")
+     * 
+     * @example
+     * // Create a variable for the bot cooldown
+     * const cooldown = bot.utils.cooldown
+     * 
+     * // Display remaining time to users
+     * const remaining = cooldown.getRemaining(`user:${userId}:!command`);
+     * if (remaining > 0) {
+     *   const timeStr = cooldown.formatTime(remaining);
+     *   bot.whisper.send(userId, `Please wait ${timeStr}`);
+     * }
+     * 
+     * @example
+     * // Different formatting examples
+     * cooldown.formatTime(500);        // "500ms"
+     * cooldown.formatTime(1500);       // "2s" (rounded up)
+     * cooldown.formatTime(65000);      // "1m 5s"
+     * cooldown.formatTime(90000);      // "1m 30s"
+     * cooldown.formatTime(7200000);    // "2h"
+     * cooldown.formatTime(172800000);  // "2d"
+     * cooldown.formatTime(0);          // "0s"
+     * 
+     * @example
+     * // Use in game timers
+     * function displayBossTimer(remainingMs: number) {
+     *   const timeStr = cooldown.formatTime(remainingMs);
+     *   bot.message.send(`Boss respawns in ${timeStr}`);
+     * }
+     */
+    static formatTime(ms: number): string;
+}
+
+/**
+ * Hidden channel system for bot-to-bot communication
+ * Messages are broadcast to all bots in the same room
+ */
+declare class Channel {
+    /**
+     * Send a message to the hidden channel
+     * All bots in the room will receive this message
+     * 
+     * @param message - The message content to send
+     * @param tags - Tags for categorizing and filtering the message
+     * @returns Promise resolving to true if sent successfully, false otherwise
+     * 
+     * @example
+     * ```typescript
+     * // Send a JSON message with tags
+     * const success = await bot.channel.send(
+     *   JSON.stringify({ username: 'Player1', score: 100 }),
+     *   ['game', 'score-update']
+     * );
+     * 
+     * // Send a plain text message
+     * await bot.channel.send('Game starting in 10 seconds', ['game', 'countdown']);
+     * 
+     * // Send without tags (global broadcast)
+     * await bot.channel.send('System restarting');
+     * ```
+     */
+    send(message: string, tags?: string[]): Promise<boolean>;
+
+    /**
+     * Listen for messages with specific tags
+     * The callback receives the full ChannelMessage object
+     * 
+     * @param tags - Tag(s) to listen for. All tags must be present in message.
+     * @param callback - Function called when matching message arrives
+     * @returns Listener ID for unsubscribing, or null on error
+     * 
+     * @example
+     * ```typescript
+     * // Listen for moderation events
+     * const listenerId = bot.channel.on(['moderation', 'kick'], (data) => {
+     *   const event = JSON.parse(data.message);
+     *   console.log(`${event.username} was kicked by ${data.senderId}`);
+     * });
+     * 
+     * // Listen for game start with multiple tags
+     * bot.channel.on(['game', 'tic-tac-toe', 'start'], (data) => {
+     *   console.log(`Game starting: ${data.message}`);
+     *   startGame();
+     * });
+     * 
+     * // Listen for any message with a specific tag
+     * bot.channel.on('system', (data) => {
+     *   console.log(`System message: ${data.message}`);
+     * });
+     * ```
+     */
+    on(tags: string | string[], callback: ChannelListenerCallback): string | null;
+
+    /**
+     * Listen once for messages with specific tags
+     * Automatically unsubscribes after first matching message
+     * 
+     * @param tags - Tag(s) to listen for
+     * @param callback - Function called when matching message arrives
+     * @returns Listener ID for manual unsubscription, or null on error
+     * 
+     * @example
+     * ```typescript
+     * // Wait for shutdown signal
+     * bot.channel.once(['system', 'shutdown'], (data) => {
+     *   console.log('Received shutdown command');
+     *   bot.disconnect();
+     * });
+     * 
+     * // Wait for game initialization
+     * bot.channel.once(['game', 'init-complete'], (data) => {
+     *   console.log('Game initialized, starting...');
+     * });
+     * ```
+     */
+    once(tags: string | string[], callback: ChannelListenerCallback): string | null;
+
+    /**
+     * Remove a specific listener
+     * 
+     * @param listenerId - ID returned by on() or once()
+     * @returns true if listener was removed, false if not found
+     * 
+     * @example
+     * ```typescript
+     * // Store listener ID when subscribing
+     * const listenerId = bot.channel.on(['game'], handler);
+     * 
+     * // Later, remove the listener
+     * const removed = bot.channel.off(listenerId);
+     * console.log(`Listener removed: ${removed}`);
+     * ```
+     */
+    off(listenerId: string): boolean;
+
+    /**
+     * Remove all listeners for specific tags
+     * 
+     * @param tags - Tag(s) to remove listeners for
+     * @returns Number of listeners removed
+     * 
+     * @example
+     * ```typescript
+     * // Remove all game-related listeners
+     * const removed = bot.channel.offAll(['game']);
+     * console.log(`Removed ${removed} game listeners`);
+     * 
+     * // Remove all listeners for multiple tags
+     * bot.channel.offAll(['game', 'moderation']);
+     * ```
+     */
+    offAll(tags: string | string[]): number;
+
+    /**
+     * Query historical channel messages
+     * Searches through stored messages (max 500 most recent)
+     * 
+     * @param filter - Query filter criteria
+     * @returns Array of matching messages, newest first
+     * 
+     * @example
+     * ```typescript
+     * // Get all moderation messages from last hour
+     * const modLogs = bot.channel.query({
+     *   tags: ['moderation'],
+     *   since: Date.now() - 3600000,
+     *   limit: 100
+     * });
+     * 
+     * // Get messages with multiple tags
+     * const gameStarts = bot.channel.query({
+     *   tags: ['game', 'start'],
+     *   limit: 10
+     * });
+     * 
+     * // Get all messages from last 5 minutes
+     * const recent = bot.channel.query({
+     *   since: Date.now() - 300000
+     * });
+     * ```
+     */
+    query(filter?: ChannelFilter): ChannelMessage[];
+
+    /**
+     * Get channel system statistics
+     * 
+     * @returns Current channel statistics
+     * 
+     * @example
+     * ```typescript
+     * const stats = bot.channel.stats();
+     * console.log(`Messages stored: ${stats.totalMessages}`);
+     * console.log(`Active listeners: ${stats.listeners}`);
+     * ```
+     */
+    stats(): ChannelStats;
+
+    /**
+     * Clear all channel data
+     * Removes message history and all listeners
+     * 
+     * @example
+     * ```typescript
+     * // Reset channel system
+     * bot.channel.clear();
+     * 
+     * // Or on bot shutdown
+     * process.on('SIGINT', () => {
+     *   bot.channel.clear();
+     *   bot.disconnect();
+     * });
+     * ```
+     */
+    clear(): void;
+}
+
+declare class DanceFloor {
+
+    /**
+     * Create a new dance floor
+     * @param Id - Unique identifier
+     * @param corners - 3D boundaries {x, y, z, x1, y1, z1}
+     * @param emotes - Emote configuration (JSON file path, single emote object, or array of emotes)
+     * @returns Promise<DanceFloorConfig>
+     * @example
+     * 
+     * let danceFloor = bot.utils.DanceFloor
+     * 
+     * // From JSON file
+     * await danceFloor.create('floor1', { x:0, y:0, z:0, x1:10, y1:5, z1:10}, './dance.json');
+     * 
+     * // Single emote
+     * await danceFloor.create('floor2', corners, { id: "dance", name: "Dance", duration: 3000 });
+     * 
+     * // Array of emotes
+     * await danceFloor.create('floor3', corners, [
+     *   { id: "dance", name: "Dance", duration: 3000 },
+     *   { id: "wave", name: "Wave", duration: 2000 }
+     * ]);
+     */
+    create(Id: string, corners: DanceFloorCorners, emotes: string | DanceEmote | DanceEmote[]): Promise<DanceFloorConfig>;
+
+    /**
+     * Get dance floor information
+     * @param Id - Dance floor identifier
+     * @returns DanceFloorConfig or null if not found
+     */
+    getInfo(Id: string): DanceFloorConfig | null;
+
+    /**
+     * Hot-reload emote configuration for a specific dance floor
+     * @param floorId - Dance floor identifier
+     * @returns Promise<boolean> - Success status
+     */
+    hotReload(floorId: string): Promise<boolean>;
+
+    /**
+     * Reload all dance floors with file watchers
+     * @returns Promise<Array<{floorId: string, success: boolean, error?: string}>>
+     */
+    reloadAll(): Promise<Array<{ floorId: string, success: boolean, error?: string }>>;
+
+    /**
+     * Update emotes for a dance floor (programmatically)
+     * @param floorId - Dance floor identifier
+     * @param newEmotes - New emote configuration
+     * @returns Promise<boolean>
+     */
+    updateEmotes(floorId: string, newEmotes: string | DanceEmote | DanceEmote[]): Promise<boolean>;
+
+    /**
+     * Destroy all dance floors and cleanup
+     */
+    destroy(): void;
+}
+
+declare class AwaitClass {
+    /**
+     * Wait for chat messages that match the filter
+     * @param filter - Filter function that receives (user, message)
+     * @param timeout - Timeout in milliseconds
+     * @param maxToCollect - Maximum number of messages to collect
+     * @param uniqueUsers - If true, only collect one message per user (default: false)
+     * 
+     * @returns Promise resolving to array of matching events, or empty array if timeout
+     * @example
+     * ```typescript
+     * // Wait for a specific command from any user
+     * const results = await bot.await.chat(
+     *   (user, message) => message === '!play',
+     *   30000,
+     *   1,
+     *   false
+     * );
+     * if (results.length > 0) {
+     *   const [[user, message]] = results;
+     *   await bot.message.send(`Welcome ${user.username} to the game!`);
+     * }
+     * 
+     * // Collect one vote per user (unique users only)
+     * await bot.message.send("Vote for your favorite color: !red, !blue, or !green");
+     * const votes = await bot.await.chat(
+     *   (user, message) => ['!red', '!blue', '!green'].includes(message),
+     *   45000,
+     *   50,
+     *   true  // Each user can only vote once
+     * );
+     * 
+     * // Count votes - each user counted only once
+     * const redVotes = votes.filter(([user, message]) => message === '!red').length;
+     * const blueVotes = votes.filter(([user, message]) => message === '!blue').length;
+     * await bot.message.send(`Results - Red: ${redVotes}, Blue: ${blueVotes}`);
+     * 
+     * // Collect messages from 5 unique users
+     * const responses = await bot.await.chat(
+     *   (user, message) => message.startsWith('!feedback'),
+     *   60000,
+     *   5,
+     *   true  // One feedback per user
+     * );
+     * ```
+     */
+    chat(filter?: ChatFilter, timeout?: number, maxToCollect?: number, uniqueUsers?: boolean): Promise<[User, string][] | []>;
+
+    /**
+     * Wait for whisper messages that match the filter
+     * @param filter - Filter function that receives (user, message)
+     * @param timeout - Timeout in milliseconds  
+     * @param maxToCollect - Maximum number of whispers to collect
+     * @param uniqueUsers - If true, only collect one whisper per user (default: false)
+     * @returns Promise resolving to array of matching events, or empty array if timeout
+     * @example
+     * ```typescript
+     * // Secret command system - one request per user
+     * await bot.message.send("Whisper me '!secret' for special access");
+     * const secretRequests = await bot.await.whisper(
+     *   (user, message) => message === '!secret',
+     *   30000,
+     *   20,
+     *   true  // Each user can only request once
+     * );
+     * 
+     * // Grant access to each unique user who whispered
+     * for (const [user, message] of secretRequests) {
+     *   await bot.whisper.send(user.id, "You now have secret access! Use !commands");
+     *   await bot.room.privilege.add(user.id);
+     * }
+     * 
+     * // Private moderation reports - one report per user
+     * const reports = await bot.await.whisper(
+     *   (user, message) => message.startsWith('!report'),
+     *   60000,
+     *   10,
+     *   true  // Prevent users from spamming multiple reports
+     * );
+     * 
+     * // Each user's first report only
+     * reports.forEach(([user, message]) => {
+     *   bot.utils.logger.info('Moderation', `Report from ${user.username}: ${message}`);
+     * });
+     * ```
+     */
+    whisper(filter?: WhisperFilter, timeout?: number, maxToCollect?: number, uniqueUsers?: boolean): Promise<[User, string][] | []>;
+
+    /**
+     * Wait for direct messages that match the filter
+     * @param filter - Filter function that receives (user, message, conversation)
+     * @param timeout - Timeout in milliseconds
+     * @param maxToCollect - Maximum number of DMs to collect
+     * @param uniqueUsers - If true, only collect one DM per user (default: false)
+     * @returns Promise resolving to array of matching events, or empty array if timeout
+     * @example
+     * ```typescript
+     * // Handle support tickets - one ticket per user
+     * const supportTickets = await bot.await.direct(
+     *   (user, message, conversation) => message.includes('support') || message.includes('help'),
+     *   120000,
+     *   10,
+     *   true  // One support request per user
+     * );
+     * 
+     * // Each user gets one ticket created
+     * for (const [user, message, conversation] of supportTickets) {
+     *   await bot.direct.send(conversation.id, "Thanks for contacting support! We'll help you shortly.");
+     *   createSupportTicket(user.id, message, conversation.id);
+     * }
+     * 
+     * // Wait for confirmation from unique users
+     * const confirmations = await bot.await.direct(
+     *   (user, message, conversation) => 
+     *     conversation.id === specificConversationId && message === '!confirm',
+     *   60000,
+     *   5,
+     *   true  // One confirmation per user
+     * );
+     * 
+     * // Collect feedback from 10 unique users
+     * await bot.direct.send(conversationId, "Please rate your experience 1-5 stars");
+     * const ratings = await bot.await.direct(
+     *   (user, message, conv) => /^[1-5]$/.test(message) && conv.id === conversationId,
+     *   30000,
+     *   10,
+     *   true  // One rating per user
+     * );
+     * 
+     * // Average rating from unique users only
+     * const averageRating = ratings.reduce((sum, [user, rating]) => sum + parseInt(rating), 0) / ratings.length;
+     * ```
+     */
+    direct(filter?: DirectFilter, timeout?: number, maxToCollect?: number, uniqueUsers?: boolean): Promise<[User, string, Conversation][] | []>;
+
+    /**
+     * Wait for tips that match the filter
+     * @param filter - Filter function that receives (sender, receiver, currency)
+     * @param timeout - Timeout in milliseconds
+     * @param maxToCollect - Maximum number of tips to collect
+     * @param uniqueUsers - If true, only count one tip per sender (default: false)
+     * @returns Promise resolving to array of matching events, or empty array if timeout
+     * @example
+     * ```typescript
+     * // Track first donation from each user
+     * await bot.message.send("Fundraiser started! First donation from each user counts!");
+     * const firstDonations = await bot.await.tip(
+     *   (sender, receiver, currency) => 
+     *     receiver.id === bot.info.user.id && currency.amount >= 50,
+     *   300000,
+     *   100,
+     *   true  // Only count first donation from each user
+     * );
+     * 
+     * // Count unique donors, not total donations
+     * const uniqueDonors = firstDonations.length;
+     * let totalRaised = firstDonations.reduce((sum, [sender, receiver, currency]) => sum + currency.amount, 0);
+     * await bot.message.send(`${uniqueDonors} unique donors raised ${totalRaised} gold!`);
+     * 
+     * // VIP reward - first large donation only
+     * const vipDonors = await bot.await.tip(
+     *   (sender, receiver, currency) => 
+     *     receiver.id === bot.info.user.id && currency.amount >= 500,
+     *   180000,
+     *   20,
+     *   true  // Users can only become VIP once
+     * );
+     * 
+     * // Grant VIP to first-time large donors
+     * vipDonors.forEach(([sender, receiver, currency]) => {
+     *   await bot.whisper.send(sender.id, "You're now a VIP! Special perks unlocked.");
+     *   await bot.room.privilege.add(sender.id);
+     * });
+     * 
+     * // Track unique tippers for analytics
+     * const uniqueTippers = await bot.await.tip(
+     *   (sender, receiver, currency) => receiver.id === bot.info.user.id,
+     *   60000,
+     *   50,
+     *   true  // Count each tipper only once
+     * );
+     * 
+     * bot.utils.logger.info('Economy', `${uniqueTippers.length} unique tippers in the last minute`);
+     * ```
+     */
+    tip(filter?: TipFilter, timeout?: number, maxToCollect?: number, uniqueUsers?: boolean): Promise<[Sender, Receiver, Currency][] | []>;
+
+    /**
+     * Wait for player movements that match the filter
+     * @param filter - Filter function that receives (user, position, anchor)
+     * @param timeout - Timeout in milliseconds
+     * @param maxToCollect - Maximum number of movements to collect
+     * @param uniqueUsers - If true, only collect one movement per user (default: false)
+     * @returns Promise resolving to array of matching events, or empty array if timeout
+     * @example
+     * ```typescript
+     * // Track first entry to dance floor per user
+     * const firstEntrants = await bot.await.movement(
+     *   (user, position, anchor) => 
+     *     position.x >= 10 && position.x <= 15 && 
+     *     position.z >= 10 && position.z <= 15,
+     *   60000,
+     *   30,
+     *   true  // Only track first time each user enters
+     * );
+     * 
+     * // Welcome users on their first entry only
+     * for (const [user, position, anchor] of firstEntrants) {
+     *   await bot.message.send(`Welcome to the dance floor, ${user.username}! First time here?`);
+     *   await bot.player.emote('dance', user.id);
+     * }
+     * 
+     * // Track unique users sitting on premium chairs
+     * const uniqueChairUsers = await bot.await.movement(
+     *   (user, position, anchor) => 
+     *     anchor?.entity_id === 'premium_chair_001',
+     *   120000,
+     *   10,
+     *   true  // Track each user only once
+     * );
+     * 
+     * // VIP area entry - track first visit per user
+     * const firstVIPVisitors = await bot.await.movement(
+     *   (user, position, anchor) => 
+     *     position.y >= 5 && // Upper floor
+     *     position.x >= 20 && position.x <= 25 &&
+     *     position.z >= 20 && position.z <= 25,
+     *   180000,
+     *   50,
+     *   true  // First visit only
+     * );
+     * 
+     * // Award achievement for first time leaving spawn
+     * const spawnLeavers = await bot.await.movement(
+     *   (user, position, anchor) => {
+     *     const distanceFromSpawn = Math.sqrt(position.x ** 2 + position.z ** 2);
+     *     return distanceFromSpawn > 10;
+     *   },
+     *   60000,
+     *   100,
+     *   true  // Achievement only once per user
+     * );
+     * 
+     * // Secret room discovery - once per user
+     * const secretDiscoverers = await bot.await.movement(
+     *   (user, position, anchor) => 
+     *     position.x === 100 && position.y === 5 && position.z === 100,
+     *   300000,
+     *   50,
+     *   true  // Reward only on first discovery
+     * );
+     * 
+     * secretDiscoverers.forEach(([user, position, anchor]) => {
+     *   await bot.whisper.send(user.id, "You found the secret room! Here's your reward.");
+     *   await bot.player.tip(user.id, 100);
+     * });
+     * 
+     * // Zone crossing - track first time per user
+     * const firstZoneCrossers = await bot.await.movement(
+     *   (user, position, anchor) => {
+     *     const previousPosition = bot.cache.position.get(user.id)?.position;
+     *     if (!previousPosition) return false;
+     *     
+     *     const wasInZoneA = previousPosition.x < 0;
+     *     const nowInZoneB = position.x >= 0;
+     *     return wasInZoneA && nowInZoneB;
+     *   },
+     *   120000,
+     *   30,
+     *   true  // Only count first crossing per user
+     * );
+     * ```
+     */
+    movement(filter?: MovementFilter, timeout?: number, maxToCollect?: number, uniqueUsers?: boolean): Promise<[User, Position, AnchorPosition | null][] | []>;
+}
+
+declare class WebApi {
+    user: {
+        /**
+         * Get user information from Highrise Web API
+         * @param identifier - User ID or username
+         * @returns Promise resolving to formatted user data or null if not found
+         * @throws {TypeError} If identifier is not a non-empty string
+         * @example
+         * ```typescript
+         * const user = await bot.webapi.user.get('Unfairly');
+         * ```
+         */
+        get(identifier: string): Promise<WebApiUser | null>;
+
+        /**
+         * Get user avatar as png in high quality
+         * @param identifier - User ID or username
+         * @param imagePath - User Avatar output path (default: "avatar.png")
+         * @returns Promise resolving to getUserAvatarResponse if success or null if not
+         * @throws {TypeError} If identifier is not a non-empty string
+         * 
+         * @todo use username for imagePath -> "username".png
+         * 
+         * @example
+         * ```typescript
+         * await bot.webapi.user.get('Unfairly', `${user.username}.png`);
+         * ```
+         */
+        getUserAvatar(identifier: string, imagePath: string): Promise<getUserAvatarResponse>
+    }
+
+    room: {
+        /**
+         * Get detailed room information from Highrise Web API
+         * @param roomId - Room ID to lookup
+         * @returns Promise resolving to detailed room data or null if not found
+         * @throws {TypeError} If roomId is not a non-empty string
+         * @example
+         * ```typescript
+         * const room = await bot.webapi.room.get('692125c2521b7580234d0f35');
+         * ```
+         */
+        get(roomId: string): Promise<DetailedRoom | null>;
+
+        /**
+         * Get a list of rooms from Highrise Web API with pagination
+         * @param params - Query parameters for filtering and pagination
+         * @returns Promise resolving to rooms list with pagination info or null
+         * @throws {TypeError} If params are invalid
+         * @example
+         * ```typescript
+         * // Get recent rooms
+         * const rooms = await bot.webapi.room.list({ limit: 50, sort_order: 'desc' });
+         * 
+         * // Search rooms by name
+         * const results = await bot.webapi.room.list({ room_name: 'party', limit: 20 });
+         * 
+         * // Get rooms by owner
+         * const ownerRooms = await bot.webapi.room.list({ owner_id: '68a7dd5eecae68acca580f41' });
+         * 
+         * // Pagination example
+         * const page1 = await bot.webapi.room.list({ limit: 50 });
+         * const page2 = await bot.webapi.room.list({ limit: 50, starts_after: page1.pagination.lastId });
+         * ```
+         */
+        list(params?: RoomsParams): Promise<RoomsListResponse | null>;
+
+        /**
+         * Get bot current room details
+         */
+        getCurrentRoom(): Promise<DetailedRoom>
+
+        /**
+         * Search rooms by name (convenience method)
+         * @param name - Room name to search for
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to rooms list or null
+         * @example
+         * ```typescript
+         * const results = await bot.webapi.room.searchByName('party', 15);
+         * ```
+         */
+        searchByName(name: string, limit?: number): Promise<RoomsListResponse | null>;
+
+        /**
+         * Get rooms by owner ID (convenience method)
+         * @param ownerId - Owner user ID
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to rooms list or null
+         * @example
+         * ```typescript
+         * const ownerRooms = await bot.webapi.room.getByOwner('68a7dd5eecae68acca580f41');
+         * ```
+         */
+        getByOwner(ownerId: string, limit?: number): Promise<RoomsListResponse | null>;
+
+        /**
+         * Get recent rooms (convenience method)
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to rooms list or null
+         * @example
+         * ```typescript
+         * const recent = await bot.webapi.room.getRecent(10);
+         * ```
+         */
+        getRecent(limit?: number): Promise<RoomsListResponse | null>;
+    }
+
+    post: {
+        /**
+         * Get post information from Highrise Web API
+         * @param postId - Post ID to lookup
+         * @returns Promise resolving to formatted post data or null if not found
+         * @throws {TypeError} If postId is not a non-empty string
+         * @example
+         * ```typescript
+         * const post = await bot.webapi.post.get('post_123456');
+         * ```
+         */
+        get(postId: string): Promise<Post | null>;
+
+        /**
+         * Get a list of posts with basic information (optimized for listing)
+         * @param params - Query parameters for filtering and pagination
+         * @returns Promise resolving to posts list with pagination info or null
+         * @example
+         * ```typescript
+         * const posts = await bot.webapi.post.list({ limit: 50 });
+         * posts.posts.forEach(post => {
+         *   console.log(`${post.id}: ${post.content.text.substring(0, 50)}...`);
+         *   console.log(`Likes: ${post.stats.likes}, Items: ${post.inventoryPreview?.itemCount}`);
+         * });
+         * ```
+         */
+        list(params?: PostsParams): Promise<PostsListResponse | null>;
+
+        /**
+         * Get posts by specific author (convenience method)
+         * @param authorId - Author user ID
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to posts list or null
+         * @example
+         * ```typescript
+         * const authorPosts = await bot.webapi.post.getByAuthor('68a7dd5eecae68acca580f41');
+         * ```
+         */
+        getByAuthor(authorId: string, limit?: number): Promise<PostsListResponse | null>;
+
+        /**
+         * Get recent posts (convenience method)
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to posts list or null
+         * @example
+         * ```typescript
+         * const recent = await bot.webapi.post.getRecent(10);
+         * ```
+         */
+        getRecent(limit?: number): Promise<PostsListResponse | null>;
+    }
+
+    item: {
+        /**
+         * Get detailed item information from Highrise Web API
+         * @param itemId - Item ID to lookup
+         * @returns Promise resolving to detailed item data or null if not found
+         * @throws {TypeError} If itemId is not a non-empty string
+         * @example
+         * ```typescript
+         * const item = await bot.webapi.item.get('eye-n_fierycreatureeyes');
+         * 
+         * // Example response includes:
+         * // - Basic item info and pricing
+         * // - Acquisition details
+         * // - Skin parts and customization
+         * // - Related items and affiliations
+         * // - Storefront listings with sellers
+         * // - Seller outfits and availability
+         * ```
+         */
+        get(itemId: string): Promise<ItemDetail | null>;
+
+        /**
+         * Get a list of items from Highrise catalog with filtering and pagination
+         * @param params - Query parameters for filtering and pagination
+         * @returns Promise resolving to items list with pagination info or null
+         * @throws {TypeError} If params are invalid
+         * @example
+         * ```typescript
+         * // Get recent items
+         * const items = await bot.webapi.item.list({ limit: 50, sort_order: 'desc' });
+         * 
+         * // Get rare shirts
+         * const rareShirts = await bot.webapi.item.list({
+         *   category: ItemCategory.SHIRT,
+         *   rarity: Rarity.RARE,
+         *   limit: 20
+         * });
+         * 
+         * // Search for dragon items
+         * const dragonItems = await bot.webapi.item.list({ item_name: 'dragon', limit: 30 });
+         * 
+         * // Pagination example
+         * const page1 = await bot.webapi.item.list({ limit: 50 });
+         * const page2 = await bot.webapi.item.list({ limit: 50, starts_after: page1.pagination.lastId });
+         * ```
+         */
+        list(params?: ItemsParams): Promise<ItemsListResponse | null>;
+
+        /**
+         * Search for items in the Highrise catalog
+         * @param params - Search parameters including query and pagination
+         * @returns Promise resolving to items search results with pagination
+         * @throws {TypeError} If params are invalid
+         * @example
+         * ```typescript
+         * // Search for shirts
+         * const shirts = await bot.webapi.item.search({ query: 'shirt', limit: 20 });
+         * 
+         * // Paginate results
+         * const page1 = await bot.webapi.item.search({ query: 'hat', limit: 20, skip: 0 });
+         * const page2 = await bot.webapi.item.search({ query: 'hat', limit: 20, skip: 20 });
+         * 
+         * // Process results
+         * shirts.items.forEach(item => {
+         *   console.log(`${item.name} - ${item.pricing.gems} gems`);
+         *   console.log(`Purchasable: ${item.properties.isPurchasable}`);
+         *   console.log(`Tradable: ${item.properties.isTradable}`);
+         * });
+         * ```
+         */
+        search(params?: ItemsSearchParams): Promise<ItemsSearchResponse | null>;
+
+        /**
+         * Search items by name (convenience method)
+         * @param name - Item name to search for
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to items search results
+         * @example
+         * ```typescript
+         * const hats = await bot.webapi.item.searchByName('hat', 30);
+         * ```
+         */
+        searchByName(name: string, limit?: number): Promise<ItemsSearchResponse | null>;
+
+        /**
+         * Get items by category (convenience method)
+         * @param category - Item category to filter by
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to items list or null
+         * @example
+         * ```typescript
+         * const hats = await bot.webapi.item.getByCategory(ItemCategory.HAT, 30);
+         * ```
+         */
+        getByCategory(category: ItemCategory, limit?: number): Promise<ItemsListResponse | null>;
+
+        /**
+         * Get items by rarity (convenience method)
+         * @param rarity - Item rarity to filter by
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to items list or null
+         * @example
+         * ```typescript
+         * const epicItems = await bot.webapi.item.getByRarity(Rarity.EPIC, 25);
+         * ```
+         */
+        getByRarity(rarity: Rarity, limit?: number): Promise<ItemsListResponse | null>;
+
+        /**
+         * Get items by name (convenience method)
+         * @param name - Item name to search for
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to items list or null
+         * @example
+         * ```typescript
+         * const dragonItems = await bot.webapi.item.getByName('dragon', 20);
+         * ```
+         */
+        getByName(name: string, limit?: number): Promise<ItemsListResponse | null>;
+
+        /**
+         * Get recent items (convenience method)
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to items list or null
+         * @example
+         * ```typescript
+         * const recent = await bot.webapi.item.getRecent(15);
+         * ```
+         */
+        getRecent(limit?: number): Promise<ItemsListResponse | null>;
+
+        /**
+         * Get purchasable items (convenience method)
+         * @param query - Search query (optional)
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to purchasable items only
+         * @example
+         * ```typescript
+         * const purchasableHats = await bot.webapi.item.getPurchasable('hat');
+         * ```
+         */
+        getPurchasable(query?: string, limit?: number): Promise<ItemsSearchResponse | null>;
+
+        /**
+         * Get tradable items (convenience method)
+         * @param query - Search query (optional)
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to tradable items only
+         * @example
+         * ```typescript
+         * const tradableItems = await bot.webapi.item.getTradable('', 50);
+         * ```
+         */
+        getTradable(query?: string, limit?: number): Promise<ItemsSearchResponse | null>;
+
+        /**
+         * Get purchasable items by category (convenience method)
+         * @param category - Item category to filter by
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to purchasable items only
+         * @example
+         * ```typescript
+         * const purchasableShirts = await bot.webapi.item.getPurchasableByCategory(ItemCategory.SHIRT);
+         * ```
+         */
+        getPurchasableByCategory(category: ItemCategory, limit?: number): Promise<ItemsListResponse | null>;
+
+        /**
+         * Get tradable items by category (convenience method)
+         * @param category - Item category to filter by
+         * @param limit - Maximum number of results (default: 20, max: 100)
+         * @returns Promise resolving to tradable items only
+         * @example
+         * ```typescript
+         * const tradableHats = await bot.webapi.item.getTradableByCategory(ItemCategory.HAT);
+         * ```
+         */
+        getTradableByCategory(category: ItemCategory, limit?: number): Promise<ItemsListResponse | null>;
+    }
+
+    grab: {
+        /**
+         * Get detailed grab information from Highrise Web API
+         * @param grabId - Grab ID to lookup
+         * @returns Promise resolving to detailed grab data or null if not found
+         * @throws {TypeError} If grabId is not a non-empty string
+         * @example
+         * ```typescript
+         * const grab = await bot.webapi.grab.get('grab_123456');
+         * 
+         * // Example response includes:
+         * // - Complete grab details with all rewards and costs
+         * // - Kompu reward system data
+         * // - Limited time offers
+         * // - Progress-based rewards
+         * // - Item metadata and NFI information
+         * 
+         * console.log(`🎁 ${grab.title}`);
+         * console.log(`📝 ${grab.description}`);
+         * console.log(`🖼️ Banner: ${grab.bannerImgUrl}`);
+         * 
+         * // Process rewards
+         * grab.rewards.forEach(reward => {
+         *   console.log(`🎯 Reward: ${reward.amount}x ${reward.rewardId}`);
+         *   if (reward.itemId) console.log(`   Item: ${reward.itemId}`);
+         *   console.log(`   Bound: ${reward.accountBound}, Tradable: ${reward.isTradable}`);
+         * });
+         * 
+         * // Process costs
+         * grab.costs.forEach(cost => {
+         *   console.log(`💰 Cost: ${cost.amount}x ${cost.rewardId}`);
+         * });
+         * ```
+         */
+        get(grabId: string): Promise<Grab | null>;
+    }
+}
+
+
+declare class MovementCache {
+    /**
+     * Get user data by either userId or username
+     * Automatically detects identifier type
+     * 
+     * @param identifier - User ID (e.g., '68a7dd5eecae68acca580f41') or username (e.g., 'Unfairly')
+     * @returns Cached user data or null if not found
+     * 
+     * @example
+     * // Get user position by ID
+     * const userData = bot.cache.position.get('68a7dd5eecae68acca580f41');
+     * 
+     * // Get user position by username  
+     * const userData = bot.cache.position.get('Unfairly');
+     * 
+     * // Check if user is in cache
+     * const isCached = bot.cache.position.get(userId) !== null;
+     */
+    get(identifier: string): CachedUser | null;
+
+    /**
+     * Get all players within a square area centered at a point
+     * @param center - Center point coordinates {x, y, z}
+     * @param sideLength - Length of each side of the square
+     * @returns Array of users with their positions and cache data
+     * @example
+     * ```typescript
+     * // Get players in 8x8 square centered at (10, 0, 10)
+     * const players = bot.cache.position.getPlayersInSquare(
+     *   { x: 10, y: 0, z: 10 }, 
+     *   8
+     * );
+     * 
+     * players.forEach(player => {
+     *   console.log(`${player.user.username} at (${player.position.x}, ${player.position.z})`);
+     * });
+     * ```
+     */
+    getPlayersInSquare(center: Position, sideLength: number): SpatialUser[];
+
+    /**
+     * Get all players within a rectangular area defined by four corners
+     * @param corners - Object containing four corner coordinates
+     * @returns Array of users with their positions and cache data
+     * @example
+     * ```typescript
+     * // Get players in 10x10 rectangle
+     * const players = bot.cache.position.getPlayersInRectangle({
+     *   c1: { x: 5, z: 5 },
+     *   c2: { x: 15, z: 5 },
+     *   c3: { x: 15, z: 15 },
+     *   c4: { x: 5, z: 15 }
+     * });
+     * 
+     * // Check if specific user is in area
+     * const targetUser = players.find(p => p.user.id === '68a7dd5eecae68acca580f41');
+     * if (targetUser) {
+     *   await bot.message.send(`${targetUser.user.username} is in the designated area!`);
+     * }
+     * ```
+     */
+    getPlayersInRectangle(corners: RectangleCorners): SpatialUser[];
+
+    /**
+     * Get all players within a circular area
+     * @param center - Center point coordinates {x, z}
+     * @param radius - Radius of the circular area
+     * @returns Array of users sorted by distance from center (closest first)
+     * @example
+     * ```typescript
+     * // Get players within 5 units radius of center (10, 10)
+     * const players = bot.cache.position.getPlayersInCircle(
+     *   { x: 10, z: 10 }, 
+     *   5
+     * );
+     * 
+     * // Get the closest player to center
+     * const closestPlayer = players[0];
+     * if (closestPlayer) {
+     *   console.log(`Closest player: ${closestPlayer.user.username} (${closestPlayer.distance} units)`);
+     * }
+     * 
+     * // Filter players within specific distance
+     * const nearbyPlayers = players.filter(p => p.distance <= 3);
+     * ```
+     */
+    getPlayersInCircle(center: { x: number; z: number }, radius: number): SpatialUserWithDistance[];
+
+    /**
+     * Get players within a specific Y-level range (vertical filtering)
+     * @param minY - Minimum Y coordinate
+     * @param maxY - Maximum Y coordinate
+     * @returns Array of users within the vertical range
+     * @example
+     * ```typescript
+     * // Get players on ground level (Y between -1 and 1)
+     * const groundPlayers = bot.cache.position.getPlayersInVerticalRange(-1, 1);
+     * 
+     * // Get players on upper floors (Y > 5)
+     * const upperFloorPlayers = bot.cache.position.getPlayersInVerticalRange(5, 50);
+     * ```
+     */
+    getPlayersInVerticalRange(minY: number, maxY: number): SpatialUser[];
+
+    /**
+     * Get the closest player to a specified point
+     * @param point - Reference point coordinates {x, z}
+     * @returns The closest player or null if no players in cache
+     * @example
+     * ```typescript
+     * // Find closest player to bot's position
+     * const closest = bot.cache.position.getClosestPlayer({ x: 10, z: 10 });
+     * if (closest) {
+     *   await bot.whisper.send(closest.user.id, `You're the closest player to me!`);
+     * }
+     * ```
+     */
+    getClosestPlayer(point: { x: number; z: number }): SpatialUserWithDistance | null;
+
+    /**
+     * Get players sorted by distance from a point
+     * @param point - Reference point coordinates {x, z}
+     * @param maxDistance - Optional maximum distance filter
+     * @returns Array of players sorted by distance (closest first)
+     * @example
+     * ```typescript
+     * // Get all players sorted by distance from spawn
+     * const sortedPlayers = bot.cache.position.getPlayersByDistance(
+     *   { x: 0, z: 0 }
+     * );
+     * 
+     * // Get players within 10 units, sorted
+     * const nearbyPlayers = bot.cache.position.getPlayersByDistance(
+     *   { x: 10, z: 10 },
+     *   10
+     * );
+     * ```
+     */
+    getPlayersByDistance(point: { x: number; z: number }, maxDistance?: number): SpatialUserWithDistance[];
+
+    /**
+     * Check if a specific player is within a square area
+     * @param userId - User ID to check
+     * @param center - Center point of the square
+     * @param sideLength - Side length of the square
+     * @returns True if player is within the area
+     * @example
+     * ```typescript
+     * // Check if specific user is in dance floor area
+     * const isOnDanceFloor = bot.cache.position.isPlayerInSquare(
+     *   '68a7dd5eecae68acca580f41',
+     *   { x: 10, y: 0, z: 10 },
+     *   8
+     * );
+     * 
+     * if (isOnDanceFloor) {
+     *   await bot.player.emote('68a7dd5eecae68acca580f41', 'dance');
+     * }
+     * ```
+     */
+    isPlayerInSquare(userId: string, center: Position, sideLength: number): boolean;
+
+    /**
+     * Check if a specific player is within a rectangular area
+     * @param userId - User ID to check
+     * @param corners - Rectangle corner coordinates
+     * @returns True if player is within the area
+     * @example
+     * ```typescript
+     * const isInVIPArea = bot.cache.position.isPlayerInRectangle(
+     *   '68a7dd5eecae68acca580f41',
+     *   {
+     *     c1: { x: 20, z: 20 },
+     *     c2: { x: 25, z: 20 },
+     *     c3: { x: 25, z: 25 },
+     *     c4: { x: 20, z: 25 }
+     *   }
+     * );
+     * ```
+     */
+    isPlayerInRectangle(userId: string, corners: RectangleCorners): boolean;
+
+    /**
+     * Get the number of players in a square area
+     * @param center - Center point of the square
+     * @param sideLength - Side length of the square
+     * @returns Number of players in the area
+     * @example
+     * ```typescript
+     * // Count players in spawn area
+     * const playerCount = bot.cache.position.getPlayerCountInSquare(
+     *   { x: 0, y: 0, z: 0 },
+     *   10
+     * );
+     * await bot.message.send(`There are ${playerCount} players at spawn!`);
+     * ```
+     */
+    getPlayerCountInSquare(center: Position, sideLength: number): number;
+
+    /**
+     * Get the number of players in a rectangular area
+     * @param corners - Rectangle corner coordinates
+     * @returns Number of players in the area
+     */
+    getPlayerCountInRectangle(corners: RectangleCorners): number;
+}
+
+declare class InventoryClass {
+    /**
+     * Get the bot's inventory items
+     * @returns Promise resolving to array of inventory items
+     * @example
+     * ```typescript
+     * const items = await bot.inventory.get();
+     * console.log(items);
+     * ```
+     */
+    get(): Promise<GetInventoryResponse[]>;
+
+    /**
+     * Outfit management
+     */
+    public outfit: {
+        /**
+         * Set the bot's outfit with specified items
+         * @param outfit - Array of outfit items to wear (default: default skin)
+         * @returns Promise resolving to operation success status
+         * @example
+         * ```typescript
+         * // Set default outfit
+         * await bot.inventory.outfit.set();
+         * 
+         * // Set custom outfit
+         * await bot.inventory.outfit.set([
+         *   {
+         *     type: 'clothing',
+         *     amount: 1,
+         *     id: 'shirt-n_cooltshirt',
+         *     account_bound: false,
+         *     active_palette: null
+         *   },
+         *   {
+         *     type: 'clothing', 
+         *     amount: 1,
+         *     id: 'pants-n_jeans',
+         *     account_bound: false,
+         *     active_palette: null
+         *   }
+         * ]);
+         * ```
+         */
+        set(outfit?: Array<Outfit>): Promise<boolean>;
+    }
+
+    /**
+     * Wallet management for the bot's economy
+     */
+    public wallet: {
+        /**
+         * Get the bot's wallet information in a structured format
+         * @returns Promise resolving to organized wallet data
+         * @example
+         * ```typescript
+         * // access to specific currencies
+         * const wallet = await bot.inventory.wallet.get();
+         * console.log(`Gold: ${wallet.gold}`);
+         * console.log(`Boost tokens: ${wallet.boost_tokens}`); 
+         * console.log(`Voice tokens: ${wallet.voice_tokens}`);
+         * 
+         * // Use in economy checks
+         * if (wallet.gold >= 100) {
+         *   await bot.player.tip('68a7dd5eecae68acca580f41', 100);
+         * }
+         * ```
+         */
+        get(): Promise<WalletResponse>;
+    }
+
+    public boost: {
+        /**
+         * Buy room boosts
+         * @param payment_method - Payment method to use (default: 'bot_wallet_only')
+         * @param amount - Number of boosts to buy (default: 1)
+         * @returns Promise resolving to purchase result
+         * @example
+         * ```typescript
+         * const result = await bot.inventory.boost.buy('bot_wallet_only', 1);
+         * if (result === 'success') {
+         *   console.log('Boost purchased successfully');
+         * }
+         * ```
+         */
+        buy(payment_method?: PaymentMethods, amount?: number): Promise<string>
+    }
+
+    public voice: {
+        /**
+         * Buy room voice token
+         * @param payment_method - Payment method to use (default: 'bot_wallet_only')
+         * @param amount - Number of voice tokens to buy (default: 1)
+         * @returns Promise resolving to purchase result
+         * @example
+         * ```typescript
+         * const result = await bot.inventory.voice.buy('bot_wallet_only', 1);
+         * if (result === 'success') {
+         *   console.log('Voice token purchased successfully');
+         * }
+         * ```
+         */
+        buy(payment_method?: PaymentMethods): Promise<string>
+    }
+
+    public item: {
+        /**
+         * Buy an item from the shop
+         * @param item_id - The ID of the item to purchase
+         * @returns Promise resolving to purchase result
+         * @example
+         * ```typescript
+         * const result = await bot.shop.item.buy('item_123');
+         * if (result === 'success') {
+         *   console.log('Item purchased successfully');
+         * }
+         * ```
+         */
+        buy(item_id: string): Promise<string>
+    }
+}
+
+declare class MessageClass {
+    /**
+     * Send a message to the Highrise room (visible to all users in the room)
+     * @param message - The message to send to the Highrise room
+     * @throws {Error} If message is empty, too long, or contains invalid characters
+     * @example
+     * // Send a simple message
+     * await bot.message.send("Hello everyone!");
+     * 
+     * // Send a welcome message
+     * await bot.message.send("Welcome to the room! 🎉");
+     * 
+     * // Send a command announcement
+     * await bot.message.send("Type !help for available commands");
+     */
+    send(message: string): Promise<boolean>;
+}
+
+declare class WhisperClass {
+    /**
+     * Send a private whisper message to a specific user in the Highrise room
+     * @param user_id - The user ID to send the whisper to
+     * @param message - The private message to send
+     * @throws {Error} If user_id is invalid or message is empty/too long
+     * @example
+     * // Send a private notification
+     * await bot.whisper.send("68a7dd5eecae68acca580f41", "Your item has been delivered! Check your inventory.");
+     */
+    send(user_id: string, message: string): Promise<boolean>;
+}
+
+
+declare class DirectClass {
+
+    /**
+     * Send a direct message to a specific user using the conversation_id
+     * @param conversation_id - The conversation ID to send the message in
+     * @param message - The direct message to send
+     * @throws {Error} If conversation_id is invalid or message is empty/too long
+     * @example
+     * // Send a direct notification
+     * await bot.direct.send("1_on_1:68a7dd5eecae68acca580f41:68a7dd5eecae68acca580f41", "Your item has been delivered! Check your inventory.");
+     */
+    send(conversation_id: string, message: string): Promise<boolean>;
+
+    /**
+     * Send a direct message to a specific user using array of ID
+     * @param user_Ids - Array of IDs to send the message to
+     * @param message - The direct message to send
+     * @throws {Error} If user_Ids is not array or less than 0 or bigger than 100 or message is empty/too long
+     * @example
+     * // Send a bulk direct notification
+     * await bot.direct.bulkSend(['692125c2521b7580234d0f35', '68a7dd5eecae68acca580f41'], "Your item has been delivered! Check your inventory.");
+     */
+    bulkSend(user_Ids: string[], message: string): Promise<boolean>;
+
+    /**
+     * Send a room or world invitation to a conversation
+     * @param conversation_id - The conversation ID to send the invitation to
+     * @param options - Invitation options (must provide exactly one of room_id or world_id)
+     * @returns Promise resolving to operation success status
+     * @throws {TypeError} If conversation_id is invalid or options don't contain exactly one valid option
+     * @example
+     * ```typescript
+     * // Send room invitation
+     * await bot.direct.invite('1_on_1:user1:user2', { room_id: '692125c2521b7580234d0f35' });
+     * 
+     * // Send world invitation  
+     * await bot.direct.invite('1_on_1:user1:user2', { world_id: 'world_123456' });
+     * 
+     * // This will throw an error (no options provided):
+     * await bot.direct.invite('1_on_1:user1:user2', {});
+     * 
+     * // This will throw an error (both options provided):
+     * await bot.direct.invite('1_on_1:user1:user2', { 
+     *   room_id: 'room_123', 
+     *   world_id: 'world_456' 
+     * });
+     * ```
+     */
+    invite(conversation_id: string, options: InviteOptions): Promise<boolean>;
+
+    /**
+     * Send a room or world invitation to a conversation
+     * @param user_Ids - Array of IDs to send the invitation to
+     * @param options - Invitation options (must provide exactly one of room_id or world_id)
+     * @returns Promise resolving to operation success status
+     * @throws {TypeError} If user_Ids is not array or less than 0 or bigger than 100 or options don't contain exactly one valid option
+     * @example
+     * ```typescript
+     * // Send bulk room invitation
+     * await bot.direct.bulkInvite(['692125c2521b7580234d0f35', '68a7dd5eecae68acca580f41'], { room_id: '692125c2521b7580234d0f35' });
+     * 
+     * // Send bulk world invitation  
+     * await bot.direct.bulkInvite(['692125c2521b7580234d0f35', '68a7dd5eecae68acca580f41'], { world_id: 'world_123456' });
+     * 
+     * // This will throw an error (no options provided):
+     * await bot.direct.bulkInvite(['692125c2521b7580234d0f35', '68a7dd5eecae68acca580f41'], {});
+     * 
+     * // This will throw an error (both options provided):
+     * await bot.direct.bulkInvite(['692125c2521b7580234d0f35', '68a7dd5eecae68acca580f41'], { 
+     *   room_id: 'room_123', 
+     *   world_id: 'world_456' 
+     * });
+     * ```
+     */
+    bulkInvite(user_Ids: string[], options: InviteOptions): Promise<boolean>;
+
+    /**
+     * Conversations management for direct messaging
+     */
+    public conversations: {
+        /**
+         * Get the conversations of the bot
+         * @param last_id - Last conversation in the list, used to get the next 20 conversations
+         * @param not_joined - If true, only returns conversations that bot has not joined yet
+         * @returns Array of conversation responses
+         * @example
+         * // Get first 20 conversations
+         * const conversations = await bot.direct.conversations.get();
+         * 
+         * // Get next 20 conversations using last_id
+         * const nextConversations = await bot.direct.conversations.get(conversations[19].id);
+         * 
+         * // Get only unjoined conversations
+         * const unjoined = await bot.direct.conversations.get(undefined, true);
+         */
+        get(last_id?: string, not_joined?: boolean): Promise<GetConversationsResponse[]>;
+
+        /**
+         * Leave a conversation using conversation_id
+         * @param conversation_id - Conversation id to leave from
+         * @example
+         * await bot.direct.conversations.leave('1_on_1:68a7dd5eecae68acca580f41:68a7dd5eecae68acca580f41');
+         */
+        leave(conversation_id: string): Promise<boolean>;
+    }
+
+    /**
+     * Messages management within conversations
+     */
+    public messages: {
+        /**
+         * Get the messages of a conversation
+         * @param conversation_id - Conversation id to get the messages from
+         * @param last_message_id - Last message id to get the next 20 messages
+         * @returns Array of message responses
+         * @example
+         * // Get first 20 messages from a conversation
+         * const messages = await bot.direct.messages.get('1_on_1:68a7dd5eecae68acca580f41:68a7dd5eecae68acca580f41');
+         * 
+         * // Get next 20 messages using last_message_id
+         * const nextMessages = await bot.direct.messages.get('1_on_1:68a7dd5eecae68acca580f41:68a7dd5eecae68acca580f41', messages[19].id);
+         */
+        get(conversation_id: string, last_message_id?: string): Promise<GetMessagesResponse[]>;
+    }
+}
+
+declare class PlayerClass {
+
+    /**
+     * Walk the player to specified coordinates with optional facing direction
+     * @param x - The x coordinate to walk to
+     * @param y - The y coordinate to walk to
+     * @param z - The z coordinate to walk to
+     * @param facing - The direction the player should face after walking (default: 'FrontRight')
+     * @throws {TypeError} If any coordinate is missing or invalid types are provided
+     * @example
+     * await bot.player.walk(10, 5, 15, 'FrontLeft');
+     */
+    walk(x: number, y: number, z: number, facing?: Facing): Promise<boolean>;
+
+    /**
+     * Make the bot sit on an anchor
+     * @param entity_id - The entity ID of the anchor
+     * @param anchor_ix - The anchor index (default: 0)
+     * @returns Promise resolving to operation success status
+     * @example
+     * ```typescript
+     * const success = await bot.player.sit('chair_entity_id', 0);
+     * ```
+     */
+    sit(entity_id: string, anchor_ix?: number): Promise<boolean>;
+
+    /**
+     * Teleport a user to specified coordinates with optional facing direction
+     * @param user_id - The user ID of the player to teleport
+     * @param x - The x coordinate to teleport to
+     * @param y - The y coordinate to teleport to
+     * @param z - The z coordinate to teleport to
+     * @param facing - The direction the player should face after teleporting (default: 'FrontRight')
+     * @throws {TypeError} If user_id is missing or coordinates are invalid
+     * @example
+     * await bot.player.teleport('68a7dd5eecae68acca580f41', 20, 10, 30, 'BackLeft');
+     */
+    teleport(user_id: string, x: number, y: number, z: number, facing?: Facing): Promise<boolean>;
+
+    /**
+     * Play an emote on a user
+     * @param emote_id - The ID of the emote to play
+     * @param user_id - The user ID to play the emote on (default: current bot user)
+     * @throws {TypeError} If user_id or emote_id are missing or invalid
+     * @example
+     * // Play emote on bot
+     * await bot.player.emote('dance');
+     * 
+     * // Play emote on specific user
+     * await bot.player.emote('wave', '68a7dd5eecae68acca580f41');
+     */
+    emote(emote_id: string, user_id?: string | undefined): Promise<boolean>;
+
+    /**
+     * Send a reaction to a user
+     * @param user_id - The user ID to send the reaction to
+     * @param reaction - The reaction type to send (must be one of: 'clap', 'heart', 'thumbs', 'wave', 'wink')
+     * @throws {TypeError} If user_id or reaction are missing or invalid
+     * @throws {Error} If reaction is not one of the valid reactions
+     * @example
+     * await bot.player.react('68a7dd5eecae68acca580f41', 'clap');
+     * await bot.player.react('68a7dd5eecae68acca580f41', 'heart');
+     */
+    react(user_id: string, reaction: Reactions): Promise<boolean>;
+
+    /**
+     * Transport a user to another room
+     * @param user_id - The user ID to transport to another room
+     * @param room_id - The destination room ID
+     * @throws {TypeError} If user_id or room_id are missing or invalid
+     * @throws {Error} If attempting to transport the bot itself
+     * @example
+     * // Transport a user to another room
+     * await bot.player.transport('68a7dd5eecae68acca580f41', '692125c2521b7580234d0f35');
+     * 
+     * // This will throw an error:
+     * // await bot.player.transport(bot.info.user.id, '692125c2521b7580234d0f35');
+     */
+    transport(user_id: string, room_id: string): Promise<boolean>;
+
+    /**
+     * Send a tip to a user
+     * @param user_id - The user ID to tip (must be a non-empty string)
+     * @param gold_bar - The amount of gold bars to tip (must be a number between 1 and 10,000 and a valid gold bar amount)
+     * @throws {TypeError} When user_id is not a string or not in room, or gold_bar is invalid
+     * @throws {Error} When the tip operation fails
+     */
+    tip(user_id: string, gold_bar?: Goldbars): Promise<boolean>;
+
+    /**
+     * Player Outfit management
+     */
+    public outfit: {
+        /**
+         * Get a user's current outfit
+         * @param user_id - The user ID to get the outfit for
+         * @returns Promise resolving to array of outfit items
+         * @example
+         * ```typescript
+         * // Get user's outfit
+         * const outfit = await bot.player.outfit.get('68a7dd5eecae68acca580f41');
+         * console.log(outfit);
+         * // [
+         * //   {
+         * //     type: 'clothing',
+         * //     amount: 1,
+         * //     id: 'shirt-n_cooltshirt',
+         * //     account_bound: false,
+         * //     active_palette: null
+         * //   },
+         * //   ...
+         * // ]
+         * ```
+         */
+        get(user_id: string): Promise<GetUserOutfitResponse[]>;
+    }
+
+    /**
+     * Moderation actions for room management
+     */
+    public moderation: {
+        /**
+         * Kick a user from the room
+         * @param user_id - The user ID of the user to kick
+         * @throws {TypeError} If user_id is missing or invalid
+         * @example
+         * await bot.player.moderation.kick('68a7dd5eecae68acca580f41');
+         */
+        kick(user_id: string): Promise<boolean>;
+
+        /**
+         * Ban a user from the room for a specified duration
+         * @param user_id - The user ID of the user to ban
+         * @param duration - Ban duration in milliseconds (default: 1 hour)
+         * @throws {TypeError} If user_id is missing or duration is invalid
+         * @example
+         * // Ban for 1 hour (default)
+         * await bot.player.moderation.ban('68a7dd5eecae68acca580f41');
+         * 
+         * // Ban for 30 minutes
+         * await bot.player.moderation.ban('68a7dd5eecae68acca580f41', 30 * 60 * 1000);
+         * 
+         * // Ban for 1 day
+         * await bot.player.moderation.ban('68a7dd5eecae68acca580f41', 24 * 60 * 60 * 1000);
+         */
+        ban(user_id: string, duration?: number): Promise<boolean>;
+
+        /**
+         * Mute a user in the room for a specified duration
+         * @param user_id - The user ID of the user to mute
+         * @param duration - Mute duration in milliseconds (default: 5 minutes)
+         * @throws {TypeError} If user_id is missing or duration is invalid
+         * @example
+         * // Mute for 5 minutes (default)
+         * await bot.player.moderation.mute('68a7dd5eecae68acca580f41');
+         * 
+         * // Mute for 1 hour
+         * await bot.player.moderation.mute('68a7dd5eecae68acca580f41', 60 * 60 * 1000);
+         */
+        mute(user_id: string, duration?: number): Promise<boolean>;
+
+        /**
+         * Unmute a previously muted user in the room
+         * @param user_id - The user ID of the user to unmute
+         * @throws {TypeError} If user_id is missing or invalid
+         * @example
+         * await bot.player.moderation.unmute('68a7dd5eecae68acca580f41');
+         */
+        unmute(user_id: string): Promise<boolean>;
+
+        /**
+         * Unban a previously banned user from the room
+         * @param user_id - The user ID of the user to unban
+         * @throws {TypeError} If user_id is missing or invalid
+         * @example
+         * await bot.player.moderation.unban('68a7dd5eecae68acca580f41');
+         */
+        unban(user_id: string): Promise<boolean>;
+    }
+}
+
+declare class Logger {
+    /**
+     * Generic log method for custom log levels
+     * @param level - The log level
+     * @param method - The method name where the log originated
+     * @param message - The main log message
+     * @param data - Optional data object to include in the log
+     * @example
+     * logger.log('CUSTOM', 'myMethod', 'Custom log message', { userId: '68a7dd5eecae68acca580f41' });
+     */
+    log(level: string, method: string, message: string, data?: any): void;
+
+    /**
+     * Log a success message (green color)
+     * @param method - The method name where the log originated
+     * @param message - The success message
+     * @param data - Optional data object to include in the log
+     * @example
+     * logger.success('walk', 'Successfully walked to destination', { x: 10, y: 5, z: 15 });
+     */
+    success(method: string, message: string, data?: any): void;
+
+    /**
+     * Log an error message (red color)
+     * @param method - The method name where the log originated
+     * @param message - The error message
+     * @param data - Optional data object to include in the log
+     * @example
+     * logger.error('teleport', 'Failed to teleport user', { userId: '68a7dd5eecae68acca580f41', error: 'Invalid coordinates' });
+     */
+    error(method: string, message: string, data?: any): void;
+
+    /**
+     * Log a warning message (yellow color)
+     * @param method - The method name where the log originated
+     * @param message - The warning message
+     * @param data - Optional data object to include in the log
+     * @example
+     * logger.warn('moderation.ban', 'User was banned', { userId: '68a7dd5eecae68acca580f41', duration: 3600000 });
+     */
+    warn(method: string, message: string, data?: any): void;
+
+    /**
+     * Log an info message (blue color)
+     * @param method - The method name where the log originated
+     * @param message - The info message
+     * @param data - Optional data object to include in the log
+     * @example
+     * logger.info('emote', 'Playing emote for user', { userId: '68a7dd5eecae68acca580f41', emoteId: 'dance' });
+     */
+    info(method: string, message: string, data?: any): void;
+
+    /**
+     * Log a debug message (magenta color)
+     * @param method - The method name where the log originated
+     * @param message - The debug message
+     * @param data - Optional data object to include in the log
+     * @example
+     * logger.debug('react', 'Validating reaction parameters', { userId: '68a7dd5eecae68acca580f41', reaction: 'wave' });
+     */
+    debug(method: string, message: string, data?: any): void;
+}
+
+interface BotUtils {
+    /**
+     * Logger instance for structured, color-coded logging throughout the application
+     * Provides different log levels (SUCCESS, ERROR, WARN, INFO, DEBUG) with timestamps and method tracking
+     * 
+     * @example
+     * // Basic logging
+     * bot.utils.logger.info('connection', 'Bot connected successfully');
+     * bot.utils.logger.error('auth', 'Authentication failed', { userId: '68a7dd5eecae68acca580f41' });
+     * 
+     * // With different levels
+     * bot.utils.logger.success('payment', 'Payment processed');
+     * bot.utils.logger.warn('moderation', 'User warning issued');
+     * bot.utils.logger.debug('websocket', 'Message received', { type: message._type });
+     */
+    logger: Logger;
+
+    /**
+     * Utility method to create a delay/pause in execution
+     * Returns a Promise that resolves after the specified time, useful for rate limiting,
+     * artificial delays, or waiting between methods
+     * 
+     * @param ms - Delay duration in milliseconds
+     * @returns Promise that resolves after the specified delay
+     * 
+     * @example
+     * // Basic delay
+     * await bot.utils.sleep(1000); // Wait 1 second
+     * 
+     * // Rate limiting between messages
+     * await bot.message.send("First message");
+     * await bot.utils.sleep(500); // Wait 500ms
+     * await bot.message.send("Second message");
+     * 
+     * // Artificial delay for user experience
+     * await bot.utils.sleep(2000); // Wait 2 seconds before response
+     * await bot.message.send("Processing complete!");
+     * 
+     * // In loops with delays
+     * for (let i = 0; i < 5; i++) {
+     *   await bot.message.send(`Message ${i + 1}`);
+     *   await bot.utils.sleep(1000); // Wait 1 second between messages
+     * }
+     */
+    sleep(ms: number): Promise<boolean>;
+
+    DanceFloor: DanceFloor
+
+    /**
+     * Creates a new CooldownManager instance with empty cooldown collections.
+     */
+    cooldown: CooldownManager
+
+    /**
+     * Role-based permission management with Web API auto-sync
+     */
+    permissions: RoleManager;
+}
+
+declare class RoomClass {
+    /**
+     * Room privilege methods
+     */
+    public privilege: {
+        /**
+         * Get room privilege of a specific user
+         * @param user_id - The user ID to check privilege for
+         * @returns Promise resolving to user privileges
+         * @example
+         * ```typescript
+         * const privileges = await bot.room.privilege.get('68a7dd5eecae68acca580f41');
+         * console.log(privileges.moderator); // true/false
+         * console.log(privileges.designer); // true/false
+         * ```
+         */
+        get(user_id: string): Promise<GetRoomPrivilegeResponse>;
+
+        /**
+         * Check if a user is a moderator in the room
+         * @param user_id - The user ID to check
+         * @returns Promise resolving to boolean indicating moderator status
+         * @example
+         * ```typescript
+         * const isMod = await bot.room.privilege.isModerator('68a7dd5eecae68acca580f41');
+         * if (isMod) {
+         *   console.log('User is a moderator');
+         * }
+         * ```
+         */
+        isModerator(user_id: string): Promise<boolean>;
+
+        /**
+         * Check if a user is a designer in the room
+         * @param user_id - The user ID to check
+         * @returns Promise resolving to boolean indicating designer status
+         * @example
+         * ```typescript
+         * const isDesigner = await bot.room.privilege.isDesigner('68a7dd5eecae68acca580f41');
+         * if (isDesigner) {
+         *   console.log('User is a designer');
+         * }
+         * ```
+         */
+        isDesigner(user_id: string): Promise<boolean>;
+    }
+
+    /**
+     * Designer privilege management
+     */
+    public designer: {
+        /**
+         * Add designer privileges to a user
+         * @param user_id - The user ID to grant designer privileges to
+         * @returns Promise resolving to operation success status
+         * @example
+         * ```typescript
+         * const success = await bot.room.designer.add('68a7dd5eecae68acca580f41');
+         * if (success) {
+         *   console.log('User is now a designer');
+         * }
+         * ```
+         */
+        add(user_id: string): Promise<boolean>;
+
+        /**
+         * Remove designer privileges from a user
+         * @param user_id - The user ID to remove designer privileges from
+         * @returns Promise resolving to operation success status
+         * @example
+         * ```typescript
+         * const success = await bot.room.designer.remove('68a7dd5eecae68acca580f41');
+         * if (success) {
+         *   console.log('User is no longer a designer');
+         * }
+         * ```
+         */
+        remove(user_id: string): Promise<boolean>;
+    }
+
+    /**
+     * Moderator privilege management
+     */
+    public moderator: {
+        /**
+         * Add moderator privileges to a user
+         * @param user_id - The user ID to grant moderator privileges to
+         * @returns Promise resolving to operation success status
+         * @example
+         * ```typescript
+         * const success = await bot.room.moderator.add('68a7dd5eecae68acca580f41');
+         * if (success) {
+         *   console.log('User is now a moderator');
+         * }
+         * ```
+         */
+        add(user_id: string): Promise<boolean>;
+
+        /**
+         * Remove moderator privileges from a user
+         * @param user_id - The user ID to remove moderator privileges from
+         * @returns Promise resolving to operation success status
+         * @example
+         * ```typescript
+         * const success = await bot.room.moderator.remove('68a7dd5eecae68acca580f41');
+         * if (success) {
+         *   console.log('User is no longer a moderator');
+         * }
+         * ```
+         */
+        remove(user_id: string): Promise<boolean>;
+    }
+
+    /**
+     * Room user management methods
+     */
+    public users: {
+        /**
+         * Get all users currently in the room
+         * @returns Promise resolving to array of users with their positions
+         * @example
+         * ```typescript
+         * const users = await bot.room.users.get();
+         * ```
+         */
+        get(): Promise<Array<[
+            User,
+            Position
+        ]>>;
+
+        /**
+         * Get user ID by username
+         * @param username - The username to look up
+         * @returns Promise resolving to user ID
+         * @example
+         * ```typescript
+         * const userId = await bot.room.users.id('Unfairly');
+         * ```
+         */
+        id(username: string): Promise<string> | null;
+
+        /**
+         * Get username by user ID
+         * @param id - The user ID to look up
+         * @returns Promise resolving to username
+         * ```typescript
+         * const username = await bot.room.users.username('692118c325513614015cddbf');
+         * ```
+         */
+        username(id: string): Promise<string> | null;
+
+        /**
+         * Get user position by username or user ID
+         * @param identifier - Username or user ID
+         * @returns Promise resolving to user position
+         * @example
+         * ```typescript
+         * const pos = await bot.room.users.position('Unfairly');
+         * const pos = await bot.room.users.position('692118c325513614015cddbf');
+         * ```
+         */
+        position(identifier: string): Promise<Position | AnchorPosition>;
+    }
+
+    /**
+     * Room voice chat methods
+     */
+    public voice: {
+        /**
+         * Check the current voice chat status in the room (valid only if the bot were created on the room owner account)
+         * @returns Promise resolving an Object for success check or message on failed
+         * @example
+         * ```typescript
+         * const status = await bot.room.voice.check();
+         * 
+         * // if success
+         * console.log(status.autoSpeakersId) // [ '6734bf...', '68a73d...' ]
+         * 
+         * if failed
+         * console.log(status.message)
+         * ```
+         */
+        check(): Promise<ValidVoiceCheck | InvalidVoiceCheck>
+
+        /**
+         * Invite a user to speak in voice chat
+         * @param user_id - The user ID to invite as speaker
+         * @returns Promise resolving to operation success status
+         * @example
+         * ```typescript
+         * const success = await bot.room.voice.invite('68a7dd5eecae68acca580f41');
+         * ```
+         */
+        invite(user_id: string): Promise<boolean>;
+
+        /**
+         * Remove a user from voice chat speakers
+         * @param user_id - The user ID to remove from speakers
+         * @returns Promise resolving to operation success status
+         * @example
+         * ```typescript
+         * const success = await bot.room.voice.remove('68a7dd5eecae68acca580f41');
+         * ```
+         */
+        remove(user_id: string): Promise<boolean>;
+    }
+}
+
+/**
+ * Logger configuration - controls how bot messages appear in console
+ */
+interface LoggerOptions {
+    /** Show time in logs? (true = [2023-10-05T14:30:00.68a7dd5eecae68acca580f41Z] [INFO]) */
+    showTimestamp?: boolean;
+    /** Show method name? (true = [connect]: Connected) */
+    showMethodName?: boolean;
+    /** Use colors? (true = green success, red errors) */
+    colors?: boolean;
+}
+
+/**
+ * Bot connection settings - controls how bot handles disconnections
+ */
+interface HighriseOptions {
+    /** How logs look in console */
+    LoggerOptions?: LoggerOptions;
+    /** Wait time between reconnect tries (milliseconds) */
+    reconnectDelay: number;
+    /** Auto-reconnect if disconnected? */
+    autoReconnect: boolean;
+    /** Custom roles to create on startup */
+    customRoles?: string[];
+}
+
+/**
+ * Configuration options for request senders
+ */
+interface SenderConfig {
+    /**
+     * Default timeout for requests waiting in milliseconds (default: 10000ms)
+     */
+    defaultTimeout?: number;
+
+    /**
+     * Maximum number of retry attempts for failed requests (default: 2)
+     */
+    maxRetries?: number;
+
+    /**
+     * Delay between retry attempts in milliseconds (default: 100)
+     */
+    retryDelay?: number;
+}
+
+declare class Highrise {
+    /**
+     * Creates a new Highrise bot instance
+     * @param Events - Array of event names to listen for
+     * @param options - Configuration options for the bot
+     */
+    constructor(Events: EventType[], options?: HighriseOptions);
+
+    /** Public message actions */
+    public message: MessageClass;
+
+    /** Private whisper actions */
+    public whisper: WhisperClass;
+
+    /** Direct message and conversation actions */
+    public direct: DirectClass;
+
+    /** Player movement and interaction actions */
+    public player: PlayerClass;
+
+    /** Bot information and state */
+    public info: BotInformation;
+
+    /** Utility methods and tools for bot development and management */
+    public utils: BotUtils;
+
+    /** Room methods and management */
+    public room: RoomClass;
+
+    /** Inventory management operations */
+    public inventory: InventoryClass;
+
+    /** WebAPI Class for external Highrise API calls */
+    public webapi: WebApi
+
+    /** Await system for waiting for specific events with filters */
+    public await: AwaitClass
+
+    /**
+      * Hidden channel forbot-to-bot communication
+     * Allows sending and receiving messages between all bots in the room
+     * 
+     * @example
+     * ```typescript
+     * // Send to channel
+     * await bot.channel.send('Hello other bots!', ['greeting']);
+     * 
+     * // Listen for messages
+     * bot.channel.on(['greeting'], (data) => {
+     *   console.log(`Bot ${data.senderId} says: ${data.message}`);
+     * });
+     * ```
+     */
+    public channel: Channel;
+
+    /**
+     * Cache management system for efficient data storage and retrieval
+     * Provides optimized memory usage and fast lookups for frequently accessed data
+     */
+    public cache: {
+        /** 
+         * Movement cache for efficient user position tracking
+         * Automatically handles position changes and memory optimization
+         */
+        position: MovementCache
+    }
+
+    /**
+     * Authenticate and connect the bot to a Highrise room
+     * @param token - Bot authentication token (64 characters)
+     * @param room_id - Room ID to connect to (24 characters)
+     * @throws {Error} If token, room_id, or events are invalid
+     * @example
+     * await bot.login('your_64_character_bot_token_here', 'room_id_24_characters_long');
+     */
+    login(token: string, room_id: string): Promise<void>;
+
+    /**
+     * Manually disconnect the WebSocket connection and disable auto-reconnect
+     * Performs graceful shutdown by:
+     * - Disabling auto-reconnection
+     * - Cleaning up intervals and timeouts
+     * - Closing the WebSocket connection with code 1000 (normal closure)
+     * - Resetting connection state
+     * 
+     * @example
+     * // Gracefully disconnect from Highrise
+     * bot.disconnect();
+     * 
+     * // Example in a cleanup scenario
+     * process.on('SIGINT', () => {
+     *   console.log('Shutting down gracefully...');
+     *   bot.disconnect();
+     *   process.exit(0);
+     * });
+     * 
+     * @throws {Error} If there are issues during the cleanup process
+     * @emits Various cleanup events during the disconnection process
+     */
+    disconnect(): void;
+
+    /**
+     * Return system metrics
+     * Shows real-time statistics about bot performance, cache usage, and connection status
+     */
+    getMetrics(): MetricData
+
+    /**
+     * Configures the request/response and fire-and-forget senders
+     * @param config - Configuration object for sender behavior
+     * @example
+     * ```typescript
+     * // Configure with custom timeout and retries
+     * bot.configureSenders({
+     *   defaultTimeout: 15000,    // 15 second timeout
+     *   maxRetries: 3,           // 3 retry attempts
+     *   retryDelay: 200          // 200ms between retries
+     * });
+     * 
+     * // Configure only timeout
+     * bot.configureSenders({
+     *   defaultTimeout: 5000     // 5 second timeout only
+     * });
+     * 
+     * // Reset to defaults (empty config)
+     * bot.configureSenders();
+     * ```
+     * @throws {Error} If configuration values are outside valid ranges
+     */
+    configureSenders(config?: SenderConfig): void;
+
+    /**
+     * Register an event listener
+     * @param event - Event name to listen for
+     * @param listener - Async callback function to handle the event
+     * @returns The Highrise instance for chaining
+     */
+    on<K extends keyof EventMap>(event: K, listener: (...args: EventMap[K]) => Promise<void>): this;
+    on(event: string, listener: (...args: any[]) => Promise<void>): this;
+
+    /**
+     * Register a one-time event listener
+     * @param event - Event name to listen for
+     * @param listener - Async callback function to handle the event
+     * @returns The Highrise instance for chaining
+     */
+    once<K extends keyof EventMap>(event: K, listener: (...args: EventMap[K]) => Promise<void>): this;
+    once(event: string, listener: (...args: any[]) => Promise<void>): this;
+
+    /**
+     * Emit an event
+     * @param event - Event name to emit
+     * @param args - Arguments to pass to event listeners
+     * @returns True if the event had listeners, false otherwise
+     */
+    emit<K extends keyof EventMap>(event: K, ...args: EventMap[K]): boolean;
+    emit(event: string, ...args: any[]): boolean;
+}
+
+export { Highrise, WebApi }