@tsdevstack/nest-common 0.1.4

package/dist/auth/utils/parse-header-value.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Parses header value to appropriate JavaScript type.
+ *
+ * Kong forwards all JWT claims as strings. This function intelligently
+ * parses them back to their original types:
+ * - Arrays: "USER,ADMIN" → ["USER", "ADMIN"]
+ * - Numbers: "123" → 123
+ * - Booleans: "true" → true, "false" → false
+ * - Strings: everything else
+ *
+ * @param value - String value from header
+ * @returns Parsed value in appropriate type
+ *
+ * @example Arrays
+ * ```typescript
+ * parseHeaderValue('USER,ADMIN')     // ['USER', 'ADMIN']
+ * parseHeaderValue('read, write, delete') // ['read', 'write', 'delete']
+ * ```
+ *
+ * @example Numbers
+ * ```typescript
+ * parseHeaderValue('123')    // 123
+ * parseHeaderValue('0')      // 0
+ * parseHeaderValue('456789') // 456789
+ * ```
+ *
+ * @example Booleans
+ * ```typescript
+ * parseHeaderValue('true')   // true
+ * parseHeaderValue('false')  // false
+ * ```
+ *
+ * @example Strings
+ * ```typescript
+ * parseHeaderValue('john@example.com') // 'john@example.com'
+ * parseHeaderValue('Hello World')      // 'Hello World'
+ * parseHeaderValue('123abc')           // '123abc' (not pure number)
+ * ```
+ */
+export declare function parseHeaderValue(value: string): string | string[] | number | boolean;

package/dist/auth/utils/parse-header-value.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth/utils/to-camel-case.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Converts kebab-case to camelCase.
+ *
+ * Used to transform Kong header names (which use kebab-case) to
+ * JavaScript property names (which use camelCase).
+ *
+ * @param str - Kebab-case string (e.g., "tenant-id")
+ * @returns CamelCase string (e.g., "tenantId")
+ *
+ * @example
+ * ```typescript
+ * toCamelCase('tenant-id')      // 'tenantId'
+ * toCamelCase('is-verified')    // 'isVerified'
+ * toCamelCase('email')          // 'email'
+ * toCamelCase('user-role-name') // 'userRoleName'
+ * ```
+ */
+export declare function toCamelCase(str: string): string;

package/dist/auth/utils/to-camel-case.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bootstrap/create-app.d.ts

@@ -0,0 +1,31 @@
+import { INestApplication, Type } from "@nestjs/common";
+import { SwaggerConfig } from "../open-api-docs/create-swagger-document";
+interface AppBootstrapOptions {
+    port: number | string;
+    globalPrefix: string;
+    jsonLimit?: number;
+    urlLimit?: number;
+    enableShutdownHooks?: boolean;
+    swagger: SwaggerConfig;
+}
+interface StartAppOptions {
+    swagger?: SwaggerConfig;
+    jsonLimit?: number;
+    urlLimit?: number;
+    enableShutdownHooks?: boolean;
+}
+export declare function createApp<T>(AppModule: Type<T>, options: AppBootstrapOptions): Promise<INestApplication>;
+/**
+ * Load .env file if it exists (local development only)
+ *
+ * In local development, .env file is generated by the CLI and contains SECRETS_PROVIDER.
+ * In cloud/pipelines, platform sets environment variables directly (no .env file needed).
+ *
+ * Skips loading if SECRETS_PROVIDER is already set (cloud/pipeline environments).
+ * Walks up directory tree to find .env (similar to how .secrets.local.json is found).
+ * Silently ignores if .env doesn't exist - that's expected in cloud environments.
+ * Does NOT overwrite existing environment variables (platform vars take precedence).
+ */
+export declare function loadEnvIfExists(): void;
+export declare function startApp<T>(AppModule: Type<T>, options?: StartAppOptions): Promise<void>;
+export {};

package/dist/bootstrap/create-app.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bootstrap/start-worker.d.ts

