taverns.js 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,408 @@
+/**
+ * taverns.js - Type Definitions
+ *
+ * TypeScript interfaces that mirror the Taverns API responses.
+ * All IDs are UUIDs represented as strings.
+ */
+import { ChannelType, MessageStatus, MemberStatus, CommandOptionType } from './constants';
+import type { Embed } from './embed';
+export interface User {
+    id: string;
+    displayName: string;
+    avatarUrl: string | null;
+    bannerUrl?: string | null;
+    isBot?: boolean;
+    createdAt?: string;
+}
+/** The bot's own identity returned by GET /bots/@me */
+export interface BotSelf {
+    id: string;
+    name: string;
+    description: string | null;
+    user: User;
+    taverns: InstalledTavern[];
+}
+/** A tavern the bot is installed in */
+export interface InstalledTavern {
+    id: string;
+    name: string;
+    slug: string;
+    iconUrl: string | null;
+    memberCount: number;
+    grantedPermissions: string;
+    installedAt: string;
+}
+export interface Tavern {
+    id: string;
+    name: string;
+    slug: string;
+    iconUrl: string | null;
+    bannerUrl?: string | null;
+    description?: string | null;
+    memberCount: number;
+    isPublic?: boolean;
+    ownerId?: string;
+    grantedPermissions?: string;
+    installedAt?: string;
+    channels?: Channel[];
+    roles?: Role[];
+    members?: Member[];
+}
+export interface Channel {
+    id: string;
+    name: string;
+    type: ChannelType;
+    tavernId: string;
+    topic?: string | null;
+    position: number;
+    categoryId?: string | null;
+    slowModeSeconds?: number;
+    isNsfw?: boolean;
+    isArchived?: boolean;
+    isPrivate?: boolean;
+    createdAt?: string;
+    parentChannelId?: string | null;
+    rootMessageId?: string | null;
+    creatorId?: string | null;
+    isPrivateThread?: boolean;
+    autoArchiveDuration?: number;
+    archivedAt?: string | null;
+    threadMetadata?: ThreadMetadata | null;
+}
+export interface ThreadMetadata {
+    messageCount?: number;
+    lastMessageAt?: string;
+    lastSenderId?: string;
+    lastSenderName?: string;
+    lastSenderAvatarUrl?: string | null;
+    lastMessagePreview?: string;
+}
+export interface Category {
+    id: string;
+    name: string;
+    position: number;
+    tavernId: string;
+    isPrivate?: boolean;
+    isNsfw?: boolean;
+}
+export interface Member {
+    id: string;
+    userId: string;
+    tavernId: string;
+    nickname?: string | null;
+    status: MemberStatus;
+    user: User;
+    roles?: MemberRole[];
+    joinedAt?: string;
+}
+export interface MemberRole {
+    id: string;
+    name: string;
+    color?: string | null;
+    iconUrl?: string | null;
+    position: number;
+}
+export interface Role {
+    id: string;
+    name: string;
+    color?: string | null;
+    iconUrl?: string | null;
+    isMentionable: boolean;
+    position: number;
+    permissions: string;
+    memberCount?: number;
+    createdAt?: string;
+}
+export interface Message {
+    id: string;
+    channelId: string;
+    tavernId?: string;
+    content: string;
+    filteredContent?: string | null;
+    status: MessageStatus;
+    replyToId?: string | null;
+    replyTo?: MessageReply | null;
+    metadata?: Record<string, unknown> | null;
+    createdAt: string;
+    editedAt?: string | null;
+    isPinned?: boolean;
+    isPublished?: boolean;
+    publishedAt?: string | null;
+    isSyndicated?: boolean;
+    originalAuthorName?: string | null;
+    originalAuthorAvatar?: string | null;
+    sourceTavernName?: string | null;
+    sourceTavernId?: string | null;
+    sender: MessageSender;
+}
+export interface MessageReply {
+    id: string;
+    senderId: string;
+    senderName: string;
+    preview: string;
+}
+export interface MessageSender {
+    id: string;
+    displayName: string;
+    avatarUrl: string | null;
+    aetherName?: string | null;
+    nickname?: string | null;
+    roles?: MemberRole[];
+    isBot?: boolean;
+}
+export interface SendMessageOptions {
+    content: string;
+    replyToId?: string;
+    metadata?: Record<string, unknown>;
+    embeds?: Embed[];
+}
+export interface EditMessageOptions {
+    content: string;
+}
+export interface GetMessagesOptions {
+    limit?: number;
+    before?: string;
+    after?: string;
+}
+export interface SearchMessagesOptions {
+    query: string;
+    channelId?: string;
+    senderId?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface CreateChannelOptions {
+    name: string;
+    type?: ChannelType;
+    topic?: string;
+    categoryId?: string;
+    position?: number;
+    slowModeSeconds?: number;
+    isNsfw?: boolean;
+    isPrivate?: boolean;
+}
+export interface UpdateChannelOptions {
+    name?: string;
+    topic?: string;
+    categoryId?: string | null;
+    position?: number;
+    slowModeSeconds?: number;
+    isNsfw?: boolean;
+    isArchived?: boolean;
+}
+export interface CreateRoleOptions {
+    name: string;
+    color?: string;
+    iconUrl?: string;
+    permissions?: string;
+    isMentionable?: boolean;
+}
+export interface UpdateRoleOptions {
+    name?: string;
+    color?: string;
+    iconUrl?: string;
+    permissions?: string;
+    isMentionable?: boolean;
+}
+export interface GatewayPayload {
+    event: string;
+    data: unknown;
+}
+export interface MessageCreateEvent {
+    id: string;
+    channelId: string;
+    tavernId?: string;
+    content: string;
+    sender: MessageSender;
+    replyToId?: string | null;
+    replyTo?: MessageReply | null;
+    metadata?: Record<string, unknown> | null;
+    createdAt: string;
+}
+export interface MessageEditEvent {
+    id: string;
+    channelId: string;
+    tavernId?: string;
+    content: string;
+    editedAt: string;
+    sender: MessageSender;
+}
+export interface MessageDeleteEvent {
+    id: string;
+    channelId: string;
+    tavernId?: string;
+}
+export interface BulkDeleteEvent {
+    channelId: string;
+    tavernId: string;
+    messageIds: string[];
+    count: number;
+}
+export interface MemberJoinEvent {
+    userId: string;
+    tavernId: string;
+    displayName: string;
+    avatarUrl: string | null;
+    isBot?: boolean;
+}
+export interface MemberLeaveEvent {
+    userId: string;
+    tavernId: string;
+}
+export interface ChannelCreateEvent {
+    id: string;
+    name: string;
+    type: ChannelType;
+    tavernId: string;
+    topic?: string | null;
+    position: number;
+    categoryId?: string | null;
+}
+export interface ChannelUpdateEvent {
+    id: string;
+    tavernId: string;
+    name?: string;
+    topic?: string | null;
+    position?: number;
+}
+export interface ChannelDeleteEvent {
+    id: string;
+    tavernId: string;
+}
+export interface RoleUpdateEvent {
+    id: string;
+    tavernId?: string;
+    name: string;
+    color?: string | null;
+    iconUrl?: string | null;
+    position: number;
+    permissions: string;
+    isMentionable: boolean;
+}
+export interface RoleDeleteEvent {
+    id: string;
+    tavernId: string;
+}
+export interface TavernUpdateEvent {
+    id: string;
+    name?: string;
+    iconUrl?: string | null;
+    bannerUrl?: string | null;
+    description?: string | null;
+}
+export interface BotInstalledEvent {
+    tavernId: string;
+    tavernName: string;
+    grantedPermissions: string;
+}
+export interface BotRemovedEvent {
+    tavernId: string;
+}
+export interface TypingEvent {
+    userId: string;
+    channelId: string;
+    tavernId: string;
+    displayName: string;
+}
+export interface MessagePinnedEvent {
+    id: string;
+    channelId: string;
+    tavernId: string;
+}
+export interface MessageUnpinnedEvent {
+    id: string;
+    channelId: string;
+    tavernId: string;
+}
+export interface BotCommand {
+    id: string;
+    name: string;
+    description: string;
+    options?: CommandOption[];
+    defaultMemberPermissions?: string;
+    version: number;
+}
+export interface CommandOption {
+    name: string;
+    description: string;
+    type: CommandOptionType;
+    required?: boolean;
+    choices?: {
+        name: string;
+        value: string | number;
+    }[];
+}
+export interface Interaction {
+    id: string;
+    commandName: string;
+    tavernId: string;
+    channelId: string;
+    userId: string;
+    options: Record<string, any>;
+}
+export interface InteractionCallbackData {
+    content: string;
+    ephemeral?: boolean;
+    embeds?: Embed[];
+}
+export interface PaginatedMessages {
+    messages: Message[];
+    hasMore: boolean;
+    nextCursor?: string;
+}
+export interface ClientOptions {
+    /** Bot token (must start with tavbot_) */
+    token?: string;
+    /** Override the REST API base URL */
+    apiUrl?: string;
+    /** Override the WebSocket gateway URL */
+    wsUrl?: string;
+    /** Whether to automatically reconnect on disconnect (default: true) */
+    autoReconnect?: boolean;
+    /** Maximum number of reconnect attempts before giving up (default: Infinity) */
+    maxReconnectAttempts?: number;
+    /** Heartbeat interval in ms (default: 30000) */
+    heartbeatInterval?: number;
+    /** Gateway intents bitfield (session-level, not persisted to server) */
+    intents?: bigint;
+}
+export interface ClientEvents {
+    ready: [];
+    reconnecting: [attempt: number];
+    disconnected: [code: number, reason: string];
+    error: [error: Error];
+    debug: [message: string];
+    messageCreate: [message: Message];
+    messageUpdate: [message: MessageEditEvent];
+    messageDelete: [event: MessageDeleteEvent];
+    messageDeleteBulk: [event: BulkDeleteEvent];
+    messagePinned: [event: MessagePinnedEvent];
+    messageUnpinned: [event: MessageUnpinnedEvent];
+    messagePublished: [message: Message];
+    memberJoin: [event: MemberJoinEvent];
+    memberLeave: [event: MemberLeaveEvent];
+    memberMuted: [event: Record<string, unknown>];
+    memberUnmuted: [event: Record<string, unknown>];
+    channelCreate: [channel: ChannelCreateEvent];
+    channelUpdate: [event: ChannelUpdateEvent];
+    channelDelete: [event: ChannelDeleteEvent];
+    threadCreate: [channel: Channel];
+    threadUpdate: [event: Record<string, unknown>];
+    threadDelete: [event: Record<string, unknown>];
+    threadArchived: [event: Record<string, unknown>];
+    roleUpdate: [role: RoleUpdateEvent];
+    roleDelete: [event: RoleDeleteEvent];
+    tavernUpdate: [event: TavernUpdateEvent];
+    eventCreate: [event: Record<string, unknown>];
+    eventUpdate: [event: Record<string, unknown>];
+    eventDelete: [event: Record<string, unknown>];
+    eventStarting: [event: Record<string, unknown>];
+    eventEnded: [event: Record<string, unknown>];
+    voiceStateUpdate: [event: Record<string, unknown>];
+    typingStart: [event: TypingEvent];
+    typingStop: [event: TypingEvent];
+    botInstalled: [event: BotInstalledEvent];
+    botRemoved: [event: BotRemovedEvent];
+    interactionCreate: [interaction: Interaction];
+    raw: [event: string, data: unknown];
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * taverns.js - Type Definitions
+ *
+ * TypeScript interfaces that mirror the Taverns API responses.
+ * All IDs are UUIDs represented as strings.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/webhook.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Verify a Tavern webhook request signature.
+ *
+ * @param rawBody - The raw request body as a string or Buffer
+ * @param signature - The X-Tavern-Signature header value (format: "sha256=hex")
+ * @param secret - Your webhook signing secret
+ * @param timestamp - The X-Tavern-Timestamp header value (optional, for freshness check)
+ * @param maxAge - Maximum age in seconds for timestamp freshness (default: 300 = 5 minutes)
+ * @returns true if the signature is valid
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from 'taverns.js';
+ *
+ * app.post('/webhook', (req, res) => {
+ *   const isValid = verifyWebhookSignature(
+ *     req.body,                             // raw body (use express.raw() or body as string)
+ *     req.headers['x-tavern-signature'],
+ *     process.env.WEBHOOK_SECRET!,
+ *     req.headers['x-tavern-timestamp'],
+ *   );
+ *
+ *   if (!isValid) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = JSON.parse(req.body);
+ *   console.log(`Received ${event.event}:`, event.data);
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+export declare function verifyWebhookSignature(rawBody: string | Buffer, signature: string | undefined, secret: string, timestamp?: string, maxAge?: number): boolean;

package/dist/webhook.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWebhookSignature = verifyWebhookSignature;
+const crypto_1 = require("crypto");
+/**
+ * Verify a Tavern webhook request signature.
+ *
+ * @param rawBody - The raw request body as a string or Buffer
+ * @param signature - The X-Tavern-Signature header value (format: "sha256=hex")
+ * @param secret - Your webhook signing secret
+ * @param timestamp - The X-Tavern-Timestamp header value (optional, for freshness check)
+ * @param maxAge - Maximum age in seconds for timestamp freshness (default: 300 = 5 minutes)
+ * @returns true if the signature is valid
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from 'taverns.js';
+ *
+ * app.post('/webhook', (req, res) => {
+ *   const isValid = verifyWebhookSignature(
+ *     req.body,                             // raw body (use express.raw() or body as string)
+ *     req.headers['x-tavern-signature'],
+ *     process.env.WEBHOOK_SECRET!,
+ *     req.headers['x-tavern-timestamp'],
+ *   );
+ *
+ *   if (!isValid) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = JSON.parse(req.body);
+ *   console.log(`Received ${event.event}:`, event.data);
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+function verifyWebhookSignature(rawBody, signature, secret, timestamp, maxAge = 300) {
+    if (!signature)
+        return false;
+    // Timestamp freshness check (replay protection)
+    if (timestamp) {
+        const ts = parseInt(timestamp, 10);
+        if (isNaN(ts))
+            return false;
+        const age = Math.abs(Date.now() - ts) / 1000;
+        if (age > maxAge)
+            return false;
+    }
+    // Extract the hex digest from "sha256=<hex>"
+    const parts = signature.split('=');
+    if (parts.length !== 2 || parts[0] !== 'sha256')
+        return false;
+    const providedHex = parts[1];
+    // Compute expected signature
+    const body = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
+    const expectedHex = (0, crypto_1.createHmac)('sha256', secret).update(body).digest('hex');
+    // Timing-safe comparison
+    try {
+        const providedBuf = Buffer.from(providedHex, 'hex');
+        const expectedBuf = Buffer.from(expectedHex, 'hex');
+        if (providedBuf.length !== expectedBuf.length)
+            return false;
+        return (0, crypto_1.timingSafeEqual)(providedBuf, expectedBuf);
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "taverns.js",
+  "version": "0.2.0",
+  "description": "SDK for building Tavern bots for the Taverns platform",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "taverns",
+    "bot",
+    "sdk",
+    "api",
+    "tav"
+  ],
+  "license": "Apache-2.0",
+  "author": "Tav <https://github.com/Tav-gg>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tav-gg/taverns.js.git"
+  },
+  "homepage": "https://github.com/Tav-gg/taverns.js#readme",
+  "bugs": {
+    "url": "https://github.com/Tav-gg/taverns.js/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "ws": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}