@tsdevstack/nest-common 0.1.4

package/dist/metrics/metrics.service.d.ts

@@ -0,0 +1,79 @@
+import { OnModuleInit } from '@nestjs/common';
+import { type Counter, type Histogram, type UpDownCounter, type Meter } from '@opentelemetry/api';
+import { TelemetryService } from '../telemetry/telemetry.service';
+import type { MetricsModuleOptions } from './metrics.interface';
+export declare class MetricsService implements OnModuleInit {
+    private readonly telemetryService?;
+    private meter;
+    private prefix;
+    private _httpRequestDuration;
+    private _httpRequestTotal;
+    private _httpActiveConnections;
+    constructor(options: MetricsModuleOptions, telemetryService?: TelemetryService | undefined);
+    onModuleInit(): void;
+    /**
+     * Record HTTP request duration
+     */
+    recordHttpRequestDuration(labels: {
+        method: string;
+        route: string;
+        status_code: string;
+    }, duration: number): void;
+    /**
+     * Increment HTTP request total
+     */
+    incrementHttpRequestTotal(labels: {
+        method: string;
+        route: string;
+        status_code: string;
+    }): void;
+    /**
+     * Increment active connections
+     */
+    incrementActiveConnections(): void;
+    /**
+     * Decrement active connections
+     */
+    decrementActiveConnections(): void;
+    /**
+     * Get the meter for creating custom metrics
+     */
+    getMeter(): Meter | undefined;
+    /**
+     * Create a custom counter
+     */
+    createCounter(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): Counter | undefined;
+    /**
+     * Create a custom histogram
+     */
+    createHistogram(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): Histogram | undefined;
+    /**
+     * Create a custom up/down counter (for gauge-like metrics)
+     */
+    createUpDownCounter(name: string, options?: {
+        description?: string;
+        unit?: string;
+    }): UpDownCounter | undefined;
+    /**
+     * Get metrics in Prometheus format (delegated to TelemetryService)
+     */
+    getMetrics(): Promise<string>;
+    /**
+     * Collect metrics in Prometheus format
+     */
+    private collectMetrics;
+    /**
+     * Get content type for Prometheus metrics
+     */
+    getContentType(): string;
+    /**
+     * Get the TelemetryService (for controller access to exporter)
+     */
+    getTelemetryService(): TelemetryService | undefined;
+}

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

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

package/dist/notifications/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Notifications Module
+ *
+ * Provides email (and future SMS/push) notification capabilities.
+ *
+ * @packageDocumentation
+ */
+export { NotificationModule } from './notification.module';
+export { NotificationService, EMAIL_PROVIDER } from './notification.service';
+export type { EmailOptions } from './interfaces/email-options.interface';
+export type { SMSOptions } from './interfaces/sms-options.interface';
+export type { PushOptions } from './interfaces/push-options.interface';
+export type { EmailProvider } from './providers/email-provider.interface';
+export { ConsoleEmailProvider } from './providers/email/console.provider';
+export { ResendEmailProvider } from './providers/email/resend.provider';

package/dist/notifications/interfaces/email-options.interface.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Email Options Interface
+ *
+ * Options for sending an email via NotificationService.sendEmail()
+ */
+export interface EmailOptions {
+    /** Recipient email address(es) */
+    to: string | string[];
+    /** Email subject line */
+    subject: string;
+    /** HTML content of the email */
+    html?: string;
+    /** Plain text content (fallback if html not provided) */
+    text?: string;
+    /** Template name (for future template support) */
+    template?: string;
+    /** Data to pass to template (for future template support) */
+    data?: Record<string, unknown>;
+    /** From address (overrides default) */
+    from?: string;
+    /** Reply-to address */
+    replyTo?: string;
+}

package/dist/notifications/interfaces/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Notification Interfaces
+ */
+export type { EmailOptions } from './email-options.interface';
+export type { SMSOptions } from './sms-options.interface';
+export type { PushOptions } from './push-options.interface';

