novaapp-sdk 1.4.0 → 1.4.2

package/dist/testing/index.d.ts

@@ -0,0 +1,689 @@
+import { al as Message, ae as InteractionType, ac as Interaction, ai as Member, y as BotApplication, c as SendMessageOptions, Z as EditMessageOptions, a7 as FetchMessagesOptions, L as BulkDeleteResult, aL as RespondInteractionOptions, aU as SingleMember, a6 as FetchMembersOptions, O as Channel, aM as Role, at as NovaServer, af as Invite, r as NovaClientEvents, p as NovaClient } from '../client-DbKa6yJo.js';
+import { EventEmitter } from 'node:events';
+
+/**
+ * @module testing/types
+ * Shared types for the Nova test harness.
+ */
+
+/**
+ * A single recorded call to a mock API namespace.
+ * Stored in {@link MockClient.calls} and inspected by assertion helpers.
+ */
+interface RecordedCall {
+    /** Which API namespace was called, e.g. `'messages'`, `'interactions'`. */
+    api: string;
+    /** Method name, e.g. `'send'`, `'respond'`, `'ban'`. */
+    method: string;
+    /** Arguments passed to the method (in order). */
+    args: unknown[];
+    /** The mock value that was returned. */
+    result: unknown;
+    /** Wall-clock time of the call. */
+    timestamp: Date;
+}
+/** Minimal fields needed to simulate a message event. */
+interface SimulateMessageInput {
+    content?: string;
+    channelId?: string;
+    serverId?: string;
+    authorId?: string;
+    authorName?: string;
+    id?: string;
+    /** Extra fields merged into the Message object. */
+    extra?: Partial<Message>;
+}
+/** Minimal fields needed to simulate an interaction. */
+interface SimulateInteractionInput {
+    type?: InteractionType;
+    /** For slash-commands / prefix commands. */
+    commandName?: string;
+    /** For button / select / modal interactions. */
+    customId?: string;
+    /** For SELECT_MENU. */
+    values?: string[];
+    /** For MODAL_SUBMIT. */
+    modalData?: Record<string, string>;
+    userId?: string;
+    channelId?: string;
+    serverId?: string;
+    /** Slash-command options forwarded as `data`. */
+    data?: Record<string, unknown>;
+    extra?: Partial<Interaction>;
+}
+/** Minimal fields needed to simulate a slash-command specifically. */
+interface SimulateSlashCommandInput {
+    name: string;
+    options?: Record<string, unknown>;
+    userId?: string;
+    channelId?: string;
+    serverId?: string;
+}
+/** Minimal fields needed to simulate a button click. */
+interface SimulateButtonInput {
+    customId: string;
+    userId?: string;
+    channelId?: string;
+    serverId?: string;
+    triggerMsgId?: string;
+}
+/** Minimal fields needed to simulate a select-menu choice. */
+interface SimulateSelectInput {
+    customId: string;
+    values: string[];
+    userId?: string;
+    channelId?: string;
+    serverId?: string;
+}
+/** Minimal fields needed to simulate a modal submission. */
+interface SimulateModalInput {
+    customId: string;
+    modalData: Record<string, string>;
+    userId?: string;
+    channelId?: string;
+    serverId?: string;
+}
+/** Minimal fields needed to simulate a member join. */
+interface SimulateMemberInput {
+    userId?: string;
+    serverId?: string;
+    role?: 'OWNER' | 'ADMIN' | 'MEMBER';
+    extra?: Partial<Member>;
+}
+/** Minimal fields needed to simulate a voice-state event. */
+interface SimulateVoiceInput {
+    userId?: string;
+    channelId?: string;
+    serverId?: string;
+    muted?: boolean;
+    deafened?: boolean;
+}
+/** Minimal fields needed to simulate a reaction event. */
+interface SimulateReactionInput {
+    messageId: string;
+    emoji: string;
+    userId?: string;
+    channelId?: string;
+    serverId?: string;
+}
+/** Options to `harness.assert.sent()`. */
+interface AssertSentOptions {
+    /** Expected message content (partial match). */
+    content?: string;
+    /** Expected channelId. If omitted, any channel matches. */
+    channelId?: string;
+    /** Assert the embed's title. */
+    embedTitle?: string;
+    /** Assert any embed field by name. */
+    embedField?: string;
+    /** Number of times this kind of message should have been sent. @default ≥1 */
+    times?: number;
+}
+/** Options to `harness.assert.replied()`. */
+interface AssertRepliedOptions {
+    /** Expected content of the reply payload (partial match). */
+    content?: string;
+    /** Assert the embed title. */
+    embedTitle?: string;
+    /** Number of times. @default ≥1 */
+    times?: number;
+}
+
+/**
+ * @module testing/MockClient
+ *
+ * A lightweight in-memory substitute for {@link NovaClient} used in unit tests.
+ *
+ * `MockClient` shares the same EventEmitter interface as `NovaClient`, exposes
+ * the same API sub-namespaces, and records every API call for later inspection.
+ * It never opens a network connection.
+ *
+ * Use through {@link TestHarness} — or directly if you need lower-level control:
+ *
+ * @example
+ * ```ts
+ * import { MockClient } from 'novaapp-sdk/testing'
+ *
+ * const client = new MockClient()
+ * setupBot(client as unknown as NovaClient)
+ *
+ * // fire a message
+ * client.emit('message', buildMockMessage({ content: '!ping' }))
+ *
+ * // inspect what the bot sent
+ * const [call] = client.findCalls('messages', 'send')
+ * console.log(call?.args) // [channelId, { content: 'Pong!' }]
+ * ```
+ */
+
+/**
+ * Drop-in test double for `NovaClient`.
+ *
+ * Cast to `NovaClient` with `client as unknown as NovaClient` when passing to
+ * bot setup functions.  The {@link TestHarness} does this automatically.
+ *
+ * @example
+ * ```ts
+ * const client = new MockClient()
+ * client.botUser = defaultBotApplication()
+ * setupMyBot(client as unknown as NovaClient)
+ * ```
+ */
+declare class MockClient extends EventEmitter {
+    /** All recorded API calls, in chronological order. */
+    readonly calls: RecordedCall[];
+    /** Simulated bot application info.  Pre-set to a default test value. */
+    botUser: BotApplication;
+    /** Mocked `client.messages` — same method names as the real MessagesAPI. */
+    readonly messages: {
+        send(channelId: string, options: SendMessageOptions): Promise<Message>;
+        edit(messageId: string, options: EditMessageOptions): Promise<Message>;
+        delete(messageId: string): Promise<{
+            ok: true;
+        }>;
+        fetch(channelId: string, options?: FetchMessagesOptions): Promise<Message[]>;
+        bulkDelete(channelId: string, messageIds: string[]): Promise<BulkDeleteResult>;
+        pin(messageId: string): Promise<{
+            ok: true;
+        }>;
+        unpin(messageId: string): Promise<{
+            ok: true;
+        }>;
+    };
+    /** Mocked `client.interactions` — records `respond()` calls. */
+    readonly interactions: {
+        respond(interactionId: string, options: RespondInteractionOptions): Promise<{
+            ok: true;
+        }>;
+        followUp(interactionId: string, options: SendMessageOptions): Promise<Message>;
+        edit(interactionId: string, options: SendMessageOptions): Promise<{
+            ok: true;
+        }>;
+        delete(interactionId: string): Promise<{
+            ok: true;
+        }>;
+    };
+    /** Mocked `client.members` */
+    readonly members: {
+        fetch(serverId: string, userId: string): Promise<SingleMember>;
+        list(serverId: string, options?: FetchMembersOptions): Promise<Member[]>;
+        kick(serverId: string, userId: string, reason?: string): Promise<{
+            ok: true;
+        }>;
+        ban(serverId: string, userId: string, reason?: string): Promise<{
+            ok: true;
+        }>;
+        unban(serverId: string, userId: string): Promise<{
+            ok: true;
+        }>;
+        mute(serverId: string, userId: string, muted: boolean): Promise<{
+            ok: true;
+        }>;
+        timeout(serverId: string, userId: string, duration: number, reason?: string): Promise<{
+            ok: true;
+        }>;
+    };
+    /** Mocked `client.channels` */
+    readonly channels: {
+        fetch(channelId: string): Promise<Channel>;
+        list(serverId: string): Promise<Channel[]>;
+    };
+    /** Mocked `client.roles` */
+    readonly roles: {
+        list(serverId: string): Promise<Role[]>;
+        add(serverId: string, userId: string, roleId: string): Promise<{
+            ok: true;
+        }>;
+        remove(serverId: string, userId: string, roleId: string): Promise<{
+            ok: true;
+        }>;
+    };
+    /** Mocked `client.servers` */
+    readonly servers: {
+        fetch(serverId: string): Promise<NovaServer>;
+        leave(serverId: string): Promise<{
+            ok: true;
+        }>;
+    };
+    /** Mocked `client.invites` */
+    readonly invites: {
+        create(serverId: string, options?: Record<string, unknown>): Promise<Invite>;
+        delete(code: string): Promise<{
+            ok: true;
+        }>;
+        list(serverId: string): Promise<Invite[]>;
+    };
+    readonly webhooks: Record<string, unknown>;
+    readonly reactions: Record<string, unknown>;
+    readonly permissions: Record<string, unknown>;
+    readonly auditlog: Record<string, unknown>;
+    readonly forum: Record<string, unknown>;
+    readonly events: Record<string, unknown>;
+    readonly categories: Record<string, unknown>;
+    readonly automod: Record<string, unknown>;
+    readonly users: Record<string, unknown>;
+    /**
+     * Recorded WS sends (via `client.wsSend`).
+     * Inspected by `harness.assert.wsSent()`.
+     */
+    readonly wsSends: Array<{
+        channelId: string;
+        content: string;
+    }>;
+    wsSend(channelId: string, content: string): void;
+    wsTypingStart(channelId: string): void;
+    wsTypingStop(channelId: string): void;
+    setStatus(_status: string): void;
+    /** Simulated `client.connect()` — no-op in tests. */
+    connect(): Promise<this>;
+    /** Simulated `client.disconnect()` — emits `disconnect`. */
+    disconnect(): void;
+    /**
+     * Find all recorded calls to a given API namespace + method.
+     *
+     * @example
+     * ```ts
+     * const sends = client.findCalls('messages', 'send')
+     * // sends[0].args → [channelId, options]
+     * ```
+     */
+    findCalls(api: string, method: string): RecordedCall[];
+    /**
+     * Find all `messages.send` calls targeting a specific channel.
+     */
+    sentTo(channelId: string): RecordedCall[];
+    /**
+     * Find all `interactions.respond` calls for a specific interaction ID.
+     */
+    repliedTo(interactionId: string): RecordedCall[];
+    /** Reset all recorded calls and WS sends. */
+    resetCalls(): 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;
+}
+/** Convenience cast: use a MockClient anywhere a NovaClient is expected. */
+declare function asMockClient(client: MockClient): NovaClient;
+
+/**
+ * @module testing/EventSimulator
+ *
+ * Typed helpers for firing every Nova gateway event on a {@link MockClient}.
+ *
+ * `EventSimulator` is exposed as `harness.simulate` — but you can also use it
+ * standalone:
+ *
+ * @example
+ * ```ts
+ * import { MockClient, EventSimulator } from 'novaapp-sdk/testing'
+ *
+ * const client = new MockClient()
+ * const sim    = new EventSimulator(client)
+ *
+ * // Fire a message
+ * const msg = sim.message({ content: '!ping', channelId: 'ch-1', serverId: 'srv-1' })
+ *
+ * // Fire a slash command
+ * const interaction = sim.slashCommand({ name: 'ban', options: { user: 'user-123' } })
+ *
+ * // Fire a button click
+ * sim.buttonClick({ customId: 'confirm_delete', triggerMsgId: 'msg-456' })
+ * ```
+ */
+
+/**
+ * Fires typed events on a {@link MockClient}, returning the emitted payload
+ * so test code can reference it in assertions.
+ *
+ * Accessed via `harness.simulate`.
+ *
+ * @example
+ * ```ts
+ * const msg = harness.simulate.message({ content: '/help' })
+ * await nextTick()  // let async listeners run
+ * harness.assert.sent({ channelId: msg.channelId })
+ * ```
+ */
+declare class EventSimulator {
+    private readonly client;
+    constructor(client: MockClient);
+    /** Await all already-queued microtasks (useful after async event handlers). */
+    flush(): Promise<void>;
+    /**
+     * Emit a `message` event (bot received a message in a text channel).
+     *
+     * @example
+     * ```ts
+     * sim.message({ content: '!ping', channelId: 'ch-1' })
+     * ```
+     */
+    message(input?: SimulateMessageInput): Message;
+    /**
+     * Emit a `messageEdit` event.
+     */
+    messageEdit(input?: SimulateMessageInput & {
+        newContent?: string;
+    }): Message;
+    /**
+     * Emit a `messageDelete` event.
+     */
+    messageDelete(messageId?: string, channelId?: string): {
+        messageId: string;
+        channelId: string;
+    };
+    /**
+     * Emit an `interaction` event for any interaction type.
+     *
+     * @example
+     * ```ts
+     * sim.interaction({ type: 'PREFIX_COMMAND', commandName: 'help' })
+     * ```
+     */
+    interaction(input?: SimulateInteractionInput): Interaction;
+    /**
+     * Fire a `SLASH_COMMAND` interaction.
+     *
+     * @example
+     * ```ts
+     * sim.slashCommand({ name: 'ping' })
+     * sim.slashCommand({ name: 'ban', options: { user: 'user-123', reason: 'spam' } })
+     * ```
+     */
+    slashCommand(input: SimulateSlashCommandInput): Interaction;
+    /**
+     * Fire a `BUTTON_CLICK` interaction.
+     *
+     * @example
+     * ```ts
+     * sim.buttonClick({ customId: 'confirm_delete' })
+     * ```
+     */
+    buttonClick(input: SimulateButtonInput): Interaction;
+    /**
+     * Fire a `SELECT_MENU` interaction.
+     *
+     * @example
+     * ```ts
+     * sim.selectMenu({ customId: 'role_picker', values: ['mod', 'admin'] })
+     * ```
+     */
+    selectMenu(input: SimulateSelectInput): Interaction;
+    /**
+     * Fire a `MODAL_SUBMIT` interaction.
+     *
+     * @example
+     * ```ts
+     * sim.modalSubmit({ customId: 'report_modal', modalData: { reason: 'spam' } })
+     * ```
+     */
+    modalSubmit(input: SimulateModalInput): Interaction;
+    /**
+     * Fire a `PREFIX_COMMAND` interaction.
+     *
+     * @example
+     * ```ts
+     * sim.prefixCommand({ name: 'kick', userId: 'user-1' })
+     * ```
+     */
+    prefixCommand(input: SimulateSlashCommandInput): Interaction;
+    /**
+     * Emit a `memberJoin` event.
+     *
+     * @example
+     * ```ts
+     * sim.memberJoin({ userId: 'user-123', serverId: 'srv-1' })
+     * ```
+     */
+    memberJoin(input?: SimulateMemberInput): Member;
+    /**
+     * Emit a `memberLeave` event.
+     */
+    memberLeave(input?: SimulateMemberInput): Member;
+    /**
+     * Emit a `memberUpdate` event.
+     */
+    memberUpdate(serverId?: string, userId?: string): void;
+    /**
+     * Emit a `voiceJoin` event.
+     *
+     * @example
+     * ```ts
+     * sim.voiceJoin({ userId: 'user-1', channelId: 'vc-1', serverId: 'srv-1' })
+     * ```
+     */
+    voiceJoin(input?: SimulateVoiceInput): {
+        userId: string;
+        channelId: string;
+        serverId: string;
+    };
+    /**
+     * Emit a `voiceLeave` event.
+     */
+    voiceLeave(input?: SimulateVoiceInput): {
+        userId: string;
+        channelId: string;
+        serverId: string;
+    };
+    /**
+     * Emit a `reactionAdd` event.
+     *
+     * @example
+     * ```ts
+     * sim.reactionAdd({ messageId: 'msg-1', emoji: '👍' })
+     * ```
+     */
+    reactionAdd(input: SimulateReactionInput): void;
+    /**
+     * Emit a `reactionRemove` event.
+     */
+    reactionRemove(input: SimulateReactionInput): void;
+    /**
+     * Emit a `channelCreate` event.
+     */
+    channelCreate(partial: Partial<Channel> & {
+        serverId: string;
+    }): Channel;
+    /**
+     * Emit a `channelDelete` event.
+     */
+    channelDelete(id: string, serverId: string): void;
+    /**
+     * Emit a `roleCreate` event.
+     */
+    roleCreate(partial: Partial<Role> & {
+        serverId: string;
+    }): Role;
+    /**
+     * Emit a `roleDelete` event.
+     */
+    roleDelete(id: string, serverId: string): void;
+    /**
+     * Emit a `memberBanned` event.
+     */
+    memberBanned(userId: string, serverId: string, reason?: string): void;
+    /**
+     * Emit a `memberUnbanned` event.
+     */
+    memberUnbanned(userId: string, serverId: string): void;
+    /**
+     * Emit the `ready` event (simulates successful bot connection).
+     */
+    ready(): void;
+    /**
+     * Emit the `disconnect` event.
+     */
+    disconnect(reason?: string): void;
+}
+
+/**
+ * @module testing/TestHarness
+ *
+ * Orchestration layer for the Nova test harness.
+ *
+ * `TestHarness` wires together a {@link MockClient}, an {@link EventSimulator},
+ * and a set of assertion helpers so you can write concise, readable tests.
+ *
+ * @example
+ * ```ts
+ * import { TestHarness } from 'novaapp-sdk/testing'
+ * import { setupPingCommand } from './src/commands/ping.js'
+ *
+ * test('ping replies', async () => {
+ *   const harness = new TestHarness()
+ *   harness.use(setupPingCommand)
+ *
+ *   harness.simulate.slashCommand({ name: 'ping', channelId: 'ch-1' })
+ *   await harness.flush()
+ *
+ *   harness.assert.replied({ content: 'Pong!' })
+ * })
+ * ```
+ */
+
+/** Assertion helpers exposed as `harness.assert`. */
+declare class HarnessAssertions {
+    private readonly client;
+    constructor(client: MockClient);
+    /**
+     * Assert that `messages.send` was called **at least once** (or exactly `times`
+     * times), optionally matching specific call properties.
+     */
+    sent(options?: AssertSentOptions): void;
+    /**
+     * Assert that `interactions.respond` was called, optionally matching content.
+     */
+    replied(options?: AssertRepliedOptions): void;
+    /**
+     * Assert that `client.wsSend` was called (optionally matching channel/content).
+     */
+    wsSent(channelId?: string, content?: string): void;
+    /**
+     * Assert that a specific API method was called exactly `expected` times.
+     *
+     * @example
+     * ```ts
+     * harness.assert.callCount('members', 'kick', 1)
+     * ```
+     */
+    callCount(api: string, method: string, expected: number): void;
+    /**
+     * Assert that no API calls have been recorded.
+     */
+    noCalls(): void;
+    /**
+     * Assert that no messages were sent (neither via `messages.send` nor `wsSend`).
+     */
+    noMessagesSent(): void;
+    /**
+     * Assert that a specific API method was called at least once.
+     *
+     * @example
+     * ```ts
+     * harness.assert.called('members', 'kick')
+     * ```
+     */
+    called(api: string, method: string): void;
+    /**
+     * Assert that a specific API method was **never** called.
+     *
+     * @example
+     * ```ts
+     * harness.assert.notCalled('members', 'ban')
+     * ```
+     */
+    notCalled(api: string, method: string): void;
+}
+/**
+ * Central coordinator for Nova bot tests.
+ *
+ * Provides:
+ * - `client` — the in-memory {@link MockClient}
+ * - `simulate` — typed event-firing helpers ({@link EventSimulator})
+ * - `assert` — expectation helpers ({@link HarnessAssertions})
+ * - `use(fn)` — wire your setup functions against the mock client
+ * - `reset()` — clear state between tests
+ * - `flush()` — drain all pending microtasks
+ *
+ * @example
+ * ```ts
+ * const harness = new TestHarness()
+ * harness.use(client => registerCommands(client))
+ *
+ * harness.simulate.slashCommand({ name: 'ping' })
+ * await harness.flush()
+ *
+ * harness.assert.replied({ content: 'Pong!' })
+ * ```
+ */
+declare class TestHarness {
+    /** The in-memory mock client. */
+    readonly client: MockClient;
+    /** Typed event simulators. */
+    readonly simulate: EventSimulator;
+    /** Assertion helpers. */
+    readonly assert: HarnessAssertions;
+    constructor();
+    /**
+     * Run a setup function against the mock client (e.g. register commands /
+     * event handlers). Supports both sync and async setups.
+     *
+     * Chainable — call `use` multiple times to compose setup:
+     *
+     * @example
+     * ```ts
+     * harness
+     *   .use(registerCommands)
+     *   .use(registerEventHandlers)
+     * ```
+     */
+    use(fn: (client: NovaClient) => void | Promise<void>): this;
+    /**
+     * Clear all recorded API calls, wsSend history, and event listeners.
+     * Returns `this` so you can chain: `harness.reset().use(...)`.
+     */
+    reset(): this;
+    /**
+     * Awaits all queued microtasks and setImmediate callbacks so that any async
+     * event handlers registered with `use()` have fully run.
+     *
+     * @example
+     * ```ts
+     * harness.simulate.slashCommand({ name: 'ban', options: { user: 'u-1' } })
+     * await harness.flush()
+     * harness.assert.called('members', 'ban')
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * All recorded API calls (shorthand for `harness.client.calls`).
+     */
+    get calls(): RecordedCall[];
+    /**
+     * All `messages.send` calls targeting `channelId` (or all if omitted).
+     */
+    getSent(channelId?: string): Array<{
+        channelId: string;
+        args: unknown[];
+    }>;
+    /**
+     * All `interactions.respond` call payloads.
+     */
+    getReplies(): Array<{
+        interactionId: string;
+        args: unknown[];
+    }>;
+}
+/**
+ * Thrown by assertion helpers when an expectation fails.  Extends `Error`
+ * so it's naturally caught by any test runner.
+ */
+declare class HarnessAssertionError extends Error {
+    constructor(message: string);
+}
+
+export { type AssertRepliedOptions, type AssertSentOptions, EventSimulator, HarnessAssertionError, MockClient, type RecordedCall, type SimulateButtonInput, type SimulateInteractionInput, type SimulateMemberInput, type SimulateMessageInput, type SimulateModalInput, type SimulateReactionInput, type SimulateSelectInput, type SimulateSlashCommandInput, type SimulateVoiceInput, TestHarness, asMockClient };