@exyconn/common 2.1.0 → 2.3.2

package/dist/server/configs/index.d.mts

@@ -0,0 +1,602 @@
+import { CorsOptions } from 'cors';
+import { Options, RateLimitRequestHandler } from 'express-rate-limit';
+import { Request } from 'express';
+
+/**
+ * CORS configuration options
+ */
+interface CorsConfig {
+    /** Allowed production origins */
+    productionOrigins?: string[];
+    /** Allowed development origins */
+    developmentOrigins?: string[];
+    /** Subdomain patterns to allow (e.g., '.exyconn.com') */
+    allowedSubdomains?: string[];
+    /** Regex patterns for origin matching */
+    originPatterns?: RegExp[];
+    /** Allow requests with no origin (mobile apps, curl) */
+    allowNoOrigin?: boolean;
+    /** Allow all origins in development */
+    allowAllInDev?: boolean;
+    /** Custom origin validator */
+    customValidator?: (origin: string) => boolean;
+    /** Enable credentials */
+    credentials?: boolean;
+    /** Allowed HTTP methods */
+    methods?: string[];
+    /** Allowed headers */
+    allowedHeaders?: string[];
+    /** Exposed headers */
+    exposedHeaders?: string[];
+    /** Preflight cache duration in seconds */
+    maxAge?: number;
+}
+/**
+ * Default CORS configuration
+ */
+declare const DEFAULT_CORS_CONFIG: Required<Omit<CorsConfig, 'customValidator'>> & {
+    customValidator?: (origin: string) => boolean;
+};
+/**
+ * Create CORS options with custom configuration
+ * @param config - CORS configuration options
+ * @returns Express CORS options object
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with production origins
+ * const cors = createCorsOptions({
+ *   productionOrigins: ['https://example.com'],
+ *   allowedSubdomains: ['.example.com'],
+ * });
+ *
+ * // With custom validator
+ * const cors = createCorsOptions({
+ *   customValidator: (origin) => origin.includes('trusted'),
+ * });
+ * ```
+ */
+declare const createCorsOptions: (config?: CorsConfig) => CorsOptions;
+/**
+ * Create CORS options for a specific project/brand
+ * @param brandDomain - Primary domain (e.g., 'exyconn.com')
+ * @param additionalConfig - Additional configuration
+ */
+declare const createBrandCorsOptions: (brandDomain: string, additionalConfig?: Partial<CorsConfig>) => CorsOptions;
+/**
+ * Create CORS options for multiple projects
+ * @param domains - Array of primary domains
+ * @param additionalConfig - Additional configuration
+ */
+declare const createMultiBrandCorsOptions: (domains: string[], additionalConfig?: Partial<CorsConfig>) => CorsOptions;
+/**
+ * Exyconn preset CORS configuration
+ */
+declare const EXYCONN_CORS_CONFIG: CorsConfig;
+/**
+ * Strict CORS configuration (production only)
+ */
+declare const STRICT_CORS_CONFIG: CorsConfig;
+/**
+ * Permissive CORS configuration (development/testing)
+ */
+declare const PERMISSIVE_CORS_CONFIG: CorsConfig;
+/**
+ * @deprecated Use createCorsOptions() instead
+ */
+declare const corsOptions: CorsOptions;
+
+/**
+ * Rate limit tier configuration
+ */
+interface RateLimitTierConfig {
+    /** Window duration in milliseconds */
+    windowMs: number;
+    /** Maximum requests allowed in window */
+    maxRequests: number;
+    /** Error message to return */
+    message: string;
+    /** Skip successful requests */
+    skipSuccessfulRequests?: boolean;
+    /** Skip failed requests */
+    skipFailedRequests?: boolean;
+}
+/**
+ * Rate limiter configuration options
+ */
+interface RateLimiterConfig {
+    /** Standard tier - general API endpoints */
+    standard?: Partial<RateLimitTierConfig>;
+    /** Strict tier - sensitive endpoints (login, signup) */
+    strict?: Partial<RateLimitTierConfig>;
+    /** DDoS tier - global protection */
+    ddos?: Partial<RateLimitTierConfig>;
+    /** Custom tiers */
+    custom?: Record<string, RateLimitTierConfig>;
+    /** Use standard headers */
+    standardHeaders?: boolean;
+    /** Use legacy headers */
+    legacyHeaders?: boolean;
+    /** Custom key generator */
+    keyGenerator?: (req: Request) => string;
+    /** Skip certain requests */
+    skip?: (req: Request) => boolean;
+    /** Handler for when rate limit is exceeded */
+    handler?: Options['handler'];
+}
+/**
+ * Rate limit response format
+ */
+interface RateLimitResponse {
+    status: string;
+    statusCode: number;
+    message: string;
+    retryAfter?: number;
+}
+/**
+ * Default rate limit tier configurations
+ */
+declare const DEFAULT_RATE_LIMIT_TIERS: {
+    readonly STANDARD: {
+        readonly windowMs: number;
+        readonly maxRequests: 100;
+        readonly message: "Too many requests, please try again later.";
+        readonly skipSuccessfulRequests: false;
+        readonly skipFailedRequests: false;
+    };
+    readonly STRICT: {
+        readonly windowMs: number;
+        readonly maxRequests: 20;
+        readonly message: "Too many requests, please try again later.";
+        readonly skipSuccessfulRequests: false;
+        readonly skipFailedRequests: false;
+    };
+    readonly DDOS: {
+        readonly windowMs: number;
+        readonly maxRequests: 60;
+        readonly message: "Rate limit exceeded. Please slow down.";
+        readonly skipSuccessfulRequests: false;
+        readonly skipFailedRequests: false;
+    };
+    readonly VERY_STRICT: {
+        readonly windowMs: number;
+        readonly maxRequests: 5;
+        readonly message: "Too many attempts. Please try again in an hour.";
+        readonly skipSuccessfulRequests: false;
+        readonly skipFailedRequests: false;
+    };
+    readonly RELAXED: {
+        readonly windowMs: number;
+        readonly maxRequests: 500;
+        readonly message: "Rate limit exceeded.";
+        readonly skipSuccessfulRequests: false;
+        readonly skipFailedRequests: false;
+    };
+    readonly API: {
+        readonly windowMs: number;
+        readonly maxRequests: 30;
+        readonly message: "API rate limit exceeded.";
+        readonly skipSuccessfulRequests: false;
+        readonly skipFailedRequests: false;
+    };
+};
+/**
+ * Default IP-based key generator
+ */
+declare const defaultKeyGenerator: (req: Request) => string;
+/**
+ * Create key generator with custom prefix
+ */
+declare const createPrefixedKeyGenerator: (prefix: string) => (req: Request) => string;
+/**
+ * Create key generator based on user ID (for authenticated routes)
+ */
+declare const createUserKeyGenerator: (getUserId: (req: Request) => string | undefined) => (req: Request) => string;
+/**
+ * Create key generator based on API key
+ */
+declare const createApiKeyGenerator: (headerName?: string) => (req: Request) => string;
+/**
+ * Create a rate limiter with custom configuration
+ * @param tierConfig - Tier configuration
+ * @param options - Additional options
+ * @returns Express rate limit middleware
+ *
+ * @example
+ * ```typescript
+ * // Create custom rate limiter
+ * const apiLimiter = createRateLimiter({
+ *   windowMs: 60 * 1000, // 1 minute
+ *   maxRequests: 30,
+ *   message: 'API rate limit exceeded',
+ * });
+ *
+ * // Use with user-based limiting
+ * const userLimiter = createRateLimiter(
+ *   { windowMs: 60000, maxRequests: 10, message: 'Slow down!' },
+ *   { keyGenerator: createUserKeyGenerator((req) => req.userId) }
+ * );
+ * ```
+ */
+declare const createRateLimiter: (tierConfig: RateLimitTierConfig, options?: Partial<Omit<RateLimiterConfig, "standard" | "strict" | "ddos" | "custom">>) => RateLimitRequestHandler;
+/**
+ * Create standard rate limiter
+ * @param config - Optional custom configuration
+ */
+declare const createStandardRateLimiter: (config?: Partial<RateLimitTierConfig>, options?: Partial<Omit<RateLimiterConfig, "standard" | "strict" | "ddos" | "custom">>) => RateLimitRequestHandler;
+/**
+ * Create strict rate limiter (for sensitive endpoints)
+ * @param config - Optional custom configuration
+ */
+declare const createStrictRateLimiter: (config?: Partial<RateLimitTierConfig>, options?: Partial<Omit<RateLimiterConfig, "standard" | "strict" | "ddos" | "custom">>) => RateLimitRequestHandler;
+/**
+ * Create DDoS protection rate limiter
+ * @param config - Optional custom configuration
+ */
+declare const createDdosRateLimiter: (config?: Partial<RateLimitTierConfig>, options?: Partial<Omit<RateLimiterConfig, "standard" | "strict" | "ddos" | "custom">>) => RateLimitRequestHandler;
+/**
+ * Create API rate limiter
+ * @param config - Optional custom configuration
+ */
+declare const createApiRateLimiter: (config?: Partial<RateLimitTierConfig>, options?: Partial<Omit<RateLimiterConfig, "standard" | "strict" | "ddos" | "custom">>) => RateLimitRequestHandler;
+/**
+ * Rate limiter builder for complex configurations
+ */
+declare class RateLimiterBuilder {
+    private config;
+    private options;
+    constructor(preset?: keyof typeof DEFAULT_RATE_LIMIT_TIERS);
+    /**
+     * Set window duration
+     */
+    windowMs(ms: number): this;
+    /**
+     * Set window duration in minutes
+     */
+    windowMinutes(minutes: number): this;
+    /**
+     * Set window duration in hours
+     */
+    windowHours(hours: number): this;
+    /**
+     * Set maximum requests
+     */
+    max(requests: number): this;
+    /**
+     * Set error message
+     */
+    message(msg: string): this;
+    /**
+     * Skip successful requests
+     */
+    skipSuccessful(skip?: boolean): this;
+    /**
+     * Skip failed requests
+     */
+    skipFailed(skip?: boolean): this;
+    /**
+     * Set key generator
+     */
+    keyBy(generator: (req: Request) => string): this;
+    /**
+     * Key by IP (default)
+     */
+    keyByIp(): this;
+    /**
+     * Key by API key
+     */
+    keyByApiKey(headerName?: string): this;
+    /**
+     * Skip certain requests
+     */
+    skipWhen(predicate: (req: Request) => boolean): this;
+    /**
+     * Build the rate limiter
+     */
+    build(): RateLimitRequestHandler;
+}
+/**
+ * Create a new rate limiter builder
+ */
+declare const rateLimiter: (preset?: keyof typeof DEFAULT_RATE_LIMIT_TIERS) => RateLimiterBuilder;
+/**
+ * @deprecated Use DEFAULT_RATE_LIMIT_TIERS instead
+ */
+declare const RATE_LIMIT_CONFIG: {
+    readonly STANDARD: {
+        readonly windowMs: number;
+        readonly maxRequests: 100;
+        readonly message: "Too many requests, please try again later.";
+        readonly skipSuccessfulRequests: false;
+        readonly skipFailedRequests: false;
+    };
+    readonly STRICT: {
+        readonly windowMs: number;
+        readonly maxRequests: 20;
+        readonly message: "Too many requests, please try again later.";
+        readonly skipSuccessfulRequests: false;
+        readonly skipFailedRequests: false;
+    };
+    readonly DDOS: {
+        readonly windowMs: number;
+        readonly maxRequests: 60;
+        readonly message: "Rate limit exceeded. Please slow down.";
+        readonly skipSuccessfulRequests: false;
+        readonly skipFailedRequests: false;
+    };
+};
+/**
+ * @deprecated Use createStandardRateLimiter() instead
+ */
+declare const standardRateLimiter: RateLimitRequestHandler;
+/**
+ * @deprecated Use createStrictRateLimiter() instead
+ */
+declare const strictRateLimiter: RateLimitRequestHandler;
+/**
+ * @deprecated Use createDdosRateLimiter() instead
+ */
+declare const ddosProtectionLimiter: RateLimitRequestHandler;
+
+/**
+ * Environment type
+ */
+type Environment = 'development' | 'production' | 'test' | 'staging';
+/**
+ * Log level type
+ */
+type LogLevel = 'error' | 'warn' | 'info' | 'http' | 'debug';
+/**
+ * Server configuration interface
+ */
+interface ServerConfig {
+    /** Server name/identifier */
+    name: string;
+    /** Server version */
+    version: string;
+    /** Current environment */
+    environment: Environment;
+    /** Server port */
+    port: number;
+    /** Host binding */
+    host: string;
+    /** Base API path */
+    basePath: string;
+    /** Enable debug mode */
+    debug: boolean;
+    /** Trusted proxy settings */
+    trustProxy: boolean | string | number;
+}
+/**
+ * Database configuration interface
+ */
+interface DatabaseConfig {
+    /** MongoDB connection URI */
+    uri: string;
+    /** Database name */
+    name: string;
+    /** Max connection pool size */
+    maxPoolSize: number;
+    /** Min connection pool size */
+    minPoolSize: number;
+    /** Socket timeout in ms */
+    socketTimeoutMS: number;
+    /** Server selection timeout in ms */
+    serverSelectionTimeoutMS: number;
+    /** Max idle time in ms */
+    maxIdleTimeMS: number;
+    /** Enable retry writes */
+    retryWrites: boolean;
+    /** Enable retry reads */
+    retryReads: boolean;
+    /** Write concern */
+    writeConcern: 'majority' | number;
+}
+/**
+ * JWT/Auth configuration interface
+ */
+interface AuthConfig {
+    /** JWT secret key */
+    jwtSecret: string;
+    /** JWT expiration (e.g., '7d', '24h', '30m') */
+    jwtExpiresIn: string;
+    /** Refresh token expiration */
+    refreshTokenExpiresIn: string;
+    /** Enable refresh tokens */
+    enableRefreshTokens: boolean;
+    /** API key header name */
+    apiKeyHeader: string;
+    /** Organization header name */
+    orgHeader: string;
+}
+/**
+ * Logging configuration interface
+ */
+interface LoggingConfig {
+    /** Log level */
+    level: LogLevel;
+    /** Logs directory */
+    logsDir: string;
+    /** Max log file size */
+    maxSize: string;
+    /** Max days to keep logs */
+    maxFiles: string;
+    /** Max days to keep error logs */
+    errorMaxFiles: string;
+    /** Enable console logging */
+    console: boolean;
+    /** Enable file logging */
+    file: boolean;
+    /** Enable JSON format */
+    json: boolean;
+}
+/**
+ * CORS origins configuration
+ */
+interface CorsOriginsConfig {
+    /** Production domains */
+    production: string[];
+    /** Development domains */
+    development: string[];
+    /** Custom domain patterns (regex strings) */
+    patterns: string[];
+}
+/**
+ * Rate limit tier configuration
+ */
+interface RateLimitTier {
+    /** Window duration in ms */
+    windowMs: number;
+    /** Max requests in window */
+    maxRequests: number;
+    /** Error message */
+    message: string;
+    /** Skip successful requests */
+    skipSuccessfulRequests?: boolean;
+    /** Skip failed requests */
+    skipFailedRequests?: boolean;
+}
+/**
+ * Rate limiting configuration
+ */
+interface RateLimitConfig {
+    /** Enable rate limiting */
+    enabled: boolean;
+    /** Standard tier */
+    standard: RateLimitTier;
+    /** Strict tier (auth endpoints) */
+    strict: RateLimitTier;
+    /** DDoS protection tier */
+    ddos: RateLimitTier;
+    /** Custom tiers */
+    custom?: Record<string, RateLimitTier>;
+}
+/**
+ * Complete application configuration
+ */
+interface AppConfig {
+    server: ServerConfig;
+    database: DatabaseConfig;
+    auth: AuthConfig;
+    logging: LoggingConfig;
+    cors: CorsOriginsConfig;
+    rateLimit: RateLimitConfig;
+    /** Custom configuration */
+    custom?: Record<string, unknown>;
+}
+/**
+ * Default server configuration
+ */
+declare const DEFAULT_SERVER_CONFIG: ServerConfig;
+/**
+ * Default database configuration
+ */
+declare const DEFAULT_DATABASE_CONFIG: DatabaseConfig;
+/**
+ * Default auth configuration
+ */
+declare const DEFAULT_AUTH_CONFIG: AuthConfig;
+/**
+ * Default logging configuration
+ */
+declare const DEFAULT_LOGGING_CONFIG: LoggingConfig;
+/**
+ * Default CORS origins configuration
+ */
+declare const DEFAULT_CORS_ORIGINS: CorsOriginsConfig;
+/**
+ * Default rate limit configuration
+ */
+declare const DEFAULT_RATE_LIMIT_CONFIG: RateLimitConfig;
+/**
+ * Configuration builder for creating project-specific configs
+ */
+declare class ConfigBuilder {
+    private config;
+    constructor();
+    /**
+     * Set server configuration
+     */
+    setServer(config: Partial<ServerConfig>): this;
+    /**
+     * Set database configuration
+     */
+    setDatabase(config: Partial<DatabaseConfig>): this;
+    /**
+     * Set auth configuration
+     */
+    setAuth(config: Partial<AuthConfig>): this;
+    /**
+     * Set logging configuration
+     */
+    setLogging(config: Partial<LoggingConfig>): this;
+    /**
+     * Set CORS origins
+     */
+    setCorsOrigins(config: Partial<CorsOriginsConfig>): this;
+    /**
+     * Add CORS production origin
+     */
+    addProductionOrigin(origin: string): this;
+    /**
+     * Add CORS development origin
+     */
+    addDevelopmentOrigin(origin: string): this;
+    /**
+     * Add CORS pattern
+     */
+    addCorsPattern(pattern: string): this;
+    /**
+     * Set rate limit configuration
+     */
+    setRateLimit(config: Partial<RateLimitConfig>): this;
+    /**
+     * Add custom rate limit tier
+     */
+    addRateLimitTier(name: string, tier: RateLimitTier): this;
+    /**
+     * Set custom configuration
+     */
+    setCustom(key: string, value: unknown): this;
+    /**
+     * Load configuration from environment variables
+     */
+    loadFromEnv(): this;
+    /**
+     * Validate configuration
+     */
+    validate(): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Build the final configuration
+     */
+    build(): AppConfig;
+}
+/**
+ * Create a new configuration builder
+ */
+declare const createConfig: () => ConfigBuilder;
+/**
+ * Create config from partial object
+ */
+declare const buildConfig: (partial?: Partial<AppConfig>) => AppConfig;
+/**
+ * Check if current environment is production
+ */
+declare const isProduction: (config?: ServerConfig) => boolean;
+/**
+ * Check if current environment is development
+ */
+declare const isDevelopment: (config?: ServerConfig) => boolean;
+/**
+ * Check if current environment is test
+ */
+declare const isTest: (config?: ServerConfig) => boolean;
+/**
+ * Get database options for mongoose connect
+ */
+declare const getDatabaseOptions: (config: DatabaseConfig) => Record<string, unknown>;
+
+export { type AppConfig, type AuthConfig, ConfigBuilder, type CorsConfig, type CorsOriginsConfig, DEFAULT_AUTH_CONFIG, DEFAULT_CORS_CONFIG, DEFAULT_CORS_ORIGINS, DEFAULT_DATABASE_CONFIG, DEFAULT_LOGGING_CONFIG, DEFAULT_RATE_LIMIT_CONFIG, DEFAULT_RATE_LIMIT_TIERS, DEFAULT_SERVER_CONFIG, type DatabaseConfig, EXYCONN_CORS_CONFIG, type Environment, type LogLevel, type LoggingConfig, PERMISSIVE_CORS_CONFIG, RATE_LIMIT_CONFIG, type RateLimitConfig, type RateLimitResponse, type RateLimitTier, type RateLimitTierConfig, RateLimiterBuilder, type RateLimiterConfig, STRICT_CORS_CONFIG, type ServerConfig, buildConfig, corsOptions, createApiKeyGenerator, createApiRateLimiter, createBrandCorsOptions, createConfig, createCorsOptions, createDdosRateLimiter, createMultiBrandCorsOptions, createPrefixedKeyGenerator, createRateLimiter, createStandardRateLimiter, createStrictRateLimiter, createUserKeyGenerator, ddosProtectionLimiter, defaultKeyGenerator, getDatabaseOptions, isDevelopment, isProduction, isTest, rateLimiter, standardRateLimiter, strictRateLimiter };