package/dist/notifications/interfaces/push-options.interface.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Push Notification Options Interface (Stub)
+ *
+ * Options for sending push notifications via NotificationService.sendPush()
+ * Note: Push notification support is not implemented in v1.
+ */
+export interface PushOptions {
+    /** Device tokens to send notification to */
+    tokens: string[];
+    /** Notification title */
+    title: string;
+    /** Notification body */
+    body: string;
+    /** Additional data payload */
+    data?: Record<string, unknown>;
+}

package/dist/notifications/interfaces/sms-options.interface.d.ts

@@ -0,0 +1,12 @@
+/**
+ * SMS Options Interface (Stub)
+ *
+ * Options for sending SMS via NotificationService.sendSMS()
+ * Note: SMS support is not implemented in v1.
+ */
+export interface SMSOptions {
+    /** Recipient phone number */
+    to: string;
+    /** Message body */
+    body: string;
+}

package/dist/notifications/notification.module.d.ts

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

package/dist/notifications/notification.module.test.d.ts

@@ -0,0 +1 @@
+import './notification.module';

package/dist/notifications/notification.service.d.ts

@@ -0,0 +1,28 @@
+import type { EmailOptions } from './interfaces/email-options.interface';
+import type { SMSOptions } from './interfaces/sms-options.interface';
+import type { PushOptions } from './interfaces/push-options.interface';
+import type { EmailProvider } from './providers/email-provider.interface';
+export declare const EMAIL_PROVIDER = "EMAIL_PROVIDER";
+export declare class NotificationService {
+    private readonly emailProvider;
+    constructor(emailProvider: EmailProvider);
+    /**
+     * Send an email
+     * Uses the configured email provider (Console for local, Resend for cloud)
+     */
+    sendEmail(options: EmailOptions): Promise<void>;
+    /**
+     * Send an SMS (not implemented)
+     * @throws Error - SMS not implemented in v1
+     */
+    sendSMS(_options: SMSOptions): Promise<void>;
+    /**
+     * Send a push notification (not implemented)
+     * @throws Error - Push not implemented in v1
+     */
+    sendPush(_options: PushOptions): Promise<void>;
+    /**
+     * Get the current email provider name
+     */
+    getEmailProviderName(): string;
+}

package/dist/notifications/notification.service.test.d.ts

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

package/dist/notifications/providers/email/console.provider.d.ts

@@ -0,0 +1,9 @@
+import type { EmailOptions } from '../../interfaces/email-options.interface';
+import type { EmailProvider } from '../email-provider.interface';
+import { LoggerService } from '../../../logging/logger.service';
+export declare class ConsoleEmailProvider implements EmailProvider {
+    private readonly logger;
+    constructor(logger?: LoggerService);
+    send(options: EmailOptions): Promise<void>;
+    getName(): string;
+}

package/dist/notifications/providers/email/console.provider.test.d.ts

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

package/dist/notifications/providers/email/resend.provider.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Resend Email Provider
+ *
+ * Sends emails via Resend API.
+ * Used for cloud environments (GCP, AWS, Azure).
+ *
+ * Requires secrets:
+ * - RESEND_API_KEY: Your Resend API key
+ * - EMAIL_FROM: Default sender address (optional, defaults to onboarding@resend.dev)
+ */
+import { OnModuleInit } from '@nestjs/common';
+import type { EmailOptions } from '../../interfaces/email-options.interface';
+import type { EmailProvider } from '../email-provider.interface';
+import { SecretsService } from '../../../secrets/secrets.service';
+export declare class ResendEmailProvider implements EmailProvider, OnModuleInit {
+    private readonly secrets;
+    private readonly logger;
+    private client;
+    private defaultFrom;
+    constructor(secrets: SecretsService);
+    onModuleInit(): Promise<void>;
+    send(options: EmailOptions): Promise<void>;
+    getName(): string;
+}

package/dist/notifications/providers/email/resend.provider.test.d.ts

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

package/dist/notifications/providers/email-provider.interface.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Email Provider Interface
+ *
+ * All email providers (Console, Resend) must implement this interface.
+ */
+import type { EmailOptions } from '../interfaces/email-options.interface';
+export interface EmailProvider {
+    /**
+     * Send an email
+     * @param options - Email options (to, subject, html/text, etc.)
+     */
+    send(options: EmailOptions): Promise<void>;
+    /**
+     * Get the provider name (for logging/debugging)
+     */
+    getName(): string;
+}

