@dereekb/nestjs 13.32.0 → 13.34.0

package/discord/package.json

@@ -1,25 +0,0 @@
-{
-  "name": "@dereekb/nestjs/discord",
-  "version": "13.32.0",
-  "peerDependencies": {
-    "@dereekb/nestjs": "13.32.0",
-    "@dereekb/rxjs": "13.32.0",
-    "@dereekb/util": "13.32.0",
-    "@nestjs/common": "^11.1.19",
-    "@nestjs/config": "^4.0.4",
-    "discord.js": "^14.26.3",
-    "express": "^5.2.1"
-  },
-  "exports": {
-    "./package.json": "./package.json",
-    ".": {
-      "module": "./index.esm.js",
-      "types": "./index.d.ts",
-      "import": "./index.cjs.mjs",
-      "default": "./index.cjs.js"
-    }
-  },
-  "module": "./index.esm.js",
-  "main": "./index.cjs.js",
-  "types": "./index.d.ts"
-}

package/discord/src/index.d.ts

@@ -1 +0,0 @@
-export * from './lib';

package/discord/src/lib/discord.api.d.ts

@@ -1,69 +0,0 @@
-import { Client, type Message } from 'discord.js';
-import { type OnModuleDestroy, type OnModuleInit } from '@nestjs/common';
-import { DiscordServiceConfig } from './discord.config';
-import { type DiscordChannelId } from './discord.type';
-/**
- * Injectable service that wraps the discord.js Client for bot operations.
- *
- * Automatically logs in on module init and destroys the client on module destroy
- * when autoLogin is enabled (default).
- */
-export declare class DiscordApi implements OnModuleInit, OnModuleDestroy {
-    readonly config: DiscordServiceConfig;
-    private readonly logger;
-    /**
-     * The underlying discord.js Client instance.
-     */
-    readonly client: Client;
-    constructor(config: DiscordServiceConfig);
-    onModuleInit(): Promise<void>;
-    onModuleDestroy(): Promise<void>;
-    /**
-     * Sends a text message to a Discord channel.
-     *
-     * @param channelId - target channel's snowflake ID
-     * @param content - message text to send
-     *
-     * @throws {Error} When the channel is not found or is not a text channel.
-     *
-     * @example
-     * ```ts
-     * const message = await discordApi.sendMessage('123456789', 'Hello from the bot!');
-     * ```
-     */
-    /**
-     * Sends a text message to the specified Discord channel.
-     *
-     * @param channelId - Target channel's snowflake ID.
-     * @param content - Message text to send.
-     * @returns The sent Discord Message.
-     * @throws {Error} When the channel is not found or is not a text channel.
-     */
-    sendMessage(channelId: DiscordChannelId, content: string): Promise<Message>;
-    /**
-     * Registers a handler for the MessageCreate event (incoming messages).
-     *
-     * Returns an unsubscribe function to remove the handler.
-     *
-     * @param handler - callback invoked for each incoming message
-     *
-     * @example
-     * ```ts
-     * const unsubscribe = discordApi.onMessage((message) => {
-     *   if (!message.author.bot) {
-     *     console.log(`${message.author.tag}: ${message.content}`);
-     *   }
-     * });
-     *
-     * // Later, to stop listening:
-     * unsubscribe();
-     * ```
-     */
-    /**
-     * Registers a handler for incoming Discord messages (MessageCreate event).
-     *
-     * @param handler - Callback invoked for each incoming Message.
-     * @returns An unsubscribe function that removes the registered handler.
-     */
-    onMessage(handler: (message: Message) => void): () => void;
-}

package/discord/src/lib/discord.api.page.d.ts

