@dereekb/nestjs 13.2.2 → 13.3.0

package/openai/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/nestjs/openai",
-  "version": "13.2.2",
+  "version": "13.3.0",
   "peerDependencies": {
-    "@dereekb/date": "13.2.2",
-    "@dereekb/model": "13.2.2",
-    "@dereekb/nestjs": "13.2.2",
-    "@dereekb/rxjs": "13.2.2",
-    "@dereekb/util": "13.2.2",
+    "@dereekb/date": "13.3.0",
+    "@dereekb/model": "13.3.0",
+    "@dereekb/nestjs": "13.3.0",
+    "@dereekb/rxjs": "13.3.0",
+    "@dereekb/util": "13.3.0",
     "@nestjs/common": "^11.0.0",
     "@nestjs/config": "^4.0.0",
     "express": "^5.0.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/nestjs",
-  "version": "13.2.2",
+  "version": "13.3.0",
   "types": "./src/index.d.ts",
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
@@ -50,7 +50,7 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/util": "13.2.2",
+    "@dereekb/util": "13.3.0",
     "discord.js": "^14.25.1",
     "@nestjs/common": "^11.0.0",
     "@nestjs/config": "^4.0.0",

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

@@ -1,6 +1,6 @@
 import { type ExecutionContext } from '@nestjs/common';
 /**
- * Returns true if the request is from localhost:4200.
+ * Returns true if the request is from localhost.
  */
 export declare const IsRequestFromLocalHost: (...dataOrPipes: unknown[]) => ParameterDecorator;
 export declare function isLocalhost(context: ExecutionContext): boolean;

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

@@ -1,8 +1,81 @@
 import { type ParsedUrlQuery } from 'querystring';
+/**
+ * Buffer type alias representing a raw HTTP request body before any parsing.
+ */
 export type RawBodyBuffer = Buffer;
+/**
+ * NestJS parameter decorator that reads the raw request body directly from the incoming stream.
+ *
+ * Requires the request to still be readable (i.e., no prior body-parsing middleware has consumed it).
+ *
+ * @throws {BadRequestException} When the request stream is not readable
+ *
+ * @example
+ * ```typescript
+ * @Post('webhook')
+ * handleWebhook(@ParseRawBody() body: RawBodyBuffer) { ... }
+ * ```
+ */
 export declare const ParseRawBody: (...dataOrPipes: any[]) => ParameterDecorator;
+/**
+ * NestJS parameter decorator that retrieves the already-parsed raw body buffer from `req.body`.
+ *
+ * Expects that a prior middleware (e.g., raw body middleware) has already set `req.body` to a Buffer.
+ *
+ * @throws {InternalServerErrorException} When `req.body` is not a Buffer
+ *
+ * @example
+ * ```typescript
+ * @Post('webhook')
+ * handleWebhook(@RawBody() body: RawBodyBuffer) { ... }
+ * ```
+ */
 export declare const RawBody: (...dataOrPipes: any[]) => ParameterDecorator;
+/**
+ * NestJS parameter decorator that parses the raw body buffer as a URL-encoded query string
+ * and replaces `req.body` with the parsed result.
+ *
+ * @example
+ * ```typescript
+ * @Post('form')
+ * handleForm(@ParsedQueryRawBody() body: ParsedUrlQuery) { ... }
+ * ```
+ */
 export declare const ParsedQueryRawBody: (...dataOrPipes: any[]) => ParameterDecorator;
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * const data = RawBodyToJson<{ id: string }>(rawBody);
+ * ```
+ */
 export declare function RawBodyToJson<T extends object>(rawBody: RawBodyBuffer): T;
+/**
+ * Parses a raw body buffer as a URL-encoded query string.
+ *
+ * @param rawBody - The raw body buffer to parse
+ * @returns The parsed query parameters
+ *
+ * @example
+ * ```typescript
+ * const params = RawBodyToParsedQueryString(rawBody); // { key: "value" }
+ * ```
+ */
 export declare function RawBodyToParsedQueryString(rawBody: RawBodyBuffer): ParsedUrlQuery;
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * const text = RawBodyToString(rawBody);
+ * ```
+ */
 export declare function RawBodyToString(rawBody: RawBodyBuffer): string;

package/src/lib/index.d.ts

@@ -1,3 +1,4 @@
 export * from './decorators';
 export * from './middlewares';
 export * from './module';
+export * from './util';

package/src/lib/middlewares/json.middleware.d.ts

@@ -1,5 +1,15 @@
 import { type Request, type Response } from 'express';
 import { type NestMiddleware } from '@nestjs/common';
+/**
+ * NestJS middleware that applies JSON body parsing to incoming requests using `body-parser`.
+ *
+ * Useful when the global body parser is disabled and JSON parsing needs to be applied selectively to specific routes.
+ *
+ * @example
+ * ```typescript
+ * consumer.apply(JsonBodyMiddleware).forRoutes('api');
+ * ```
+ */
 export declare class JsonBodyMiddleware implements NestMiddleware {
     use(req: Request, res: Response, next: () => unknown): void;
 }

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

@@ -16,7 +16,7 @@ export declare class ConfigureWebhookMiddlewareModule extends AppModuleWithWebho
     configure(consumer: MiddlewareConsumer): void;
 }
 /**
- * Configures a MiddlewareConsumer to use RawBodyMiddleware for all POST requests to /webhook/*. All other routes are consumed with the JsonBodyMiddleware.
+ * Configures a MiddlewareConsumer to use RawBodyMiddleware for all POST requests to /webhook/{*path}. All other routes are consumed with the JsonBodyMiddleware.
  *
  * This is required for various webhooks that require the full body to properly parse content.
  *

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

@@ -1,8 +1,24 @@
 import { type ClientWebAppUrl } from './client';
+/**
+ * Configuration holding the client-facing web application URL.
+ *
+ * Used by backend services that need to generate links pointing to the frontend (e.g., email templates, redirect URLs).
+ */
 export interface ClientAppConfig {
     readonly clientWebAppUrl: ClientWebAppUrl;
 }
