@dereekb/nestjs 13.4.0 → 13.4.2

package/discord/index.cjs.js

@@ -59,6 +59,7 @@ function _object_spread_props$1(target, source) {
  * 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
  */ function discordWebhookInteraction(interaction) {
     return interaction;
 }
@@ -67,7 +68,6 @@ var discordInteractionHandlerFactory = util.handlerFactory(function(x) {
 });
 var discordInteractionHandlerConfigurerFactory = util.handlerConfigurerFactory({
     configurerForAccessor: function configurerForAccessor(accessor) {
-        // eslint-disable-next-line
         var fnWithKey = util.handlerMappedSetFunctionFactory(accessor, discordWebhookInteraction);
         var configurer = _object_spread_props$1(_object_spread$2({}, accessor), {
             handleApplicationCommand: fnWithKey(discord_js.InteractionType.ApplicationCommand),
@@ -292,6 +292,7 @@ function _ts_generator$3(thisArg, body) {
  * 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
@@ -811,6 +812,9 @@ function _class_call_check$3(instance, Constructor) {
 }
 /**
  * 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
  */ function discordWebhookServiceConfigFactory(configService) {
     var config = {
         discordWebhook: {
@@ -1127,7 +1131,9 @@ function _ts_generator(thisArg, body) {
                         _this = this;
                         _this_config_discord = this.config.discord, _this_config_discord_autoLogin = _this_config_discord.autoLogin, autoLogin = _this_config_discord_autoLogin === void 0 ? true : _this_config_discord_autoLogin, botToken = _this_config_discord.botToken;
                         if (autoLogin) {
-                            result = this.client.login(botToken).then(function() {}).catch(function(e) {
+                            result = this.client.login(botToken).then(function() {
+                                return undefined;
+                            }).catch(function(e) {
                                 _this.logger.error('Failed to log in to Discord', e);
                             });
                         } else {
@@ -1168,6 +1174,13 @@ function _ts_generator(thisArg, body) {
      * ```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
      */ function sendMessage(channelId, content) {
                 return _async_to_generator(function() {
                     var channel;
@@ -1211,6 +1224,11 @@ function _ts_generator(thisArg, body) {
      * // 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
      */ key: "onMessage",
             value: function onMessage(handler) {
                 var _this = this;
@@ -1235,6 +1253,9 @@ function _class_call_check(instance, Constructor) {
 }
 /**
  * Factory that creates a DiscordServiceConfig from environment variables.
+ *
+ * @param configService - the NestJS config service used to read Discord environment variables
+ * @returns a validated DiscordServiceConfig populated from environment variables
  */ function discordServiceConfigFactory(configService) {
     var config = {
         discord: {
@@ -1330,14 +1351,12 @@ function _object_spread_props(target, source) {
  * 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 fetch - The Discord fetch function to paginate over
- * @param config - Optional config for reading message IDs
- * @param defaults - Optional default configuration for the page factory
+ * @param input - The factory input configuration
  * @returns A page factory that produces iterable page fetchers
  *
  * @example
  * ```typescript
- * const pageFactory = discordFetchMessagePageFactory(fetchChannelMessages);
+ * const pageFactory = discordFetchMessagePageFactory({ fetch: fetchChannelMessages });
  *
  * const fetchPage = pageFactory({ limit: 50 });
  * const firstPage = await fetchPage.fetchNext();
@@ -1346,8 +1365,9 @@ function _object_spread_props(target, source) {
  *   const secondPage = await firstPage.fetchNext();
  * }
  * ```
- */ function discordFetchMessagePageFactory(fetch$1, config, defaults) {
+ */ function discordFetchMessagePageFactory(input) {
     var _ref;
+    var fetch$1 = input.fetch, config = input.config, defaults = input.defaults;
     var readMessageId = (_ref = config === null || config === void 0 ? void 0 : config.readMessageId) !== null && _ref !== void 0 ? _ref : function(message) {
         return message.id;
     };
@@ -1355,8 +1375,7 @@ function _object_spread_props(target, source) {
         fetch: fetch$1,
         readFetchPageResultInfo: function readFetchPageResultInfo(result) {
             var count = result.data.length;
-            var lastMessage = util.lastValue(result.data);
-            var nextCursor = lastMessage ? readMessageId(lastMessage) : undefined;
+            var nextCursor = count > 0 ? readMessageId(util.lastValue(result.data)) : undefined;
             return {
                 hasNext: count > 0,
                 nextPageCursor: nextCursor
@@ -1412,6 +1431,8 @@ function _unsupported_iterable_to_array(o, minLen) {
  *
  * Includes Guilds, GuildMessages, and MessageContent intents.
  *
+ * @returns partial ClientOptions with the default bot intents set
+ *
  * @example
  * ```ts
  * const options = discordDefaultClientOptions();
@@ -1426,6 +1447,7 @@ function _unsupported_iterable_to_array(o, minLen) {
  * 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

package/discord/index.esm.js

@@ -57,6 +57,7 @@ function _object_spread_props$1(target, source) {
  * 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
  */ function discordWebhookInteraction(interaction) {
     return interaction;
 }
@@ -65,7 +66,6 @@ var discordInteractionHandlerFactory = handlerFactory(function(x) {
 });
 var discordInteractionHandlerConfigurerFactory = handlerConfigurerFactory({
     configurerForAccessor: function configurerForAccessor(accessor) {
-        // eslint-disable-next-line
         var fnWithKey = handlerMappedSetFunctionFactory(accessor, discordWebhookInteraction);
         var configurer = _object_spread_props$1(_object_spread$2({}, accessor), {
             handleApplicationCommand: fnWithKey(InteractionType.ApplicationCommand),
@@ -290,6 +290,7 @@ function _ts_generator$3(thisArg, body) {
  * 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
@@ -809,6 +810,9 @@ function _class_call_check$3(instance, Constructor) {
 }
 /**
  * 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
  */ function discordWebhookServiceConfigFactory(configService) {
     var config = {
         discordWebhook: {
@@ -1125,7 +1129,9 @@ function _ts_generator(thisArg, body) {
                         _this = this;
                         _this_config_discord = this.config.discord, _this_config_discord_autoLogin = _this_config_discord.autoLogin, autoLogin = _this_config_discord_autoLogin === void 0 ? true : _this_config_discord_autoLogin, botToken = _this_config_discord.botToken;
                         if (autoLogin) {
-                            result = this.client.login(botToken).then(function() {}).catch(function(e) {
+                            result = this.client.login(botToken).then(function() {
+                                return undefined;
+                            }).catch(function(e) {
                                 _this.logger.error('Failed to log in to Discord', e);
                             });
                         } else {
@@ -1166,6 +1172,13 @@ function _ts_generator(thisArg, body) {
      * ```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
      */ function sendMessage(channelId, content) {
                 return _async_to_generator(function() {
                     var channel;
@@ -1209,6 +1222,11 @@ function _ts_generator(thisArg, body) {
      * // 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
      */ key: "onMessage",
             value: function onMessage(handler) {
                 var _this = this;
@@ -1233,6 +1251,9 @@ function _class_call_check(instance, Constructor) {
 }
 /**
  * Factory that creates a DiscordServiceConfig from environment variables.
+ *
+ * @param configService - the NestJS config service used to read Discord environment variables
+ * @returns a validated DiscordServiceConfig populated from environment variables
  */ function discordServiceConfigFactory(configService) {
     var config = {
         discord: {
@@ -1328,14 +1349,12 @@ function _object_spread_props(target, source) {
  * 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 fetch - The Discord fetch function to paginate over
- * @param config - Optional config for reading message IDs
- * @param defaults - Optional default configuration for the page factory
+ * @param input - The factory input configuration
  * @returns A page factory that produces iterable page fetchers
  *
  * @example
  * ```typescript
- * const pageFactory = discordFetchMessagePageFactory(fetchChannelMessages);
+ * const pageFactory = discordFetchMessagePageFactory({ fetch: fetchChannelMessages });
  *
  * const fetchPage = pageFactory({ limit: 50 });
  * const firstPage = await fetchPage.fetchNext();
@@ -1344,8 +1363,9 @@ function _object_spread_props(target, source) {
  *   const secondPage = await firstPage.fetchNext();
  * }
  * ```
- */ function discordFetchMessagePageFactory(fetch, config, defaults) {
+ */ function discordFetchMessagePageFactory(input) {
     var _ref;
+    var fetch = input.fetch, config = input.config, defaults = input.defaults;
     var readMessageId = (_ref = config === null || config === void 0 ? void 0 : config.readMessageId) !== null && _ref !== void 0 ? _ref : function(message) {
         return message.id;
     };
@@ -1353,8 +1373,7 @@ function _object_spread_props(target, source) {
         fetch: fetch,
         readFetchPageResultInfo: function readFetchPageResultInfo(result) {
             var count = result.data.length;
-            var lastMessage = lastValue(result.data);
-            var nextCursor = lastMessage ? readMessageId(lastMessage) : undefined;
+            var nextCursor = count > 0 ? readMessageId(lastValue(result.data)) : undefined;
             return {
                 hasNext: count > 0,
                 nextPageCursor: nextCursor
@@ -1410,6 +1429,8 @@ function _unsupported_iterable_to_array(o, minLen) {
  *
  * Includes Guilds, GuildMessages, and MessageContent intents.
  *
+ * @returns partial ClientOptions with the default bot intents set
+ *
  * @example
  * ```ts
  * const options = discordDefaultClientOptions();
@@ -1424,6 +1445,7 @@ function _unsupported_iterable_to_array(o, minLen) {
  * 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

package/discord/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@dereekb/nestjs/discord",
-  "version": "13.4.0",
+  "version": "13.4.2",
   "peerDependencies": {
-    "@dereekb/nestjs": "13.4.0",
-    "@dereekb/util": "13.4.0",
+    "@dereekb/nestjs": "13.4.2",
+    "@dereekb/util": "13.4.2",
     "@nestjs/common": "^11.1.16",
     "@nestjs/config": "^4.0.3",
     "discord.js": "^14.25.1",

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

@@ -31,6 +31,14 @@ export declare class DiscordApi implements OnModuleInit, OnModuleDestroy {
      * 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).
@@ -51,5 +59,11 @@ export declare class DiscordApi implements OnModuleInit, OnModuleDestroy {
      * 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

@@ -60,6 +60,26 @@ export interface DiscordFetchMessagePageFactoryConfig<T> {
      */
     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.
  *
@@ -67,14 +87,12 @@ export interface DiscordFetchMessagePageFactoryConfig<T> {
  * 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 fetch - The Discord fetch function to paginate over
- * @param config - Optional config for reading message IDs
- * @param defaults - Optional default configuration for the page factory
+ * @param input - The factory input configuration
  * @returns A page factory that produces iterable page fetchers
  *
  * @example
  * ```typescript
- * const pageFactory = discordFetchMessagePageFactory(fetchChannelMessages);
+ * const pageFactory = discordFetchMessagePageFactory({ fetch: fetchChannelMessages });
  *
  * const fetchPage = pageFactory({ limit: 50 });
  * const firstPage = await fetchPage.fetchNext();
@@ -86,4 +104,4 @@ export interface DiscordFetchMessagePageFactoryConfig<T> {
  */
 export declare function discordFetchMessagePageFactory<I extends DiscordMessagePageFilter, T extends {
     id: string;
-}>(fetch: DiscordFetchMessagePageFetchFunction<I, T>, config?: Maybe<DiscordFetchMessagePageFactoryConfig<T>>, defaults?: Maybe<FetchPageFactoryConfigDefaults>): FetchPageFactory<I, DiscordMessagePageResult<T>>;
+}>(input: DiscordFetchMessagePageFactoryInput<I, T>): FetchPageFactory<I, DiscordMessagePageResult<T>>;

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

@@ -2,6 +2,9 @@ import { ConfigService } from '@nestjs/config';
 import { DiscordServiceConfig } from './discord.config';
 /**
  * Factory that creates a DiscordServiceConfig from environment variables.
+ *
+ * @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;
 /**

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

@@ -4,6 +4,8 @@ import { type GatewayIntentBits, type ClientOptions } from 'discord.js';
  *
  * Includes Guilds, GuildMessages, and MessageContent intents.
  *
+ * @returns partial ClientOptions with the default bot intents set
+ *
  * @example
  * ```ts
  * const options = discordDefaultClientOptions();
@@ -15,6 +17,7 @@ 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

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

@@ -21,6 +21,7 @@ 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>;

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

@@ -2,6 +2,9 @@ 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;
 /**

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

@@ -31,6 +31,7 @@ export type DiscordWebhookEventVerifier = (req: Request, rawBody: Buffer) => Pro
  * 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

package/index.cjs.js

@@ -13,7 +13,14 @@ var crypto = require('crypto');
  */ var IsRequestFromLocalHost = common.createParamDecorator(function(data, context) {
     return isLocalhost(context);
 });
-function isLocalhost(context) {
+/**
+ * Returns true if the request's origin header indicates the request came from localhost.
+ *
+ * Checks for both http://localhost and https://localhost origins.
+ *
+ * @param context - the NestJS execution context containing the HTTP request
+ * @returns true if the request origin is localhost
+ */ function isLocalhost(context) {
     var _req_headers_origin;
     var req = context.switchToHttp().getRequest();
     var origin = (_req_headers_origin = req.headers['origin']) !== null && _req_headers_origin !== void 0 ? _req_headers_origin : '';
@@ -160,7 +167,8 @@ function _ts_generator(thisArg, body) {
  * @Post('webhook')
  * handleWebhook(@ParseRawBody() body: RawBodyBuffer) { ... }
  * ```
- */ var ParseRawBody = common.createParamDecorator(function(_, context) {
+ */ var rawBodyLogger = new common.Logger('RawBody');
+var ParseRawBody = common.createParamDecorator(function(_, context) {
     return _async_to_generator(function() {
         var req, body;
         return _ts_generator(this, function(_state) {
@@ -168,7 +176,7 @@ function _ts_generator(thisArg, body) {
                 case 0:
                     req = context.switchToHttp().getRequest();
                     if (!req.readable) {
-                        console.error('RawBody request was not readable. This is generally due to bad configuration.');
+                        rawBodyLogger.error('RawBody request was not readable. This is generally due to bad configuration.');
                         throw new common.BadRequestException('Invalid body');
                     }
                     return [
@@ -204,7 +212,7 @@ function _ts_generator(thisArg, body) {
             req = context.switchToHttp().getRequest();
             body = req.body;
             if (!Buffer.isBuffer(body)) {
-                console.error('RawBody expected a buffer set to req.body.');
+                rawBodyLogger.error('RawBody expected a buffer set to req.body.');
                 throw new common.InternalServerErrorException('failed parsing body');
             }
             return [
@@ -556,9 +564,9 @@ function _type_of(obj) {
 /**
  * Merges two module metadata entries together.
  *
- * @param base
- * @param additional
- * @returns
+ * @param base - the base module metadata
+ * @param additional - additional metadata to merge in
+ * @returns the merged module metadata
  */ function mergeModuleMetadata(base) {
     var additional = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
     return {
@@ -580,7 +588,14 @@ function _type_of(obj) {
         ])
     };
 }
-function injectionTokensFromProviders(providers) {
+/**
+ * Extracts the injection tokens from an array (or single value) of NestJS Providers.
+ *
+ * For class providers, returns the class itself; for object providers, returns the provide token.
+ *
+ * @param providers - the providers to extract tokens from
+ * @returns an array of injection tokens
+ */ function injectionTokensFromProviders(providers) {
     return util.asArray(providers).map(function(x) {
         return (typeof x === "undefined" ? "undefined" : _type_of(x)) === 'object' ? x.provide : x;
     });
@@ -720,7 +735,14 @@ function _class_call_check$2(instance, Constructor) {
         throw new TypeError("Cannot call a class as a function");
     }
 }
-function clientAppConfigFactory(configService) {
+/**
+ * Factory that creates a ClientAppServiceConfig from environment variables.
+ *
+ * Reads the client web app URL from the CLIENT_WEB_APP_URL environment variable.
+ *
+ * @param configService - NestJS config service for reading environment variables
+ * @returns a validated ClientAppServiceConfig
+ */ function clientAppConfigFactory(configService) {
     var config = {
         client: {
             clientWebAppUrl: configService.get(CLIENT_WEB_APP_URL_ENV_VAR)
@@ -729,7 +751,11 @@ function clientAppConfigFactory(configService) {
     ClientAppServiceConfig.assertValidConfig(config);
     return config;
 }
-exports.ClientAppModule = function ClientAppModule() {
+/**
+ * NestJS module that provides the ClientAppService for accessing client application configuration.
+ *
+ * Reads the client web app URL from environment variables and makes it available via ClientAppService.
+ */ exports.ClientAppModule = function ClientAppModule() {
     _class_call_check$2(this, ClientAppModule);
 };
 exports.ClientAppModule = __decorate([
@@ -744,7 +770,8 @@ exports.ClientAppModule = __decorate([
                     config.ConfigService
                 ],
                 useFactory: clientAppConfigFactory
-            }
+            },
+            exports.ClientAppService
         ],
         exports: [
             exports.ClientAppService
@@ -772,7 +799,14 @@ function _class_call_check$1(instance, Constructor) {
 /**
  * Token to access a configured ServerEnvironmentServiceConfig for the app.
  */ var SERVER_ENV_TOKEN = 'SERVER_ENV_TOKEN';
-function serverEnvTokenProvider(env) {
+/**
+ * Creates a NestJS Provider that supplies a ServerEnvironmentConfig under the SERVER_ENV_TOKEN injection token.
+ *
+ * Use this to register a server environment configuration instance with the NestJS dependency injection container.
+ *
+ * @param env - the server environment config to provide
+ * @returns a NestJS Provider that supplies the config under SERVER_ENV_TOKEN
+ */ function serverEnvTokenProvider(env) {
     return {
         provide: SERVER_ENV_TOKEN,
         useValue: env
@@ -780,7 +814,9 @@ function serverEnvTokenProvider(env) {
 }
 
 /**
- * Checks process.env.NODE_ENV for "test"
+ * Checks process.env.NODE_ENV for "test".
+ *
+ * @returns true if the current Node environment is "test", false otherwise
  */ function isTestNodeEnv() {
     return process.env['NODE_ENV'] === 'test';
 }
@@ -871,6 +907,9 @@ var ENCRYPTED_FIELD_KEY_LENGTH = 32;
 /**
  * Validates that the given secret is a 64-character hexadecimal string (32 bytes for AES-256).
  *
+ * @param secret - the hex-encoded secret key string to validate
+ * @returns true if the secret is exactly 64 valid hex characters, false otherwise
+ *
  * @example
  * ```typescript
  * isValidAES256GCMEncryptionSecret('a'.repeat(64)); // true