@dereekb/nestjs 13.11.13 → 13.11.15

package/mailgun/src/lib/mailgun.d.ts

@@ -172,6 +172,7 @@ export declare const MAX_BATCH_SEND_RECIPIENTS = 1000;
  *
  * @param config - The conversion configuration containing the email request, default sender, and recipient variable settings.
  * @returns The constructed {@link MailgunMessageData} ready to be sent via the Mailgun API.
+ * @throws {Error} When `batchSend` is enabled with `cc`/`bcc` set, when the recipient list exceeds {@link MAX_BATCH_SEND_RECIPIENTS}, or when attachments are supplied via both `messageData` and `request.attachments`.
  */
 export declare function convertMailgunTemplateEmailRequestToMailgunMessageData(config: ConvertMailgunTemplateEmailRequestToMailgunMessageDataConfig): MailgunMessageData;
 /**
@@ -179,8 +180,8 @@ export declare function convertMailgunTemplateEmailRequestToMailgunMessageData(c
  *
  * Each recipient is formatted as "Name <email>" when a name is present, or just the email address.
  *
- * @param recipients - the recipients to convert
- * @returns an array of formatted email address strings
+ * @param recipients - Recipients to convert.
+ * @returns Formatted email address strings.
  */
 export declare function convertMailgunRecipientsToStrings(recipients: MailgunRecipient[]): EmailParticipantString[];
 /**
@@ -188,14 +189,15 @@ export declare function convertMailgunRecipientsToStrings(recipients: MailgunRec
  *
  * Returns "Name <email>" when a name is present, or just the email address otherwise.
  *
- * @param recipient - the recipient to convert
- * @returns a formatted email participant string
+ * @param recipient - The recipient to convert.
+ * @returns A formatted email participant string.
  */
 export declare function convertMailgunRecipientToString(recipient: MailgunRecipient): EmailParticipantString;
 /**
  * Encodes a value to a string for use as a Mailgun template variable. Throws an error if the value is not supported.
  *
- * @param value The value to encode.
+ * @param value - The value to encode.
  * @returns The encoded value, or undefined if the value is null or undefined.
+ * @throws {Error} When `value` has an unsupported runtime type.
  */
 export declare function encodeMailgunTemplateVariableValue(value: unknown): Maybe<string>;

package/mailgun/src/lib/mailgun.service.module.d.ts

@@ -6,9 +6,10 @@ import { MailgunServiceConfig } from './mailgun.config';
  *
  * Automatically switches to sandbox credentials when USE_MAILGUN_SANDBOX is true or the environment is a test environment.
  *