@@ -1,107 +0,0 @@
-import { type Maybe } from '@dereekb/util';
-import { type FetchPageFactory, type FetchPageFactoryConfigDefaults } from '@dereekb/util/fetch';
-import { type DiscordMessageId } from './discord.type';
-/**
- * Default number of messages per page when fetching Discord channel messages.
- */
-export declare const DEFAULT_DISCORD_MESSAGES_PER_PAGE = 100;
-/**
- * Base pagination parameters for Discord channel message endpoints.
- *
- * Discord uses cursor-based pagination via snowflake IDs rather than page numbers.
- * Only one of `before`, `after`, or `around` should be specified per request.
- */
-export interface DiscordMessagePageFilter {
-    /**
-     * Fetch messages before this message ID.
-     */
-    readonly before?: Maybe<DiscordMessageId>;
-    /**
-     * Fetch messages after this message ID.
-     */
-    readonly after?: Maybe<DiscordMessageId>;
-    /**
-     * Fetch messages around this message ID.
-     */
-    readonly around?: Maybe<DiscordMessageId>;
-    /**
-     * Maximum number of messages to return per page (1-100).
-     *
-     * Defaults to {@link DEFAULT_DISCORD_MESSAGES_PER_PAGE}.
-     */
-    readonly limit?: Maybe<number>;
-}
-/**
- * Result of a paginated Discord message fetch containing the array of messages.
- *
- * @typeParam T - The message type (typically discord.js `Message`)
- */
-export interface DiscordMessagePageResult<T> {
-    /**
-     * Array of messages returned.
-     */
-    readonly data: T[];
-}
-/**
- * A fetch function that accepts {@link DiscordMessagePageFilter} input and returns a {@link DiscordMessagePageResult}.
- * Used as the underlying data source for {@link discordFetchMessagePageFactory}.
- */
-export type DiscordFetchMessagePageFetchFunction<I extends DiscordMessagePageFilter, T> = (input: I) => Promise<DiscordMessagePageResult<T>>;
-/**
- * Configuration for {@link discordFetchMessagePageFactory}.
- *
- * @typeParam T - The message type
- */
-export interface DiscordFetchMessagePageFactoryConfig<T> {
-    /**
-     * Extracts the snowflake ID from a message object. Used to determine the cursor for the next page.
-     *
-     * Defaults to reading the `id` property on the message.
-     */
-    readonly readMessageId?: (message: T) => DiscordMessageId;
-}
-/**
- * Configuration for {@link discordFetchMessagePageFactory}.
- *
- * @typeParam I - The input filter type
- * @typeParam T - The message type
- */
-export interface DiscordFetchMessagePageFactoryInput<I extends DiscordMessagePageFilter, T> {
-    /**
-     * The Discord fetch function to paginate over.
-     */
-    readonly fetch: DiscordFetchMessagePageFetchFunction<I, T>;
-    /**
-     * Optional config for reading message IDs.
-     */
-    readonly config?: Maybe<DiscordFetchMessagePageFactoryConfig<T>>;
-    /**
-     * Optional default configuration for the page factory.
-     */
-    readonly defaults?: Maybe<FetchPageFactoryConfigDefaults>;
-}
-/**
- * Creates a page factory that wraps a Discord message fetch function with automatic cursor-based pagination.
- *
- * Discord paginates via `before`/`after` snowflake IDs. This factory automatically reads the last
- * message's ID from each response and sets it as the `before` cursor for the next request.
- * When the number of returned messages is less than the requested limit, pagination stops.
- *
- * @param input - The factory input configuration.
- * @returns A page factory that produces iterable page fetchers.
- *
- * @example
- * ```typescript
- * const pageFactory = discordFetchMessagePageFactory({ fetch: fetchChannelMessages });
- *
- * const fetchPage = pageFactory({ limit: 50 });
- * const firstPage = await fetchPage.fetchNext();
- *
- * if (firstPage.hasNext) {
- *   const secondPage = await firstPage.fetchNext();
- * }
- * ```
- */
-export declare function discordFetchMessagePageFactory<I extends DiscordMessagePageFilter, T extends {
-    id: string;
-}>(input: DiscordFetchMessagePageFactoryInput<I, T>): FetchPageFactory<I, DiscordMessagePageResult<T>>;

