taverns.js 0.2.0

package/dist/client.js

@@ -0,0 +1,517 @@
+"use strict";
+/**
+ * taverns.js - Client
+ *
+ * The main entry point for building Tavern bots. Construct with a token,
+ * listen for events, and interact with the API.
+ *
+ * @example
+ * ```ts
+ * import { Client } from 'taverns.js';
+ *
+ * const client = new Client({ token: 'tavbot_...' });
+ *
+ * client.on('ready', () => {
+ *   console.log(`Logged in as ${client.user.displayName}`);
+ *   console.log(`Connected to ${client.taverns.size} taverns`);
+ * });
+ *
+ * client.on('messageCreate', (message) => {
+ *   if (message.content === '!ping') {
+ *     message.reply('Pong!');
+ *   }
+ * });
+ *
+ * client.login();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Client = void 0;
+const events_1 = require("events");
+const collection_1 = require("./collection");
+const rest_1 = require("./rest");
+const gateway_1 = require("./gateway");
+const constants_1 = require("./constants");
+// ─── Client ─────────────────────────────────────────────────
+class Client extends events_1.EventEmitter {
+    constructor(options = {}) {
+        super();
+        /** The bot's own user identity. Set after login(). */
+        this._user = null;
+        /** The bot application info. Set after login(). */
+        this._application = null;
+        /** Collection of taverns the bot is installed in, keyed by tavern ID. */
+        this.taverns = new collection_1.Collection();
+        /** Collection of all known channels across all taverns, keyed by channel ID. */
+        this.channels = new collection_1.Collection();
+        /** Cached members per tavern: Map<tavernId, Collection<userId, Member>> */
+        this.memberCache = new Map();
+        this.ready = false;
+        this.options = options;
+        this.token = options.token || null;
+        // Initialize REST client
+        this.rest = new rest_1.RESTClient(this.token || '', options.apiUrl || constants_1.DEFAULT_API_URL);
+        // Initialize Gateway
+        this.gateway = new gateway_1.Gateway({
+            token: this.token || '',
+            url: options.wsUrl || constants_1.DEFAULT_WS_URL,
+            heartbeatInterval: options.heartbeatInterval || 30000,
+            autoReconnect: options.autoReconnect ?? true,
+            maxReconnectAttempts: options.maxReconnectAttempts,
+            intents: options.intents,
+        });
+        // Wire up gateway events
+        this.setupGatewayListeners();
+    }
+    /**
+     * The bot's user identity. Throws if accessed before login().
+     */
+    get user() {
+        if (!this._user) {
+            throw new Error('Client is not logged in. Call client.login() first.');
+        }
+        return this._user;
+    }
+    /**
+     * The bot application info. Throws if accessed before login().
+     */
+    get application() {
+        if (!this._application) {
+            throw new Error('Client is not logged in. Call client.login() first.');
+        }
+        return this._application;
+    }
+    /**
+     * Whether the client has completed login and is ready.
+     */
+    get isReady() {
+        return this.ready;
+    }
+    /**
+     * Log in with the bot token, fetch identity, connect to the gateway,
+     * and emit the 'ready' event.
+     *
+     * @param token - Optional token override (otherwise uses the one from constructor)
+     */
+    async login(token) {
+        if (token) {
+            this.token = token;
+        }
+        if (!this.token) {
+            throw new Error('No bot token provided. Pass it to the constructor or login().');
+        }
+        if (!this.token.startsWith(constants_1.BOT_TOKEN_PREFIX)) {
+            throw new Error(`Invalid bot token format. Tokens must start with "${constants_1.BOT_TOKEN_PREFIX}".`);
+        }
+        // Update the REST client token
+        this.rest.setToken(this.token);
+        // Step 1: Fetch bot identity
+        this.emit('debug', 'Fetching bot identity...');
+        try {
+            this._application = await this.rest.getSelf();
+            this._user = this._application.user;
+        }
+        catch (err) {
+            if (err instanceof rest_1.TavernAPIError && (err.status === 401 || err.status === 403)) {
+                throw new Error(`Authentication failed: ${err.message}`);
+            }
+            throw err;
+        }
+        // Step 2: Populate taverns cache
+        this.emit('debug', `Bot "${this._user.displayName}" has ${this._application.taverns.length} tavern(s)`);
+        this.taverns.clear();
+        for (const installed of this._application.taverns) {
+            this.taverns.set(installed.id, this.installedToTavern(installed));
+        }
+        // Step 3: Fetch channels for each tavern (parallel, best-effort)
+        this.emit('debug', 'Fetching channels for all taverns...');
+        const channelFetches = this._application.taverns.map(async (installed) => {
+            try {
+                const channels = await this.rest.getChannels(installed.id);
+                for (const channel of channels) {
+                    channel.tavernId = installed.id;
+                    this.channels.set(channel.id, channel);
+                }
+                // Attach channels to the tavern object
+                const tavern = this.taverns.get(installed.id);
+                if (tavern) {
+                    tavern.channels = channels;
+                }
+            }
+            catch (err) {
+                this.emit('debug', `Failed to fetch channels for tavern ${installed.id}: ${err.message}`);
+            }
+        });
+        await Promise.all(channelFetches);
+        // Step 4: Connect to the WebSocket gateway
+        this.emit('debug', 'Connecting to gateway...');
+        // Update gateway token in case it was provided via login() instead of constructor
+        this.gateway.setToken(this.token);
+        await this.gateway.connect();
+        this.ready = true;
+        this.emit('ready');
+    }
+    /**
+     * Gracefully disconnect and clean up all resources.
+     */
+    destroy() {
+        this.ready = false;
+        this.gateway.destroy();
+        this.taverns.clear();
+        this.channels.clear();
+        this.memberCache.clear();
+        this._user = null;
+        this._application = null;
+        this.emit('debug', 'Client destroyed');
+        this.removeAllListeners();
+    }
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    once(event, listener) {
+        return super.once(event, listener);
+    }
+    off(event, listener) {
+        return super.off(event, listener);
+    }
+    emit(event, ...args) {
+        return super.emit(event, ...args);
+    }
+    // ─── Convenience API Methods ──────────────────────────
+    /**
+     * Send a message to a channel.
+     *
+     * @example
+     * ```ts
+     * await client.sendMessage(tavernId, channelId, { content: 'Hello!' });
+     * // Or with reply:
+     * await client.sendMessage(tavernId, channelId, {
+     *   content: 'Replying!',
+     *   replyToId: originalMessageId,
+     * });
+     * ```
+     */
+    async sendMessage(tavernId, channelId, options) {
+        const opts = typeof options === 'string' ? { content: options } : options;
+        return this.rest.sendMessage(tavernId, channelId, opts);
+    }
+    /**
+     * Get messages from a channel.
+     */
+    async getMessages(tavernId, channelId, options) {
+        return this.rest.getMessages(tavernId, channelId, options);
+    }
+    /**
+     * Edit a message.
+     */
+    async editMessage(tavernId, messageId, options) {
+        const opts = typeof options === 'string' ? { content: options } : options;
+        return this.rest.editMessage(tavernId, messageId, opts);
+    }
+    /**
+     * Delete a message.
+     */
+    async deleteMessage(tavernId, messageId) {
+        return this.rest.deleteMessage(tavernId, messageId);
+    }
+    /**
+     * Create a channel in a tavern.
+     */
+    async createChannel(tavernId, options) {
+        const channel = await this.rest.createChannel(tavernId, options);
+        channel.tavernId = tavernId;
+        this.channels.set(channel.id, channel);
+        return channel;
+    }
+    /**
+     * Update a channel.
+     */
+    async updateChannel(tavernId, channelId, options) {
+        const channel = await this.rest.updateChannel(tavernId, channelId, options);
+        channel.tavernId = tavernId;
+        this.channels.set(channel.id, channel);
+        return channel;
+    }
+    /**
+     * Delete a channel.
+     */
+    async deleteChannel(tavernId, channelId) {
+        await this.rest.deleteChannel(tavernId, channelId);
+        this.channels.delete(channelId);
+    }
+    /**
+     * Get members of a tavern (with caching).
+     */
+    async getMembers(tavernId, options) {
+        const members = await this.rest.getMembers(tavernId, options);
+        const collection = new collection_1.Collection();
+        for (const member of members) {
+            collection.set(member.userId, member);
+        }
+        this.memberCache.set(tavernId, collection);
+        return collection;
+    }
+    /**
+     * Get a specific member of a tavern.
+     */
+    async getMember(tavernId, userId) {
+        return this.rest.getMember(tavernId, userId);
+    }
+    /**
+     * Send a typing indicator to a channel.
+     */
+    startTyping(tavernId, channelId) {
+        this.gateway.send('tavern_typing_start', { tavernId, channelId });
+    }
+    // ─── Gateway Event Wiring ─────────────────────────────
+    setupGatewayListeners() {
+        // Forward gateway lifecycle events
+        this.gateway.on('debug', (msg) => {
+            this.emit('debug', `[Gateway] ${msg}`);
+        });
+        this.gateway.on('error', (err) => {
+            this.emit('error', err);
+        });
+        this.gateway.on('close', (code, reason) => {
+            this.emit('disconnected', code, reason);
+        });
+        this.gateway.on('reconnecting', (attempt) => {
+            this.emit('reconnecting', attempt);
+        });
+        this.gateway.on('reconnected', () => {
+            this.emit('debug', 'Reconnected to gateway');
+            // Re-emit ready so the bot knows it can resume
+            this.emit('ready');
+        });
+        this.gateway.on('reconnectFailed', () => {
+            this.ready = false;
+            this.emit('error', new Error('Failed to reconnect to gateway after maximum attempts'));
+        });
+        // Handle incoming gateway events
+        this.gateway.on('event', (eventName, data) => {
+            this.handleGatewayEvent(eventName, data);
+        });
+    }
+    handleGatewayEvent(eventName, data) {
+        // Always emit the raw event
+        this.emit('raw', eventName, data);
+        // Update caches based on events
+        this.updateCaches(eventName, data);
+        // Map to friendly event name and emit
+        const friendlyName = constants_1.FRIENDLY_EVENT_MAP[eventName];
+        if (friendlyName) {
+            // For messageCreate, enrich the message with helper methods
+            if (friendlyName === 'messageCreate') {
+                const message = this.enrichMessage(data);
+                this.emit(friendlyName, message);
+            }
+            else if (friendlyName === 'interactionCreate') {
+                const interaction = this.enrichInteraction(data);
+                this.emit(friendlyName, interaction);
+            }
+            else {
+                this.emit(friendlyName, data);
+            }
+        }
+        else {
+            // Emit unknown events as-is (for future event support)
+            this.emit(eventName, data);
+        }
+    }
+    /**
+     * Update internal caches based on gateway events.
+     */
+    updateCaches(eventName, data) {
+        const payload = data;
+        switch (eventName) {
+            case constants_1.GatewayEvent.CHANNEL_CREATED: {
+                const channel = payload;
+                if (channel.id && channel.tavernId) {
+                    this.channels.set(channel.id, channel);
+                    const tavern = this.taverns.get(channel.tavernId);
+                    if (tavern?.channels) {
+                        tavern.channels.push(channel);
+                    }
+                }
+                break;
+            }
+            case constants_1.GatewayEvent.CHANNEL_UPDATED: {
+                const existing = this.channels.get(payload.id);
+                if (existing) {
+                    Object.assign(existing, payload);
+                }
+                break;
+            }
+            case constants_1.GatewayEvent.CHANNEL_DELETED: {
+                this.channels.delete(payload.id);
+                const tavern = this.taverns.get(payload.tavernId);
+                if (tavern?.channels) {
+                    tavern.channels = tavern.channels.filter((c) => c.id !== payload.id);
+                }
+                break;
+            }
+            case constants_1.GatewayEvent.TAVERN_UPDATED: {
+                const tavern = this.taverns.get(payload.id);
+                if (tavern) {
+                    Object.assign(tavern, payload);
+                }
+                break;
+            }
+            case constants_1.GatewayEvent.BOT_INSTALLED: {
+                // New tavern install - add to cache
+                const tavernId = payload.tavernId;
+                if (tavernId && !this.taverns.has(tavernId)) {
+                    this.taverns.set(tavernId, {
+                        id: tavernId,
+                        name: payload.tavernName || 'Unknown',
+                        slug: '',
+                        iconUrl: null,
+                        memberCount: 0,
+                        grantedPermissions: payload.grantedPermissions,
+                    });
+                    // Fetch full tavern data in background
+                    this.rest.getChannels(tavernId).then((channels) => {
+                        for (const channel of channels) {
+                            channel.tavernId = tavernId;
+                            this.channels.set(channel.id, channel);
+                        }
+                        const tavern = this.taverns.get(tavernId);
+                        if (tavern)
+                            tavern.channels = channels;
+                    }).catch((err) => {
+                        this.emit('debug', `Failed to fetch channels for new tavern ${tavernId}: ${err.message}`);
+                    });
+                }
+                break;
+            }
+            case constants_1.GatewayEvent.BOT_REMOVED: {
+                const removedTavernId = payload.tavernId;
+                this.taverns.delete(removedTavernId);
+                // Remove channels for this tavern
+                for (const [id, channel] of this.channels) {
+                    if (channel.tavernId === removedTavernId) {
+                        this.channels.delete(id);
+                    }
+                }
+                this.memberCache.delete(removedTavernId);
+                break;
+            }
+            case constants_1.GatewayEvent.MEMBER_JOINED: {
+                const tavernMembers = this.memberCache.get(payload.tavernId);
+                if (tavernMembers) {
+                    const member = {
+                        id: payload.userId,
+                        userId: payload.userId,
+                        tavernId: payload.tavernId,
+                        status: 'ACTIVE',
+                        user: {
+                            id: payload.userId,
+                            displayName: payload.displayName,
+                            avatarUrl: payload.avatarUrl || null,
+                            isBot: payload.isBot,
+                        },
+                    };
+                    tavernMembers.set(member.userId, member);
+                }
+                // Update member count
+                const tavern = this.taverns.get(payload.tavernId);
+                if (tavern)
+                    tavern.memberCount++;
+                break;
+            }
+            case constants_1.GatewayEvent.MEMBER_LEFT: {
+                const tavernMembersLeave = this.memberCache.get(payload.tavernId);
+                if (tavernMembersLeave) {
+                    tavernMembersLeave.delete(payload.userId);
+                }
+                const tavernLeave = this.taverns.get(payload.tavernId);
+                if (tavernLeave && tavernLeave.memberCount > 0)
+                    tavernLeave.memberCount--;
+                break;
+            }
+        }
+    }
+    /**
+     * Enrich a raw message with convenience methods like .reply(), .edit(), .delete().
+     */
+    enrichMessage(raw) {
+        const tavernId = this.findTavernForChannel(raw.channelId);
+        const message = raw;
+        message.tavernId = tavernId;
+        message.reply = async (content) => {
+            const opts = typeof content === 'string'
+                ? { content, replyToId: raw.id }
+                : { ...content, replyToId: raw.id };
+            return this.rest.sendMessage(tavernId, raw.channelId, opts);
+        };
+        message.edit = async (content) => {
+            return this.rest.editMessage(tavernId, raw.id, { content });
+        };
+        message.delete = async () => {
+            return this.rest.deleteMessage(tavernId, raw.id);
+        };
+        message.pin = async () => {
+            return this.rest.pinMessage(tavernId, raw.id);
+        };
+        message.unpin = async () => {
+            return this.rest.unpinMessage(tavernId, raw.id);
+        };
+        message.react = async (emoji) => {
+            return this.rest.addReaction(tavernId, raw.id, emoji);
+        };
+        return message;
+    }
+    /**
+     * Enrich a raw interaction with convenience methods like .reply(), .deferReply(), .followUp().
+     */
+    enrichInteraction(raw) {
+        const interaction = raw;
+        interaction.reply = async (content) => {
+            const data = typeof content === 'string' ? { content } : content;
+            return this.rest.replyToInteraction(raw.id, data);
+        };
+        interaction.deferReply = async () => {
+            return this.rest.deferInteraction(raw.id);
+        };
+        interaction.followUp = async (content) => {
+            const data = typeof content === 'string' ? { content } : content;
+            return this.rest.followUpInteraction(raw.id, data);
+        };
+        interaction.sendMessage = async (options) => {
+            const opts = typeof options === 'string' ? { content: options } : options;
+            return this.rest.sendMessage(raw.tavernId, raw.channelId, opts);
+        };
+        return interaction;
+    }
+    /**
+     * Find the tavern that owns a channel by checking the channels cache.
+     */
+    findTavernForChannel(channelId) {
+        const channel = this.channels.get(channelId);
+        if (channel?.tavernId)
+            return channel.tavernId;
+        // Fallback: search tavern channel lists
+        for (const [tavernId, tavern] of this.taverns) {
+            if (tavern.channels?.some((c) => c.id === channelId)) {
+                return tavernId;
+            }
+        }
+        // Last resort: return empty string (the API call will fail with a clear error)
+        return '';
+    }
+    /**
+     * Convert an InstalledTavern (from @me response) to the Tavern cache format.
+     */
+    installedToTavern(installed) {
+        return {
+            id: installed.id,
+            name: installed.name,
+            slug: installed.slug,
+            iconUrl: installed.iconUrl,
+            memberCount: installed.memberCount,
+            grantedPermissions: installed.grantedPermissions,
+            installedAt: installed.installedAt,
+        };
+    }
+}
+exports.Client = Client;