@@ -0,0 +1,24 @@
+import { Type } from '@nestjs/common';
+interface StartWorkerOptions {
+    healthPort?: number;
+}
+/**
+ * Bootstrap a worker process with standard configuration.
+ *
+ * Handles:
+ * 1. loadEnvIfExists() - loads root .env for SECRETS_PROVIDER
+ * 2. Sets SERVICE_NAME from package.json (required by SecretsModule)
+ * 3. Creates application context with the worker module
+ * 4. Health endpoint on configurable port (default :8080)
+ * 5. Graceful shutdown with 9s timeout
+ * 6. SIGTERM/SIGINT signal handlers
+ *
+ * @example
+ * // apps/auth-service/src/worker.ts
+ * import { startWorker } from '@tsdevstack/nest-common';
+ * import { WorkerModule } from './worker.module';
+ *
+ * startWorker(WorkerModule);
+ */
+export declare function startWorker<T>(WorkerModule: Type<T>, options?: StartWorkerOptions): Promise<void>;
+export {};

package/dist/bootstrap/start-worker.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bull/bull-config.module.d.ts

@@ -0,0 +1,22 @@
+import { type DynamicModule } from '@nestjs/common';
+/**
+ * BullConfigModule
+ *
+ * Configures BullMQ with Redis connection from SecretsService.
+ * Portable across GCP/AWS/Azure/k8s - just needs Redis.
+ *
+ * Usage:
+ * ```typescript
+ * @Module({
+ *   imports: [
+ *     BullConfigModule.forRoot(),
+ *     BullModule.registerQueue({ name: 'email' }),
+ *   ],
+ *   providers: [EmailProcessor],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+export declare class BullConfigModule {
+    static forRoot(): DynamicModule;
+}

package/dist/bull/bull-config.module.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bull/index.d.ts

@@ -0,0 +1 @@
+export { BullConfigModule } from './bull-config.module';

package/dist/config/load-framework-config.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Framework service configuration
+ * Loaded from .tsdevstack/config.json
+ */
+export interface FrameworkServiceConfig {
+    serviceName: string;
+    type: string;
+    port: number;
+    globalPrefix: string;
+    hasDatabase: boolean;
+    databaseType?: string;
+}
+/**
+ * Load framework configuration for a specific service
+ *
+ * This function:
+ * 1. Finds .tsdevstack/config.json by walking up the directory tree
+ * 2. Parses and validates the JSON
+ * 3. Finds the service by name
+ * 4. Returns typed configuration object
+ *
+ * @param serviceName - The name of the service (e.g., 'auth-service')
+ * @returns Service configuration from framework config
+ * @throws Error if config file not found or service not found
+ *
+ * @example
+ * ```typescript
+ * const config = loadFrameworkConfig('auth-service');
+ * // Returns: { serviceName: 'auth-service', port: 3001, ... }
+ * ```
+ */
+export declare function loadFrameworkConfig(serviceName: string): FrameworkServiceConfig;

package/dist/config/load-framework-config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/database/prisma-connection.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Prisma Connection Manager
+ *
+ * Provides connection configuration for Prisma 7 with pg adapter.
+ * Prisma 7's "client" engine requires an adapter - pg Pool is used in all environments.
+ * Production uses DB_POOL_MAX for pool size, development defaults to 5 connections.
+ */
+import { Pool } from 'pg';
+import { PrismaPg } from '@prisma/adapter-pg';
+export interface PrismaConnectionConfig {
+    /** Prisma adapter (required for Prisma 7 client engine) */
+    adapter: PrismaPg;
+}
+export interface PrismaConnectionResult {
+    /** Config to pass to PrismaClient constructor */
+    config: PrismaConnectionConfig;
+    /** Pool instance - call pool.end() on shutdown */
+    pool: Pool;
+}
+/**
+ * Create Prisma connection configuration with pg adapter.
+ *
+ * Prisma 7 with "client" engine requires an adapter, so pg Pool is used
+ * in all environments. Production requires DB_POOL_MAX, development
+ * defaults to 5 connections.
+ *
+ * @returns Configuration object and pool reference for cleanup
+ *
+ * @example
+ * ```typescript
+ * import { createPrismaConnection } from '@tsdevstack/nest-common';
+ * import { PrismaClient } from './generated/prisma';
+ *
+ * const { config, pool } = createPrismaConnection();
+ *
+ * class PrismaService extends PrismaClient {
+ *   constructor() {
+ *     super(config);
+ *   }
+ *
+ *   async onModuleDestroy() {
+ *     await this.$disconnect();
+ *     await pool.end();
+ *   }
+ * }
+ * ```
+ */
+export declare function createPrismaConnection(): PrismaConnectionResult;