package/discord/src/lib/discord.api.spec.client.d.ts

@@ -1,20 +0,0 @@
-import { DiscordApi } from './discord.api';
-/**
- * Shared, process-singleton Discord test client.
- *
- * Integration spec files import {@link getSharedDiscordTestClient} so that at most one
- * `client.login()` call occurs per vitest worker process, regardless of how many spec
- * files participate. This keeps the bot's daily gateway-session quota intact during
- * normal development.
- */
-export interface SharedDiscordTestClient {
-    readonly discordApi: DiscordApi;
-    readonly testChannelId: string;
-}
-/**
- * Returns the shared logged-in test client, creating it on first call and reusing it
- * on subsequent calls within the same process.
- *
- * @returns The cached {@link SharedDiscordTestClient}.
- */
-export declare function getSharedDiscordTestClient(): Promise<SharedDiscordTestClient>;

package/discord/src/lib/discord.config.d.ts

@@ -1,58 +0,0 @@
-import { type Maybe } from '@dereekb/util';
-import { type ClientOptions, GatewayIntentBits } from 'discord.js';
-import { type DiscordBotToken } from './discord.type';
-/**
- * Default environment variable for the Discord bot token.
- */
-export declare const DISCORD_BOT_TOKEN_ENV_VAR = "DISCORD_BOT_TOKEN";
-/**
- * Placeholder bot token value used in development and CI environments where a real Discord
- * login should not be attempted. Mirrors the value used in the workspace's .env file.
- */
-export declare const DISCORD_BOT_TOKEN_PLACEHOLDER = "placeholder";
-/**
- * Returns true if the input is a real, usable Discord bot token.
- *
- * A token is usable when it is non-empty and is not the shared placeholder value, allowing
- * non-production environments to skip a real gateway login that would always fail.
- *
- * @param botToken - The bot token read from configuration, if any.
- * @returns True when the token should be used to log in.
- *
- * @example
- * ```ts
- * isUsableDiscordBotToken('placeholder'); // false
- * isUsableDiscordBotToken('real-token');  // true
- * ```
- */
-export declare function isUsableDiscordBotToken(botToken: Maybe<DiscordBotToken>): boolean;
-/**
- * Default gateway intents for a bot that reads guild messages.
- *
- * Includes Guilds, GuildMessages, and MessageContent.
- * Note: MessageContent is a privileged intent and must be enabled in the Discord Developer Portal.
- */
-export declare const DEFAULT_DISCORD_INTENTS: GatewayIntentBits[];
-export interface DiscordServiceApiConfig {
-    /**
-     * The bot token used to authenticate with the Discord gateway.
-     */
-    readonly botToken: DiscordBotToken;
-    /**
-     * discord.js Client options. Intents default to DEFAULT_DISCORD_INTENTS if not provided.
-     */
-    readonly clientOptions?: Partial<ClientOptions>;
-    /**
-     * Whether to automatically call client.login() during module initialization.
-     *
-     * Defaults to true.
-     */
-    readonly autoLogin?: boolean;
-}
-/**
- * Configuration for the DiscordApi service.
- */
-export declare abstract class DiscordServiceConfig {
-    readonly discord: DiscordServiceApiConfig;
-    static assertValidConfig(config: DiscordServiceConfig): void;
-}

package/discord/src/lib/discord.module.d.ts

@@ -1,20 +0,0 @@
-import { ConfigService } from '@nestjs/config';
-import { DiscordServiceConfig } from './discord.config';
-/**
- * Factory that creates a DiscordServiceConfig from environment variables.
- *
- * autoLogin is enabled only when a real bot token is configured and the process is not running
- * under a test environment, so development and CI runs (which use a placeholder token) never
- * attempt a real gateway login that would fail.
- *
- * @param configService - The NestJS config service used to read Discord environment variables.
- * @returns A validated DiscordServiceConfig populated from environment variables.
- */
-export declare function discordServiceConfigFactory(configService: ConfigService): DiscordServiceConfig;
-/**
- * NestJS module that provides the DiscordApi service.
- *
- * Reads the bot token from the DISCORD_BOT_TOKEN environment variable.
- */
-export declare class DiscordModule {
-}

