novaapp-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,535 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * Lightweight HTTP client for the Nova Bot API.
+ * Uses the native fetch API (Node 18+).
+ */
+declare class HttpClient {
+    readonly baseUrl: string;
+    private readonly token;
+    constructor(baseUrl: string, token: string);
+    private request;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+}
+
+interface BotUser {
+    id: string;
+    username: string;
+    displayName: string;
+    avatar: string | null;
+    isBot: true;
+}
+interface BotApplication {
+    id: string;
+    name: string;
+    description: string | null;
+    avatar: string | null;
+    category: string | null;
+    isPublic: boolean;
+    isVerified: boolean;
+    callbackUrl: string | null;
+    createdAt: string;
+    botUser: BotUser;
+    scopes: string[];
+}
+interface NovaServer {
+    id: string;
+    name: string;
+    icon: string | null;
+    description: string | null;
+    memberCount: number;
+    channelCount: number;
+    joinedAt: string;
+}
+interface Member {
+    role: 'OWNER' | 'ADMIN' | 'MEMBER';
+    joinedAt: string;
+    user: {
+        id: string;
+        username: string;
+        displayName: string;
+        avatar: string | null;
+        status: 'ONLINE' | 'IDLE' | 'DND' | 'OFFLINE';
+        isBot: boolean;
+    };
+}
+interface Attachment {
+    id: string;
+    url: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+}
+interface Reaction {
+    emoji: string;
+    count: number;
+    userIds: string[];
+}
+interface EmbedField {
+    name: string;
+    value: string;
+    inline?: boolean;
+}
+interface Embed {
+    title?: string;
+    description?: string;
+    url?: string;
+    color?: number;
+    thumbnail?: string;
+    image?: string;
+    footer?: string;
+    fields?: EmbedField[];
+    timestamp?: string;
+}
+interface MessageComponent {
+    type: 'button' | 'select';
+    customId: string;
+    label?: string;
+    style?: 'primary' | 'secondary' | 'success' | 'danger';
+    placeholder?: string;
+    options?: Array<{
+        label: string;
+        value: string;
+        description?: string;
+    }>;
+    disabled?: boolean;
+}
+interface Message {
+    id: string;
+    content: string;
+    channelId: string;
+    author: BotUser | {
+        id: string;
+        username: string;
+        displayName: string;
+        avatar: string | null;
+        isBot: boolean;
+    };
+    embed?: Embed | null;
+    components?: MessageComponent[] | null;
+    replyToId?: string | null;
+    attachments: Attachment[];
+    reactions: Reaction[];
+    createdAt: string;
+    editedAt?: string | null;
+    deletedAt?: string | null;
+}
+type InteractionType = 'SLASH_COMMAND' | 'BUTTON_CLICK' | 'SELECT_MENU' | 'MODAL_SUBMIT' | 'AUTOCOMPLETE' | 'CONTEXT_MENU' | 'PREFIX_COMMAND';
+interface Interaction {
+    id: string;
+    type: InteractionType;
+    commandName?: string | null;
+    customId?: string | null;
+    data?: unknown;
+    userId: string;
+    channelId: string;
+    serverId?: string | null;
+    triggerMsgId?: string | null;
+    createdAt: string;
+}
+interface SlashCommandOption {
+    name: string;
+    description: string;
+    type: 'STRING' | 'INTEGER' | 'BOOLEAN' | 'USER' | 'CHANNEL' | 'ROLE';
+    required?: boolean;
+    choices?: Array<{
+        name: string;
+        value: string | number;
+    }>;
+}
+interface SlashCommandDefinition {
+    name: string;
+    description: string;
+    options?: SlashCommandOption[];
+}
+interface PrefixCommandDefinition {
+    prefix: string;
+    name: string;
+    description: string;
+    options?: SlashCommandOption[];
+    guildId?: string | null;
+}
+interface ContextCommandDefinition {
+    name: string;
+    target: 'MESSAGE' | 'USER';
+    guildId?: string | null;
+}
+interface RegisteredSlashCommand {
+    id: string;
+    name: string;
+    description: string;
+    options: SlashCommandOption[];
+    guildId: string | null;
+    enabled: boolean;
+    createdAt: string;
+}
+interface RegisteredPrefixCommand {
+    id: string;
+    prefix: string;
+    name: string;
+    description: string;
+    options: SlashCommandOption[];
+    guildId: string | null;
+    enabled: boolean;
+    createdAt: string;
+}
+interface RegisteredContextCommand {
+    id: string;
+    name: string;
+    target: 'MESSAGE' | 'USER';
+    guildId: string | null;
+    enabled: boolean;
+    createdAt: string;
+}
+type BotEventType = 'message.created' | 'message.edited' | 'message.deleted' | 'message.reaction_added' | 'message.reaction_removed' | 'message.pinned' | 'user.joined_server' | 'user.left_server' | 'user.updated_profile' | 'user.banned' | 'user.unbanned' | 'user.role_added' | 'user.role_removed' | 'user.started_typing' | 'user.voice_joined' | 'user.voice_left' | 'interaction.slash_command' | 'interaction.button_click' | 'interaction.select_menu' | 'interaction.modal_submit' | 'interaction.autocomplete' | 'server.updated' | 'channel.created' | 'channel.deleted' | 'channel.updated' | 'role.created' | 'role.deleted';
+interface BotEvent<T = unknown> {
+    type: BotEventType;
+    data: T;
+    timestamp: string;
+}
+interface SendMessageOptions {
+    content?: string;
+    embed?: Embed;
+    components?: MessageComponent[];
+    replyToId?: string;
+}
+interface EditMessageOptions {
+    content?: string;
+    embed?: Embed;
+    components?: MessageComponent[];
+}
+interface RespondInteractionOptions {
+    content?: string;
+    embed?: Embed;
+    components?: MessageComponent[];
+    ephemeral?: boolean;
+}
+interface FetchMessagesOptions {
+    limit?: number;
+    before?: string;
+}
+interface FetchMembersOptions {
+    limit?: number;
+}
+interface PollInteractionsOptions {
+    limit?: number;
+    since?: string;
+}
+interface NovaClientOptions {
+    /** Your bot token — starts with "nova_bot_" */
+    token: string;
+    /**
+     * Base URL of the Nova server.
+     * @default "https://api.nova.chat"
+     */
+    baseUrl?: string;
+}
+interface NovaClientEvents {
+    /** Fired when the bot successfully connects and is identified. */
+    ready: (bot: BotApplication) => void;
+    /** Fired for every bot:event from the gateway. */
+    event: (event: BotEvent) => void;
+    /** Fired when an interaction is created (slash command, button, etc.). */
+    interactionCreate: (interaction: Interaction) => void;
+    /** Fired when the gateway connection is lost. */
+    disconnect: (reason: string) => void;
+    /** Fired on gateway/API errors. */
+    error: (err: {
+        code: number;
+        message: string;
+    }) => void;
+    /** A message was sent in a channel the bot is in. */
+    messageCreate: (data: BotEvent['data']) => void;
+    /** A message was edited. */
+    messageUpdate: (data: BotEvent['data']) => void;
+    /** A message was deleted. */
+    messageDelete: (data: BotEvent['data']) => void;
+    /** A reaction was added to a message. */
+    reactionAdd: (data: BotEvent['data']) => void;
+    /** A reaction was removed from a message. */
+    reactionRemove: (data: BotEvent['data']) => void;
+    /** A user joined a server the bot is in. */
+    memberAdd: (data: BotEvent['data']) => void;
+    /** A user left a server the bot is in. */
+    memberRemove: (data: BotEvent['data']) => void;
+    /** A user started typing. */
+    typingStart: (data: BotEvent['data']) => void;
+}
+
+declare class MessagesAPI {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Send a message to a channel.
+     *
+     * @example
+     * await client.messages.send('channel-id', { content: 'Hello!' })
+     * await client.messages.send('channel-id', {
+     *   embed: { title: 'Report', description: 'Everything is fine.' }
+     * })
+     */
+    send(channelId: string, options: SendMessageOptions): Promise<Message>;
+    /**
+     * Edit a message previously sent by this bot.
+     */
+    edit(messageId: string, options: EditMessageOptions): Promise<Message>;
+    /**
+     * Delete a message previously sent by this bot.
+     */
+    delete(messageId: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Fetch recent messages from a channel.
+     */
+    fetch(channelId: string, options?: FetchMessagesOptions): Promise<Message[]>;
+    /**
+     * Send a typing indicator in a channel (appears for ~5 seconds).
+     */
+    typing(channelId: string): Promise<{
+        ok: true;
+    }>;
+}
+
+declare class CommandsAPI {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Register (or fully replace) slash commands.
+     * Pass `guildId` to register guild-specific commands; omit for global.
+     *
+     * @example
+     * await client.commands.setSlash([
+     *   { name: 'ping', description: 'Responds with pong!' },
+     *   { name: 'ban', description: 'Ban a user', options: [
+     *     { name: 'user', description: 'User to ban', type: 'USER', required: true }
+     *   ]}
+     * ])
+     */
+    setSlash(commands: SlashCommandDefinition[], guildId?: string): Promise<{
+        registered: number;
+    }>;
+    /**
+     * Fetch all registered slash commands.
+     */
+    getSlash(guildId?: string): Promise<RegisteredSlashCommand[]>;
+    /**
+     * Delete a slash command by name.
+     */
+    deleteSlash(name: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Register (or fully replace) prefix commands.
+     *
+     * @example
+     * await client.commands.setPrefix([
+     *   { prefix: '!', name: 'help', description: 'Show help' },
+     *   { prefix: '!', name: 'kick', description: 'Kick a user' },
+     * ])
+     */
+    setPrefix(commands: PrefixCommandDefinition[]): Promise<{
+        created: number;
+    }>;
+    /**
+     * Fetch all registered prefix commands.
+     */
+    getPrefix(): Promise<RegisteredPrefixCommand[]>;
+    /**
+     * Delete a prefix command.
+     */
+    deletePrefix(prefix: string, name: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Register (or fully replace) context menu commands.
+     *
+     * @example
+     * await client.commands.setContext([
+     *   { name: 'Report message', target: 'MESSAGE' },
+     *   { name: 'View profile', target: 'USER' },
+     * ])
+     */
+    setContext(commands: ContextCommandDefinition[]): Promise<{
+        created: number;
+    }>;
+    /**
+     * Fetch all registered context menu commands.
+     */
+    getContext(): Promise<RegisteredContextCommand[]>;
+    /**
+     * Delete a context menu command by name.
+     */
+    deleteContext(name: string): Promise<{
+        ok: true;
+    }>;
+}
+
+declare class MembersAPI {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Fetch members of a server the bot is in.
+     *
+     * @example
+     * const members = await client.members.list('server-id', { limit: 50 })
+     */
+    list(serverId: string, options?: FetchMembersOptions): Promise<Member[]>;
+    /**
+     * Kick a member from a server.
+     * Bots cannot kick owners or admins (403 will be thrown).
+     *
+     * @example
+     * await client.members.kick('server-id', 'user-id')
+     */
+    kick(serverId: string, userId: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Ban a member from a server.
+     * Bots cannot ban owners or admins (403 will be thrown).
+     *
+     * @example
+     * await client.members.ban('server-id', 'user-id', 'Spamming')
+     */
+    ban(serverId: string, userId: string, reason?: string): Promise<{
+        ok: true;
+    }>;
+}
+
+declare class ServersAPI {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Fetch all servers the bot is currently a member of.
+     *
+     * @example
+     * const servers = await client.servers.list()
+     * console.log(`Bot is in ${servers.length} servers`)
+     */
+    list(): Promise<NovaServer[]>;
+}
+
+declare class InteractionsAPI {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Acknowledge an interaction without sending a visible response.
+     * Shows a loading state to the user. You must follow up with `respond()`.
+     *
+     * @example
+     * client.on('interactionCreate', async (interaction) => {
+     *   await client.interactions.ack(interaction.id)
+     *   // ... do work ...
+     *   await client.interactions.respond(interaction.id, { content: 'Done!' })
+     * })
+     */
+    ack(interactionId: string): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Respond to an interaction with a message.
+     * Set `ephemeral: true` to only show the response to the triggering user.
+     *
+     * @example
+     * await client.interactions.respond(interaction.id, {
+     *   content: 'Pong!',
+     *   ephemeral: true,
+     * })
+     */
+    respond(interactionId: string, options: RespondInteractionOptions): Promise<Message | {
+        ok: true;
+        ephemeral: true;
+    }>;
+    /**
+     * Poll for pending (unacknowledged) interactions.
+     * Useful when not using the WebSocket gateway.
+     *
+     * @example
+     * const pending = await client.interactions.poll({ limit: 20 })
+     * for (const i of pending) {
+     *   await client.interactions.respond(i.id, { content: 'Got it!' })
+     * }
+     */
+    poll(options?: PollInteractionsOptions): Promise<Interaction[]>;
+}
+
+/**
+ * The main Nova bot client.
+ *
+ * @example
+ * import { NovaClient } from 'nova-bot-sdk'
+ *
+ * const client = new NovaClient({ token: 'nova_bot_...' })
+ *
+ * client.on('ready', (bot) => {
+ *   console.log(`Logged in as ${bot.botUser.username}`)
+ * })
+ *
+ * client.on('interactionCreate', async (interaction) => {
+ *   if (interaction.commandName === 'ping') {
+ *     await client.interactions.respond(interaction.id, { content: 'Pong!' })
+ *   }
+ * })
+ *
+ * await client.connect()
+ */
+declare class NovaClient extends EventEmitter {
+    /** The authenticated bot application. Available after `ready` fires. */
+    botUser: BotApplication | null;
+    /** Send, edit, delete and fetch messages. */
+    readonly messages: MessagesAPI;
+    /** Register and manage slash, prefix, and context menu commands. */
+    readonly commands: CommandsAPI;
+    /** List, kick and ban server members. */
+    readonly members: MembersAPI;
+    /** List servers the bot is a member of. */
+    readonly servers: ServersAPI;
+    /** Acknowledge and respond to interactions. */
+    readonly interactions: InteractionsAPI;
+    private socket;
+    private readonly http;
+    private readonly options;
+    constructor(options: NovaClientOptions);
+    /**
+     * Connect to the Nova WebSocket gateway.
+     * Resolves when the `ready` event is received.
+     *
+     * @example
+     * await client.connect()
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the gateway and clean up.
+     */
+    disconnect(): void;
+    /**
+     * Send a message via the WebSocket gateway (lower latency than HTTP).
+     * Requires the `messages.write` scope.
+     *
+     * @example
+     * client.wsSend('channel-id', 'Hello from the gateway!')
+     */
+    wsSend(channelId: string, content: string): void;
+    /**
+     * Start a typing indicator via WebSocket.
+     */
+    wsTypingStart(channelId: string): void;
+    /**
+     * Stop a typing indicator via WebSocket.
+     */
+    wsTypingStop(channelId: string): void;
+    on<K extends keyof NovaClientEvents>(event: K, listener: NovaClientEvents[K]): this;
+    on(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    once<K extends keyof NovaClientEvents>(event: K, listener: NovaClientEvents[K]): this;
+    once(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    off<K extends keyof NovaClientEvents>(event: K, listener: NovaClientEvents[K]): this;
+    off(event: string | symbol, listener: (...args: unknown[]) => void): this;
+    emit<K extends keyof NovaClientEvents>(event: K, ...args: Parameters<NovaClientEvents[K]>): boolean;
+    emit(event: string | symbol, ...args: unknown[]): boolean;
+}
+
+export { type Attachment, type BotApplication, type BotEvent, type BotEventType, type BotUser, CommandsAPI, type ContextCommandDefinition, type EditMessageOptions, type Embed, type EmbedField, type FetchMembersOptions, type FetchMessagesOptions, HttpClient, type Interaction, type InteractionType, InteractionsAPI, type Member, MembersAPI, type Message, type MessageComponent, MessagesAPI, NovaClient, type NovaClientEvents, type NovaClientOptions, type NovaServer, type PollInteractionsOptions, type PrefixCommandDefinition, type Reaction, type RegisteredContextCommand, type RegisteredPrefixCommand, type RegisteredSlashCommand, type RespondInteractionOptions, type SendMessageOptions, ServersAPI, type SlashCommandDefinition, type SlashCommandOption };