taverns.js 0.2.0

package/dist/gateway.js

@@ -0,0 +1,273 @@
+"use strict";
+/**
+ * taverns.js - Gateway (WebSocket Client)
+ *
+ * Manages the WebSocket connection to the Tavern gateway.
+ * Handles authentication, heartbeats, auto-reconnection with exponential
+ * backoff, and event dispatching.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Gateway = void 0;
+const events_1 = require("events");
+const ws_1 = __importDefault(require("ws"));
+const constants_1 = require("./constants");
+var ConnectionState;
+(function (ConnectionState) {
+    ConnectionState[ConnectionState["DISCONNECTED"] = 0] = "DISCONNECTED";
+    ConnectionState[ConnectionState["CONNECTING"] = 1] = "CONNECTING";
+    ConnectionState[ConnectionState["CONNECTED"] = 2] = "CONNECTED";
+    ConnectionState[ConnectionState["RECONNECTING"] = 3] = "RECONNECTING";
+})(ConnectionState || (ConnectionState = {}));
+class Gateway extends events_1.EventEmitter {
+    constructor(options) {
+        super();
+        this.ws = null;
+        this.heartbeatTimer = null;
+        this.reconnectTimer = null;
+        this.state = ConnectionState.DISCONNECTED;
+        this.reconnectAttempts = 0;
+        this.destroyed = false;
+        this.token = options.token;
+        this.url = options.url || constants_1.DEFAULT_WS_URL;
+        this.heartbeatInterval = options.heartbeatInterval || 30000;
+        this.autoReconnect = options.autoReconnect ?? true;
+        this.maxReconnectAttempts = options.maxReconnectAttempts ?? Infinity;
+        this.intents = options.intents;
+    }
+    /** Whether the gateway is currently connected. */
+    get connected() {
+        return this.state === ConnectionState.CONNECTED;
+    }
+    /** Update the bot token (used when login() provides a new token). */
+    setToken(token) {
+        this.token = token;
+    }
+    /**
+     * Connect to the gateway.
+     * Resolves once the WebSocket connection is open.
+     */
+    connect() {
+        if (this.destroyed) {
+            return Promise.reject(new Error('Gateway has been destroyed'));
+        }
+        if (this.state === ConnectionState.CONNECTED || this.state === ConnectionState.CONNECTING) {
+            return Promise.resolve();
+        }
+        this.state = ConnectionState.CONNECTING;
+        this.emit('debug', `Connecting to gateway: ${this.url}`);
+        return new Promise((resolve, reject) => {
+            let wsUrl = `${this.url}?token=${encodeURIComponent(this.token)}`;
+            if (this.intents !== undefined) {
+                wsUrl += `&intents=${this.intents.toString()}`;
+            }
+            try {
+                this.ws = new ws_1.default(wsUrl);
+            }
+            catch (err) {
+                this.state = ConnectionState.DISCONNECTED;
+                reject(err);
+                return;
+            }
+            const onOpen = () => {
+                this.state = ConnectionState.CONNECTED;
+                this.reconnectAttempts = 0;
+                this.startHeartbeat();
+                this.emit('debug', 'Gateway connection established');
+                cleanup();
+                resolve();
+            };
+            const onError = (err) => {
+                this.emit('debug', `Gateway connection error: ${err.message}`);
+                if (this.state === ConnectionState.CONNECTING) {
+                    cleanup();
+                    this.state = ConnectionState.DISCONNECTED;
+                    reject(err);
+                }
+            };
+            const onClose = (code, reason) => {
+                const reasonStr = reason.toString('utf-8');
+                this.emit('debug', `Gateway closed during connect: ${code} ${reasonStr}`);
+                if (this.state === ConnectionState.CONNECTING) {
+                    cleanup();
+                    this.state = ConnectionState.DISCONNECTED;
+                    reject(new Error(`WebSocket closed: ${code} ${reasonStr}`));
+                }
+            };
+            const cleanup = () => {
+                this.ws?.removeListener('open', onOpen);
+                this.ws?.removeListener('error', onError);
+                this.ws?.removeListener('close', onClose);
+                // Re-attach permanent handlers
+                if (this.ws) {
+                    this.ws.on('message', this.onMessage.bind(this));
+                    this.ws.on('close', this.onClose.bind(this));
+                    this.ws.on('error', this.onError.bind(this));
+                }
+            };
+            this.ws.once('open', onOpen);
+            this.ws.once('error', onError);
+            this.ws.once('close', onClose);
+        });
+    }
+    /**
+     * Send a JSON message to the gateway.
+     */
+    send(action, data) {
+        if (!this.ws || this.state !== ConnectionState.CONNECTED) {
+            this.emit('debug', `Cannot send "${action}": not connected`);
+            return;
+        }
+        const payload = JSON.stringify({ action, data });
+        try {
+            this.ws.send(payload);
+        }
+        catch (err) {
+            this.emit('debug', `Failed to send "${action}": ${err.message}`);
+        }
+    }
+    /**
+     * Gracefully disconnect and clean up. The gateway cannot be reused after this.
+     */
+    destroy() {
+        this.destroyed = true;
+        this.autoReconnect = false;
+        this.cleanup();
+        this.state = ConnectionState.DISCONNECTED;
+        this.emit('debug', 'Gateway destroyed');
+        this.removeAllListeners();
+    }
+    /**
+     * Disconnect without destroying (allows reconnection).
+     */
+    disconnect() {
+        this.cleanup();
+        this.state = ConnectionState.DISCONNECTED;
+        this.emit('debug', 'Gateway disconnected');
+    }
+    // ─── Internal ──────────────────────────────────────────
+    onMessage(data) {
+        let raw;
+        if (data instanceof Buffer) {
+            raw = data.toString('utf-8');
+        }
+        else if (data instanceof ArrayBuffer) {
+            raw = Buffer.from(data).toString('utf-8');
+        }
+        else if (Array.isArray(data)) {
+            raw = Buffer.concat(data).toString('utf-8');
+        }
+        else {
+            raw = String(data);
+        }
+        let payload;
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch {
+            this.emit('debug', `Received non-JSON message: ${raw.substring(0, 200)}`);
+            return;
+        }
+        const eventName = payload.event || payload.action;
+        if (!eventName) {
+            this.emit('debug', `Received message without event/action: ${raw.substring(0, 200)}`);
+            return;
+        }
+        this.emit('debug', `Gateway event: ${eventName}`);
+        this.emit('event', eventName, payload.data);
+    }
+    onClose(code, reason) {
+        const reasonStr = reason.toString('utf-8');
+        this.emit('debug', `Gateway closed: ${code} ${reasonStr}`);
+        this.stopHeartbeat();
+        this.state = ConnectionState.DISCONNECTED;
+        this.emit('close', code, reasonStr);
+        // Auth failures should not trigger reconnect
+        if (code === 4001 || code === 4003 || code === 4004) {
+            this.emit('debug', `Authentication error (${code}), not reconnecting`);
+            return;
+        }
+        if (this.autoReconnect && !this.destroyed) {
+            this.scheduleReconnect();
+        }
+    }
+    onError(err) {
+        this.emit('debug', `Gateway error: ${err.message}`);
+        this.emit('error', err);
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            this.send(constants_1.GatewayAction.HEARTBEAT);
+            this.emit('debug', 'Sent heartbeat');
+        }, this.heartbeatInterval);
+        // Prevent the timer from keeping the process alive
+        if (this.heartbeatTimer.unref) {
+            this.heartbeatTimer.unref();
+        }
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        this.reconnectAttempts++;
+        if (this.reconnectAttempts > this.maxReconnectAttempts) {
+            this.emit('debug', `Max reconnect attempts (${this.maxReconnectAttempts}) reached, giving up`);
+            this.emit('reconnectFailed');
+            return;
+        }
+        // Exponential backoff: 1s, 2s, 4s, 8s, 16s, 30s (max)
+        const baseDelay = Math.min(1000 * Math.pow(2, this.reconnectAttempts - 1), 30000);
+        // Add jitter (0-25% of base delay)
+        const jitter = Math.floor(Math.random() * baseDelay * 0.25);
+        const delay = baseDelay + jitter;
+        this.state = ConnectionState.RECONNECTING;
+        this.emit('debug', `Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
+        this.emit('reconnecting', this.reconnectAttempts);
+        this.reconnectTimer = setTimeout(async () => {
+            this.reconnectTimer = null;
+            if (this.destroyed)
+                return;
+            try {
+                await this.connect();
+                this.emit('reconnected');
+            }
+            catch (err) {
+                this.emit('debug', `Reconnect attempt ${this.reconnectAttempts} failed: ${err.message}`);
+                if (!this.destroyed && this.autoReconnect) {
+                    this.scheduleReconnect();
+                }
+            }
+        }, delay);
+        if (this.reconnectTimer.unref) {
+            this.reconnectTimer.unref();
+        }
+    }
+    cleanup() {
+        this.stopHeartbeat();
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.removeAllListeners();
+            if (this.ws.readyState === ws_1.default.OPEN || this.ws.readyState === ws_1.default.CONNECTING) {
+                try {
+                    this.ws.close(1000, 'Client disconnect');
+                }
+                catch {
+                    // Ignore close errors
+                }
+            }
+            this.ws = null;
+        }
+    }
+}
+exports.Gateway = Gateway;

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * taverns.js - SDK for building Tavern bots
+ *
+ * SDK for building bots on the Taverns platform.
+ *
+ * @example
+ * ```ts
+ * import { Client, PermissionsBitField } from 'taverns.js';
+ *
+ * const client = new Client({ token: 'tavbot_...' });
+ *
+ * client.on('ready', () => {
+ *   console.log(`Logged in as ${client.user.displayName}`);
+ * });
+ *
+ * client.on('messageCreate', (message) => {
+ *   if (message.content === '!ping') {
+ *     message.reply('Pong!');
+ *   }
+ * });
+ *
+ * client.login();
+ * ```
+ */
+export { Client } from './client';
+export type { ActionableMessage, ActionableInteraction } from './client';
+export { PermissionsBitField, PermissionFlags } from './permissions';
+export type { PermissionFlagName } from './permissions';
+export { Collection } from './collection';
+export { RESTClient, TavernAPIError } from './rest';
+export { Gateway } from './gateway';
+export type { GatewayOptions } from './gateway';
+export * from './types';
+export * from './constants';
+export { verifyWebhookSignature } from './webhook';
+export { EmbedBuilder } from './embed';
+export type { Embed, EmbedField, EmbedFooter, EmbedImage } from './embed';

package/dist/index.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * taverns.js - SDK for building Tavern bots
+ *
+ * SDK for building bots on the Taverns platform.
+ *
+ * @example
+ * ```ts
+ * import { Client, PermissionsBitField } from 'taverns.js';
+ *
+ * const client = new Client({ token: 'tavbot_...' });
+ *
+ * client.on('ready', () => {
+ *   console.log(`Logged in as ${client.user.displayName}`);
+ * });
+ *
+ * client.on('messageCreate', (message) => {
+ *   if (message.content === '!ping') {
+ *     message.reply('Pong!');
+ *   }
+ * });
+ *
+ * client.login();
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmbedBuilder = exports.verifyWebhookSignature = exports.Gateway = exports.TavernAPIError = exports.RESTClient = exports.Collection = exports.PermissionFlags = exports.PermissionsBitField = exports.Client = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_1.Client; } });
+var permissions_1 = require("./permissions");
+Object.defineProperty(exports, "PermissionsBitField", { enumerable: true, get: function () { return permissions_1.PermissionsBitField; } });
+Object.defineProperty(exports, "PermissionFlags", { enumerable: true, get: function () { return permissions_1.PermissionFlags; } });
+var collection_1 = require("./collection");
+Object.defineProperty(exports, "Collection", { enumerable: true, get: function () { return collection_1.Collection; } });
+var rest_1 = require("./rest");
+Object.defineProperty(exports, "RESTClient", { enumerable: true, get: function () { return rest_1.RESTClient; } });
+Object.defineProperty(exports, "TavernAPIError", { enumerable: true, get: function () { return rest_1.TavernAPIError; } });
+var gateway_1 = require("./gateway");
+Object.defineProperty(exports, "Gateway", { enumerable: true, get: function () { return gateway_1.Gateway; } });
+__exportStar(require("./types"), exports);
+__exportStar(require("./constants"), exports);
+var webhook_1 = require("./webhook");
+Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhook_1.verifyWebhookSignature; } });
+var embed_1 = require("./embed");
+Object.defineProperty(exports, "EmbedBuilder", { enumerable: true, get: function () { return embed_1.EmbedBuilder; } });