package/dist/database/prisma-connection.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/email-rate-limit/email-rate-limit.decorator.d.ts

@@ -0,0 +1,8 @@
+export interface EmailRateLimitOptions {
+    windowMs?: number;
+    maxRequests?: number;
+    message?: string;
+    emailField?: string;
+}
+export declare const EMAIL_RATE_LIMIT_KEY = "emailRateLimit";
+export declare const EmailRateLimitDecorator: (options: EmailRateLimitOptions) => import("@nestjs/common").CustomDecorator<string>;

package/dist/email-rate-limit/email-rate-limit.decorator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/email-rate-limit/email-rate-limit.guard.d.ts

@@ -0,0 +1,11 @@
+import { CanActivate, ExecutionContext } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { RedisService } from "../redis/redis.service";
+export declare class EmailRateLimitGuard implements CanActivate {
+    private readonly redisService;
+    private readonly reflector;
+    private readonly logger;
+    constructor(redisService: RedisService, reflector: Reflector);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    private checkEmailRateLimit;
+}

package/dist/email-rate-limit/email-rate-limit.guard.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/email-rate-limit/email-rate-limit.module.d.ts

@@ -0,0 +1,2 @@
+export declare class EmailRateLimitModule {
+}

package/dist/health/health.controller.d.ts

@@ -0,0 +1,11 @@
+import { HealthService } from './health.service';
+import type { HealthCheckResult } from './health.interface';
+export declare class HealthController {
+    private readonly healthService;
+    constructor(healthService: HealthService);
+    healthCheck(): Promise<HealthCheckResult>;
+    ping(): {
+        message: string;
+        timestamp: string;
+    };
+}

package/dist/health/health.controller.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/health/health.interface.d.ts

@@ -0,0 +1,31 @@
+export interface HealthIndicatorResult {
+    status: 'up' | 'down';
+    details?: Record<string, unknown>;
+}
+export interface HealthCheckResult {
+    status: 'ok' | 'degraded' | 'down';
+    timestamp: string;
+    uptime: number;
+    checks: Record<string, HealthIndicatorResult>;
+    memory: {
+        used: number;
+        total: number;
+    };
+}
+export interface HealthModuleOptions {
+    /**
+     * Enable Redis health indicator
+     * Requires RedisModule to be imported
+     */
+    redis?: boolean;
+    /**
+     * Memory health indicator options
+     */
+    memory?: {
+        /**
+         * Heap threshold in bytes. If exceeded, status becomes 'degraded'
+         * Default: 500MB (500 * 1024 * 1024)
+         */
+        heapThreshold?: number;
+    };
+}

package/dist/health/health.module.d.ts

@@ -0,0 +1,5 @@
+import { DynamicModule } from '@nestjs/common';
+import type { HealthModuleOptions } from './health.interface';
+export declare class HealthModule {
+    static forRoot(options?: HealthModuleOptions): DynamicModule;
+}

package/dist/health/health.service.d.ts

@@ -0,0 +1,12 @@
+import { OnModuleInit } from '@nestjs/common';
+import type { HealthCheckResult, HealthModuleOptions } from './health.interface';
+import { RedisHealthIndicator } from './indicators/redis.indicator';
+import { MemoryHealthIndicator } from './indicators/memory.indicator';
+export declare class HealthService implements OnModuleInit {
+    private readonly options;
+    private readonly redisIndicator?;
+    private readonly memoryIndicator?;
+    constructor(options: HealthModuleOptions, redisIndicator?: RedisHealthIndicator | undefined, memoryIndicator?: MemoryHealthIndicator | undefined);
+    onModuleInit(): void;
+    check(): Promise<HealthCheckResult>;
+}