- * @param configService - NestJS config service for reading environment variables
- * @param serverEnvironmentService - service indicating the current server environment
- * @returns a validated MailgunServiceConfig
+ * @param configService - NestJS config service for reading environment variables.
+ * @param serverEnvironmentService - Service indicating the current server environment.
+ * @returns A validated MailgunServiceConfig.
+ * @throws {Error} When sandbox mode is requested without sandbox credentials, or when `MAILGUN_SENDER_EMAIL` / `MAILGUN_API_KEY` / `MAILGUN_DOMAIN` are missing.
  */
 export declare function mailgunServiceConfigFactory(configService: ConfigService, serverEnvironmentService: ServerEnvironmentService): MailgunServiceConfig;
 /**

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

@@ -73,8 +73,8 @@ export type MailgunRecipientBatchSendTargetFromReplyToBatchGroupKey = string;
 /**
  * Creates a composite key from the from/replyTo email addresses used to group MailgunRecipientBatchSendTarget values.
  *
- * @param recipient - the batch send target whose from/replyTo addresses are used as the grouping key
- * @returns a string key in the form "f:{fromEmail}|r:{replyToEmail}" used to group recipients into batches
+ * @param recipient - Batch send target whose from/replyTo addresses are used as the grouping key.
+ * @returns Composite key in the form "f:{fromEmail}|r:{replyToEmail}" used to group recipients into batches.
  */
 export declare function mailgunRecipientBatchSendTargetFromReplyToBatchGroupKey(recipient: MailgunRecipientBatchSendTarget): MailgunRecipientBatchSendTargetFromReplyToBatchGroupKey;
 /**
@@ -126,8 +126,9 @@ export type ExpandMailgunRecipientBatchSendTargetRequestFactory = (recipients: M
 /**
  * Creates a ExpandMailgunRecipientBatchSendTargetRequestFactory from the input config.
  *
- * @param config
- * @returns
+ * @param config - Factory configuration providing the base request, recipient lookup, and per-recipient variable handling.
+ * @returns A factory that expands `MailgunRecipientBatchSendTarget` lists into individual `MailgunTemplateEmailRequest` objects.
+ * @throws {Error} When no subject is configured and `useSubjectFromRecipientUserVariables` is false.
  */
 export declare function expandMailgunRecipientBatchSendTargetRequestFactory(config: ExpandMailgunRecipientBatchSendTargetRequestFactoryConfig): ExpandMailgunRecipientBatchSendTargetRequestFactory;
 /**
@@ -165,7 +166,7 @@ export interface MailgunRecipientBatchSendTargetEntityKeyRecipientLookupConfig {
 /**
  * Creates a MailgunRecipientBatchSendTargetEntityKeyRecipientLookup given the input configuration.
  *
- * @param config The configuration for the lookup.
+ * @param config - The configuration for the lookup.
  * @returns The lookup.
  */
 export declare function mailgunRecipientBatchSendTargetEntityKeyRecipientLookup(config: MailgunRecipientBatchSendTargetEntityKeyRecipientLookupConfig): MailgunRecipientBatchSendTargetEntityKeyRecipientLookup;

package/openai/index.cjs.js

