@chirp-dev/chirp-sdk 1.0.2

package/dist/index.d.ts

@@ -0,0 +1,891 @@
+import { Socket } from 'socket.io-client';
+
+/**
+ * Core API types for the Chirp Bot SDK
+ * Based on the Chirp REST API and WebSocket events
+ */
+interface User {
+    id: string;
+    username: string;
+    displayName: string;
+    avatarUrl: string | null;
+    status: 'online' | 'idle' | 'dnd' | 'offline';
+    isBot: true;
+    botTokenId: string;
+    createdAt: string;
+}
+interface PartialUser {
+    id: string;
+    username: string;
+    displayName: string;
+    avatarUrl: string | null;
+    status?: string;
+    isBot?: boolean;
+}
+interface Server {
+    id: string;
+    name: string;
+    iconUrl: string | null;
+    ownerId: string;
+    createdAt: string;
+    memberCount?: number;
+}
+interface ServerMember {
+    serverId: string;
+    userId: string;
+    roles: string[];
+    joinedAt: string;
+    user: PartialUser;
+}
+interface Channel {
+    id: string;
+    serverId: string;
+    name: string;
+    type: 'text' | 'voice' | 'media' | 'forum';
+    parentId: string | null;
+    position: number;
+    permissions?: Record<string, boolean>;
+    createdAt: string;
+}
+interface PartialChannel {
+    id: string;
+    name: string;
+    type: string;
+    serverId?: string;
+}
+interface Message {
+    id: string;
+    channel_id: string;
+    author: string;
+    username: string;
+    avatar_url: string | null;
+    bot_id?: string;
+    user_id?: string;
+    content: string;
+    created_at: string;
+    updated_at?: string;
+    edited?: boolean;
+    edited_at?: string;
+    replying_to_id?: string;
+    replying_to_author?: string;
+    replying_to_content?: string;
+    replyingTo?: MessageReply;
+    reactions?: Reaction[];
+    attachments?: Attachment[];
+    is_bot?: boolean;
+    authorAvatar?: string | null;
+    server_id?: string;
+    everyone_ping?: boolean;
+    channelId?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    isEdited?: boolean;
+}
+interface MessageReply {
+    id: string;
+    content: string;
+    author: string;
+}
+interface Reaction {
+    id: string;
+    messageId: string;
+    userId: string;
+    emoji: string;
+    customEmojiId: string | null;
+    createdAt: string;
+}
+interface Attachment {
+    id: string;
+    messageId: string;
+    fileName: string;
+    fileSize: number;
+    mimeType: string;
+    url: string;
+    thumbnailUrl?: string;
+    width?: number;
+    height?: number;
+}
+interface MessageOptions {
+    replyTo?: string;
+    attachments?: Array<{
+        fileName: string;
+        file: Blob | Buffer;
+        mimeType?: string;
+    }>;
+}
+interface BotTokenInfo {
+    id: string;
+    botUsername: string;
+    botAvatarUrl: string | null;
+    userId: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+}
+interface BotServerInfo {
+    serverId: string;
+    serverName: string;
+    serverIconUrl: string | null;
+    botUsername: string;
+    botAvatarUrl: string | null;
+    joinedAt: string;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+}
+interface APIError$1 {
+    message: string;
+    statusCode: number;
+    code?: string;
+}
+interface ChirpClientOptions {
+    token?: string;
+    baseUrl?: string;
+    wsUrl?: string;
+    commandPrefix?: string;
+    intents?: Intent[];
+    reconnectAttempts?: number;
+    reconnectDelay?: number;
+}
+type Intent = 'messages' | 'messageUpdates' | 'userStatus' | 'typing' | 'voice' | 'polls' | 'threads' | 'servers';
+interface Command {
+    name: string;
+    description: string;
+    usage?: string;
+    handler: (context: CommandContext$1) => void | Promise<void>;
+}
+interface CommandContext$1 {
+    command: string;
+    args: string[];
+    message: Message;
+    channel: Channel;
+    client: any;
+    api: any;
+}
+interface RESTClient$1 {
+    getBotInfo(): Promise<User>;
+    getServers(): Promise<Server[]>;
+    getBotServers(): Promise<BotServerInfo[]>;
+    getChannels(serverId: string): Promise<Channel[]>;
+    getMessages(channelId: string, options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<Message>>;
+    sendMessage(channelId: string, content: string, options?: {
+        replyTo?: string;
+    }): Promise<Message>;
+    reply(channelId: string, messageId: string, content: string, author: string, originalContent: string): Promise<Message>;
+    editMessage(messageId: string, content: string): Promise<Message>;
+    deleteMessage(messageId: string): Promise<void>;
+    joinServer(inviteCode: string): Promise<Server>;
+    leaveServer(serverId: string): Promise<void>;
+}
+declare class Collection<K, V> extends Map<K, V> {
+    constructor(entries?: readonly (readonly [K, V])[] | null);
+    get(key: K): V | undefined;
+    set(key: K, value: V): this;
+    find(predicate: (value: V, key: K) => boolean): V | undefined;
+    filter(predicate: (value: V, key: K) => boolean): V[];
+    first(): V | undefined;
+    last(): V | undefined;
+}
+
+/**
+ * REST API Client for Chirp Bot SDK
+ * Extracted and refactored from examples/demo-bot/src/api.js
+ */
+
+declare class APIError extends Error {
+    statusCode: number;
+    code?: string;
+    constructor(message: string, statusCode: number, code?: string);
+}
+declare class RESTClient {
+    private readonly baseUrl;
+    private readonly token;
+    constructor(baseUrl: string, token: string);
+    /**
+     * Make an authenticated API request
+     */
+    private request;
+    /**
+     * GET request
+     */
+    private get;
+    /**
+     * POST request
+     */
+    private post;
+    /**
+     * PATCH request
+     */
+    private patch;
+    /**
+     * PUT request
+     */
+    private put;
+    /**
+     * DELETE request
+     */
+    private delete;
+    /**
+     * Get the bot's user information
+     */
+    getBotInfo(): Promise<User>;
+    /**
+     * Get the bot's token information
+     */
+    getTokenInfo(): Promise<BotTokenInfo>;
+    /**
+     * List all servers the bot has access to
+     */
+    getServers(): Promise<Server[]>;
+    /**
+     * List the bot's server memberships with details
+     */
+    getBotServers(): Promise<BotServerInfo[]>;
+    /**
+     * Get channels in a server
+     */
+    getChannels(serverId: string): Promise<Channel[]>;
+    /**
+     * Get messages in a channel
+     */
+    getMessages(channelId: string, options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<Message>>;
+    /**
+     * Send a message to a channel
+     */
+    sendMessage(channelId: string, content: string, options?: MessageOptions): Promise<Message>;
+    /**
+     * Reply to a specific message
+     */
+    reply(channelId: string, messageId: string, content: string, author: string, originalContent: string): Promise<Message>;
+    /**
+     * Edit a message (only works for bot's own messages)
+     */
+    editMessage(messageId: string, content: string): Promise<Message>;
+    /**
+     * Delete a message (only works for bot's own messages)
+     */
+    deleteMessage(messageId: string): Promise<void>;
+    /**
+     * Join a server via invite code
+     */
+    joinServer(inviteCode: string): Promise<Server>;
+    /**
+     * Leave a server
+     */
+    leaveServer(serverId: string): Promise<void>;
+}
+
+/**
+ * Type-safe EventEmitter wrapper around EventEmitter3
+ */
+type EventNames<T> = T extends any ? (keyof T & string) : never;
+type EventListener<T, K extends keyof T & string> = T[K] extends (...args: any[]) => any ? T[K] : (...args: any[]) => void;
+/**
+ * Type-safe event emitter
+ */
+declare class SafeEventEmitter<TEvents extends Record<string, any>> {
+    private readonly emitter;
+    constructor();
+    /**
+     * Register an event listener
+     */
+    on<K extends EventNames<TEvents>>(event: K, listener: EventListener<TEvents, K>): this;
+    /**
+     * Register a one-time event listener
+     */
+    once<K extends EventNames<TEvents>>(event: K, listener: EventListener<TEvents, K>): this;
+    /**
+     * Remove an event listener
+     */
+    off<K extends EventNames<TEvents>>(event: K, listener: EventListener<TEvents, K>): this;
+    /**
+     * Emit an event
+     */
+    emit<K extends EventNames<TEvents>>(event: K, ...args: any[]): boolean;
+    /**
+     * Remove all listeners for an event or all events
+     */
+    removeAllListeners<K extends EventNames<TEvents>>(event?: K): this;
+    /**
+     * Get the count of listeners for an event
+     */
+    listenerCount<K extends EventNames<TEvents>>(event: K): number;
+}
+
+/**
+ * Event type definitions for Chirp Bot SDK
+ */
+
+type ReadyEventHandler = () => void;
+type ErrorHandler = (error: Error) => void;
+type DisconnectedHandler = (reason?: string) => void;
+type ReconnectingHandler = (attemptNumber: number) => void;
+type ReconnectedHandler = (attemptNumber: number) => void;
+type MessageNewHandler = (message: Message, channelId: string) => void;
+type MessageUpdatedHandler = (message: Message, channelId: string) => void;
+type MessageDeletedHandler = (messageId: string, channelId: string) => void;
+type UserStatusHandler = (userId: string, status: 'online' | 'idle' | 'dnd' | 'offline', user: PartialUser) => void;
+type TypingStartHandler = (userId: string, channelId: string) => void;
+type PollVotedHandler = (pollId: string, userId: string, optionId: string) => void;
+type ThreadReopenedHandler = (threadId: string, channelId: string) => void;
+type UserJoinedThreadHandler = (threadId: string, userId: string) => void;
+type VoiceJoinedHandler = (userId: string, channelId: string, serverId: string) => void;
+type VoiceLeftHandler = (userId: string, channelId: string, serverId: string) => void;
+type BotServerJoinedHandler = (serverId: string, serverName: string) => void;
+type BotServerLeftHandler = (serverId: string, serverName: string) => void;
+type SubscriptionAddedHandler = (data: {
+    subscriptionId: string;
+    channelId: string;
+    userId: string;
+    tier: string;
+}) => void;
+interface ChirpEvents {
+    ready: ReadyEventHandler;
+    error: ErrorHandler;
+    disconnected: DisconnectedHandler;
+    reconnecting: ReconnectingHandler;
+    reconnected: ReconnectedHandler;
+    'message:new': MessageNewHandler;
+    'message:updated': MessageUpdatedHandler;
+    'message:deleted': MessageDeletedHandler;
+    'user:status': UserStatusHandler;
+    'typing:start': TypingStartHandler;
+    'poll:voted': PollVotedHandler;
+    'thread:reopened': ThreadReopenedHandler;
+    'user_joined_thread': UserJoinedThreadHandler;
+    'voice:joined': VoiceJoinedHandler;
+    'voice:left': VoiceLeftHandler;
+    'bot:server_joined': BotServerJoinedHandler;
+    'bot:server_left': BotServerLeftHandler;
+    'subscription:added': SubscriptionAddedHandler;
+}
+type ChirpEventName = keyof ChirpEvents;
+
+/**
+ * Command Manager - handles command registration and execution
+ */
+
+type ChirpClientInstance = ChirpClient;
+/**
+ * Command Manager class
+ */
+declare class CommandManager {
+    private readonly commands;
+    private readonly prefix;
+    private client?;
+    constructor(prefix?: string);
+    /**
+     * Set the client reference (called by ChirpClient)
+     * @internal
+     */
+    _setClient(client: ChirpClientInstance): void;
+    /**
+     * Register a command
+     */
+    register(command: Command): this;
+    register(builder: {
+        build(): Command;
+    }): this;
+    /**
+     * Register multiple commands
+     */
+    registerMany(commands: (Command | {
+        build(): Command;
+    })[]): this;
+    /**
+     * Unregister a command
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get a command by name
+     */
+    get(name: string): Command | undefined;
+    /**
+     * Check if a command exists
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered commands
+     */
+    getAll(): Map<string, Command>;
+    /**
+     * Clear all commands
+     */
+    clear(): void;
+    /**
+     * Parse a message to check if it's a command
+     * Returns { command, args } if it's a command, null otherwise
+     */
+    parse(message: Message): {
+        command: string;
+        args: string[];
+    } | null;
+    /**
+     * Execute a command
+     * @internal
+     */
+    execute(commandName: string, args: string[], message: Message, channel: Channel, client: ChirpClientInstance, api: RESTClient$1): Promise<void>;
+}
+
+/**
+ * Channel Manager - manages channel caching and operations
+ */
+
+/**
+ * Manager for channel operations
+ */
+declare class ChannelManager {
+    private readonly api;
+    readonly cache: Collection<string, Channel>;
+    constructor(api: RESTClient$1);
+    /**
+     * Create a Collection instance (avoiding circular dependency)
+     */
+    private static createCollection;
+    /**
+     * Fetch channels for a server
+     */
+    fetch(serverId: string): Promise<Channel[]>;
+    /**
+     * Get a channel from cache by ID
+     */
+    get(channelId: string): Channel | undefined;
+    /**
+     * Find a channel by name in a server
+     */
+    findByName(serverId: string, name: string): Channel | undefined;
+    /**
+     * Get all channels from cache
+     */
+    getAll(): Collection<string, Channel>;
+    /**
+     * Clear the channel cache
+     */
+    clear(): void;
+    /**
+     * Add or update a channel in cache
+     */
+    set(channel: Channel): this;
+    /**
+     * Remove a channel from cache
+     */
+    delete(channelId: string): boolean;
+}
+
+/**
+ * Message Manager - manages message operations
+ */
+
+/**
+ * Manager for message operations
+ */
+declare class MessageManager {
+    private readonly api;
+    readonly cache: Collection<string, Message>;
+    constructor(api: RESTClient$1);
+    /**
+     * Create a Collection instance (avoiding circular dependency)
+     */
+    private static createCollection;
+    /**
+     * Fetch messages for a channel
+     */
+    fetch(channelId: string, options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<Message>>;
+    /**
+     * Send a message to a channel
+     */
+    send(channelId: string, content: string, options?: MessageOptions): Promise<Message>;
+    /**
+     * Reply to a message
+     */
+    reply(channelId: string, messageId: string, content: string, author: string, originalContent: string): Promise<Message>;
+    /**
+     * Edit a message
+     */
+    edit(messageId: string, content: string): Promise<Message>;
+    /**
+     * Delete a message
+     */
+    delete(messageId: string): Promise<void>;
+    /**
+     * Get a message from cache by ID
+     */
+    get(messageId: string): Message | undefined;
+    /**
+     * Get all messages from cache
+     */
+    getAll(): Collection<string, Message>;
+    /**
+     * Clear the message cache
+     */
+    clear(): void;
+    /**
+     * Add or update a message in cache
+     */
+    set(message: Message): this;
+    /**
+     * Remove a message from cache
+     */
+    deleteFromCache(messageId: string): boolean;
+}
+
+/**
+ * Server Manager - manages server caching and operations
+ */
+
+/**
+ * Manager for server operations
+ */
+declare class ServerManager {
+    private readonly api;
+    readonly cache: Collection<string, Server>;
+    constructor(api: RESTClient$1);
+    /**
+     * Create a Collection instance (avoiding circular dependency)
+     */
+    private static createCollection;
+    /**
+     * Fetch all servers the bot has access to
+     */
+    fetch(): Promise<Server[]>;
+    /**
+     * Fetch the bot's server memberships with details
+     */
+    fetchBotServers(): Promise<Server[]>;
+    /**
+     * Join a server via invite code
+     */
+    join(inviteCode: string): Promise<Server>;
+    /**
+     * Leave a server
+     */
+    leave(serverId: string): Promise<void>;
+    /**
+     * Get a server from cache by ID
+     */
+    get(serverId: string): Server | undefined;
+    /**
+     * Find a server by name
+     */
+    findByName(name: string): Server | undefined;
+    /**
+     * Get all servers from cache
+     */
+    getAll(): Collection<string, Server>;
+    /**
+     * Clear the server cache
+     */
+    clear(): void;
+    /**
+     * Add or update a server in cache
+     */
+    set(server: Server): this;
+    /**
+     * Remove a server from cache
+     */
+    delete(serverId: string): boolean;
+}
+
+/**
+ * Main ChirpClient class
+ * The primary entry point for the Chirp Bot SDK
+ */
+
+/**
+ * Connection status enum
+ */
+declare enum ConnectionStatus {
+    Disconnected = "disconnected",
+    Connecting = "connecting",
+    Connected = "connected",
+    Reconnecting = "reconnecting"
+}
+/**
+ * Main Chirp Bot SDK client
+ */
+declare class ChirpClient extends SafeEventEmitter<ChirpEvents> {
+    readonly options: Required<ChirpClientOptions>;
+    readonly commands: CommandManager;
+    api: RESTClient;
+    user: User | null;
+    servers: Collection<string, Server>;
+    channels: Collection<string, Channel>;
+    ws: Socket;
+    channelsManager: ChannelManager;
+    messagesManager: MessageManager;
+    serversManager: ServerManager;
+    private token;
+    private baseUrl;
+    private wsUrl;
+    private socket;
+    private status;
+    private reconnectAttempts;
+    private reconnectTimer;
+    private readonly log;
+    constructor(options?: ChirpClientOptions);
+    /**
+     * Connect and authenticate the bot
+     */
+    login(token?: string): Promise<void>;
+    /**
+     * Disconnect the bot
+     */
+    logout(): Promise<void>;
+    /**
+     * Get current connection status
+     */
+    getStatus(): ConnectionStatus;
+    /**
+     * Check if the client is connected
+     */
+    isConnected(): boolean;
+    private fetchInitialData;
+    private setupProcessHandlers;
+    private connectWebSocket;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private setupEventHandlers;
+    private hasIntent;
+    private handleMessageNew;
+    private handleMessageUpdated;
+    private handleMessageDeleted;
+    private handleUserStatus;
+    private handleTypingStart;
+    private handlePollVoted;
+    private handleThreadReopened;
+    private handleUserJoinedThread;
+    private handleVoiceJoined;
+    private handleVoiceLeft;
+    private handleBotServerJoined;
+    private handleBotServerLeft;
+    private handleSubscriptionAdded;
+}
+
+/**
+ * Command Context - provides context for command execution
+ */
+
+type ChirpClientType = any;
+type RESTClientType = any;
+/**
+ * Command execution context
+ */
+declare class CommandContext implements CommandContext$1 {
+    readonly command: string;
+    readonly args: string[];
+    readonly message: Message;
+    readonly channel: Channel;
+    readonly client: ChirpClientType;
+    readonly api: RESTClientType;
+    constructor(command: string, args: string[], message: Message, channel: Channel, client: ChirpClientType, api: RESTClientType);
+    /**
+     * Reply to the command message
+     */
+    reply(content: string): Promise<Message>;
+    /**
+     * Send a message to the same channel
+     */
+    send(content: string): Promise<Message>;
+    /**
+     * Edit the bot's response message
+     */
+    edit(messageId: string, content: string): Promise<Message>;
+    /**
+     * Delete a message
+     */
+    delete(messageId: string): Promise<void>;
+    /**
+     * Get the raw command string
+     */
+    get rawCommand(): string;
+}
+
+/**
+ * Command Builder - fluent API for building commands
+ */
+
+declare class CommandBuilder {
+    private name;
+    private description;
+    private usage?;
+    private handler?;
+    /**
+     * Set the command name
+     */
+    setName(name: string): this;
+    /**
+     * Set the command description
+     */
+    setDescription(description: string): this;
+    /**
+     * Set the command usage example
+     */
+    setUsage(usage: string): this;
+    /**
+     * Set the command handler
+     */
+    setHandler(handler: (context: CommandContext) => void | Promise<void>): this;
+    /**
+     * Build the command object
+     */
+    build(): Command;
+}
+
+/**
+ * Custom error classes for the Chirp Bot SDK
+ */
+/**
+ * Base error class for all SDK errors
+ */
+declare class ChirpError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when authentication fails
+ */
+declare class AuthenticationError extends ChirpError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when a rate limit is hit
+ */
+declare class RateLimitError extends ChirpError {
+    readonly retryAfter: number;
+    constructor(message: string, retryAfter?: number);
+}
+/**
+ * Error thrown when a requested resource is not found
+ */
+declare class NotFoundError extends ChirpError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when the client lacks permission for an action
+ */
+declare class PermissionError extends ChirpError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when a request is invalid
+ */
+declare class ValidationError extends ChirpError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when the WebSocket connection fails
+ */
+declare class ConnectionError extends ChirpError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when command execution fails
+ */
+declare class CommandError extends ChirpError {
+    readonly commandName: string;
+    constructor(message: string, commandName: string);
+}
+
+/**
+ * Logger utility for the SDK
+ */
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3
+}
+declare class Logger {
+    private level;
+    private prefix;
+    constructor(prefix?: string, level?: LogLevel);
+    /**
+     * Set the log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Format a log message
+     */
+    private format;
+    /**
+     * Log a debug message
+     */
+    debug(message: string, ...args: any[]): void;
+    /**
+     * Log an info message
+     */
+    info(message: string, ...args: any[]): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, ...args: any[]): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, ...args: any[]): void;
+    /**
+     * Create a child logger with a different prefix
+     */
+    child(prefix: string): Logger;
+}
+/**
+ * Default logger instance
+ */
+declare const logger: Logger;
+
+/**
+ * Utility helper functions
+ */
+/**
+ * Convert a WebSocket URL to HTTP URL
+ */
+declare function wsToHttp(wsUrl: string): string;
+/**
+ * Convert an HTTP URL to WebSocket URL
+ */
+declare function httpToWs(httpUrl: string): string;
+/**
+ * Parse command arguments from a string
+ * Handles quoted strings as single arguments
+ */
+declare function parseArgs(input: string): string[];
+/**
+ * Format a user mention
+ */
+declare function formatMention(userId: string): string;
+/**
+ * Format a channel mention
+ */
+declare function formatChannelMention(channelId: string): string;
+/**
+ * Extract user IDs from mentions in a message
+ */
+declare function extractMentionIds(content: string): string[];
+/**
+ * Delay execution for a specified time
+ */
+declare function delay(ms: number): Promise<void>;
+/**
+ * Retry a function with exponential backoff
+ */
+declare function retry<T>(fn: () => Promise<T>, options?: {
+    maxAttempts?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    factor?: number;
+}): Promise<T>;
+
+export { APIError, type APIError$1 as APIErrorType, type Attachment, AuthenticationError, type BotServerInfo, type BotTokenInfo, type Channel, ChannelManager, ChirpClient, type ChirpClientOptions, ChirpError, type ChirpEventName, type ChirpEvents, Collection, type Command, CommandBuilder, CommandContext, CommandError, CommandManager, ConnectionError, ConnectionStatus, type CommandContext$1 as ICommandContext, type Intent, LogLevel, Logger, type Message, MessageManager, type MessageOptions, type MessageReply, NotFoundError, type PaginatedResponse, type PartialChannel, type PartialUser, PermissionError, RESTClient, RateLimitError, type Reaction, SafeEventEmitter, type Server, ServerManager, type ServerMember, type User, ValidationError, ChirpClient as default, delay, extractMentionIds, formatChannelMention, formatMention, httpToWs, logger, parseArgs, retry, wsToHttp };