+/**
+ * Abstract service configuration that provides access to the client application config.
+ *
+ * Subclass this to supply environment-specific client URLs to NestJS services.
+ */
 export declare abstract class ClientAppServiceConfig {
     readonly client: ClientAppConfig;
+    /**
+     * 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
+     */
     static assertValidConfig(config: ClientAppServiceConfig): void;
 }

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

@@ -22,4 +22,10 @@ export declare abstract class ServerEnvironmentConfig {
      * This is always false when production is true.
      */
     abstract developerToolsEnabled?: boolean;
+    /**
+     * The primary URL of the application (e.g., 'https://app.example.com').
+     *
+     * Should not end with a trailing slash.
+     */
+    abstract appUrl?: string;
 }

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

@@ -6,4 +6,5 @@ export declare class ServerEnvironmentService {
     get isProduction(): boolean;
     get isStaging(): boolean;
     get developerToolsEnabled(): boolean;
+    get appUrl(): string | undefined;
 }

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

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

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

@@ -0,0 +1,130 @@
+import { type StringEncryptionProvider, type Getter, type GetterOrValue } from '@dereekb/util';
+/**
+ * A hex-encoded secret key for AES-256-GCM encryption. Must be 64 hex characters (32 bytes).
+ */
+export type AES256GCMEncryptionSecret = string;
+/**
+ * Validates that the given secret is a 64-character hexadecimal string (32 bytes for AES-256).
+ *
+ * @example
+ * ```typescript
+ * isValidAES256GCMEncryptionSecret('a'.repeat(64)); // true
+ * isValidAES256GCMEncryptionSecret('too-short');     // false
+ * ```
+ */
+export declare function isValidAES256GCMEncryptionSecret(secret: AES256GCMEncryptionSecret): boolean;
+/**
+ * The source for the encryption secret.
+ *
+ * - If a string, it is used directly as the hex-encoded key (64 hex chars = 32 bytes).
+ * - If a Getter, it is called each time to retrieve the key (useful for rotation or lazy loading).
+ */
+export type AES256GCMEncryptionSecretSource = GetterOrValue<AES256GCMEncryptionSecret>;
+/**
+ * Factory that eagerly resolves and validates the encryption key from a secret source.
+ *
+ * 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.
+ *
+ * @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>;
+/**
+ * Provides AES-256-GCM encryption/decryption for JSON-serializable values.
+ *
+ * The key is captured in the closure at creation time via `createAES256GCMEncryption()`.
+ */
+export interface AES256GCMEncryption {
+    /**
+     * Encrypts a raw string to a base64-encoded ciphertext string.
+     *
+     * Format: base64(IV (12 bytes) + ciphertext + authTag (16 bytes))
+     */
+    encryptString(plaintext: string): string;
+    /**
+     * Decrypts a base64-encoded ciphertext string back to the original plaintext.
+     */
+    decryptString(encoded: string): string;
+    /**
+     * Encrypts a JSON-serializable value to a base64-encoded string.
+     *
+     * The value is JSON.stringified before encryption.
+     */
+    encryptValue<T>(value: T): string;
+    /**
+     * Decrypts a base64-encoded string back to the original JSON-parsed value.
+     */
+    decryptValue<T>(encoded: string): T;
+}
+/**
+ * Creates an `AES256GCMEncryption` instance that captures the resolved key in a closure.
+ *
+ * @example
+ * ```typescript
+ * const encryption = createAES256GCMEncryption('a'.repeat(64));
+ *
+ * const encrypted = encryption.encryptValue({ sensitive: 'data' });
+ * const decrypted = encryption.decryptValue<{ sensitive: string }>(encrypted);
+ *
+ * const encryptedStr = encryption.encryptString('hello');
+ * const decryptedStr = encryption.decryptString(encryptedStr);
+ * // 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.
+ */
+export declare function createAES256GCMEncryption(source: AES256GCMEncryptionSecretSource): AES256GCMEncryption;
+/**
+ * Encrypts a JSON-serializable value to a base64-encoded string using AES-256-GCM.
+ *
+ * Format: base64(IV (12 bytes) + ciphertext + authTag (16 bytes))
+ *
+ * @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;
+/**
+ * Decrypts a base64-encoded string back to the original value.
+ *
+ * @param encoded - The base64-encoded encrypted string (IV + ciphertext + authTag).
+ * @param key - The 32-byte encryption key Buffer from calling the getter returned by `resolveEncryptionKey()`.
+ * @returns The decrypted JSON-parsed value.
+ */
+export declare function decryptValue<T>(encoded: string, key: Buffer): T;
+/**
+ * Creates a `StringEncryptionProvider` backed by AES-256-GCM from a secret source.
+ *
+ * The key is resolved and validated eagerly at creation time. The provider encrypts/decrypts
+ * raw strings (no JSON serialization) — suitable for use with `selectiveFieldEncryptor`.
+ *
+ * @example
+ * ```typescript
+ * const provider = createAesStringEncryptionProvider('a'.repeat(64));
+ * const encrypted = provider.encrypt('sensitive data');
+ * const decrypted = provider.decrypt(encrypted);
+ * // 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.
+ */
+export declare function createAesStringEncryptionProvider(source: AES256GCMEncryptionSecretSource): StringEncryptionProvider;

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

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