@@ -391,8 +391,8 @@ function _ts_generator$2(thisArg, body) {
 /**
  * Verifies an OpenAI webhook event header using the OpenAI client's built-in signature verification.
  *
- * @param config - The verification config containing the OpenAI webhook secret and client.
- * @returns A function that verifies an OpenAI webhook event.
+ * @param config - Verification config containing the OpenAI webhook secret and client.
+ * @returns Verifier function that validates the webhook signature on each request.
  */ function openAIWebhookEventVerifier(config) {
     var secret = config.secret, client = config.client;
     return function(request, _rawBody) {
@@ -908,8 +908,8 @@ function _class_call_check$1(instance, Constructor) {
  *
  * Reads the API key, base URL, organization ID, and project ID from environment variables.
  *
- * @param configService - NestJS config service for reading environment variables
- * @returns a validated OpenAIServiceConfig
+ * @param configService - NestJS config service for reading environment variables.
+ * @returns A validated OpenAIServiceConfig.
  */ function openAIServiceConfigFactory(configService) {
     var _configService_get;
     var config = {
@@ -963,8 +963,8 @@ function _class_call_check(instance, Constructor) {
  *
  * Reads the OpenAI webhook secret token from environment variables.
  *
- * @param configService - NestJS config service for reading environment variables
- * @returns a validated OpenAIWebhookServiceConfig
+ * @param configService - NestJS config service for reading environment variables.
+ * @returns A validated OpenAIWebhookServiceConfig.
  */ function openAIWebhookServiceConfigFactory(configService) {
     var config = {
         openaiWebhook: {
@@ -1017,7 +1017,7 @@ exports.OpenAIWebhookModule = __decorate([
 /**
  * Parses the OpenAI response into a ParsedOpenAIJsonResponse.
  *
- * @param response The OpenAI response to parse.
+ * @param response - The OpenAI response to parse.
  * @returns The parsed OpenAI response.
  */ function parseOpenAIJsonResponse(response) {
     var output_text = typeof response === 'string' ? response : response.output_text;
@@ -1039,8 +1039,8 @@ exports.OpenAIWebhookModule = __decorate([
 /**
  * Creates a map of the OpenAI json response fields.
  *
- * @param response The OpenAI json response to create a map from.
- * @returns The map of the OpenAI json response fields.
+ * @param response - OpenAI json response to index.
+ * @returns Map keyed by field name for direct lookup.
  */ function openAIJsonResponseFieldsMap(response) {
     return new Map(response.fields.map(function(x) {
         return [

package/openai/index.esm.js

@@ -389,8 +389,8 @@ function _ts_generator$2(thisArg, body) {
 /**
  * Verifies an OpenAI webhook event header using the OpenAI client's built-in signature verification.
  *
- * @param config - The verification config containing the OpenAI webhook secret and client.
- * @returns A function that verifies an OpenAI webhook event.
+ * @param config - Verification config containing the OpenAI webhook secret and client.
+ * @returns Verifier function that validates the webhook signature on each request.
  */ function openAIWebhookEventVerifier(config) {
     var secret = config.secret, client = config.client;
     return function(request, _rawBody) {
@@ -906,8 +906,8 @@ function _class_call_check$1(instance, Constructor) {
  *
  * Reads the API key, base URL, organization ID, and project ID from environment variables.
  *
- * @param configService - NestJS config service for reading environment variables
- * @returns a validated OpenAIServiceConfig
+ * @param configService - NestJS config service for reading environment variables.
+ * @returns A validated OpenAIServiceConfig.
  */ function openAIServiceConfigFactory(configService) {
     var _configService_get;
     var config = {
@@ -961,8 +961,8 @@ function _class_call_check(instance, Constructor) {
  *
  * Reads the OpenAI webhook secret token from environment variables.
  *
- * @param configService - NestJS config service for reading environment variables
- * @returns a validated OpenAIWebhookServiceConfig
+ * @param configService - NestJS config service for reading environment variables.
+ * @returns A validated OpenAIWebhookServiceConfig.
  */ function openAIWebhookServiceConfigFactory(configService) {
     var config = {
         openaiWebhook: {
@@ -1015,7 +1015,7 @@ OpenAIWebhookModule = __decorate([
 /**
  * Parses the OpenAI response into a ParsedOpenAIJsonResponse.
  *
- * @param response The OpenAI response to parse.
+ * @param response - The OpenAI response to parse.
  * @returns The parsed OpenAI response.
  */ function parseOpenAIJsonResponse(response) {
     var output_text = typeof response === 'string' ? response : response.output_text;
@@ -1037,8 +1037,8 @@ OpenAIWebhookModule = __decorate([
 /**
  * Creates a map of the OpenAI json response fields.
  *
- * @param response The OpenAI json response to create a map from.
- * @returns The map of the OpenAI json response fields.
+ * @param response - OpenAI json response to index.
+ * @returns Map keyed by field name for direct lookup.
  */ function openAIJsonResponseFieldsMap(response) {
     return new Map(response.fields.map(function(x) {
         return [

package/openai/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/openai",
-  "version": "13.11.13",
+  "version": "13.11.15",
   "peerDependencies": {
-    "@dereekb/date": "13.11.13",
-    "@dereekb/model": "13.11.13",
-    "@dereekb/nestjs": "13.11.13",
-    "@dereekb/rxjs": "13.11.13",
-    "@dereekb/util": "13.11.13",
+    "@dereekb/date": "13.11.15",
+    "@dereekb/model": "13.11.15",
+    "@dereekb/nestjs": "13.11.15",
+    "@dereekb/rxjs": "13.11.15",
+    "@dereekb/util": "13.11.15",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

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

@@ -5,8 +5,8 @@ import { OpenAIServiceConfig } from './openai.config';
  *
  * Reads the API key, base URL, organization ID, and project ID from environment variables.
  *
- * @param configService - NestJS config service for reading environment variables
- * @returns a validated OpenAIServiceConfig
+ * @param configService - NestJS config service for reading environment variables.
+ * @returns A validated OpenAIServiceConfig.
  */
 export declare function openAIServiceConfigFactory(configService: ConfigService): OpenAIServiceConfig;
 /**

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

@@ -52,7 +52,7 @@ export declare function isParsedOpenAIJsonResponseWithJson(response: ParsedOpenA
 /**
  * Parses the OpenAI response into a ParsedOpenAIJsonResponse.
  *
- * @param response The OpenAI response to parse.
+ * @param response - The OpenAI response to parse.
  * @returns The parsed OpenAI response.
  */
 export declare function parseOpenAIJsonResponse(response: string | OpenAI.Responses.Response): ParsedOpenAIJsonResponse;
@@ -63,7 +63,7 @@ export type OpenAIJsonResponseFieldMap = Map<OpenAIJsonResponseFieldName, OpenAI
 /**
  * Creates a map of the OpenAI json response fields.
  *
- * @param response The OpenAI json response to create a map from.
- * @returns The map of the OpenAI json response fields.
+ * @param response - OpenAI json response to index.
+ * @returns Map keyed by field name for direct lookup.
  */
 export declare function openAIJsonResponseFieldsMap(response: OpenAIJsonResponse): OpenAIJsonResponseFieldMap;

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

@@ -5,8 +5,8 @@ import { ConfigService } from '@nestjs/config';
  *
  * Reads the OpenAI webhook secret token from environment variables.
  *
- * @param configService - NestJS config service for reading environment variables
- * @returns a validated OpenAIWebhookServiceConfig
+ * @param configService - NestJS config service for reading environment variables.
+ * @returns A validated OpenAIWebhookServiceConfig.
  */
 export declare function openAIWebhookServiceConfigFactory(configService: ConfigService): OpenAIWebhookServiceConfig;
 /**

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

@@ -30,7 +30,7 @@ export type OpenAIWebhookEventVerifier = (req: Request, rawBody: Buffer) => Prom
 /**
  * Verifies an OpenAI webhook event header using the OpenAI client's built-in signature verification.
  *
- * @param config - The verification config containing the OpenAI webhook secret and client.
- * @returns A function that verifies an OpenAI webhook event.
+ * @param config - Verification config containing the OpenAI webhook secret and client.
+ * @returns Verifier function that validates the webhook signature on each request.
  */
 export declare function openAIWebhookEventVerifier(config: OpenAIWebhookEventVerificationConfig): OpenAIWebhookEventVerifier;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/nestjs",
-  "version": "13.11.13",
+  "version": "13.11.15",
   "types": "./src/index.d.ts",
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
@@ -56,8 +56,8 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/rxjs": "13.11.13",
-    "@dereekb/util": "13.11.13",
+    "@dereekb/rxjs": "13.11.15",
+    "@dereekb/util": "13.11.15",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "@typeform/api-client": "^2.10.2",
@@ -75,8 +75,8 @@
   "devDependencies": {
     "@angular/core": "21.2.11",
     "@nestjs/core": "^11.1.19",
-    "@typescript-eslint/parser": "8.59.0",
-    "eslint": "9.39.4",
+    "@typescript-eslint/parser": "8.59.3",
+    "eslint": "10.4.0",
     "rxjs": "^7.8.2"
   }
 }

package/src/lib/asset/asset.loader.node.d.ts

@@ -18,6 +18,9 @@ export interface NodeJsLocalAssetLoaderConfig {
  * The ref's {@link AssetLocalPathRef.path} is resolved relative
  * to the configured {@link NodeJsLocalAssetLoaderConfig.basePath}.
  *
+ * @param config - Filesystem configuration with base path.
+ * @returns An {@link AssetLoader} backed by the local filesystem.
+ *
  * @example
  * ```ts
  * const loader = nodeJsLocalAssetLoader({ basePath: './assets' });
@@ -25,8 +28,5 @@ export interface NodeJsLocalAssetLoaderConfig {
  *   // reads from ./assets/data/districts.json
  * });
  * ```
- *
- * @param config - Filesystem configuration with base path.
- * @returns An {@link AssetLoader} backed by the local filesystem.
  */
 export declare function nodeJsLocalAssetLoader(config: NodeJsLocalAssetLoaderConfig): AssetLoader;

package/src/lib/asset/asset.nest.d.ts

@@ -24,15 +24,16 @@ export interface AppAssetLoaderModuleMetadataConfig {
  * Local assets are loaded from the filesystem. Remote assets (which always
  * have absolute URLs) are loaded via `fetch`.
  *
- * @example
- * ```ts
- * @Module(appAssetLoaderModuleMetadata({
+ * @param config - Local filesystem config and optional remote fetch config.
+ * @returns NestJS {@link ModuleMetadata} that provides an {@link AssetLoader}.
+ *
+ * @Module (appAssetLoaderModuleMetadata({
  *   local: { basePath: './assets' }
  * }))
  * export class AppAssetLoaderModule {}
  * ```
  *
- * @param config - Local filesystem config and optional remote fetch config.
- * @returns NestJS {@link ModuleMetadata} that provides an {@link AssetLoader}.
+ * @example
+ * ```ts
  */
 export declare function appAssetLoaderModuleMetadata(config: AppAssetLoaderModuleMetadataConfig): ModuleMetadata;

package/src/lib/decorators/local.decorator.d.ts

@@ -8,7 +8,7 @@ export declare const IsRequestFromLocalHost: (...dataOrPipes: unknown[]) => Para
  *
  * 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
+ * @param context - The NestJS execution context containing the HTTP request.
+ * @returns True if the request origin is localhost.
  */
 export declare function isLocalhost(context: ExecutionContext): boolean;

package/src/lib/decorators/rawbody.d.ts

@@ -32,9 +32,9 @@ export declare const ParsedQueryRawBody: (...dataOrPipes: any[]) => ParameterDec
 /**
  * Parses a raw body buffer as JSON.
  *
- * @param rawBody - The raw body buffer to parse
- * @returns The parsed JSON object
- * @throws {SyntaxError} When the body is not valid JSON
+ * @param rawBody - The raw body buffer to parse.
+ * @returns The parsed JSON object.
+ * @throws {SyntaxError} When the body is not valid JSON.
  *
  * @example
  * ```typescript
@@ -45,8 +45,8 @@ export declare function RawBodyToJson<T extends object>(rawBody: RawBodyBuffer):
 /**
  * Parses a raw body buffer as a URL-encoded query string.
  *
- * @param rawBody - The raw body buffer to parse
- * @returns The parsed query parameters
+ * @param rawBody - The raw body buffer to parse.
+ * @returns The parsed query parameters.
  *
  * @example
  * ```typescript
@@ -57,8 +57,8 @@ export declare function RawBodyToParsedQueryString(rawBody: RawBodyBuffer): Pars
 /**
  * Converts a raw body buffer to a trimmed UTF-8 string.
  *
- * @param rawBody - The raw body buffer to convert
- * @returns The decoded and trimmed string content
+ * @param rawBody - The raw body buffer to convert.
+ * @returns The decoded and trimmed string content.
  *
  * @example
  * ```typescript

package/src/lib/module/client/client.config.d.ts

@@ -17,8 +17,8 @@ export declare abstract class ClientAppServiceConfig {
     /**
      * Validates that the configuration contains a non-empty client web app URL.
      *
-     * @param config - The configuration to validate
-     * @throws {Error} When `clientWebAppUrl` is not specified
+     * @param config - The configuration to validate.
+     * @throws {Error} When `clientWebAppUrl` is not specified.
      */
     static assertValidConfig(config: ClientAppServiceConfig): void;
 }

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

@@ -5,8 +5,9 @@ import { ClientAppServiceConfig } from './client.config';
  *
  * 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
+ * @param configService - NestJS config service for reading environment variables.
+ * @returns A validated ClientAppServiceConfig.
+ *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function clientAppConfigFactory(configService: ConfigService): ClientAppServiceConfig;

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

@@ -1,6 +1,6 @@
 /**
  * Checks process.env.NODE_ENV for "test".
  *
- * @returns true if the current Node environment is "test", false otherwise
+ * @returns True if the current Node environment is "test", false otherwise.
  */
 export declare function isTestNodeEnv(): boolean;

package/src/lib/module/env/env.nest.d.ts

@@ -9,7 +9,7 @@ export declare const SERVER_ENV_TOKEN: InjectionToken;
  *
  * 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
+ * @param env - The server environment config to provide.
+ * @returns A NestJS Provider that supplies the config under SERVER_ENV_TOKEN.
  */
 export declare function serverEnvTokenProvider<T extends ServerEnvironmentConfig = ServerEnvironmentConfig>(env: T): Provider;

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

@@ -4,9 +4,9 @@ export type AdditionalModuleMetadata = Partial<ModuleMetadata>;
 /**
  * Merges two module metadata entries together.
  *
- * @param base - the base module metadata
- * @param additional - additional metadata to merge in
- * @returns the merged module metadata
+ * @param base - The base module metadata.
+ * @param additional - Additional metadata to merge in.
+ * @returns The merged module metadata.
  */
 export declare function mergeModuleMetadata(base: ModuleMetadata, additional?: AdditionalModuleMetadata): ModuleMetadata;
 /**
@@ -14,7 +14,7 @@ export declare function mergeModuleMetadata(base: ModuleMetadata, additional?: A
  *
  * 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
+ * @param providers - Providers to extract tokens from.
+ * @returns Injection tokens collected from each provider.
  */
 export declare function injectionTokensFromProviders(providers: ArrayOrValue<Provider<unknown>>): InjectionToken[];

package/src/lib/util/encryption/json.encrypt.d.ts

@@ -6,8 +6,8 @@ export type AES256GCMEncryptionSecret = string;
 /**
  * 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
+ * @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
@@ -29,15 +29,15 @@ export type AES256GCMEncryptionSecretSource = GetterOrValue<AES256GCMEncryptionS
  * The getter is called immediately and the key is validated on creation. The returned
  * function provides the resolved Buffer without re-resolving or re-validating.
  *
+ * @param source - The secret source configuration.
+ * @returns A getter that returns the resolved 32-byte Buffer for AES-256 encryption.
+ * @throws {Error} When the resolved key is not 64 hex characters.
+ *
  * @example
  * ```typescript
  * const getKey = resolveEncryptionKey('a'.repeat(64));
  * const key: Buffer = getKey();
  * ```
- *
- * @param source - The secret source configuration.
- * @returns A getter that returns the resolved 32-byte Buffer for AES-256 encryption.
- * @throws Error if the resolved key is not 64 hex characters.
  */
 export declare function resolveEncryptionKey(source: AES256GCMEncryptionSecretSource): Getter<Buffer>;
 /**
@@ -70,6 +70,10 @@ export interface AES256GCMEncryption {
 /**
  * Creates an `AES256GCMEncryption` instance that captures the resolved key in a closure.
  *
+ * @param source - The hex-encoded secret or getter for the AES-256 key.
+ * @returns An `AES256GCMEncryption` instance.
+ * @throws {Error} When the resolved key is not 64 hex characters.
+ *
  * @example
  * ```typescript
  * const encryption = createAES256GCMEncryption('a'.repeat(64));
@@ -82,9 +86,6 @@ export interface AES256GCMEncryption {
  * // decryptedStr === 'hello'
  * ```
  *
- * @param source - The hex-encoded secret or getter for the AES-256 key.
- * @returns An `AES256GCMEncryption` instance.
- * @throws Error if the resolved key is not 64 hex characters.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function createAES256GCMEncryption(source: AES256GCMEncryptionSecretSource): AES256GCMEncryption;
@@ -93,16 +94,16 @@ export declare function createAES256GCMEncryption(source: AES256GCMEncryptionSec
  *
  * Format: base64(IV (12 bytes) + ciphertext + authTag (16 bytes))
  *
+ * @param value - The value to encrypt (must be JSON-serializable).
+ * @param key - The 32-byte encryption key from `resolveEncryptionKey()`.
+ * @returns The encrypted value as a base64 string.
+ *
  * @example
  * ```typescript
  * const getKey = resolveEncryptionKey(mySecret);
  * const encrypted = encryptValue({ sensitive: 'data' }, getKey());
  * const decrypted = decryptValue<{ sensitive: string }>(encrypted, getKey());
  * ```
- *
- * @param value - The value to encrypt (must be JSON-serializable).
- * @param key - The 32-byte encryption key from `resolveEncryptionKey()`.
- * @returns The encrypted value as a base64 string.
  */
 export declare function encryptValue<T>(value: T, key: Buffer): string;
 /**
@@ -119,6 +120,10 @@ export declare function decryptValue<T>(encoded: string, key: Buffer): T;
  * The key is resolved and validated eagerly at creation time. The provider encrypts/decrypts
  * raw strings (no JSON serialization) — suitable for use with `selectiveFieldEncryptor`.
  *
+ * @param source - The hex-encoded secret or getter for the AES-256 key.
+ * @returns A `StringEncryptionProvider` that encrypts/decrypts strings via AES-256-GCM.
+ * @throws {Error} When the resolved key is not 64 hex characters.
+ *
  * @example
  * ```typescript
  * const provider = createAesStringEncryptionProvider('a'.repeat(64));
@@ -127,9 +132,6 @@ export declare function decryptValue<T>(encoded: string, key: Buffer): T;
  * // decrypted === 'sensitive data'
  * ```
  *
- * @param source - The hex-encoded secret or getter for the AES-256 key.
- * @returns A `StringEncryptionProvider` that encrypts/decrypts strings via AES-256-GCM.
- * @throws Error if the resolved key is not 64 hex characters.
  * @__NO_SIDE_EFFECTS__
  */
 export declare function createAesStringEncryptionProvider(source: AES256GCMEncryptionSecretSource): StringEncryptionProvider;

package/src/lib/util/file/file.json.d.ts

@@ -41,7 +41,7 @@ export interface WriteJsonFileInput {
  * @param input.dirPath - Absolute path to the parent directory; created (recursively) when missing.
  * @param input.data - Value to serialize as JSON (pretty-printed with two-space indentation).
  * @param input.mode - Optional numeric file mode (e.g. `0o600`) applied via `chmod` after the write.
- * @returns A promise that resolves once the JSON has been written and the optional `chmod` has completed.
+ * @returns Resolves once the JSON has been written and the optional `chmod` has completed.
  */
 export declare function writeJsonFile(input: WriteJsonFileInput): Promise<void>;
 /**
@@ -52,6 +52,6 @@ export declare function writeJsonFile(input: WriteJsonFileInput): Promise<void>;
  * swallowing them masks real failures and makes operations appear to have succeeded.
  *
  * @param filePath - Absolute path to the file to remove.
- * @returns A promise that resolves once the file is removed (or was already absent).
+ * @returns Resolves once the file is removed (or was already absent).
  */
 export declare function removeFile(filePath: string): Promise<void>;

package/src/lib/util/pdf/pdf.encryption.d.ts

@@ -30,6 +30,9 @@ export type PdfEncryptionStatus = 'none' | 'write_protected_only' | 'fully_encry
  * Lives in `@dereekb/nestjs` (rather than `@dereekb/util`) because it uses Node's
  * built-in `node:crypto` module, which isn't available in the browser.
  *
+ * @param buffer - PDF file contents.
+ * @returns The encryption status of the PDF.
+ *
  * @example
  * ```ts
  * const status = detectPdfEncryption(buffer);
@@ -41,8 +44,5 @@ export type PdfEncryptionStatus = 'none' | 'write_protected_only' | 'fully_encry
  *   // Safe to read, but not to mutate without the owner password.
  * }
  * ```
- *
- * @param buffer - PDF file contents.
- * @returns The encryption status of the PDF.
  */
 export declare function detectPdfEncryption(buffer: Buffer): PdfEncryptionStatus;