package/dist/permissions.d.ts

@@ -0,0 +1,161 @@
+/**
+ * taverns.js - PermissionsBitField
+ *
+ * Permissions utility for working with Tavern permission
+ * bitfields. Permissions are stored as BigInt flags, matching the server-side
+ * TavernPermission enum.
+ */
+/**
+ * All Tavern permission flags. Each flag is a bit position (0-35).
+ * The actual bitfield value is `1n << BigInt(position)`.
+ */
+export declare const PermissionFlags: {
+    readonly VIEW_CHANNELS: 0n;
+    readonly MANAGE_CHANNELS: 1n;
+    readonly MANAGE_ROLES: 2n;
+    readonly MANAGE_TAVERN: 3n;
+    readonly CREATE_INVITE: 4n;
+    readonly KICK_MEMBERS: 5n;
+    readonly BAN_MEMBERS: 6n;
+    readonly MANAGE_NICKNAMES: 7n;
+    readonly MANAGE_PERMISSIONS: 8n;
+    readonly PIN_MESSAGES: 9n;
+    readonly SEND_MESSAGES: 10n;
+    readonly MANAGE_MESSAGES: 11n;
+    readonly ATTACH_FILES: 13n;
+    readonly ADD_REACTIONS: 14n;
+    readonly MENTION_EVERYONE: 15n;
+    readonly EMBED_LINKS: 16n;
+    readonly READ_MESSAGE_HISTORY: 17n;
+    readonly USE_EXTERNAL_EMOJI: 18n;
+    readonly USE_EXTERNAL_STICKERS: 19n;
+    readonly MANAGE_STICKERS: 12n;
+    readonly MUTE_MEMBERS: 20n;
+    readonly BYPASS_SLOWMODE: 21n;
+    readonly CONNECT_VOICE: 22n;
+    readonly SPEAK: 23n;
+    readonly MANAGE_VOICE: 24n;
+    readonly VIDEO: 25n;
+    readonly CREATE_EVENTS: 26n;
+    readonly MANAGE_EVENTS: 27n;
+    readonly CREATE_POLLS: 28n;
+    readonly VOTE_IN_POLLS: 29n;
+    readonly ADMINISTRATOR: 30n;
+    readonly CREATE_PUBLIC_THREADS: 31n;
+    readonly CREATE_PRIVATE_THREADS: 32n;
+    readonly MANAGE_THREADS: 33n;
+    readonly SEND_MESSAGES_IN_THREADS: 34n;
+    readonly MANAGE_BOTS: 35n;
+};
+export type PermissionFlagName = keyof typeof PermissionFlags;
+/**
+ * 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']
+ * ```
+ */
+export declare class PermissionsBitField {
+    /**
+     * Static reference to all permission flags.
+     * @example PermissionsBitField.FLAGS.SEND_MESSAGES
+     */
+    static readonly FLAGS: {
+        readonly VIEW_CHANNELS: 0n;
+        readonly MANAGE_CHANNELS: 1n;
+        readonly MANAGE_ROLES: 2n;
+        readonly MANAGE_TAVERN: 3n;
+        readonly CREATE_INVITE: 4n;
+        readonly KICK_MEMBERS: 5n;
+        readonly BAN_MEMBERS: 6n;
+        readonly MANAGE_NICKNAMES: 7n;
+        readonly MANAGE_PERMISSIONS: 8n;
+        readonly PIN_MESSAGES: 9n;
+        readonly SEND_MESSAGES: 10n;
+        readonly MANAGE_MESSAGES: 11n;
+        readonly ATTACH_FILES: 13n;
+        readonly ADD_REACTIONS: 14n;
+        readonly MENTION_EVERYONE: 15n;
+        readonly EMBED_LINKS: 16n;
+        readonly READ_MESSAGE_HISTORY: 17n;
+        readonly USE_EXTERNAL_EMOJI: 18n;
+        readonly USE_EXTERNAL_STICKERS: 19n;
+        readonly MANAGE_STICKERS: 12n;
+        readonly MUTE_MEMBERS: 20n;
+        readonly BYPASS_SLOWMODE: 21n;
+        readonly CONNECT_VOICE: 22n;
+        readonly SPEAK: 23n;
+        readonly MANAGE_VOICE: 24n;
+        readonly VIDEO: 25n;
+        readonly CREATE_EVENTS: 26n;
+        readonly MANAGE_EVENTS: 27n;
+        readonly CREATE_POLLS: 28n;
+        readonly VOTE_IN_POLLS: 29n;
+        readonly ADMINISTRATOR: 30n;
+        readonly CREATE_PUBLIC_THREADS: 31n;
+        readonly CREATE_PRIVATE_THREADS: 32n;
+        readonly MANAGE_THREADS: 33n;
+        readonly SEND_MESSAGES_IN_THREADS: 34n;
+        readonly MANAGE_BOTS: 35n;
+    };
+    /** The raw bitfield value. */
+    readonly bitfield: bigint;
+    /**
+     * Create a new PermissionsBitField.
+     * @param bits - A BigInt, numeric string, number, or another PermissionsBitField
+     */
+    constructor(bits?: bigint | string | number | PermissionsBitField);
+    /**
+     * Check if this bitfield has a specific permission.
+     * @param permission - Permission flag name or bit position
+     */
+    has(permission: PermissionFlagName | bigint): boolean;
+    /**
+     * Check if this bitfield has any of the specified permissions.
+     */
+    hasAny(...permissions: (PermissionFlagName | bigint)[]): boolean;
+    /**
+     * Check if this bitfield has all of the specified permissions.
+     */
+    hasAll(...permissions: (PermissionFlagName | bigint)[]): boolean;
+    /**
+     * Return a new PermissionsBitField with the given permission(s) added.
+     */
+    add(...permissions: (PermissionFlagName | bigint)[]): PermissionsBitField;
+    /**
+     * Return a new PermissionsBitField with the given permission(s) removed.
+     */
+    remove(...permissions: (PermissionFlagName | bigint)[]): PermissionsBitField;
+    /**
+     * Return an array of all permission flag names that are set.
+     */
+    toArray(): PermissionFlagName[];
+    /**
+     * Serialize to a decimal string (matches API format).
+     */
+    toString(): string;
+    /**
+     * Serialize to JSON as a decimal string.
+     */
+    toJSON(): string;
+    /**
+     * Check if this bitfield equals another.
+     */
+    equals(other: PermissionsBitField | bigint | string): boolean;
+    /**
+     * Get a bitfield with all permissions set.
+     */
+    static all(): PermissionsBitField;
+    /**
+     * Resolve a permission name or bigint to its bitfield flag.
+     */
+    private resolve;
+}