package/dist/health/health.service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/health/index.d.ts

@@ -0,0 +1,6 @@
+export { HealthModule } from './health.module';
+export { HealthController } from './health.controller';
+export { HealthService } from './health.service';
+export { RedisHealthIndicator } from './indicators/redis.indicator';
+export { MemoryHealthIndicator } from './indicators/memory.indicator';
+export type { HealthModuleOptions, HealthCheckResult, HealthIndicatorResult, } from './health.interface';

package/dist/health/indicators/memory.indicator.d.ts

@@ -0,0 +1,7 @@
+import type { HealthIndicatorResult } from '../health.interface';
+export declare class MemoryHealthIndicator {
+    private heapThreshold;
+    constructor();
+    setThreshold(bytes: number): void;
+    check(): HealthIndicatorResult;
+}

package/dist/health/indicators/memory.indicator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/health/indicators/redis.indicator.d.ts

@@ -0,0 +1,7 @@
+import { RedisService } from '../../redis/redis.service';
+import type { HealthIndicatorResult } from '../health.interface';
+export declare class RedisHealthIndicator {
+    private readonly redisService;
+    constructor(redisService: RedisService);
+    check(): Promise<HealthIndicatorResult>;
+}

package/dist/health/indicators/redis.indicator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+export { AuthModule } from './auth/auth.module';
+export { AuthGuard } from './auth/auth.guard';
+export { Public, IS_PUBLIC_KEY } from './auth/public.decorator';
+export { PartnerApi, IS_PARTNER_API_KEY } from './auth/partner-api.decorator';
+export { Partner } from './auth/partner.decorator';
+export type { KongUser, AuthenticatedRequest } from './auth/auth-user.interface';
+export { KongHeaders } from './auth/auth-user.interface';
+export { RedisModule } from './redis/redis.module';
+export { RedisService } from './redis/redis.service';
+export { RateLimitModule } from './rate-limit/rate-limit.module';
+export { RateLimitGuard } from './rate-limit/rate-limit.guard';
+export { RateLimitDecorator } from './rate-limit/rate-limit.decorator';
+export { RateLimitHeadersInterceptor } from './rate-limit/rate-limit-headers.interceptor';
+export { RateLimitDecorator as RateLimit } from './rate-limit/rate-limit.decorator';
+export { EmailRateLimitModule } from './email-rate-limit/email-rate-limit.module';
+export { EmailRateLimitGuard } from './email-rate-limit/email-rate-limit.guard';
+export { EmailRateLimitDecorator } from './email-rate-limit/email-rate-limit.decorator';
+export { SecretsModule } from './secrets/secrets.module';
+export { SecretsService } from './secrets/secrets.service';
+export type { SecretsProvider, SecretsConfig, SecretsLoadResult } from './secrets/secrets.interface';
+export { BaseServiceClient } from './service-client/base-service-client';
+export type { ServiceClientConfig } from './service-client/base-service-client';
+export { filterForwardHeaders } from './service-client/filter-forward-headers';
+export { startApp, loadEnvIfExists } from './bootstrap/create-app';
+export { startWorker } from './bootstrap/start-worker';
+export { generateSwaggerDocs } from './open-api-docs/generate-swagger-docs';
+export { ObservabilityModule } from './observability/observability.module';
+export type { ObservabilityModuleOptions } from './observability/observability.interface';
+export { LoggerService } from './logging/logger.service';
+export type { LogContext } from './logging/logger.service';
+export { MetricsService } from './metrics/metrics.service';
+export { createPrismaConnection } from './database/prisma-connection';
+export type { PrismaConnectionConfig, PrismaConnectionResult } from './database/prisma-connection';
+export { NotificationModule } from './notifications/notification.module';
+export { NotificationService } from './notifications/notification.service';
+export type { EmailOptions } from './notifications/interfaces/email-options.interface';
+export type { SMSOptions } from './notifications/interfaces/sms-options.interface';
+export type { PushOptions } from './notifications/interfaces/push-options.interface';
+export { BullConfigModule } from './bull/bull-config.module';
+export { SchedulerGuard } from './scheduler/scheduler.guard';