taverns.js 0.2.0

package/dist/permissions.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * taverns.js - PermissionsBitField
+ *
+ * Permissions utility for working with Tavern permission
+ * bitfields. Permissions are stored as BigInt flags, matching the server-side
+ * TavernPermission enum.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionsBitField = exports.PermissionFlags = void 0;
+/**
+ * All Tavern permission flags. Each flag is a bit position (0-35).
+ * The actual bitfield value is `1n << BigInt(position)`.
+ */
+exports.PermissionFlags = {
+    // General
+    VIEW_CHANNELS: 0n,
+    MANAGE_CHANNELS: 1n,
+    MANAGE_ROLES: 2n,
+    MANAGE_TAVERN: 3n,
+    CREATE_INVITE: 4n,
+    KICK_MEMBERS: 5n,
+    BAN_MEMBERS: 6n,
+    MANAGE_NICKNAMES: 7n,
+    MANAGE_PERMISSIONS: 8n,
+    PIN_MESSAGES: 9n,
+    // Text
+    SEND_MESSAGES: 10n,
+    MANAGE_MESSAGES: 11n,
+    ATTACH_FILES: 13n,
+    ADD_REACTIONS: 14n,
+    MENTION_EVERYONE: 15n,
+    EMBED_LINKS: 16n,
+    READ_MESSAGE_HISTORY: 17n,
+    USE_EXTERNAL_EMOJI: 18n,
+    USE_EXTERNAL_STICKERS: 19n,
+    // Content
+    MANAGE_STICKERS: 12n,
+    // Moderation
+    MUTE_MEMBERS: 20n,
+    BYPASS_SLOWMODE: 21n,
+    // Voice
+    CONNECT_VOICE: 22n,
+    SPEAK: 23n,
+    MANAGE_VOICE: 24n,
+    VIDEO: 25n,
+    // Events
+    CREATE_EVENTS: 26n,
+    MANAGE_EVENTS: 27n,
+    // Polls
+    CREATE_POLLS: 28n,
+    VOTE_IN_POLLS: 29n,
+    // Admin
+    ADMINISTRATOR: 30n,
+    // Threads
+    CREATE_PUBLIC_THREADS: 31n,
+    CREATE_PRIVATE_THREADS: 32n,
+    MANAGE_THREADS: 33n,
+    SEND_MESSAGES_IN_THREADS: 34n,
+    // Bots
+    MANAGE_BOTS: 35n,
+};
+/** All permission flags OR'd together */
+const ALL_PERMISSIONS = Object.values(exports.PermissionFlags).reduce((acc, bit) => acc | (1n << bit), 0n);
+/**
+ * A bitfield that represents a set of permissions.
+ *
+ * @example
+ * ```ts
+ * const perms = new PermissionsBitField('2048'); // from API string
+ *
+ * if (perms.has('SEND_MESSAGES')) {
+ *   // Bot can send messages
+ * }
+ *
+ * const withAdmin = perms.add('ADMINISTRATOR');
+ * console.log(withAdmin.toArray()); // ['SEND_MESSAGES', 'ADMINISTRATOR']
+ * ```
+ */
+class PermissionsBitField {
+    /**
+     * Create a new PermissionsBitField.
+     * @param bits - A BigInt, numeric string, number, or another PermissionsBitField
+     */
+    constructor(bits) {
+        if (bits === undefined || bits === null) {
+            this.bitfield = 0n;
+        }
+        else if (bits instanceof PermissionsBitField) {
+            this.bitfield = bits.bitfield;
+        }
+        else if (typeof bits === 'bigint') {
+            this.bitfield = bits;
+        }
+        else if (typeof bits === 'string') {
+            this.bitfield = BigInt(bits);
+        }
+        else {
+            this.bitfield = BigInt(bits);
+        }
+    }
+    /**
+     * Check if this bitfield has a specific permission.
+     * @param permission - Permission flag name or bit position
+     */
+    has(permission) {
+        const flag = this.resolve(permission);
+        // ADMINISTRATOR grants everything
+        if ((this.bitfield & (1n << exports.PermissionFlags.ADMINISTRATOR)) !== 0n) {
+            return true;
+        }
+        return (this.bitfield & flag) === flag;
+    }
+    /**
+     * Check if this bitfield has any of the specified permissions.
+     */
+    hasAny(...permissions) {
+        return permissions.some((p) => this.has(p));
+    }
+    /**
+     * Check if this bitfield has all of the specified permissions.
+     */
+    hasAll(...permissions) {
+        return permissions.every((p) => this.has(p));
+    }
+    /**
+     * Return a new PermissionsBitField with the given permission(s) added.
+     */
+    add(...permissions) {
+        let bits = this.bitfield;
+        for (const perm of permissions) {
+            bits |= this.resolve(perm);
+        }
+        return new PermissionsBitField(bits);
+    }
+    /**
+     * Return a new PermissionsBitField with the given permission(s) removed.
+     */
+    remove(...permissions) {
+        let bits = this.bitfield;
+        for (const perm of permissions) {
+            bits &= ~this.resolve(perm);
+        }
+        return new PermissionsBitField(bits);
+    }
+    /**
+     * Return an array of all permission flag names that are set.
+     */
+    toArray() {
+        const result = [];
+        for (const [name, bit] of Object.entries(exports.PermissionFlags)) {
+            const flag = 1n << bit;
+            if ((this.bitfield & flag) === flag) {
+                result.push(name);
+            }
+        }
+        return result;
+    }
+    /**
+     * Serialize to a decimal string (matches API format).
+     */
+    toString() {
+        return this.bitfield.toString();
+    }
+    /**
+     * Serialize to JSON as a decimal string.
+     */
+    toJSON() {
+        return this.toString();
+    }
+    /**
+     * Check if this bitfield equals another.
+     */
+    equals(other) {
+        const otherBits = other instanceof PermissionsBitField
+            ? other.bitfield
+            : BigInt(other);
+        return this.bitfield === otherBits;
+    }
+    /**
+     * Get a bitfield with all permissions set.
+     */
+    static all() {
+        return new PermissionsBitField(ALL_PERMISSIONS);
+    }
+    /**
+     * Resolve a permission name or bigint to its bitfield flag.
+     */
+    resolve(permission) {
+        if (typeof permission === 'bigint') {
+            return 1n << permission;
+        }
+        const bit = exports.PermissionFlags[permission];
+        if (bit === undefined) {
+            throw new RangeError(`Unknown permission: ${permission}`);
+        }
+        return 1n << bit;
+    }
+}
+exports.PermissionsBitField = PermissionsBitField;
+/**
+ * Static reference to all permission flags.
+ * @example PermissionsBitField.FLAGS.SEND_MESSAGES
+ */
+PermissionsBitField.FLAGS = exports.PermissionFlags;