package/dist/collection.d.ts

@@ -0,0 +1,63 @@
+/**
+ * taverns.js - Collection
+ *
+ * A utility class that extends Map with convenience methods,
+ * with convenience methods for working with cached data.
+ */
+export declare class Collection<K, V> extends Map<K, V> {
+    /**
+     * Find the first value that satisfies the predicate.
+     */
+    find(fn: (value: V, key: K, collection: this) => boolean): V | undefined;
+    /**
+     * Filter the collection and return a new Collection with matching entries.
+     */
+    filter(fn: (value: V, key: K, collection: this) => boolean): Collection<K, V>;
+    /**
+     * Map each value in the collection to a new value.
+     */
+    map<T>(fn: (value: V, key: K, collection: this) => T): T[];
+    /**
+     * Check if any value satisfies the predicate.
+     */
+    some(fn: (value: V, key: K, collection: this) => boolean): boolean;
+    /**
+     * Check if every value satisfies the predicate.
+     */
+    every(fn: (value: V, key: K, collection: this) => boolean): boolean;
+    /**
+     * Reduce the collection to a single value.
+     */
+    reduce<T>(fn: (accumulator: T, value: V, key: K, collection: this) => T, initialValue: T): T;
+    /**
+     * Get the first value(s) in the collection.
+     */
+    first(): V | undefined;
+    first(count: number): V[];
+    /**
+     * Get the last value(s) in the collection.
+     */
+    last(): V | undefined;
+    last(count: number): V[];
+    /**
+     * Get a random value from the collection.
+     */
+    random(): V | undefined;
+    random(count: number): V[];
+    /**
+     * Return an array of all values in the collection.
+     */
+    toArray(): V[];
+    /**
+     * Return an array of all keys in the collection.
+     */
+    keyArray(): K[];
+    /**
+     * Sort the collection by a comparator and return a new Collection.
+     */
+    sort(compareFn?: (a: V, b: V, aKey: K, bKey: K) => number): Collection<K, V>;
+    /**
+     * Create a Collection from an array using a key extractor.
+     */
+    static from<K, V>(items: V[], keyFn: (item: V) => K): Collection<K, V>;
+}