package/discord/src/lib/discord.type.d.ts

@@ -1,26 +0,0 @@
-/**
- * A Discord snowflake ID string.
- */
-export type DiscordId = string;
-/**
- * Bot token used to authenticate the Discord bot with the gateway.
- */
-export type DiscordBotToken = string;
-/**
- * A Discord channel ID (snowflake string).
- */
-export type DiscordChannelId = string;
-/**
- * A Discord guild (server) ID (snowflake string).
- */
-export type DiscordGuildId = string;
-/**
- * A Discord message snowflake ID string.
- */
-export type DiscordMessageId = string;
-/**
- * The Ed25519 public key of your Discord application, used to verify interaction webhooks.
- *
- * Found in the Discord Developer Portal under your application's General Information page.
- */
-export type DiscordPublicKey = string;

package/discord/src/lib/discord.util.d.ts

@@ -1,28 +0,0 @@
-import { type GatewayIntentBits, type ClientOptions } from 'discord.js';
-/**
- * Returns default ClientOptions for a bot that reads guild messages.
- *
- * Includes Guilds, GuildMessages, and MessageContent intents.
- *
- * @returns Partial ClientOptions with the default bot intents set.
- *
- * @example
- * ```ts
- * const options = discordDefaultClientOptions();
- * // options.intents === [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent]
- * ```
- */
-export declare function discordDefaultClientOptions(): Partial<ClientOptions>;
-/**
- * Returns ClientOptions with additional intents merged with the defaults.
- *
- * @param additionalIntents - Extra intents to include beyond the defaults.
- * @returns Partial ClientOptions with the merged intent list.
- *
- * @example
- * ```ts
- * const options = discordClientOptionsWithIntents([GatewayIntentBits.DirectMessages]);
- * // options.intents includes Guilds, GuildMessages, MessageContent, and DirectMessages
- * ```
- */
-export declare function discordClientOptionsWithIntents(additionalIntents: GatewayIntentBits[]): Partial<ClientOptions>;

package/discord/src/lib/index.d.ts

@@ -1,7 +0,0 @@
-export * from './webhook';
-export * from './discord.module';
-export * from './discord.api';
-export * from './discord.api.page';
-export * from './discord.config';
-export * from './discord.type';
-export * from './discord.util';

package/discord/src/lib/webhook/index.d.ts

@@ -1,6 +0,0 @@
-export * from './webhook.discord';
-export * from './webhook.discord.config';
-export * from './webhook.discord.controller';
-export * from './webhook.discord.module';
-export * from './webhook.discord.service';
-export * from './webhook.discord.verify';

package/discord/src/lib/webhook/webhook.discord.config.d.ts

@@ -1,22 +0,0 @@
-import { type DiscordPublicKey } from '../discord.type';
-/**
- * Default environment variable for the Discord application public key.
- */
-export declare const DISCORD_PUBLIC_KEY_ENV_VAR = "DISCORD_PUBLIC_KEY";
-/**
- * The byte length of a Discord Ed25519 public key (32 bytes = 64 hex characters).
- */
-export declare const DISCORD_ED25519_PUBLIC_KEY_BYTE_LENGTH = 32;
-export interface DiscordWebhookConfig {
-    /**
-     * The Ed25519 public key used to verify incoming interaction webhook signatures.
-     */
-    readonly publicKey: DiscordPublicKey;
-}
-/**
- * Configuration for the DiscordWebhookService.
- */
-export declare abstract class DiscordWebhookServiceConfig {
-    readonly discordWebhook: DiscordWebhookConfig;
-    static assertValidConfig(config: DiscordWebhookServiceConfig): void;
-}