package/dist/observability/index.d.ts

@@ -0,0 +1,2 @@
+export { ObservabilityModule } from './observability.module';
+export type { ObservabilityModuleOptions } from './observability.interface';

package/dist/observability/observability.interface.d.ts

@@ -0,0 +1,32 @@
+export interface ObservabilityModuleOptions {
+    /**
+     * Enable logging
+     * Default: true
+     */
+    logging?: boolean;
+    /**
+     * Enable metrics collection
+     * Default: true
+     */
+    metrics?: boolean;
+    /**
+     * Enable distributed tracing
+     * Default: true
+     */
+    tracing?: boolean;
+    /**
+     * Enable health endpoints
+     * Default: true
+     */
+    health?: boolean;
+    /**
+     * OTLP base endpoint for tracing (Jaeger, OTEL Collector, etc.)
+     * Default: OTEL_EXPORTER_OTLP_ENDPOINT env var or 'http://localhost:4318'
+     */
+    tracingEndpoint?: string;
+    /**
+     * Service name for telemetry identification
+     * Default: SERVICE_NAME env var
+     */
+    serviceName?: string;
+}

package/dist/observability/observability.module.d.ts

@@ -0,0 +1,24 @@
+import { DynamicModule } from '@nestjs/common';
+import type { ObservabilityModuleOptions } from './observability.interface';
+/**
+ * Unified observability module that provides logging, metrics, tracing, and health.
+ *
+ * Usage:
+ * ```typescript
+ * @Module({
+ *   imports: [ObservabilityModule],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * Or with options:
+ * ```typescript
+ * @Module({
+ *   imports: [ObservabilityModule.forRoot({ tracing: false })],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+export declare class ObservabilityModule {
+    static forRoot(options?: ObservabilityModuleOptions): DynamicModule;
+}

package/dist/observability/observability.module.test.d.ts

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

package/dist/open-api-docs/create-swagger-document.d.ts

@@ -0,0 +1,10 @@
+import { INestApplication } from "@nestjs/common";
+import { OpenAPIObject } from "@nestjs/swagger";
+export interface SwaggerConfig {
+    title: string;
+    description: string;
+    version?: string;
+    tags?: string[];
+    globalPrefix?: string;
+}
+export declare function createSwaggerDocument(app: INestApplication, config: SwaggerConfig): OpenAPIObject;

package/dist/open-api-docs/create-swagger-document.test.d.ts

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

package/dist/open-api-docs/generate-swagger-docs.d.ts

@@ -0,0 +1,12 @@
+import { Type } from '@nestjs/common';
+import { OpenAPIObject } from '@nestjs/swagger';
+/**
+ * Generate Swagger/OpenAPI documentation
+ *
+ * Reads service metadata from package.json automatically.
+ * No validation is performed - validation happens at dev/build time via CLI.
+ *
+ * @param AppModule - The NestJS application module
+ * @returns OpenAPI document object
+ */
+export declare function generateSwaggerDocs<T>(AppModule: Type<T>): Promise<OpenAPIObject>;

package/dist/open-api-docs/generate-swagger-docs.test.d.ts

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

package/dist/rate-limit/rate-limit-headers.interceptor.d.ts