package/dist/rest.d.ts

@@ -0,0 +1,119 @@
+/**
+ * taverns.js - REST Client
+ *
+ * HTTP client for the Taverns API.
+ * Handles bot token authentication, rate limiting, and retries.
+ */
+import { EventEmitter } from 'events';
+import type { BotSelf, InstalledTavern, Tavern, Channel, Member, Role, Message, SendMessageOptions, EditMessageOptions, GetMessagesOptions, SearchMessagesOptions, CreateChannelOptions, UpdateChannelOptions, CreateRoleOptions, UpdateRoleOptions, BotCommand, InteractionCallbackData } from './types';
+export declare class RESTClient extends EventEmitter {
+    private token;
+    private baseUrl;
+    private buckets;
+    private globalRateLimit;
+    constructor(token: string, baseUrl?: string);
+    /** Update the bot token (used when login() provides a new token). */
+    setToken(token: string): void;
+    get<T = unknown>(path: string, query?: Record<string, string | number | undefined>): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    delete<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /** Get the bot's own profile and installed taverns. */
+    getSelf(): Promise<BotSelf>;
+    /** Get the list of taverns the bot is installed in. */
+    getMyTaverns(): Promise<InstalledTavern[]>;
+    /** Get a tavern by ID. */
+    getTavern(tavernId: string): Promise<Tavern>;
+    /** List all channels in a tavern. */
+    getChannels(tavernId: string): Promise<Channel[]>;
+    /** Create a new channel in a tavern. */
+    createChannel(tavernId: string, options: CreateChannelOptions): Promise<Channel>;
+    /** Update a channel. */
+    updateChannel(tavernId: string, channelId: string, options: UpdateChannelOptions): Promise<Channel>;
+    /** Delete a channel. */
+    deleteChannel(tavernId: string, channelId: string): Promise<void>;
+    /** Send a message to a channel. */
+    sendMessage(tavernId: string, channelId: string, options: SendMessageOptions): Promise<Message>;
+    /** Get messages from a channel. */
+    getMessages(tavernId: string, channelId: string, options?: GetMessagesOptions): Promise<Message[]>;
+    /** Edit a message. */
+    editMessage(tavernId: string, messageId: string, options: EditMessageOptions): Promise<Message>;
+    /** Delete a message. */
+    deleteMessage(tavernId: string, messageId: string): Promise<void>;
+    /** Pin a message. */
+    pinMessage(tavernId: string, messageId: string): Promise<void>;
+    /** Unpin a message. */
+    unpinMessage(tavernId: string, messageId: string): Promise<void>;
+    /** Get pinned messages in a channel. */
+    getPinnedMessages(tavernId: string, channelId: string): Promise<Message[]>;
+    /** Search messages in a tavern or specific channel. */
+    searchMessages(tavernId: string, options: SearchMessagesOptions): Promise<{
+        messages: Message[];
+        total: number;
+    }>;
+    /** Add a reaction to a message. */
+    addReaction(tavernId: string, messageId: string, emoji: string): Promise<void>;
+    /** Remove a reaction from a message. */
+    removeReaction(tavernId: string, messageId: string, emoji: string): Promise<void>;
+    /** Bulk delete messages in a channel. */
+    bulkDeleteMessages(tavernId: string, channelId: string, messageIds: string[]): Promise<void>;
+    /** List members of a tavern. */
+    getMembers(tavernId: string, options?: {
+        limit?: number;
+        after?: string;
+    }): Promise<Member[]>;
+    /** Get a specific member. */
+    getMember(tavernId: string, userId: string): Promise<Member>;
+    /** Kick a member from a tavern. */
+    kickMember(tavernId: string, userId: string, reason?: string): Promise<void>;
+    /** Ban a member from a tavern. */
+    banMember(tavernId: string, userId: string, reason?: string): Promise<void>;
+    /** Unban a member from a tavern. */
+    unbanMember(tavernId: string, userId: string): Promise<void>;
+    /** List roles in a tavern. */
+    getRoles(tavernId: string): Promise<Role[]>;
+    /** Create a new role in a tavern. */
+    createRole(tavernId: string, options: CreateRoleOptions): Promise<Role>;
+    /** Update a role. */
+    updateRole(tavernId: string, roleId: string, options: UpdateRoleOptions): Promise<Role>;
+    /** Delete a role. */
+    deleteRole(tavernId: string, roleId: string): Promise<void>;
+    /** Add a role to a member. */
+    addMemberRole(tavernId: string, userId: string, roleId: string): Promise<void>;
+    /** Remove a role from a member. */
+    removeMemberRole(tavernId: string, userId: string, roleId: string): Promise<void>;
+    /** Create a thread in a channel. */
+    createThread(tavernId: string, channelId: string, options: {
+        name: string;
+        rootMessageId?: string;
+        starterMessage?: string;
+        autoArchiveDuration?: number;
+        isPrivate?: boolean;
+    }): Promise<Channel>;
+    /** List threads in a channel. */
+    getThreads(tavernId: string, channelId: string): Promise<Channel[]>;
+    /** Get active threads across the tavern. */
+    getActiveThreads(tavernId: string): Promise<Channel[]>;
+    /** Register or overwrite all slash commands for this bot. */
+    registerCommands(commands: Omit<BotCommand, 'id' | 'version'>[]): Promise<BotCommand[]>;
+    /** Get all registered commands for this bot. */
+    getCommands(): Promise<BotCommand[]>;
+    /** Delete a registered command by ID. */
+    deleteCommand(commandId: string): Promise<void>;
+    /** Reply to an interaction. */
+    replyToInteraction(interactionId: string, data: InteractionCallbackData): Promise<void>;
+    /** Acknowledge an interaction with a deferred response (shows loading state). */
+    deferInteraction(interactionId: string): Promise<void>;
+    /** Send a follow-up message after replying or deferring an interaction. */
+    followUpInteraction(interactionId: string, data: InteractionCallbackData): Promise<void>;
+    private request;
+    private updateRateLimits;
+    private parseRetryAfter;
+    private sleep;
+}
+export declare class TavernAPIError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}