package/discord/src/lib/webhook/webhook.discord.controller.d.ts

@@ -1,8 +0,0 @@
-import { type RawBodyBuffer } from '@dereekb/nestjs';
-import { type Request } from 'express';
-import { DiscordWebhookService } from './webhook.discord.service';
-export declare class DiscordWebhookController {
-    private readonly _discordWebhookService;
-    constructor(discordWebhookService: DiscordWebhookService);
-    handleDiscordWebhook(req: Request, rawBody: RawBodyBuffer): Promise<void>;
-}

package/discord/src/lib/webhook/webhook.discord.d.ts

@@ -1,59 +0,0 @@
-import { type HandlerBindAccessor, type HandlerMappedSetFunction, type Handler } from '@dereekb/util';
-import { InteractionType, type Interaction } from 'discord.js';
-/**
- * Discord interaction type numeric key, used for handler dispatch.
- */
-export type DiscordInteractionType = InteractionType;
-/**
- * An untyped Discord interaction received via webhook.
- */
-export type UntypedDiscordInteraction = Interaction;
-/**
- * A typed Discord interaction, narrowed from the base Interaction type.
- *
- * @example
- * ```ts
- * const interaction: DiscordWebhookInteraction<ChatInputCommandInteraction> = discordWebhookInteraction(rawInteraction);
- * ```
- */
-export type DiscordWebhookInteraction<T extends Interaction = Interaction> = T;
-/**
- * Casts an untyped Discord interaction to a typed one.
- *
- * @param interaction - The raw interaction to cast.
- * @returns The interaction cast to the specified typed DiscordWebhookInteraction.
- */
-export declare function discordWebhookInteraction<T extends Interaction = Interaction>(interaction: UntypedDiscordInteraction): DiscordWebhookInteraction<T>;
-export type DiscordInteractionHandler = Handler<UntypedDiscordInteraction, DiscordInteractionType>;
-export declare const discordInteractionHandlerFactory: import("@dereekb/util").HandlerFactory<UntypedDiscordInteraction, InteractionType, boolean>;
-export type DiscordHandlerMappedSetFunction<T extends Interaction = Interaction> = HandlerMappedSetFunction<DiscordWebhookInteraction<T>>;
-/**
- * Configurer for Discord interaction handlers.
- *
- * Handlers are keyed on InteractionType. Use discord.js type guards
- * (e.g., interaction.isChatInputCommand(), interaction.isButton()) within
- * your handler callback for sub-type refinement.
- */
-export interface DiscordInteractionHandlerConfigurer extends HandlerBindAccessor<UntypedDiscordInteraction, DiscordInteractionType> {
-    /**
-     * Handles application commands (slash commands + context menu commands).
-     *
-     * Use interaction.isChatInputCommand() or interaction.isContextMenuCommand() to narrow the type within your handler.
-     */
-    readonly handleApplicationCommand: DiscordHandlerMappedSetFunction;
-    /**
-     * Handles message component interactions (buttons + select menus).
-     *
-     * Use interaction.isButton() or interaction.isStringSelectMenu() to narrow the type within your handler.
-     */
-    readonly handleMessageComponent: DiscordHandlerMappedSetFunction;
-    /**
-     * Handles modal submit interactions.
-     */
-    readonly handleModalSubmit: DiscordHandlerMappedSetFunction;
-    /**
-     * Handles autocomplete interactions for slash command options.
-     */
-    readonly handleAutocomplete: DiscordHandlerMappedSetFunction;
-}
-export declare const discordInteractionHandlerConfigurerFactory: import("@dereekb/util").HandlerConfigurerFactory<DiscordInteractionHandlerConfigurer, UntypedDiscordInteraction, InteractionType, boolean>;

package/discord/src/lib/webhook/webhook.discord.module.d.ts