@@ -0,0 +1,5 @@
+import { NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { Observable } from 'rxjs';
+export declare class RateLimitHeadersInterceptor implements NestInterceptor {
+    intercept(context: ExecutionContext, next: CallHandler): Observable<unknown>;
+}

package/dist/rate-limit/rate-limit-headers.interceptor.test.d.ts

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

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

@@ -0,0 +1,11 @@
+import { ExecutionContext } from '@nestjs/common';
+export interface RateLimitOptions {
+    windowMs?: number;
+    maxRequests?: number;
+    keyGenerator?: 'ip' | 'apiKey' | 'userId' | 'custom';
+    customKeyGenerator?: (context: ExecutionContext) => string;
+    skipIf?: (context: ExecutionContext) => boolean;
+    message?: string;
+}
+export declare const RATE_LIMIT_KEY = "rateLimit";
+export declare const RateLimitDecorator: (options: RateLimitOptions) => import("@nestjs/common").CustomDecorator<string>;

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

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

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

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

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

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

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

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

package/dist/redis/redis.module.d.ts

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

package/dist/redis/redis.service.d.ts

@@ -0,0 +1,17 @@
+import { OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import Redis from 'ioredis';
+import { SecretsService } from '../secrets/secrets.service';
+export declare class RedisService implements OnModuleInit, OnModuleDestroy {
+    private readonly secrets;
+    private redis;
+    private readonly logger;
+    constructor(secrets: SecretsService);
+    onModuleInit(): Promise<void>;
+    getClient(): Redis;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<boolean>;
+    incr(key: string): Promise<number | null>;
+    expire(key: string, seconds: number): Promise<boolean>;
+    del(key: string): Promise<boolean>;
+    onModuleDestroy(): void;
+}

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

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

package/dist/scheduler/index.d.ts

@@ -0,0 +1 @@
+export { SchedulerGuard } from './scheduler.guard';

package/dist/scheduler/scheduler.guard.d.ts

@@ -0,0 +1,73 @@
+import { CanActivate, ExecutionContext } from '@nestjs/common';
+import { SecretsService } from '../secrets/secrets.service';
+/**
+ * SchedulerGuard
+ *
+ * Multi-cloud guard for scheduled job endpoints.
+ * Validates that requests come from the cloud scheduler, not external sources.
+ *
+ * Security model:
+ * - GCP: Full OIDC token validation (implemented)
+ * - AWS: EventBridge integration (not yet implemented - fails safe)
+ * - Azure: Logic Apps integration (not yet implemented - fails safe)
+ * - Development/Local: Skips validation for easy local testing
+ *
+ * Combined with @ApiExcludeController(), provides two-layer security:
+ * 1. @ApiExcludeController() keeps routes out of OpenAPI → no Kong route generated
+ * 2. SchedulerGuard validates OIDC token if someone hits endpoint directly
+ *
+ * Usage:
+ * ```typescript
+ * @ApiExcludeController()  // Layer 1: Exclude from Kong
+ * @Controller('jobs')
+ * export class JobsController {
+ *   @Post('cleanup-tokens')
+ *   @UseGuards(SchedulerGuard)  // Layer 2: Validate scheduler token
+ *   async cleanupTokens() {
+ *     // Only accessible from Cloud Scheduler
+ *   }
+ * }
+ * ```
+ *
+ * Local testing:
+ * ```bash
+ * # SECRETS_PROVIDER=local skips validation
+ * curl -X POST http://localhost:3001/jobs/cleanup-tokens
+ * ```
+ */
+export declare class SchedulerGuard implements CanActivate {
+    private readonly secrets;
+    private readonly logger;
+    private readonly oauth2Client;
+    constructor(secrets: SecretsService);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+    /**
+     * Validates AWS EventBridge job invocation via shared secret.
+     *
+     * AWS EventBridge cannot make authenticated HTTP calls directly, so we use
+     * a Job Invoker Lambda that adds the X-Job-Secret header from Secrets Manager.
+     * This validates that header matches the expected secret.
+     *
+     * @param request - HTTP request with X-Job-Secret header
+     * @returns true if secret matches, false otherwise
+     */
+    private validateAwsJobSecret;
+    /**
+     * Validates Azure Container App Job invocation via shared secret.
+     *
+     * Azure Container App Jobs inject the JOB_SECRET env var from Terraform.
+     * The job's curl command sends it as X-Job-Secret header.
+     * This validates that header matches the expected secret from Key Vault.
+     */
+    private validateAzureJobSecret;
+    /**
+     * Validates GCP Cloud Scheduler OIDC token.
+     *
+     * Cloud Scheduler sends requests with an OIDC token in the Authorization header.
+     * We verify the token was issued by Google for our service URL.
+     *
+     * @param request - HTTP request with Authorization header
+     * @returns true if token is valid, false otherwise
+     */
+    private validateGcpOidc;
+}

package/dist/scheduler/scheduler.guard.test.d.ts

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

package/dist/secrets/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Secrets Management Module
+ *
+ * Provides unified secrets management across local development and cloud environments.
+ *
+ * @packageDocumentation
+ */
+export * from './secrets.interface';
+export * from './secrets.service';
+export * from './providers/local.provider';

package/dist/secrets/providers/aws.provider.d.ts

@@ -0,0 +1,56 @@
+import { CloudSecretsProvider, CloudProviderConfig } from './cloud-provider.interface';
+export declare class AWSSecretsProvider implements CloudSecretsProvider {
+    private client;
+    private projectName;
+    private serviceName;
+    private region;
+    private cache;
+    private readonly CACHE_TTL_MS;
+    constructor(config: CloudProviderConfig);
+    /**
+     * Get secret with service-scoped → shared fallback and caching
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set a secret with optional metadata tags
+     */
+    set(key: string, value: string, metadata?: Record<string, string>): Promise<void>;
+    /**
+     * Remove a secret
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * List all secrets for this service (both service-scoped and shared)
+     */
+    list(): Promise<string[]>;
+    /**
+     * Check if a secret exists (checks both service-scoped and shared)
+     */
+    exists(key: string): Promise<boolean>;
+    getProviderName(): string;
+    /**
+     * Build secret name following convention: {projectName}-{scope}-{KEY}
+     */
+    private buildSecretName;
+    /**
+     * Extract key from secret name
+     * Input: "tsdevstack-auth-service-DATABASE_URL" or "tsdevstack-shared-DATABASE_URL"
+     * Output: "DATABASE_URL"
+     */
+    private extractKeyFromSecretName;
+    /**
+     * Fetch secret value from AWS
+     */
+    private fetchSecretFromAWS;
+    /**
+     * Build AWS tags from metadata
+     * AWS supports up to 50 tags per secret
+     */
+    private buildTags;
+    /**
+     * Cache management methods
+     */
+    private getFromCache;
+    private setCache;
+    private invalidateCache;
+}

package/dist/secrets/providers/aws.provider.test.d.ts

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

package/dist/secrets/providers/azure.provider.d.ts

@@ -0,0 +1,70 @@
+import { CloudSecretsProvider, CloudProviderConfig } from './cloud-provider.interface';
+export declare class AzureSecretsProvider implements CloudSecretsProvider {
+    private client;
+    private projectName;
+    private serviceName;
+    private keyVaultName;
+    private cache;
+    private readonly CACHE_TTL_MS;
+    constructor(config: CloudProviderConfig);
+    /**
+     * Get secret with service-scoped → shared fallback and caching
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Set a secret with optional metadata tags
+     */
+    set(key: string, value: string, metadata?: Record<string, string>): Promise<void>;
+    /**
+     * Remove a secret
+     * Note: Azure soft-deletes secrets by default (recoverable for 90 days)
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * List all secrets for this service (both service-scoped and shared)
+     */
+    list(): Promise<string[]>;
+    /**
+     * Check if a secret exists (checks both service-scoped and shared)
+     */
+    exists(key: string): Promise<boolean>;
+    getProviderName(): string;
+    /**
+     * Build secret name following convention: {projectName}-{scope}-{KEY}
+     * Azure Key Vault only allows alphanumeric and hyphens
+     * Transform underscores to hyphens: DATABASE_URL → DATABASE-URL
+     */
+    private buildSecretName;
+    /**
+     * Extract key from secret name and reverse transform
+     * Input: "tsdevstack-auth-service-DATABASE-URL" or "tsdevstack-shared-DATABASE-URL"
+     * Output: "DATABASE_URL"
+     */
+    private extractKeyFromSecretName;
+    /**
+     * Fetch secret value from Azure
+     */
+    private fetchSecretFromAzure;
+    /**
+     * Build Azure tags from metadata
+     * Azure supports up to 15 tags per secret
+     */
+    private buildTags;
+    /**
+     * Transform key to Azure-compatible format
+     * Azure Key Vault only allows alphanumeric and hyphens
+     * DATABASE_URL → DATABASE-URL
+     */
+    private transformKey;
+    /**
+     * Reverse transform Azure key back to standard format
+     * DATABASE-URL → DATABASE_URL
+     */
+    private reverseTransformKey;
+    /**
+     * Cache management methods
+     */
+    private getFromCache;
+    private setCache;
+    private invalidateCache;
+}

package/dist/secrets/providers/azure.provider.test.d.ts

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