@vritti/api-sdk 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -1,3 +1,534 @@
-declare const getHello: () => string;
+import { DynamicModule, OnModuleInit, OnModuleDestroy, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
+import { Observable } from 'rxjs';
 
-export { getHello };
+/**
+ * Primary database connection configuration
+ */
+interface PrimaryDbConfig {
+    /** Database host */
+    host: string;
+    /** Database port (default: 5432) */
+    port?: number;
+    /** Database username */
+    username: string;
+    /** Database password */
+    password: string;
+    /** Database name */
+    database: string;
+    /** Default schema (default: 'public') */
+    schema?: string;
+    /** SSL mode: 'require' | 'prefer' | 'disable' (default: 'require') */
+    sslMode?: 'require' | 'prefer' | 'disable';
+}
+/**
+ * Configuration options for DatabaseModule
+ */
+interface DatabaseModuleOptions {
+    /**
+     * Primary database configuration (for tenant registry queries)
+     * Only required in gateway mode
+     * @example
+     * primaryDb: {
+     *   host: 'aws-pooler.supabase.com',
+     *   port: 5432,
+     *   username: 'postgres.xxx',
+     *   password: 'xxx',
+     *   database: 'postgres',
+     *   schema: 'public',
+     *   sslMode: 'require',
+     * }
+     */
+    primaryDb: PrimaryDbConfig;
+    /**
+     * Primary database client constructor (for querying tenant registry)
+     * Only required in gateway mode
+     * @example import { PrismaClient } from '@prisma/client'
+     */
+    prismaClientConstructor: any;
+    /**
+     * Connection cache TTL in milliseconds
+     * Idle connections will be closed after this period
+     * @default 300000 (5 minutes)
+     */
+    connectionCacheTTL?: number;
+    /**
+     * Maximum number of concurrent connections per tenant
+     * @default 10
+     */
+    maxConnections?: number;
+    /**
+     * Encryption key for decrypting database credentials
+     * Required if tenant config stores encrypted passwords
+     */
+    encryptionKey?: string;
+}
+
+/**
+ * Tenant configuration stored in cloud database
+ * This is the shape of data returned from the tenant registry
+ */
+interface TenantInfo {
+    /** Unique tenant identifier */
+    id: string;
+    /** Human-readable tenant slug */
+    subdomain: string;
+    /** Tenant type */
+    type: 'SHARED' | 'DEDIACTED';
+    /** Tenant status */
+    status: string;
+    /** For CLOUD tenants: schema name */
+    schemaName?: string;
+    /** For ENTERPRISE tenants: database configuration */
+    databaseName?: string;
+    databaseHost?: string;
+    databasePort?: number;
+    databaseUsername?: string;
+    databasePassword?: string;
+    databaseSslMode?: string;
+    connectionPoolSize?: number;
+}
+
+/**
+ * Dynamic module for multi-tenant database management
+ *
+ * This module provides:
+ * - Tenant context management (request-scoped)
+ * - Database connection pooling
+ * - Dynamic schema/cluster routing
+ * - Support for both gateway and microservice modes
+ *
+ * ## Gateway Mode (API Gateway)
+ * - Automatically extracts tenant from subdomain, falls back to x-tenant-id header
+ * - Provide primaryDb configuration and prismaClientConstructor
+ * - Automatically queries primary DB for tenant config
+ * - Attaches TenantContextInterceptor globally
+ *
+ * ## Microservice Mode
+ * - Only provide prismaClientConstructor
+ * - Tenant context comes from RabbitMQ messages
+ * - Use MessageTenantContextInterceptor manually
+ *
+ * @example
+ * // Gateway configuration
+ * DatabaseModule.forRootAsync({
+ *   imports: [ConfigModule],
+ *   useFactory: (config: ConfigService) => ({
+ *     primaryDb: {
+ *       host: config.get('PRIMARY_DB_HOST'),
+ *       port: config.get('PRIMARY_DB_PORT'),
+ *       username: config.get('PRIMARY_DB_USERNAME'),
+ *       password: config.get('PRIMARY_DB_PASSWORD'),
+ *       database: config.get('PRIMARY_DB_DATABASE'),
+ *     },
+ *     prismaClientConstructor: PrismaClient,
+ *   }),
+ *   inject: [ConfigService],
+ * })
+ *
+ * @example
+ * // Microservice configuration
+ * DatabaseModule.forRoot({
+ *   prismaClientConstructor: PrismaClient,
+ * })
+ */
+declare class DatabaseModule {
+    /**
+     * Synchronous configuration
+     *
+     * @param options Module configuration options
+     * @returns Dynamic module configuration
+     */
+    static forRoot(options: DatabaseModuleOptions): DynamicModule;
+    /**
+     * Asynchronous configuration (recommended)
+     *
+     * Allows injecting ConfigService or other dependencies
+     *
+     * @param options Async configuration options
+     * @returns Dynamic module configuration
+     *
+     * @example
+     * DatabaseModule.forRootAsync({
+     *   imports: [ConfigModule],
+     *   useFactory: async (config: ConfigService) => ({
+     *     cloudDatabaseUrl: config.get('CLOUD_DATABASE_URL'),
+     *     prismaClientConstructor: PrismaClient,
+     *     tenantResolver: 'subdomain',
+     *   }),
+     *   inject: [ConfigService],
+     * })
+     */
+    static forRootAsync(options: {
+        useFactory: (...args: any[]) => Promise<DatabaseModuleOptions> | DatabaseModuleOptions;
+        inject?: any[];
+    }): DynamicModule;
+}
+
+/**
+ * Service responsible for querying the primary database to resolve tenant configurations
+ *
+ * This service:
+ * - Connects to the primary database (tenant registry)
+ * - Queries tenant metadata (database location, credentials, etc.)
+ * - Caches tenant configs in memory to reduce database load
+ * - Only used in GATEWAY MODE (microservices receive tenant config from messages)
+ *
+ * @example
+ * // In API Gateway
+ * const config = await primaryDatabase.getTenantConfig('acme');
+ * // Returns: { id, slug, type, databaseHost, databaseName, ... }
+ */
+declare class PrimaryDatabaseService implements OnModuleInit, OnModuleDestroy {
+    private readonly options;
+    private readonly logger;
+    /** Primary database client for querying tenant registry */
+    private primaryDbClient;
+    /** In-memory cache: Map<tenantIdentifier, TenantConfig> */
+    private readonly tenantConfigCache;
+    /** Cache TTL in milliseconds */
+    private readonly cacheTTL;
+    constructor(options: DatabaseModuleOptions);
+    onModuleInit(): Promise<void>;
+    /**
+     * Initialize connection to primary database
+     */
+    private initializePrimaryDbClient;
+    /**
+     * Build connection URL from primary database properties
+     */
+    private buildPrimaryDbUrl;
+    /**
+     * Mask password in connection URL for logging
+     */
+    private maskPassword;
+    /**
+     * Get tenant configuration by identifier (ID or slug)
+     *
+     * @param tenantIdentifier Tenant ID or slug
+     * @returns Tenant configuration or null if not found
+     */
+    getTenantInfo(tenantIdentifier: string): Promise<TenantInfo | null>;
+    /**
+     * Cache tenant information with TTL
+     */
+    private cacheInfo;
+    /**
+     * Clear cached tenant information
+     *
+     * Useful when tenant settings are updated and cache needs to be invalidated
+     *
+     * @param tenantIdentifier Tenant ID or slug
+     */
+    clearTenantCache(tenantIdentifier: string): void;
+    /**
+     * Clear all cached tenant configurations
+     */
+    clearAllCaches(): void;
+    /**
+     * Get primary database client for direct database access
+     *
+     * This is useful for platform admin operations (creating tenants, billing, etc.)
+     *
+     * @returns Primary database client instance
+     * @throws Error if primary database client is not initialized
+     */
+    getPrimaryDbClient<T = any>(): T;
+    /**
+     * Decrypt database credentials
+     *
+     * Override this method to implement your encryption strategy
+     *
+     * @param encrypted Encrypted value
+     * @returns Decrypted value
+     */
+    private decrypt;
+    onModuleDestroy(): Promise<void>;
+}
+
+/**
+ * Request-scoped service that holds tenant context for the current request or RabbitMQ message
+ *
+ * IMPORTANT: This service is REQUEST-SCOPED, meaning NestJS creates a new instance
+ * for each HTTP request or RabbitMQ message. This ensures tenant isolation and
+ * prevents cross-tenant data leaks in concurrent scenarios.
+ *
+ * @example
+ * // In a controller or service
+ * constructor(private readonly tenantContext: TenantContextService) {}
+ *
+ * async handleRequest() {
+ *   const tenant = this.tenantContext.getTenant();
+ *   console.log(`Processing request for tenant: ${tenant.tenantSlug}`);
+ * }
+ */
+declare class TenantContextService {
+    private tenantInfo;
+    /**
+     * Set tenant information for this request/message
+     *
+     * This is typically called by:
+     * - TenantContextInterceptor (for HTTP requests in gateway)
+     * - MessageTenantContextInterceptor (for RabbitMQ messages in microservices)
+     * - Manual context setup in message handlers
+     *
+     * @param tenantInfo Complete tenant information
+     * @throws Error if tenant context is already set (prevents accidental overwrites)
+     */
+    setTenant(tenantInfo: TenantInfo): void;
+    /**
+     * Get tenant information for this request/message
+     *
+     * @returns Tenant information
+     * @throws UnauthorizedException if tenant context hasn't been set
+     */
+    getTenant(): TenantInfo;
+    /**
+     * Check if tenant context has been set
+     *
+     * @returns true if tenant context is available
+     */
+    hasTenant(): boolean;
+    /**
+     * Clear tenant context
+     *
+     * This is useful for cleanup in RabbitMQ message handlers
+     * after the message has been processed.
+     *
+     * HTTP requests don't need manual cleanup as the service
+     * instance is destroyed when the request ends.
+     */
+    clearTenant(): void;
+    /**
+     * Get tenant ID safely (returns null if not set)
+     *
+     * @returns Tenant ID or null
+     */
+    getTenantIdSafe(): string | null;
+    /**
+     * Get tenant subdomain safely (returns null if not set)
+     *
+     * @returns Tenant subdomain or null
+     */
+    getTenantSubdomainSafe(): string | null;
+}
+
+/**
+ * Service responsible for managing tenant-scoped database connections
+ *
+ * This service:
+ * - Maintains a connection pool (Map<cacheKey, DbClient>)
+ * - Creates new connections dynamically based on tenant context
+ * - Reuses existing connections for the same tenant
+ * - Supports both cloud schemas and enterprise databases
+ * - Automatically cleans up idle connections
+ *
+ * @example
+ * // In a controller or service
+ * const dbClient = await this.tenantDatabase.getDbClient<PrismaClient>();
+ * const users = await dbClient.user.findMany();
+ */
+declare class TenantDatabaseService implements OnModuleDestroy {
+    private readonly options;
+    private readonly tenantContext;
+    private readonly logger;
+    /** Connection pool: Map<cacheKey, DbClient> */
+    private readonly clients;
+    /** Track last usage time for idle connection cleanup */
+    private readonly clientLastUsed;
+    /** Cleanup interval timer */
+    private cleanupInterval?;
+    constructor(options: DatabaseModuleOptions, tenantContext: TenantContextService);
+    /**
+     * Get tenant-scoped database client for the current request/message
+     *
+     * This method:
+     * 1. Gets tenant info from TenantContextService
+     * 2. Builds a connection URL based on tenant type
+     * 3. Returns cached client if exists, otherwise creates new one
+     *
+     * @returns Promise<Database client instance>
+     * @throws UnauthorizedException if tenant context not set
+     * @throws InternalServerErrorException if connection fails
+     *
+     * @example
+     * const dbClient = await tenantDatabase.getDbClient<PrismaClient>();
+     * const users = await dbClient.user.findMany();
+     */
+    getDbClient<T = any>(): Promise<T>;
+    /**
+     * Create a new database client for the given tenant
+     */
+    private createDbClient;
+    /**
+     * Build connection URL for enterprise tenant (dedicated database)
+     */
+    private buildTenantDbUrl;
+    /**
+     * Build cache key for connection pooling
+     */
+    private buildCacheKey;
+    /**
+     * Start periodic cleanup of idle connections
+     */
+    private startConnectionCleaner;
+    /**
+     * Clean up idle connections that haven't been used recently
+     */
+    private cleanupIdleConnections;
+    /**
+     * Get current connection pool statistics
+     */
+    getPoolStats(): {
+        activeConnections: number;
+        tenants: string[];
+    };
+    /**
+     * Mask password in connection URL for logging
+     */
+    private maskPassword;
+    onModuleDestroy(): Promise<void>;
+}
+
+/**
+ * Interceptor that extracts tenant context from RabbitMQ messages (Microservice Mode)
+ *
+ * This interceptor:
+ * 1. Extracts tenant info from RabbitMQ message payload
+ * 2. Sets it in REQUEST-SCOPED TenantContextService
+ * 3. Cleans up after message is processed
+ *
+ * Expected message format:
+ * {
+ *   dto: { ... },
+ *   tenant: {
+ *     tenantId: 'abc-123',
+ *     tenantSlug: 'acme',
+ *     tenantType: 'ENTERPRISE',
+ *     databaseHost: 'enterprise-1.aws.com',
+ *     databaseName: 'acme_db',
+ *     ...
+ *   }
+ * }
+ *
+ * @example
+ * // In microservice module
+ * {
+ *   provide: APP_INTERCEPTOR,
+ *   useClass: MessageTenantContextInterceptor,
+ * }
+ */
+declare class MessageTenantContextInterceptor implements NestInterceptor {
+    private readonly tenantContext;
+    private readonly logger;
+    constructor(tenantContext: TenantContextService);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<any>;
+    /**
+     * Clean up tenant context after message is processed
+     */
+    private cleanupContext;
+}
+
+/**
+ * Interceptor that extracts tenant context from HTTP requests (Gateway Mode)
+ *
+ * This interceptor runs BEFORE the controller and:
+ * 1. Extracts tenant identifier from request (tries subdomain first, then falls back to header)
+ * 2. Queries primary database for tenant configuration
+ * 3. Stores tenant info in REQUEST-SCOPED TenantContextService
+ *
+ * Tenant resolution order:
+ * - First: Subdomain (e.g., acme.vritti.com → 'acme')
+ * - Fallback: x-tenant-id or x-tenant-slug header
+ *
+ * Only used in API Gateway. Microservices use MessageTenantContextInterceptor instead.
+ *
+ * @example
+ * // Request: https://acme.vritti.com/api/users
+ * // Interceptor extracts "acme" from subdomain, queries primary DB, sets context
+ */
+declare class TenantContextInterceptor implements NestInterceptor {
+    private readonly tenantContext;
+    private readonly primaryDatabase;
+    private readonly options;
+    private readonly logger;
+    constructor(tenantContext: TenantContextService, primaryDatabase: PrimaryDatabaseService, options: DatabaseModuleOptions);
+    intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<any>>;
+    /**
+     * Extract tenant identifier: tries subdomain first, then falls back to header
+     */
+    private extractTenantIdentifier;
+    /**
+     * Extract tenant from subdomain
+     * @example acme.vritti.com → 'acme'
+     */
+    private extractFromSubdomain;
+    /**
+     * Extract tenant from HTTP headers
+     * Checks x-tenant-id and x-subdomain headers
+     */
+    private extractFromHeader;
+}
+
+/**
+ * Parameter decorator that injects tenant metadata into controller method
+ *
+ * This decorator retrieves tenant information (ID, slug, type, etc.)
+ * from the REQUEST-SCOPED TenantContextService.
+ *
+ * Useful for:
+ * - Logging tenant-specific information
+ * - Implementing tenant-specific business logic
+ * - Auditing and tracking
+ * - Conditional feature flags
+ *
+ * @returns TenantInfo object with tenant metadata
+ *
+ * @example
+ * // Access tenant metadata
+ * @Get('info')
+ * async getTenantInfo(@Tenant() tenant: TenantInfo) {
+ *   return {
+ *     tenantId: tenant.tenantId,
+ *     tenantSlug: tenant.tenantSlug,
+ *     tenantType: tenant.tenantType,
+ *   };
+ * }
+ *
+ * @example
+ * // Use for logging
+ * @Post()
+ * async createUser(
+ *   @Body() dto: CreateUserDto,
+ *   @Tenant() tenant: TenantInfo,
+ * ) {
+ *   this.logger.log(`Creating user for tenant: ${tenant.tenantSlug}`);
+ *   // ...
+ * }
+ *
+ * @example
+ * // Conditional business logic
+ * @Get('features')
+ * async getFeatures(@Tenant() tenant: TenantInfo) {
+ *   if (tenant.tenantType === 'ENTERPRISE') {
+ *     return ['feature-a', 'feature-b', 'feature-c'];
+ *   }
+ *   return ['feature-a'];
+ * }
+ */
+declare const Tenant: (...dataOrPipes: unknown[]) => ParameterDecorator;
+
+/**
+ * Extract subdomain from hostname
+ *
+ * @param host Full hostname (e.g., 'acme.vritti.com:3000' or 'acme.vritti.com')
+ * @returns Subdomain or null if not found
+ *
+ * @example
+ * extractSubdomain('acme.vritti.com') // 'acme'
+ * extractSubdomain('staging-acme.vritti.com') // 'staging-acme'
+ * extractSubdomain('localhost') // null
+ * extractSubdomain('vritti.com') // null
+ */
+declare function extractSubdomain(host: string): string | null;
+
+export { DatabaseModule, type DatabaseModuleOptions, MessageTenantContextInterceptor, PrimaryDatabaseService, type PrimaryDbConfig, Tenant, TenantContextInterceptor, TenantContextService, TenantDatabaseService, type TenantInfo, extractSubdomain };