@@ -1,17 +0,0 @@
-import { ConfigService } from '@nestjs/config';
-import { DiscordWebhookServiceConfig } from './webhook.discord.config';
-/**
- * Factory that creates a DiscordWebhookServiceConfig from environment variables.
- *
- * @param configService - The NestJS config service used to read the Discord public key environment variable.
- * @returns A validated DiscordWebhookServiceConfig populated from environment variables.
- */
-export declare function discordWebhookServiceConfigFactory(configService: ConfigService): DiscordWebhookServiceConfig;
-/**
- * NestJS module that provides Discord interaction webhook handling.
- *
- * Standalone — does not depend on DiscordModule (no bot token needed).
- * Reads the application public key from the DISCORD_PUBLIC_KEY environment variable.
- */
-export declare class DiscordWebhookModule {
-}

package/discord/src/lib/webhook/webhook.discord.service.d.ts

@@ -1,18 +0,0 @@
-import { type Request } from 'express';
-import { type DiscordInteractionType, type UntypedDiscordInteraction } from './webhook.discord';
-import { type Handler } from '@dereekb/util';
-import { DiscordWebhookServiceConfig } from './webhook.discord.config';
-/**
- * Service that handles Discord interaction webhook events.
- *
- * Verifies incoming webhook signatures and dispatches interactions to registered handlers.
- */
-export declare class DiscordWebhookService {
-    private readonly logger;
-    private readonly _verifier;
-    readonly handler: Handler<UntypedDiscordInteraction, DiscordInteractionType>;
-    readonly configure: import("@dereekb/util").HandlerConfigurer<import("./webhook.discord").DiscordInteractionHandlerConfigurer, UntypedDiscordInteraction, import("discord.js").InteractionType, boolean>;
-    constructor(discordWebhookServiceConfig: DiscordWebhookServiceConfig);
-    updateForWebhook(req: Request, rawBody: Buffer): Promise<void>;
-    updateForDiscordInteraction(interaction: UntypedDiscordInteraction): Promise<void>;
-}

package/discord/src/lib/webhook/webhook.discord.verify.d.ts

@@ -1,46 +0,0 @@
-import { type Request } from 'express';
-import { type DiscordPublicKey } from '../discord.type';
-export interface DiscordWebhookEventVerificationConfig {
-    /**
-     * The Ed25519 public key from the Discord Developer Portal.
-     */
-    readonly publicKey: DiscordPublicKey;
-}
-export type DiscordWebhookEventVerificationResult = DiscordWebhookEventVerificationSuccessResult | DiscordWebhookEventVerificationErrorResult;
-export interface DiscordWebhookEventVerificationSuccessResult {
-    readonly valid: true;
-    /**
-     * The parsed JSON body of the verified interaction.
-     */
-    readonly body: unknown;
-}
-export interface DiscordWebhookEventVerificationErrorResult {
-    readonly valid: false;
-}
-/**
- * Function that verifies a Discord interaction webhook request using Ed25519 signatures.
- */
-export type DiscordWebhookEventVerifier = (req: Request, rawBody: Buffer) => Promise<DiscordWebhookEventVerificationResult>;
-/**
- * Creates a verifier for Discord interaction webhook requests.
- *
- * Discord signs interaction webhook requests with Ed25519. The signed message is
- * the concatenation of the x-signature-timestamp header and the raw request body.
- * The signature is provided in the x-signature-ed25519 header as a hex string.
- *
- * Uses Node.js built-in crypto with JWK key import — no external dependencies required.
- *
- * @param config - Verification config containing the application's public key.
- * @returns A DiscordWebhookEventVerifier function that validates Ed25519-signed requests.
- *
- * @example
- * ```ts
- * const verifier = discordWebhookEventVerifier({ publicKey: 'your-hex-public-key' });
- * const result = await verifier(req, rawBody);
- *
- * if (result.valid) {
- *   // result.body contains the parsed interaction
- * }
- * ```
- */
-export declare function discordWebhookEventVerifier(config: DiscordWebhookEventVerificationConfig): DiscordWebhookEventVerifier;