@plyaz/core 1.1.1 → 1.2.0

package/dist/index.mjs

@@ -1,12 +1,20 @@
-import { CACHE_MAX_SIZE_DEFAULT, CACHE_CLEANUP_INTERVAL_DEFAULT, TIME_CONSTANTS, FORMAT_CONSTANTS, FILE_CHECK_INTERVAL_DEFAULT, FEATURE_FLAG_FILE_PATHS, FEATURE_FLAG_CACHE_TTL_DEFAULT, MATH_CONSTANTS, ISO_STANDARDS, FEATURES, FNV_CONSTANTS, HASH_SEED_CONSTANTS } from '@plyaz/config';
+import { CACHE_MAX_SIZE_DEFAULT, CACHE_CLEANUP_INTERVAL_DEFAULT, TIME_CONSTANTS, FORMAT_CONSTANTS, FILE_CHECK_INTERVAL_DEFAULT, FEATURE_FLAG_FILE_PATHS, FEATURE_FLAG_CACHE_TTL_DEFAULT, FEATURE_FLAG_PROVIDERS, NUMERIC_CONSTANTS, MATH_CONSTANTS, ISO_STANDARDS, FEATURES, DEVELOPMENT_CONFIG, STAGING_CONFIG, PRODUCTION_CONFIG, FNV_CONSTANTS, HASH_SEED_CONSTANTS, HTTP_STATUS as HTTP_STATUS$1 } from '@plyaz/config';
+import { DATABASE_ERROR_CODES, SORT_DIRECTION, FEATURE_FLAG_FIELD, DATABASE_TABLE, FEATURE_FLAG_RULE_FIELD, EVALUATION_REASONS, DATABASE_FIELDS, SYSTEM_USERS, FEATURE_FLAG_TYPES, ERROR_CODES, HTTP_STATUS, NODE_ENVIRONMENTS, FEATURE_FLAG_PROVIDERS as FEATURE_FLAG_PROVIDERS$1, FEATURE_FLAG_DEFAULTS, PACKAGE_STATUS_CODES, API_ERROR_CODES, OPERATIONS, FEATURE_FLAG_METADATA } from '@plyaz/types';
+import { Injectable, Post, Param, Body, Put, Delete, Get, Query, Controller, Logger, Global, Module, SetMetadata } from '@nestjs/common';
+import { of, tap } from 'rxjs';
 import * as fs from 'fs';
 import * as path from 'path';
 import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import * as yaml from 'yaml';
-import { Post, Param, Body, Put, Delete, Get, Query, Controller, Injectable, Global, Module, HttpException, HttpStatus, Logger } from '@nestjs/common';
+import { createDatabaseService } from '@plyaz/db';
+import { DatabaseError, BaseError, ValidationError } from '@plyaz/errors';
+import { ADAPTER_TYPES } from '@plyaz/types/db';
+import { randomUUID } from 'crypto';
+import { catchError } from 'rxjs/operators';
 import React, { createContext, useState, useRef, useCallback, useEffect, useContext, useMemo } from 'react';
-import { jsx } from 'react/jsx-runtime';
+import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
+import { mergeConfigs, createApiClient, ApiPackageError, setDefaultApiClient } from '@plyaz/api';
 
 // @plyaz package - Built with tsup
 var __defProp = Object.defineProperty;
@@ -193,6 +201,10 @@ var ValueUtils = {
     return current;
   }, "getNestedProperty")
 };
+var isString = /* @__PURE__ */ __name((value) => typeof value === "string", "isString");
+var isDefined = /* @__PURE__ */ __name((value) => value !== void 0, "isDefined");
+var isNumber = /* @__PURE__ */ __name((value) => typeof value === "number", "isNumber");
+var getValidProviders = /* @__PURE__ */ __name(() => Object.values(FEATURE_FLAG_PROVIDERS$1), "getValidProviders");
 var FeatureFlagContextBuilder = class _FeatureFlagContextBuilder {
   static {
     __name(this, "FeatureFlagContextBuilder");
@@ -1336,6 +1348,27 @@ var RedisCacheStrategy = class {
     return `${this.keyPrefix}${key}`;
   }
 };
+var Caching = class {
+  // Map to store cached responses keyed by URL + active feature flags
+  cache = /* @__PURE__ */ new Map();
+  intercept(context, next) {
+    const request = context.switchToHttp().getRequest();
+    const flagsKey = JSON.stringify(request.featureFlags ?? {});
+    const cacheKey = `${request.url}|${flagsKey}`;
+    if (this.cache.has(cacheKey)) {
+      return of(this.cache.get(cacheKey));
+    }
+    return next.handle().pipe(
+      tap((response) => {
+        this.cache.set(cacheKey, response);
+      })
+    );
+  }
+};
+__name(Caching, "Caching");
+Caching = __decorateClass([
+  Injectable()
+], Caching);
 
 // src/base/cache/index.ts
 var CacheManager = class {
@@ -2664,212 +2697,1245 @@ Example: "https://api.plyaz.co.uk"`
     };
   }
 };
-
-// src/domain/featureFlags/providers/database.ts
-var DatabaseFeatureFlagProvider = class extends FeatureFlagProvider {
+var DatabaseConnectionManager = class _DatabaseConnectionManager {
   static {
-    __name(this, "DatabaseFeatureFlagProvider");
+    __name(this, "DatabaseConnectionManager");
   }
-  /**
-   * Creates a new database feature flag provider.
-   *
-   * @param config - Provider configuration with database settings
-   * @throws Error indicating that @plyaz/db implementation is required
-   */
-  constructor(config, features) {
-    super(config, features);
-    this.validateConfig();
-    throw new Error("Database provider requires @plyaz/db package implementation");
+  static instance;
+  databaseService = null;
+  constructor() {
   }
   /**
-   * Fetches flags and rules from the database.
-   * Currently throws an error as the database implementation is not ready.
+   * Gets the singleton instance of DatabaseConnectionManager
    *
-   * @protected
-   * @returns Promise that rejects with implementation error
-   * @throws Error indicating missing database implementation
+   * @description Returns the single instance of the connection manager, creating it if it doesn't exist.
+   * This ensures only one database connection pool is maintained across the application.
+   *
+   * @returns {DatabaseConnectionManager} The singleton instance
+   *
+   * @example Getting the Instance
+   * ```typescript
+   * // Always returns the same instance
+   * const manager1 = DatabaseConnectionManager.getInstance();
+   * const manager2 = DatabaseConnectionManager.getInstance();
+   * console.log(manager1 === manager2); // true
+   *
+   * // Use in services
+   * class FeatureFlagRepository {
+   *   private connectionManager = DatabaseConnectionManager.getInstance();
+   *
+   *   async getFlags() {
+   *     const db = this.connectionManager.getDatabase();
+   *     return db.query('feature_flags');
+   *   }
+   * }
+   * ```
    */
-  async fetchData() {
-    throw new Error(
-      'Database Provider is not yet implemented. This requires @plyaz/db package with the following components:\n\nRequired Database Setup:\n1. PostgreSQL or MySQL database\n2. Tables created using provided schema\n3. ORM implementation (Drizzle or Prisma)\n4. Repository pattern for data access\n5. NestJS modules and services\n\nRequired Tables:\n- feature_flags (main flags table)\n- feature_flag_rules (targeting rules table)\n- feature_flag_evaluations (audit log table)\n- feature_flag_overrides (temporary overrides table)\n\nDatabase Schema:\nThe complete schema is provided in:\n/docs/feature-flag-to-implement/database-requirements.md\n\nRequired Implementation Steps:\n1. Install and configure @plyaz/db package\n2. Set up database connection and ORM\n3. Create tables using the provided SQL schema\n4. Implement FeatureFlagsRepository interface\n5. Add NestJS modules, services, and controllers\n6. Set up database migrations\n7. Add comprehensive test coverage\n\nExample Configuration:\n{\n  provider: "database",\n  databaseConfig: {\n    connectionString: "postgresql://user:pass@localhost:5432/plyaz",\n    tableName: "feature_flags"\n  },\n  isCacheEnabled: true,\n  cacheTtl: 300\n}\n\nSee /docs/feature-flag-to-implement/database-requirements.md for complete implementation details.\n\nMigration Note: This provider will be moved to @plyaz/core/src/domain/featureFlags/providers/'
-    );
+  static getInstance() {
+    if (!_DatabaseConnectionManager.instance) {
+      _DatabaseConnectionManager.instance = new _DatabaseConnectionManager();
+    }
+    return _DatabaseConnectionManager.instance;
   }
   /**
-   * Validates the database provider configuration.
+   * Initializes the database connection and registers feature flag tables
    *
-   * @private
-   * @throws Error if configuration is invalid or incomplete
+   * @description Sets up the Supabase connection using environment variables and registers
+   * all feature flag related tables. This method is idempotent - calling it multiple
+   * times won't create additional connections.
+   *
+   * **What it does:**
+   * 1. Validates required environment variables
+   * 2. Creates Supabase database service
+   * 3. Configures caching (5-minute TTL)
+   * 4. Registers feature flag tables with proper ID columns
+   * 5. Disables audit logging (until tables are created)
+   *
+   * @throws {DatabaseError} When environment variables are missing or connection fails
+   *
+   * @example Initialization Process
+   * ```typescript
+   * // Called automatically by FeatureFlagService.onModuleInit()
+   * const manager = DatabaseConnectionManager.getInstance();
+   *
+   * try {
+   *   await manager.initialize();
+   *   console.log('Database connection established');
+   * } catch (error) {
+   *   console.error('Failed to connect to database:', error.message);
+   *   // Error: Missing environment variables for Supabase connection
+   * }
+   * ```
+   *
+   * @example Environment Variable Validation
+   * ```typescript
+   * // If any of these are missing, initialization fails:
+   * // SUPABASE_URL=undefined
+   * // SUPABASE_SERVICE_ROLE_KEY=undefined
+   * // SUPABASE_ANON_PUBLIC_KEY=undefined
+   *
+   * // Throws: DatabaseError with code CONFIG_REQUIRED
+   * ```
+   *
+   * @example Registered Tables
+   * ```typescript
+   * // These tables are automatically registered:
+   * // - feature_flags (ID: key)
+   * // - feature_flag_rules (ID: id)
+   * // - feature_flag_overrides (ID: id)
+   * // - feature_flag_evaluations (ID: id)
+   * ```
    */
-  validateConfig() {
-    this.validateProviderType();
-    this.validateDatabaseConfig();
-    this.validateConnectionString();
-    this.logConfigurationStatus();
-  }
-  validateProviderType() {
-    if (this.config.provider !== "database") {
-      throw new Error('Database provider requires provider to be set to "database"');
+  async initialize() {
+    if (this.databaseService) {
+      return;
     }
-  }
-  validateDatabaseConfig() {
-    if (!this.config.databaseConfig) {
-      throw new Error(
-        'Database configuration is required for database provider. Set databaseConfig in your configuration.\nExample: databaseConfig: { connectionString: "postgresql://...", tableName: "feature_flags" }'
+    const supabaseUrl = process.env.SUPABASE_URL;
+    const supabaseServiceKey = process.env.SUPABASE_SERVICE_ROLE_KEY;
+    const supabaseAnonKey = process.env.SUPABASE_ANON_PUBLIC_KEY;
+    if (!supabaseUrl || !supabaseServiceKey || !supabaseAnonKey) {
+      throw new DatabaseError(
+        "Missing environment variables for Supabase connection. Please check your .env file.",
+        DATABASE_ERROR_CODES.CONFIG_REQUIRED
       );
     }
-  }
-  validateConnectionString() {
-    const { connectionString, tableName } = this.config.databaseConfig;
-    if (!connectionString) {
-      throw new Error(
-        'Database connection string is required. Set connectionString in your databaseConfig.\nExample: connectionString: "postgresql://user:pass@localhost:5432/plyaz"'
+    this.databaseService = await createDatabaseService({
+      adapter: ADAPTER_TYPES.SUPABASE,
+      config: {
+        supabaseUrl,
+        supabaseServiceKey,
+        supabaseAnonKey
+      },
+      // Enable working extensions only
+      audit: {
+        enabled: false,
+        retentionDays: 90
+      },
+      cache: {
+        enabled: true,
+        provider: "memory",
+        ttl: 300
+      },
+      softDelete: {
+        enabled: false,
+        field: "deleted_at"
+      }
+    });
+    const serviceWithAdapter = this.databaseService;
+    if (serviceWithAdapter.adapter?.registerTable) {
+      serviceWithAdapter.adapter.registerTable("feature_flags", "feature_flags", "key");
+      serviceWithAdapter.adapter.registerTable("feature_flag_rules", "feature_flag_rules", "id");
+      serviceWithAdapter.adapter.registerTable(
+        "feature_flag_overrides",
+        "feature_flag_overrides",
+        "id"
       );
-    }
-    if (!this.isValidPostgresUrl(connectionString) && !this.isValidMysqlUrl(connectionString)) {
-      throw new Error(
-        `Database connection string must be a valid PostgreSQL or MySQL URL. Received: ${connectionString}
-Examples:
-- PostgreSQL: "postgresql://user:pass@localhost:5432/plyaz"
-- MySQL: "mysql://user:pass@localhost:3306/plyaz"`
+      serviceWithAdapter.adapter.registerTable(
+        "feature_flag_evaluations",
+        "feature_flag_evaluations",
+        "id"
       );
     }
-    if (!tableName || typeof tableName !== "string") {
-      throw new Error("Database provider requires databaseConfig.tableName");
-    }
-  }
-  logConfigurationStatus() {
-    const { connectionString, tableName } = this.config.databaseConfig;
-    this.log("Database provider configuration is valid, but implementation is not ready");
-    this.log("Connection String:", this.maskConnectionString(connectionString));
-    this.log("Table Name:", tableName ?? "feature_flags (default)");
   }
   /**
-   * Validates PostgreSQL URL format.
+   * Gets the initialized database service instance
    *
-   * @private
-   * @param url - URL to validate
-   * @returns True if valid PostgreSQL URL
-   */
-  isValidPostgresUrl(url) {
-    return url.startsWith("postgresql://") || url.startsWith("postgres://");
-  }
-  /**
-   * Validates MySQL URL format.
+   * @description Returns the database service for performing queries. The database must be
+   * initialized first using initialize() method, otherwise this will throw an error.
    *
-   * @private
-   * @param url - URL to validate
-   * @returns True if valid MySQL URL
+   * @returns {DatabaseServiceInterface} The database service instance
+   * @throws {DatabaseError} When database is not initialized
+   *
+   * @example Basic Usage
+   * ```typescript
+   * const manager = DatabaseConnectionManager.getInstance();
+   * await manager.initialize(); // Must initialize first
+   *
+   * const db = manager.getDatabase();
+   *
+   * // Query feature flags
+   * const result = await db.query('feature_flags', {
+   *   filters: [{ field: 'is_enabled', operator: 'eq', value: true }],
+   *   sort: [{ field: 'key', direction: 'asc' }]
+   * });
+   *
+   * if (result.success) {
+   *   console.log('Found flags:', result.value.data);
+   * }
+   * ```
+   *
+   * @example Error Handling
+   * ```typescript
+   * const manager = DatabaseConnectionManager.getInstance();
+   * // Don't call initialize()
+   *
+   * try {
+   *   const db = manager.getDatabase();
+   * } catch (error) {
+   *   console.error(error.message);
+   *   // "Database not initialized. Call initialize() first."
+   * }
+   * ```
+   *
+   * @example CRUD Operations
+   * ```typescript
+   * const db = manager.getDatabase();
+   *
+   * // Create a flag
+   * const createResult = await db.create('feature_flags', {
+   *   key: 'NEW_FEATURE',
+   *   value: true,
+   *   is_enabled: true
+   * });
+   *
+   * // Update a flag
+   * const updateResult = await db.update('feature_flags', 'NEW_FEATURE', {
+   *   value: false
+   * });
+   *
+   * // Delete a flag
+   * const deleteResult = await db.delete('feature_flags', 'NEW_FEATURE');
+   * ```
    */
-  isValidMysqlUrl(url) {
-    return url.startsWith("mysql://");
+  getDatabase() {
+    if (!this.databaseService) {
+      throw new DatabaseError(
+        "Database not initialized. Call initialize() first.",
+        DATABASE_ERROR_CODES.INIT_FAILED
+      );
+    }
+    return this.databaseService;
   }
   /**
-   * Masks sensitive parts of connection string for logging.
+   * Executes a database transaction with automatic rollback on failure
    *
-   * @private
-   * @param connectionString - Original connection string
-   * @returns Masked connection string
+   * @description Provides atomic database operations by wrapping multiple queries in a transaction.
+   * If any operation fails, all changes are rolled back automatically. This is essential for
+   * maintaining data consistency when creating flags with rules or performing bulk operations.
+   *
+   * @template T The return type of the transaction callback
+   * @param {Function} callback - Function that receives transaction object and performs operations
+   * @returns {Promise<T>} The result of the transaction callback
+   * @throws {DatabaseError} When transaction fails or returns no value
+   *
+   * @example Atomic Flag Creation with Rules
+   * ```typescript
+   * const manager = DatabaseConnectionManager.getInstance();
+   *
+   * const result = await manager.transaction(async (tx) => {
+   *   // Create the flag
+   *   const flag = await tx.create('feature_flags', {
+   *     key: 'PREMIUM_CHECKOUT',
+   *     value: true,
+   *     is_enabled: true,
+   *     description: 'Premium checkout flow'
+   *   });
+   *
+   *   // Create targeting rule
+   *   const rule = await tx.create('feature_flag_rules', {
+   *     flag_key: 'PREMIUM_CHECKOUT',
+   *     name: 'Premium Users Only',
+   *     conditions: [
+   *       { field: 'userRole', operator: 'equals', value: 'premium' },
+   *       { field: 'subscriptionActive', operator: 'equals', value: true }
+   *     ],
+   *     value: true,
+   *     priority: 100
+   *   });
+   *
+   *   return { flag, rule };
+   * });
+   *
+   * console.log('Created flag and rule:', result);
+   * ```
+   *
+   * @example Bulk Flag Updates
+   * ```typescript
+   * const flagsToUpdate = ['FEATURE_A', 'FEATURE_B', 'FEATURE_C'];
+   *
+   * await manager.transaction(async (tx) => {
+   *   for (const flagKey of flagsToUpdate) {
+   *     await tx.update('feature_flags', flagKey, {
+   *       is_enabled: false,
+   *       updated_at: new Date().toISOString()
+   *     });
+   *   }
+   *
+   *   // Log the bulk update
+   *   await tx.create('feature_flag_evaluations', {
+   *     flag_key: 'BULK_UPDATE',
+   *     result: { updatedFlags: flagsToUpdate },
+   *     reason: 'bulk_disable',
+   *     evaluated_at: new Date().toISOString()
+   *   });
+   * });
+   * ```
+   *
+   * @example Error Handling and Rollback
+   * ```typescript
+   * try {
+   *   await manager.transaction(async (tx) => {
+   *     await tx.create('feature_flags', { key: 'TEST_FLAG', value: true });
+   *
+   *     // This will cause the entire transaction to rollback
+   *     throw new Error('Something went wrong');
+   *
+   *     // This won't execute, and the flag creation above will be rolled back
+   *     await tx.create('feature_flag_rules', { flag_key: 'TEST_FLAG' });
+   *   });
+   * } catch (error) {
+   *   console.log('Transaction failed, all changes rolled back');
+   * }
+   * ```
    */
-  maskConnectionString(connectionString) {
-    try {
-      const url = new URL(connectionString);
-      const masked = `${url.protocol}//${url.username}:****@${url.host}${url.pathname}`;
-      return masked;
-    } catch {
-      return "[INVALID_URL]";
+  async transaction(callback) {
+    const db = this.getDatabase();
+    const result = await db.transaction(callback);
+    if (!result.success) {
+      const errorMessage = result.error?.message ?? "Transaction failed";
+      throw new DatabaseError(errorMessage, DATABASE_ERROR_CODES.TRANSACTION_FAILED);
     }
+    if (result.value === void 0 || result.value === null) {
+      throw new DatabaseError("Transaction returned no value", DATABASE_ERROR_CODES.INVALID_RESULT);
+    }
+    return result.value;
   }
   /**
-   * Gets database provider status and configuration info.
+   * Closes the database connection and cleans up resources
    *
-   * @returns Database provider status information
+   * @description Properly closes the database connection and resets the singleton instance.
+   * This is typically called during application shutdown or in tests that need to reset
+   * the connection state.
+   *
+   * @example Application Shutdown
+   * ```typescript
+   * // In your NestJS module's onModuleDestroy
+   * export class FeatureFlagModule implements OnModuleDestroy {
+   *   async onModuleDestroy() {
+   *     const manager = DatabaseConnectionManager.getInstance();
+   *     await manager.close();
+   *     console.log('Database connection closed');
+   *   }
+   * }
+   * ```
+   *
+   * @example Test Cleanup
+   * ```typescript
+   * describe('Feature Flag Tests', () => {
+   *   afterEach(async () => {
+   *     // Clean up connection between tests
+   *     const manager = DatabaseConnectionManager.getInstance();
+   *     await manager.close();
+   *   });
+   * });
+   * ```
    */
-  getDatabaseInfo() {
-    return {
-      connectionString: this.config.databaseConfig?.connectionString ? this.maskConnectionString(this.config.databaseConfig.connectionString) : void 0,
-      tableName: this.config.databaseConfig?.tableName ?? "feature_flags",
-      isImplemented: false,
-      requiredPackages: ["@plyaz/db"],
-      recommendedORM: ["drizzle-orm", "prisma"],
-      documentationPath: "/docs/feature-flag-to-implement/database-requirements.md",
-      schemaPath: "/docs/feature-flag-to-implement/database-requirements.md#database-schema"
-    };
+  async close() {
+    this.databaseService = null;
   }
 };
-var PROVIDER_REGISTRY = {
-  memory: MemoryFeatureFlagProvider,
-  file: FileFeatureFlagProvider,
-  redis: RedisFeatureFlagProvider,
-  api: ApiFeatureFlagProvider,
-  database: DatabaseFeatureFlagProvider
-};
-var FeatureFlagProviderFactory = class {
+var FeatureFlagDatabaseRepository = class {
   static {
-    __name(this, "FeatureFlagProviderFactory");
+    __name(this, "FeatureFlagDatabaseRepository");
   }
+  connectionManager = DatabaseConnectionManager.getInstance();
   /**
-   * Creates a new feature flag provider instance based on configuration.
+   * Retrieves all feature flags from the database with optional environment filtering
+   *
+   * @description Fetches all feature flags from the database. This method is primarily called
+   * during system initialization to load flags into cache, but can also be used for
+   * administrative purposes or cache refresh operations.
+   *
+   * @param {string} [environment] - Optional environment filter (e.g., 'production', 'staging')
+   * @returns {Promise<FeatureFlag<TKey>[]>} Array of feature flags matching the criteria
+   *
+   * @throws {Error} When database query fails critically
+   *
+   * @example
+   * ```typescript
+   * // Get all flags for system initialization
+   * const repository = new FeatureFlagDatabaseRepository();
+   * const allFlags = await repository.getAllFlags();
+   * console.log(`Loaded ${allFlags.length} feature flags`);
+   *
+   * // Get only production flags
+   * const prodFlags = await repository.getAllFlags('production');
+   * console.log(`Production flags: ${prodFlags.length}`);
+   *
+   * // Handle empty results
+   * const flags = await repository.getAllFlags('nonexistent');
+   * if (flags.length === 0) {
+   *   console.log('No flags found for environment');
+   * }
+   * ```
    *
-   * @param config - Provider configuration
-   * @param features - Record of feature flag keys to their default values
-   * @returns Configured provider instance
-   * @throws Error if provider type is unsupported or configuration is invalid
    */
-  static create(config, features) {
-    this.validateConfig(config);
-    const ProviderClass = PROVIDER_REGISTRY[config.provider];
-    if (!ProviderClass) {
-      throw new Error(
-        `Unsupported provider type: ${config.provider}. Supported types: ${this.getSupportedProviders().join(", ")}`
-      );
-    }
-    try {
-      return new ProviderClass(config, features);
-    } catch (error) {
-      throw new Error(
-        `Failed to create ${config.provider} provider: ${error instanceof Error ? error.message : "Unknown error"}`
-      );
+  async getAllFlags(environment) {
+    const db = this.connectionManager.getDatabase();
+    const options = {
+      sort: [
+        {
+          field: FEATURE_FLAG_FIELD.Key,
+          direction: SORT_DIRECTION.Asc
+        }
+      ],
+      pagination: { page: 1, limit: 1e3 }
+    };
+    const result = await db.query(DATABASE_TABLE.FeatureFlags, options);
+    if (!result.success) {
+      console.warn("Query failed, returning empty array:", result.error?.message);
+      return [];
+    }
+    let flags = result.value?.data ?? [];
+    if (environment) {
+      flags = flags.filter((flag) => {
+        return Boolean(flag.environments?.includes(environment));
+      });
     }
+    return flags.map((flag) => this.mapToFeatureFlag(flag));
   }
   /**
-   * Creates a provider with automatic initialization.
+   * Retrieves a specific feature flag by its key
+   *
+   * @description Fetches a single feature flag from the database using its unique key.
+   * This method is optimized for runtime flag evaluation and uses the primary key index
+   * for O(1) lookup performance.
+   *
+   * @param {TKey} key - The unique identifier of the feature flag to retrieve
+   * @returns {Promise<FeatureFlag<TKey> | null>} The feature flag object or null if not found
+   *
+   * @throws {Error} When database operation fails
+   *
+   * @example
+   * ```typescript
+   * const repository = new FeatureFlagDatabaseRepository();
+   *
+   * // Get a specific flag for evaluation
+   * const premiumFlag = await repository.getFlag('PREMIUM_FEATURE');
+   * if (premiumFlag) {
+   *   console.log(`Flag enabled: ${premiumFlag.isEnabled}`);
+   *   console.log(`Flag value:`, premiumFlag.value);
+   * } else {
+   *   console.log('Flag not found');
+   * }
+   *
+   * // Handle flag evaluation
+   * const checkoutFlag = await repository.getFlag('NEW_CHECKOUT');
+   * const isNewCheckoutEnabled = checkoutFlag?.isEnabled ?? false;
+   * ```
    *
-   * @param config - Provider configuration
-   * @param features - Record of feature flag keys to their default values
-   * @returns Promise resolving to initialized provider instance
    */
-  static async createAndInitialize(config, features) {
-    const provider = this.create(config, features);
-    await provider.initialize();
-    return provider;
+  async getFlag(key) {
+    const db = this.connectionManager.getDatabase();
+    const result = await db.get(DATABASE_TABLE.FeatureFlags, key);
+    if (!result.success) {
+      throw new DatabaseError(
+        `Failed to get flag: ${result.error?.message}`,
+        DATABASE_ERROR_CODES.NO_DATA
+      );
+    }
+    return result.value ? this.mapToFeatureFlag(result.value) : null;
   }
   /**
-   * Gets a list of all supported provider types.
+   * Creates a new feature flag in the database
+   *
+   * @description Creates a new feature flag record with the provided configuration.
+   * This method is typically called through administrative interfaces or during
+   * system setup and migration processes.
+   *
+   * @param {CreateFlagRequest<TKey>} data - The feature flag creation data
+   * @returns {Promise<FeatureFlag<TKey>>} The created feature flag object
+   *
+   * @throws {Error} When flag key already exists (primary key constraint violation)
+   * @throws {Error} When database operation fails
+   *
+   * @example
+   * ```typescript
+   * const repository = new FeatureFlagDatabaseRepository();
+   *
+   * // Create a simple boolean flag
+   * const simpleFlag = await repository.createFlag({
+   *   key: 'ENABLE_DARK_MODE',
+   *   value: true,
+   *   isEnabled: true,
+   *   environment: 'production',
+   *   description: 'Enable dark mode theme'
+   * });
+   *
+   * // Create a complex flag with object value
+   * const complexFlag = await repository.createFlag({
+   *   key: 'CHECKOUT_CONFIG',
+   *   value: {
+   *     variant: 'blue',
+   *     showPromo: true,
+   *     maxItems: 10
+   *   },
+   *   isEnabled: false,
+   *   environment: 'staging',
+   *   description: 'Checkout page configuration'
+   * });
+   *
+   * console.log(`Created flag: ${simpleFlag.key}`);
+   * ```
    *
-   * @returns Array of supported provider names
    */
-  static getSupportedProviders() {
-    return Object.keys(PROVIDER_REGISTRY);
+  async createFlag(data) {
+    const db = this.connectionManager.getDatabase();
+    const flagData = {
+      [FEATURE_FLAG_FIELD.Key]: data.key,
+      [FEATURE_FLAG_FIELD.Value]: data.value,
+      [FEATURE_FLAG_FIELD.IsEnabled]: data.isEnabled ?? true,
+      [FEATURE_FLAG_FIELD.Environments]: data.environment ? [data.environment] : void 0,
+      [FEATURE_FLAG_FIELD.Description]: data.description,
+      [FEATURE_FLAG_FIELD.UpdatedAt]: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const result = await db.create(DATABASE_TABLE.FeatureFlags, flagData);
+    if (!result.success || !result.value) {
+      throw new DatabaseError(
+        `Failed to create flag: ${result.error?.message}`,
+        DATABASE_ERROR_CODES.CREATE_FAILED
+      );
+    }
+    return this.mapToFeatureFlag(result.value);
   }
   /**
-   * Checks if a provider type is supported.
+   * Updates an existing feature flag in the database
+   *
+   * @description Updates specific fields of an existing feature flag. Only provided
+   * fields will be updated, leaving other fields unchanged. The updated_at timestamp
+   * is automatically set to the current time.
+   *
+   * @param {TKey} key - The unique identifier of the feature flag to update
+   * @param {Partial<CreateFlagRequest<TKey>>} data - Partial flag data to update
+   * @returns {Promise<FeatureFlag<TKey>>} The updated feature flag object
+   *
+   * @throws {Error} When flag with the specified key is not found
+   * @throws {Error} When database operation fails
+   *
+   * @example
+   * ```typescript
+   * const repository = new FeatureFlagDatabaseRepository();
+   *
+   * // Enable a flag
+   * const enabledFlag = await repository.updateFlag('BETA_FEATURE', {
+   *   isEnabled: true
+   * });
+   *
+   * // Update flag value and description
+   * const updatedFlag = await repository.updateFlag('CHECKOUT_CONFIG', {
+   *   value: { variant: 'green', showPromo: false },
+   *   description: 'Updated checkout configuration'
+   * });
+   *
+   * // Change environment
+   * const prodFlag = await repository.updateFlag('NEW_FEATURE', {
+   *   environment: 'production'
+   * });
+   *
+   * console.log(`Updated flag: ${updatedFlag.key}`);
+   * ```
    *
-   * @param providerType - Provider type to check
-   * @returns True if provider type is supported
    */
-  static isProviderSupported(providerType) {
-    return providerType in PROVIDER_REGISTRY;
+  async updateFlag(key, data) {
+    const db = this.connectionManager.getDatabase();
+    const updateData = {
+      ...data,
+      [FEATURE_FLAG_FIELD.UpdatedAt]: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const result = await db.update(DATABASE_TABLE.FeatureFlags, key, updateData);
+    if (!result.success || !result.value) {
+      throw new DatabaseError(
+        `Failed to update flag: ${result.error?.message}`,
+        DATABASE_ERROR_CODES.UPDATE_FAILED
+      );
+    }
+    return this.mapToFeatureFlag(result.value);
   }
   /**
-   * Gets provider information including implementation status.
+   * Deletes a feature flag from the database
    *
-   * @returns Record of provider information
-   */
-  static getProvidersInfo() {
-    return {
-      memory: {
-        name: "Memory Provider",
-        isImplemented: true,
+   * @description Permanently removes a feature flag from the database. This operation
+   * cannot be undone. All associated rules, evaluations, and overrides should be
+   * cleaned up separately if needed.
+   *
+   * @param {TKey} key - The unique identifier of the feature flag to delete
+   * @returns {Promise<void>} Promise that resolves when deletion is complete
+   *
+   * @throws {Error} When flag with the specified key is not found
+   * @throws {Error} When database operation fails
+   *
+   * @example
+   * ```typescript
+   * const repository = new FeatureFlagDatabaseRepository();
+   *
+   * // Delete a flag
+   * try {
+   *   await repository.deleteFlag('OLD_FEATURE');
+   *   console.log('Flag deleted successfully');
+   * } catch (error) {
+   *   console.error('Failed to delete flag:', error.message);
+   * }
+   *
+   * // Verify deletion
+   * const deletedFlag = await repository.getFlag('OLD_FEATURE');
+   * console.log(deletedFlag === null); // true
+   * ```
+   *
+   */
+  async deleteFlag(key) {
+    const db = this.connectionManager.getDatabase();
+    const result = await db.delete(DATABASE_TABLE.FeatureFlags, key);
+    if (!result.success) {
+      throw new DatabaseError(
+        `Failed to delete flag: ${result.error?.message}`,
+        DATABASE_ERROR_CODES.DELETE_FAILED
+      );
+    }
+  }
+  /**
+   * Retrieves all rules associated with a specific feature flag
+   *
+   * @description Fetches all rules configured for a specific feature flag, ordered by
+   * priority in descending order. Rules are used for advanced flag evaluation logic
+   * based on user context and conditions.
+   *
+   * @param {TKey} key - The feature flag key to get rules for
+   * @returns {Promise<FeatureFlagRule<TKey>[]>} Array of rules for the specified flag
+   *
+   * @example
+   * ```typescript
+   * const repository = new FeatureFlagDatabaseRepository();
+   *
+   * // Get rules for a flag
+   * const rules = await repository.getFlagRules('PREMIUM_FEATURE');
+   * console.log(`Found ${rules.length} rules`);
+   *
+   * // Process rules by priority
+   * rules.forEach(rule => {
+   *   console.log(`Rule: ${rule.name}, Priority: ${rule.priority}`);
+   * });
+   * ```
+   *
+   */
+  async getFlagRules(key) {
+    const db = this.connectionManager.getDatabase();
+    const options = {
+      filter: {
+        field: FEATURE_FLAG_RULE_FIELD.FlagKey,
+        operator: "eq",
+        value: key
+      },
+      sort: [
+        {
+          field: FEATURE_FLAG_RULE_FIELD.Priority,
+          direction: SORT_DIRECTION.Desc
+        }
+      ]
+    };
+    const result = await db.list(
+      DATABASE_TABLE.FeatureFlagRules,
+      options
+    );
+    if (!result.success) {
+      console.warn("getFlagRules failed, returning empty array:", result.error?.message);
+      return [];
+    }
+    const rules = result.value?.data ?? [];
+    return rules.map((rule) => this.mapToFeatureFlagRule(rule));
+  }
+  /**
+   * Retrieves all enabled feature flag rules from the database
+   *
+   * @description Fetches all enabled rules across all feature flags, sorted by flag key
+   * and then by priority. This method is used during system initialization to load
+   * all active rules into the evaluation engine.
+   *
+   * @returns {Promise<FeatureFlagRule<TKey>[]>} Array of all enabled rules
+   *
+   * @example
+   * ```typescript
+   * const repository = new FeatureFlagDatabaseRepository();
+   *
+   * // Load all rules for evaluation engine
+   * const allRules = await repository.getAllRules();
+   * console.log(`Loaded ${allRules.length} active rules`);
+   *
+   * // Group rules by flag
+   * const rulesByFlag = allRules.reduce((acc, rule) => {
+   *   if (!acc[rule.flagKey]) acc[rule.flagKey] = [];
+   *   acc[rule.flagKey].push(rule);
+   *   return acc;
+   * }, {});
+   * ```
+   *
+   */
+  async getAllRules() {
+    const db = this.connectionManager.getDatabase();
+    const options = {
+      filter: {
+        field: FEATURE_FLAG_RULE_FIELD.IsEnabled,
+        operator: "eq",
+        value: true
+      },
+      sort: [
+        { field: FEATURE_FLAG_RULE_FIELD.FlagKey, direction: SORT_DIRECTION.Asc },
+        { field: FEATURE_FLAG_RULE_FIELD.Priority, direction: SORT_DIRECTION.Desc }
+      ]
+    };
+    const result = await db.list(
+      DATABASE_TABLE.FeatureFlagRules,
+      options
+    );
+    if (!result.success) {
+      console.warn("getAllRules failed, returning empty array:", result.error?.message);
+      return [];
+    }
+    const rules = result.value?.data ?? [];
+    return rules.map((rule) => this.mapToFeatureFlagRule(rule));
+  }
+  /**
+   * Logs a feature flag evaluation for audit and analytics purposes
+   *
+   * @description Records feature flag evaluation events for compliance tracking,
+   * debugging, and analytics. This method is called after each flag evaluation
+   * when audit logging is enabled.
+   *
+   * @param {Object} params - The evaluation parameters
+   * @param {TKey} params.flagKey - The feature flag key that was evaluated
+   * @param {string} [params.userId] - Optional user ID who triggered the evaluation
+   * @param {FeatureFlagContext} [params.context] - Optional evaluation context
+   * @param {FeatureFlagValue} params.result - The evaluation result
+   * @returns {Promise<void>} Promise that resolves when log entry is created
+   *
+   * @example
+   * ```typescript
+   * const repository = new FeatureFlagDatabaseRepository();
+   *
+   * // Log a user evaluation
+   * await repository.logEvaluation({
+   *   flagKey: 'PREMIUM_FEATURE',
+   *   userId: 'user123',
+   *   context: {
+   *     userRole: 'premium',
+   *     environment: 'production',
+   *     requestId: 'req-456'
+   *   },
+   *   result: true
+   * });
+   *
+   * // Log anonymous evaluation
+   * await repository.logEvaluation({
+   *   flagKey: 'PUBLIC_FEATURE',
+   *   result: { variant: 'blue', enabled: true }
+   * });
+   * ```
+   *
+   */
+  async logEvaluation(params) {
+    try {
+      const db = this.connectionManager.getDatabase();
+      const evaluationData = {
+        id: randomUUID(),
+        flag_key: params.flagKey,
+        user_id: params.userId,
+        context: params.context ? params.context : void 0,
+        result: params.result,
+        reason: EVALUATION_REASONS.EVALUATION,
+        evaluated_at: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      const result = await db.create(DATABASE_TABLE.FeatureFlagEvaluations, evaluationData);
+      if (!result.success) {
+        console.warn("logEvaluation failed:", result.error?.message);
+      }
+    } catch (error) {
+      console.warn("logEvaluation error:", error);
+    }
+  }
+  /**
+   * Sets a user-specific override for a feature flag
+   *
+   * @description Creates a user-specific override that takes precedence over the
+   * default flag value and rules. Overrides can have optional expiration times
+   * and are useful for testing, gradual rollouts, or user-specific configurations.
+   *
+   * @param {TKey} flagKey - The feature flag key to override
+   * @param {string} userId - The user ID for whom to set the override
+   * @param {FeatureFlagValue} value - The override value
+   * @param {Date} [expiresAt] - Optional expiration date for the override
+   * @returns {Promise<void>} Promise that resolves when override is created
+   *
+   * @example
+   * ```typescript
+   * const repository = new FeatureFlagDatabaseRepository();
+   *
+   * // Set permanent override
+   * await repository.setOverride(
+   *   'BETA_FEATURE',
+   *   'user123',
+   *   true
+   * );
+   *
+   * // Set temporary override (expires in 1 hour)
+   * const expiresAt = new Date(Date.now() + 60 * 60 * 1000);
+   * await repository.setOverride(
+   *   'PREMIUM_FEATURE',
+   *   'testuser456',
+   *   { enabled: true, variant: 'premium' },
+   *   expiresAt
+   * );
+   * ```
+   *
+   */
+  async setOverride(flagKey, userId, value, expiresAt) {
+    const db = this.connectionManager.getDatabase();
+    const overrideData = {
+      id: randomUUID(),
+      flag_key: flagKey,
+      user_id: userId,
+      value,
+      expires_at: expiresAt?.toISOString(),
+      created_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const result = await db.create(DATABASE_TABLE.FeatureFlagOverrides, overrideData);
+    if (!result.success) {
+      console.warn("setOverride failed:", result.error?.message);
+    }
+  }
+  /**
+   * Retrieves a user-specific override for a feature flag
+   *
+   * @description Fetches the override value for a specific user and flag combination.
+   * Automatically filters out expired overrides. Returns null if no valid override
+   * exists for the user.
+   *
+   * @param {TKey} flagKey - The feature flag key to check for overrides
+   * @param {string} userId - The user ID to get the override for
+   * @returns {Promise<FeatureFlagValue | null>} The override value or null if none exists
+   *
+   * @example
+   * ```typescript
+   * const repository = new FeatureFlagDatabaseRepository();
+   *
+   * // Check for user override
+   * const override = await repository.getOverride('BETA_FEATURE', 'user123');
+   * if (override !== null) {
+   *   console.log('User has override:', override);
+   * } else {
+   *   console.log('No override found, using default flag value');
+   * }
+   *
+   * // Use in flag evaluation
+   * const userOverride = await repository.getOverride('PREMIUM_FEATURE', userId);
+   * const flagValue = userOverride ?? defaultFlagValue;
+   * ```
+   *
+   */
+  async getOverride(flagKey, userId) {
+    const db = this.connectionManager.getDatabase();
+    const options = {
+      filter: {
+        field: DATABASE_FIELDS.FlagKey,
+        operator: "eq",
+        value: flagKey
+      }
+    };
+    const result = await db.list(
+      DATABASE_TABLE.FeatureFlagOverrides,
+      options
+    );
+    if (!result.success || !result.value?.data) {
+      return null;
+    }
+    const typedData = result.value.data;
+    const validOverrides = typedData.filter((override) => {
+      if (override.user_id !== userId) return false;
+      if (override.expires_at && new Date(override.expires_at) < /* @__PURE__ */ new Date()) return false;
+      return true;
+    });
+    return validOverrides.length > 0 ? validOverrides[0].value : null;
+  }
+  /**
+   * Removes user-specific overrides for a feature flag
+   *
+   * @description Deletes all override records for a specific user and flag combination.
+   * This operation cannot be undone and will cause the user to receive the default
+   * flag value or rule-based evaluation on subsequent requests.
+   *
+   * @param {TKey} flagKey - The feature flag key to remove overrides for
+   * @param {string} userId - The user ID to remove overrides for
+   * @returns {Promise<void>} Promise that resolves when overrides are removed
+   *
+   * @example
+   * ```typescript
+   * const repository = new FeatureFlagDatabaseRepository();
+   *
+   * // Remove user override
+   * await repository.removeOverride('BETA_FEATURE', 'user123');
+   * console.log('Override removed, user will get default flag value');
+   *
+   * // Verify removal
+   * const override = await repository.getOverride('BETA_FEATURE', 'user123');
+   * console.log(override === null); // true
+   *
+   * // Bulk cleanup - remove overrides for multiple users
+   * const userIds = ['user1', 'user2', 'user3'];
+   * for (const userId of userIds) {
+   *   await repository.removeOverride('OLD_FEATURE', userId);
+   * }
+   * ```
+   *
+   */
+  async removeOverride(flagKey, userId) {
+    const db = this.connectionManager.getDatabase();
+    const options = {
+      filter: {
+        field: DATABASE_FIELDS.FlagKey,
+        operator: "eq",
+        value: flagKey
+      }
+    };
+    const listResult = await db.list(
+      DATABASE_TABLE.FeatureFlagOverrides,
+      options
+    );
+    if (!listResult.success || !listResult.value?.data) {
+      return;
+    }
+    const typedOverrides = listResult.value.data;
+    const overridesToDelete = typedOverrides.filter((override) => override.user_id === userId);
+    for (const override of overridesToDelete) {
+      await db.delete(DATABASE_TABLE.FeatureFlagOverrides, override.id);
+    }
+  }
+  /**
+   * Maps a database row to a FeatureFlag object
+   *
+   * @description Converts raw database row data to a properly typed FeatureFlag object.
+   * Handles field name variations between database schema and application types,
+   * provides default values for missing fields, and ensures type safety.
+   *
+   * @private
+   * @param {DatabaseFeatureFlagRow} row - Raw database row data
+   * @returns {FeatureFlag<TKey>} Typed FeatureFlag object
+   *
+   * @example
+   * ```typescript
+   * // Database row input:
+   * const dbRow = {
+   *   key: 'PREMIUM_FEATURE',
+   *   value: { enabled: true, variant: 'blue' },
+   *   is_enabled: true,
+   *   environments: ['production'],
+   *   description: 'Premium feature toggle',
+   *   created_at: '2024-01-15T10:30:00Z'
+   * };
+   *
+   * // Mapped output:
+   * const flag = this.mapToFeatureFlag(dbRow);
+   * // {
+   * //   key: 'PREMIUM_FEATURE',
+   * //   type: 'boolean',
+   * //   name: 'PREMIUM_FEATURE',
+   * //   value: { enabled: true, variant: 'blue' },
+   * //   isEnabled: true,
+   * //   environment: 'production',
+   * //   description: 'Premium feature toggle',
+   * //   createdAt: Date('2024-01-15T10:30:00Z'),
+   * //   updatedAt: Date('2024-01-15T10:30:00Z'),
+   * //   createdBy: 'system',
+   * //   updatedBy: 'system'
+   * // }
+   * ```
+   *
+   */
+  mapToFeatureFlag(row) {
+    return {
+      key: row.key,
+      type: FEATURE_FLAG_TYPES.BOOLEAN,
+      name: row.key,
+      value: row.value,
+      isEnabled: this.getIsEnabled(row),
+      environment: row.environments?.[0] ?? "",
+      description: row.description ?? "",
+      createdAt: this.getCreatedAt(row),
+      updatedAt: this.getUpdatedAt(row),
+      createdBy: SYSTEM_USERS.SYSTEM,
+      updatedBy: SYSTEM_USERS.SYSTEM
+    };
+  }
+  /**
+   * Extracts the enabled status from a database row
+   *
+   * @private
+   * @param {DatabaseFeatureFlagRow} row - Database row with enabled field variations
+   * @returns {boolean} The enabled status, defaulting to true if not specified
+   */
+  getIsEnabled(row) {
+    return row.isEnabled ?? row.is_enabled ?? true;
+  }
+  /**
+   * Extracts the creation date from a database row
+   *
+   * @private
+   * @param {DatabaseFeatureFlagRow} row - Database row with creation date field variations
+   * @returns {Date} The creation date, defaulting to current date if not specified
+   */
+  getCreatedAt(row) {
+    return row.createdAt ?? (row.created_at ? new Date(row.created_at) : /* @__PURE__ */ new Date());
+  }
+  /**
+   * Extracts the update date from a database row
+   *
+   * @private
+   * @param {DatabaseFeatureFlagRow} row - Database row with update date field variations
+   * @returns {Date} The update date, defaulting to current date if not specified
+   */
+  getUpdatedAt(row) {
+    return row.updatedAt ?? (row.updated_at ? new Date(row.updated_at) : /* @__PURE__ */ new Date());
+  }
+  /**
+   * Maps a database row to a FeatureFlagRule object
+   *
+   * @description Converts raw database rule row data to a properly typed FeatureFlagRule object.
+   * Handles field name variations and ensures type safety for rule evaluation.
+   *
+   * @private
+   * @param {DatabaseFeatureFlagRuleRow} row - Raw database rule row data
+   * @returns {FeatureFlagRule<TKey>} Typed FeatureFlagRule object
+   *
+   */
+  mapToFeatureFlagRule(row) {
+    return {
+      id: row.id,
+      flagKey: row.flagKey || row.flag_key,
+      name: row.name,
+      conditions: row.conditions,
+      value: row.value,
+      priority: row.priority,
+      isEnabled: row.isEnabled ?? row.is_enabled ?? true
+    };
+  }
+};
+
+// src/domain/featureFlags/providers/database.ts
+var DatabaseFeatureFlagProvider = class extends FeatureFlagProvider {
+  static {
+    __name(this, "DatabaseFeatureFlagProvider");
+  }
+  connectionManager = DatabaseConnectionManager.getInstance();
+  repository = new FeatureFlagDatabaseRepository();
+  /**
+   * Creates a new database feature flag provider.
+   *
+   * @param config - Provider configuration with database settings
+   */
+  constructor(config, features) {
+    super(config, features);
+    throw new Error("Database provider requires @plyaz/db package implementation");
+  }
+  /**
+   * Initialize database connection
+   */
+  async initialize() {
+    await this.connectionManager.initialize();
+    await super.initialize();
+  }
+  /**
+   * Fetches flags and rules from the database.
+   *
+   * @protected
+   * @returns Promise with flags and rules from database
+   */
+  async fetchData() {
+    throw new Error(
+      "Database Provider is not yet implemented.\n\nRequired Database Setup:\n- Install @plyaz/db package\n- Configure database connection\n- Run database migrations\n\nRequired Tables:\n- feature_flags\n- feature_flag_rules\n\nDatabase Schema:\nSee /src/backend/featureFlags/database/schema.ts for table definitions"
+    );
+  }
+  /**
+   * Dispose resources
+   */
+  dispose() {
+    super.dispose();
+    this.connectionManager.close().catch((error) => {
+      this.log("Error closing database connection:", error);
+    });
+  }
+  /**
+   * Validates the database provider configuration.
+   *
+   * @private
+   * @throws Error if configuration is invalid or incomplete
+   */
+  validateConfig() {
+    this.validateProviderType();
+    this.validateDatabaseConfig();
+    this.validateConnectionString();
+    this.logConfigurationStatus();
+  }
+  validateProviderType() {
+    if (this.config.provider !== "database") {
+      throw new Error('Database provider requires provider to be set to "database"');
+    }
+  }
+  validateDatabaseConfig() {
+    if (!this.config.databaseConfig) {
+      throw new Error(
+        'Database configuration is required for database provider. Set databaseConfig in your configuration.\nExample: databaseConfig: { connectionString: "postgresql://...", tableName: "feature_flags" }'
+      );
+    }
+  }
+  validateConnectionString() {
+    const { connectionString, tableName } = this.config.databaseConfig;
+    if (!connectionString) {
+      throw new Error(
+        'Database connection string is required. Set connectionString in your databaseConfig.\nExample: connectionString: "postgresql://user:pass@localhost:5432/plyaz"'
+      );
+    }
+    if (!this.isValidPostgresUrl(connectionString) && !this.isValidMysqlUrl(connectionString)) {
+      throw new Error(
+        `Database connection string must be a valid PostgreSQL or MySQL URL. Received: ${connectionString}
+Examples:
+- PostgreSQL: "postgresql://user:pass@localhost:5432/plyaz"
+- MySQL: "mysql://user:pass@localhost:3306/plyaz"`
+      );
+    }
+    if (!tableName || typeof tableName !== "string") {
+      throw new Error("Database provider requires databaseConfig.tableName");
+    }
+  }
+  logConfigurationStatus() {
+    const { connectionString, tableName } = this.config.databaseConfig;
+    this.log("Database provider configuration is valid, but implementation is not ready");
+    this.log("Connection String:", this.maskConnectionString(connectionString));
+    this.log("Table Name:", tableName ?? "feature_flags (default)");
+  }
+  /**
+   * Validates PostgreSQL URL format.
+   *
+   * @private
+   * @param url - URL to validate
+   * @returns True if valid PostgreSQL URL
+   */
+  isValidPostgresUrl(url) {
+    return url.startsWith("postgresql://") || url.startsWith("postgres://");
+  }
+  /**
+   * Validates MySQL URL format.
+   *
+   * @private
+   * @param url - URL to validate
+   * @returns True if valid MySQL URL
+   */
+  isValidMysqlUrl(url) {
+    return url.startsWith("mysql://");
+  }
+  /**
+   * Masks sensitive parts of connection string for logging.
+   *
+   * @private
+   * @param connectionString - Original connection string
+   * @returns Masked connection string
+   */
+  maskConnectionString(connectionString) {
+    try {
+      const url = new URL(connectionString);
+      const masked = `${url.protocol}//${url.username}:****@${url.host}${url.pathname}`;
+      return masked;
+    } catch {
+      return "[INVALID_URL]";
+    }
+  }
+  /**
+   * Gets database provider status and configuration info.
+   *
+   * @returns Database provider status information
+   */
+  getDatabaseInfo() {
+    return {
+      connectionString: this.config.databaseConfig?.connectionString ? this.maskConnectionString(this.config.databaseConfig.connectionString) : void 0,
+      tableName: this.config.databaseConfig?.tableName ?? "feature_flags",
+      isImplemented: false,
+      requiredPackages: ["@plyaz/db"],
+      recommendedORM: ["drizzle-orm", "prisma"],
+      documentationPath: "/docs/feature-flag-to-implement/database-requirements.md",
+      schemaPath: "/docs/feature-flag-to-implement/database-requirements.md#database-schema"
+    };
+  }
+};
+var PROVIDER_REGISTRY = {
+  memory: MemoryFeatureFlagProvider,
+  file: FileFeatureFlagProvider,
+  redis: RedisFeatureFlagProvider,
+  api: ApiFeatureFlagProvider,
+  database: DatabaseFeatureFlagProvider
+};
+var FeatureFlagProviderFactory = class {
+  static {
+    __name(this, "FeatureFlagProviderFactory");
+  }
+  /**
+   * Creates a new feature flag provider instance based on configuration.
+   *
+   * @param config - Provider configuration
+   * @param features - Record of feature flag keys to their default values
+   * @returns Configured provider instance
+   * @throws Error if provider type is unsupported or configuration is invalid
+   */
+  static create(config, features) {
+    this.validateConfig(config);
+    const ProviderClass = PROVIDER_REGISTRY[config.provider];
+    if (!ProviderClass) {
+      throw new Error(
+        `Unsupported provider type: ${config.provider}. Supported types: ${this.getSupportedProviders().join(", ")}`
+      );
+    }
+    try {
+      return new ProviderClass(config, features);
+    } catch (error) {
+      throw new Error(
+        `Failed to create ${config.provider} provider: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Creates a provider with automatic initialization.
+   *
+   * @param config - Provider configuration
+   * @param features - Record of feature flag keys to their default values
+   * @returns Promise resolving to initialized provider instance
+   */
+  static async createAndInitialize(config, features) {
+    const provider = this.create(config, features);
+    await provider.initialize();
+    return provider;
+  }
+  /**
+   * Gets a list of all supported provider types.
+   *
+   * @returns Array of supported provider names
+   */
+  static getSupportedProviders() {
+    return Object.keys(PROVIDER_REGISTRY);
+  }
+  /**
+   * Checks if a provider type is supported.
+   *
+   * @param providerType - Provider type to check
+   * @returns True if provider type is supported
+   */
+  static isProviderSupported(providerType) {
+    return providerType in PROVIDER_REGISTRY;
+  }
+  /**
+   * Gets provider information including implementation status.
+   *
+   * @returns Record of provider information
+   */
+  static getProvidersInfo() {
+    return {
+      memory: {
+        name: "Memory Provider",
+        isImplemented: true,
         description: "In-memory provider using FEATURES constant"
       },
       file: {
@@ -3095,9 +4161,10 @@ var FeatureFlagController = class {
     try {
       return await this.featureFlagService.evaluateFlag(key, body.context);
     } catch (error) {
-      throw new HttpException(
-        `Failed to evaluate flag: ${error instanceof Error ? error.message : "Unknown error"}`,
-        HttpStatus.BAD_REQUEST
+      throw new BaseError(
+        ERROR_CODES.API_INVALID_INPUT,
+        HTTP_STATUS.BAD_REQUEST,
+        `Failed to evaluate flag: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   }
@@ -3106,9 +4173,10 @@ var FeatureFlagController = class {
       const isEnabled = await this.featureFlagService.isEnabled(key, body.context);
       return { isEnabled };
     } catch (error) {
-      throw new HttpException(
-        `Failed to check flag status: ${error instanceof Error ? error.message : "Unknown error"}`,
-        HttpStatus.BAD_REQUEST
+      throw new BaseError(
+        ERROR_CODES.API_INVALID_INPUT,
+        HTTP_STATUS.BAD_REQUEST,
+        `Failed to check flag status: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   }
@@ -3116,9 +4184,10 @@ var FeatureFlagController = class {
     try {
       return await this.featureFlagService.getAllFlags(body.context);
     } catch (error) {
-      throw new HttpException(
-        `Failed to evaluate all flags: ${error instanceof Error ? error.message : "Unknown error"}`,
-        HttpStatus.INTERNAL_SERVER_ERROR
+      throw new BaseError(
+        ERROR_CODES.SERVER_ERROR,
+        HTTP_STATUS.INTERNAL_SERVER_ERROR,
+        `Failed to evaluate all flags: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   }
@@ -3126,9 +4195,10 @@ var FeatureFlagController = class {
     try {
       return await this.featureFlagService.createFlag(createData);
     } catch (error) {
-      throw new HttpException(
-        `Failed to create flag: ${error instanceof Error ? error.message : "Unknown error"}`,
-        HttpStatus.BAD_REQUEST
+      throw new BaseError(
+        ERROR_CODES.API_INVALID_INPUT,
+        HTTP_STATUS.BAD_REQUEST,
+        `Failed to create flag: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   }
@@ -3136,9 +4206,10 @@ var FeatureFlagController = class {
     try {
       return await this.featureFlagService.updateFlag(key, updateData);
     } catch (error) {
-      throw new HttpException(
-        `Failed to update flag: ${error instanceof Error ? error.message : "Unknown error"}`,
-        HttpStatus.BAD_REQUEST
+      throw new BaseError(
+        ERROR_CODES.API_INVALID_INPUT,
+        HTTP_STATUS.BAD_REQUEST,
+        `Failed to update flag: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   }
@@ -3147,9 +4218,10 @@ var FeatureFlagController = class {
       await this.featureFlagService.deleteFlag(key);
       return { isSuccessful: true };
     } catch (error) {
-      throw new HttpException(
-        `Failed to delete flag: ${error instanceof Error ? error.message : "Unknown error"}`,
-        HttpStatus.BAD_REQUEST
+      throw new BaseError(
+        ERROR_CODES.API_INVALID_INPUT,
+        HTTP_STATUS.BAD_REQUEST,
+        `Failed to delete flag: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   }
@@ -3158,9 +4230,10 @@ var FeatureFlagController = class {
       await this.featureFlagService.setOverride(key, value);
       return { isSuccessful: true };
     } catch (error) {
-      throw new HttpException(
-        `Failed to set override: ${error instanceof Error ? error.message : "Unknown error"}`,
-        HttpStatus.BAD_REQUEST
+      throw new BaseError(
+        ERROR_CODES.API_INVALID_INPUT,
+        HTTP_STATUS.BAD_REQUEST,
+        `Failed to set override: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   }
@@ -3169,9 +4242,10 @@ var FeatureFlagController = class {
       await this.featureFlagService.removeOverride(key);
       return { isSuccessful: true };
     } catch (error) {
-      throw new HttpException(
-        `Failed to remove override: ${error instanceof Error ? error.message : "Unknown error"}`,
-        HttpStatus.BAD_REQUEST
+      throw new BaseError(
+        ERROR_CODES.API_INVALID_INPUT,
+        HTTP_STATUS.BAD_REQUEST,
+        `Failed to remove override: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   }
@@ -3179,9 +4253,10 @@ var FeatureFlagController = class {
     try {
       return await this.featureFlagService.getAllFeatureFlags(environment);
     } catch (error) {
-      throw new HttpException(
-        `Failed to get flags: ${error instanceof Error ? error.message : "Unknown error"}`,
-        HttpStatus.INTERNAL_SERVER_ERROR
+      throw new BaseError(
+        ERROR_CODES.SERVER_ERROR,
+        HTTP_STATUS.INTERNAL_SERVER_ERROR,
+        `Failed to get flags: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   }
@@ -3189,9 +4264,10 @@ var FeatureFlagController = class {
     try {
       return await this.featureFlagService.getFlagRules(key);
     } catch (error) {
-      throw new HttpException(
-        `Failed to get flag rules: ${error instanceof Error ? error.message : "Unknown error"}`,
-        HttpStatus.BAD_REQUEST
+      throw new BaseError(
+        ERROR_CODES.API_INVALID_INPUT,
+        HTTP_STATUS.BAD_REQUEST,
+        `Failed to get flag rules: ${error instanceof Error ? error.message : "Unknown error"}`
       );
     }
   }
@@ -3200,64 +4276,443 @@ var FeatureFlagController = class {
       await this.featureFlagService.refreshCache();
       return { isSuccessful: true };
     } catch (error) {
-      throw new HttpException(
-        `Failed to refresh cache: ${error instanceof Error ? error.message : "Unknown error"}`,
-        HttpStatus.INTERNAL_SERVER_ERROR
+      throw new BaseError(
+        ERROR_CODES.SERVER_ERROR,
+        HTTP_STATUS.INTERNAL_SERVER_ERROR,
+        `Failed to refresh cache: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+};
+__name(FeatureFlagController, "FeatureFlagController");
+__decorateClass([
+  Post(":key/evaluate"),
+  __decorateParam(0, Param("key")),
+  __decorateParam(1, Body())
+], FeatureFlagController.prototype, "evaluateFlag", 1);
+__decorateClass([
+  Post(":key/enabled"),
+  __decorateParam(0, Param("key")),
+  __decorateParam(1, Body())
+], FeatureFlagController.prototype, "isEnabled", 1);
+__decorateClass([
+  Post("evaluate-all"),
+  __decorateParam(0, Body())
+], FeatureFlagController.prototype, "evaluateAllFlags", 1);
+__decorateClass([
+  Post(),
+  __decorateParam(0, Body())
+], FeatureFlagController.prototype, "createFlag", 1);
+__decorateClass([
+  Put(":key"),
+  __decorateParam(0, Param("key")),
+  __decorateParam(1, Body())
+], FeatureFlagController.prototype, "updateFlag", 1);
+__decorateClass([
+  Delete(":key"),
+  __decorateParam(0, Param("key"))
+], FeatureFlagController.prototype, "deleteFlag", 1);
+__decorateClass([
+  Post(":key/override"),
+  __decorateParam(0, Param("key")),
+  __decorateParam(1, Body("value"))
+], FeatureFlagController.prototype, "setOverride", 1);
+__decorateClass([
+  Delete(":key/override"),
+  __decorateParam(0, Param("key"))
+], FeatureFlagController.prototype, "removeOverride", 1);
+__decorateClass([
+  Get(),
+  __decorateParam(0, Query("environment"))
+], FeatureFlagController.prototype, "getAllFeatureFlags", 1);
+__decorateClass([
+  Get(":key/rules"),
+  __decorateParam(0, Param("key"))
+], FeatureFlagController.prototype, "getFlagRules", 1);
+__decorateClass([
+  Post("refresh")
+], FeatureFlagController.prototype, "refreshCache", 1);
+FeatureFlagController = __decorateClass([
+  Controller("feature-flags")
+], FeatureFlagController);
+var FeatureFlagConfigValidator = class {
+  static {
+    __name(this, "FeatureFlagConfigValidator");
+  }
+  /**
+   * Validates feature flag configuration and returns detailed results
+   *
+   * @description Performs comprehensive validation of feature flag configuration,
+   * checking all aspects including provider settings, cache configuration,
+   * database connections, and environment-specific settings.
+   *
+   * @param {FeatureFlagEnvironmentConfig} config - Configuration object to validate
+   * @returns {ValidationResult} Validation result with errors and warnings
+   *
+   * @example Successful Validation
+   * ```typescript
+   * const validConfig = {
+   *   provider: 'memory',
+   *   isCacheEnabled: true,
+   *   cacheTtl: 300,
+   *   refreshInterval: 60
+   * };
+   *
+   * const result = FeatureFlagConfigValidator.validate(validConfig);
+   * // result.isValid = true
+   * // result.errors = []
+   * // result.warnings = []
+   * ```
+   *
+   * @example Validation with Errors
+   * ```typescript
+   * const invalidConfig = {
+   *   provider: 'invalid_provider', // Error: invalid provider
+   *   cacheTtl: -100,              // Error: negative TTL
+   *   databaseConfig: {            // Error: missing connection string
+   *     tableName: 'flags'
+   *   }
+   * };
+   *
+   * const result = FeatureFlagConfigValidator.validate(invalidConfig);
+   * // result.isValid = false
+   * // result.errors = [
+   * //   { field: 'provider', message: 'Invalid provider...', code: 'INVALID_PROVIDER' },
+   * //   { field: 'cacheTtl', message: 'Cache TTL must be non-negative', code: 'INVALID_CACHE_TTL' }
+   * // ]
+   * ```
+   *
+   * @example Validation with Warnings
+   * ```typescript
+   * const configWithWarnings = {
+   *   provider: 'database',
+   *   cacheTtl: 7200, // Warning: very high TTL
+   *   isLoggingEnabled: true, // Warning: logging in production
+   *   databaseConfig: {
+   *     connectionString: 'https://project.supabase.co',
+   *     tableName: 'feature_flags'
+   *   }
+   * };
+   *
+   * process.env.NODE_ENV = 'production';
+   * const result = FeatureFlagConfigValidator.validate(configWithWarnings);
+   * // result.isValid = true (warnings don't fail validation)
+   * // result.warnings = [
+   * //   { field: 'cacheTtl', message: 'Cache TTL is very high...', code: 'HIGH_CACHE_TTL' },
+   * //   { field: 'isLoggingEnabled', message: 'Logging is enabled in production...', code: 'PRODUCTION_LOGGING_ENABLED' }
+   * // ]
+   * ```
+   */
+  static validate(config) {
+    try {
+      this.validateProvider(config);
+      this.validateCacheSettings(config);
+      if (config.provider === FEATURE_FLAG_PROVIDERS.DATABASE) {
+        this.validateDatabaseConfig(config);
+      }
+      return {
+        isValid: true,
+        errors: [],
+        warnings: this.getWarnings(config)
+      };
+    } catch (error) {
+      return {
+        isValid: false,
+        errors: [
+          {
+            field: "config",
+            message: error instanceof Error ? error.message : "Validation failed",
+            code: error instanceof BaseError ? error.code : "VALIDATION_ERROR"
+          }
+        ],
+        warnings: []
+      };
+    }
+  }
+  static validateProvider(config) {
+    const validProviders = getValidProviders();
+    if (!validProviders.includes(config.provider)) {
+      throw new ValidationError(
+        ERROR_CODES.CLIENT_INVALID_CONFIG,
+        HTTP_STATUS.BAD_REQUEST,
+        `Invalid provider: ${config.provider}. Must be one of: ${validProviders.join(", ")}`
+      );
+    }
+  }
+  static validateCacheSettings(config) {
+    if (config.cacheTtl < 0) {
+      throw new ValidationError(
+        ERROR_CODES.CLIENT_INVALID_CONFIG,
+        HTTP_STATUS.BAD_REQUEST,
+        "Cache TTL must be non-negative"
+      );
+    }
+    if (config.refreshInterval < 0) {
+      throw new ValidationError(
+        ERROR_CODES.CLIENT_INVALID_CONFIG,
+        HTTP_STATUS.BAD_REQUEST,
+        "Refresh interval must be non-negative"
+      );
+    }
+  }
+  static validateDatabaseConfig(config) {
+    if (!config.databaseConfig) {
+      throw new ValidationError(
+        ERROR_CODES.DB_CONFIG_REQUIRED,
+        HTTP_STATUS.BAD_REQUEST,
+        "Database configuration is required for database provider"
+      );
+    }
+    const { connectionString, tableName, poolSize, timeout } = config.databaseConfig;
+    this.validateConnectionString(connectionString);
+    this.validateTableName(tableName);
+    this.validatePoolSize(poolSize);
+    this.validateTimeout(timeout);
+  }
+  static validateConnectionString(connectionString) {
+    if (!connectionString) {
+      throw new ValidationError(
+        ERROR_CODES.DB_CONFIG_REQUIRED,
+        HTTP_STATUS.BAD_REQUEST,
+        "Database connection string is required"
+      );
+    }
+    try {
+      new URL(connectionString);
+    } catch {
+      throw new ValidationError(
+        ERROR_CODES.CLIENT_INVALID_CONFIG,
+        HTTP_STATUS.BAD_REQUEST,
+        "Invalid database connection string format"
+      );
+    }
+  }
+  static validateTableName(tableName) {
+    if (tableName && !isString(tableName)) {
+      throw new ValidationError(
+        ERROR_CODES.CLIENT_INVALID_CONFIG,
+        HTTP_STATUS.BAD_REQUEST,
+        "Table name must be a string"
+      );
+    }
+  }
+  static validatePoolSize(poolSize) {
+    if (isDefined(poolSize) && (poolSize < NUMERIC_CONSTANTS.MIN_POOL_SIZE || poolSize > NUMERIC_CONSTANTS.MAX_POOL_SIZE)) {
+      throw new ValidationError(
+        ERROR_CODES.CLIENT_INVALID_CONFIG,
+        HTTP_STATUS.BAD_REQUEST,
+        "Pool size must be between 1 and 100"
+      );
+    }
+  }
+  static validateTimeout(timeout) {
+    if (isDefined(timeout) && timeout < NUMERIC_CONSTANTS.MIN_TIMEOUT_MS) {
+      throw new ValidationError(
+        ERROR_CODES.CLIENT_INVALID_CONFIG,
+        HTTP_STATUS.BAD_REQUEST,
+        "Timeout must be at least 1000ms"
+      );
+    }
+  }
+  static getWarnings(config) {
+    const env = process.env.NODE_ENV;
+    if (config.cacheTtl > NUMERIC_CONSTANTS.ONE_HOUR_SECONDS) {
+      Logger.warn(
+        "Cache TTL is very high (>1 hour). Consider reducing for better responsiveness.",
+        {
+          field: "cacheTtl",
+          value: config.cacheTtl,
+          code: "HIGH_CACHE_TTL"
+        }
+      );
+    }
+    if (env === NODE_ENVIRONMENTS.PRODUCTION && config.isLoggingEnabled) {
+      Logger.warn("Logging is enabled in production. Consider disabling for performance.", {
+        field: "isLoggingEnabled",
+        code: "PRODUCTION_LOGGING_ENABLED"
+      });
+    }
+    if (env === NODE_ENVIRONMENTS.DEVELOPMENT && !config.isCacheEnabled) {
+      Logger.warn("Cache is disabled in development. This may impact performance testing.", {
+        field: "isCacheEnabled",
+        code: "DEVELOPMENT_CACHE_DISABLED"
+      });
+    }
+    return [];
+  }
+  /**
+   * Validates configuration and throws error if validation fails
+   *
+   * @description Convenience method that validates configuration and throws a detailed
+   * error if validation fails. This is typically used during application startup
+   * to ensure the system doesn't start with invalid configuration.
+   *
+   * @param {FeatureFlagEnvironmentConfig} config - Configuration to validate
+   * @throws {DatabaseError} When validation fails with detailed error messages
+   *
+   * @example Startup Validation
+   * ```typescript
+   * // In FeatureFlagService.onModuleInit()
+   * try {
+   *   const config = FeatureFlagConfigFactory.fromEnvironment();
+   *   FeatureFlagConfigValidator.validateOrThrow(config);
+   *
+   *   // Configuration is valid, proceed with initialization
+   *   this.provider = FeatureFlagProviderFactory.create(config, FEATURES);
+   *   await this.provider.initialize();
+   * } catch (error) {
+   *   this.logger.error('Configuration validation failed:', error.message);
+   *   throw error; // Prevent service from starting
+   * }
+   * ```
+   *
+   * @example Error Output
+   * ```typescript
+   * // When validation fails, throws DatabaseError with message:
+   * // "Configuration validation failed:
+   * // provider: Invalid provider: invalid_type. Must be one of: memory, file, redis, api, database
+   * // cacheTtl: Cache TTL must be non-negative
+   * // databaseConfig.connectionString: Database connection string is required"
+   * ```
+   *
+   * @example Environment Variable Validation
+   * ```bash
+   * # Missing required environment variables:
+   * # SUPABASE_URL=  # Empty/missing
+   * # FEATURE_FLAG_PROVIDER=database
+   *
+   * # Results in error:
+   * # "Configuration validation failed:
+   * # databaseConfig.connectionString: Database connection string is required"
+   * ```
+   */
+  static validateOrThrow(config) {
+    this.validateProvider(config);
+    this.validateCacheSettings(config);
+    if (config.provider === FEATURE_FLAG_PROVIDERS.DATABASE) {
+      this.validateDatabaseConfig(config);
+    }
+  }
+};
+var FeatureFlagConfigFactory = class {
+  static {
+    __name(this, "FeatureFlagConfigFactory");
+  }
+  /**
+   * Creates configuration from environment variables
+   *
+   * **EXECUTION ORDER: This is called FIRST in the initialization chain**
+   *
+   * Flow:
+   * 1. NestJS starts → FeatureFlagModule loads
+   * 2. FeatureFlagService.onModuleInit() called
+   * 3. → initializeProvider() called
+   * 4. → **THIS METHOD CALLED** ← YOU ARE HERE
+   * 5. → Configuration validated
+   * 6. → Provider created and initialized
+   * 7. → Database connection established
+   *
+   * @returns Validated configuration object ready for provider creation
+   * @throws {FeatureFlagConfigError} If environment variables are missing or invalid
+   *
+   * @example
+   * ```typescript
+   * // This method reads from process.env and creates:
+   * {
+   *   provider: 'database',
+   *   isCacheEnabled: true,
+   *   cacheTtl: 300,
+   *   databaseConfig: {
+   *     connectionString: 'https://your-project.supabase.co',
+   *     tableName: 'feature_flags',
+   *     poolSize: 10,
+   *     timeout: 30000
+   *   }
+   * }
+   * ```
+   */
+  static fromEnvironment() {
+    const config = {
+      provider: this.getProvider(),
+      isCacheEnabled: this.getCacheEnabled(),
+      cacheTtl: this.getCacheTtl(),
+      refreshInterval: this.getRefreshInterval(),
+      shouldFallbackToDefaults: true,
+      isLoggingEnabled: this.getLoggingEnabled()
+    };
+    if (config.provider === FEATURE_FLAG_PROVIDERS$1.DATABASE) {
+      config.databaseConfig = this.getDatabaseConfig();
+    }
+    FeatureFlagConfigValidator.validateOrThrow(config);
+    return config;
+  }
+  /**
+   * Determines which provider to use - now uses constants instead of environment variables
+   *
+   * @private
+   * @returns Provider type from constants
+   */
+  static getProvider() {
+    return FEATURE_FLAG_PROVIDERS$1.MEMORY;
+  }
+  static getCacheEnabled() {
+    return true;
+  }
+  static getCacheTtl() {
+    return FEATURE_FLAG_DEFAULTS.CACHE_TTL;
+  }
+  static getRefreshInterval() {
+    return FEATURE_FLAG_DEFAULTS.REFRESH_INTERVAL;
+  }
+  static getLoggingEnabled() {
+    return process.env.NODE_ENV === NODE_ENVIRONMENTS.DEVELOPMENT || process.env.FEATURE_FLAG_LOGGING === "true";
+  }
+  /**
+   * Creates database configuration from environment variables
+   *
+   * **CRITICAL**: This method requires SUPABASE_URL to be set in .env.local
+   *
+   * @private
+   * @returns Database configuration object
+   * @throws {FeatureFlagConfigError} If SUPABASE_URL is missing
+   *
+   * @example Environment Variables Required:
+   * ```bash
+   * SUPABASE_URL=https://your-project.supabase.co          # REQUIRED
+   * SUPABASE_ANON_PUBLIC_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... # Used in connection
+   * FEATURE_FLAG_TABLE_NAME=feature_flags                           # Optional, defaults to 'feature_flags'
+   * DB_POOL_SIZE=10                                                 # Optional, defaults to 10
+   * DB_TIMEOUT=30000                                                # Optional, defaults to 30000ms
+   * ```
+   *
+   * @example Generated Configuration:
+   * ```typescript
+   * {
+   *   connectionString: 'https://your-project.supabase.co',
+   *   tableName: 'feature_flags',
+   *   poolSize: 10,
+   *   timeout: 30000
+   * }
+   * ```
+   */
+  static getDatabaseConfig() {
+    const connectionString = process.env.SUPABASE_URL;
+    if (!connectionString) {
+      throw new DatabaseError(
+        "SUPABASE_URL is required for database provider",
+        DATABASE_ERROR_CODES.CONFIG_REQUIRED
       );
     }
+    return {
+      connectionString,
+      tableName: FEATURE_FLAG_DEFAULTS.TABLE_NAME,
+      poolSize: FEATURE_FLAG_DEFAULTS.POOL_SIZE,
+      timeout: FEATURE_FLAG_DEFAULTS.TIMEOUT
+    };
   }
 };
-__name(FeatureFlagController, "FeatureFlagController");
-__decorateClass([
-  Post(":key/evaluate"),
-  __decorateParam(0, Param("key")),
-  __decorateParam(1, Body())
-], FeatureFlagController.prototype, "evaluateFlag", 1);
-__decorateClass([
-  Post(":key/enabled"),
-  __decorateParam(0, Param("key")),
-  __decorateParam(1, Body())
-], FeatureFlagController.prototype, "isEnabled", 1);
-__decorateClass([
-  Post("evaluate-all"),
-  __decorateParam(0, Body())
-], FeatureFlagController.prototype, "evaluateAllFlags", 1);
-__decorateClass([
-  Post(),
-  __decorateParam(0, Body())
-], FeatureFlagController.prototype, "createFlag", 1);
-__decorateClass([
-  Put(":key"),
-  __decorateParam(0, Param("key")),
-  __decorateParam(1, Body())
-], FeatureFlagController.prototype, "updateFlag", 1);
-__decorateClass([
-  Delete(":key"),
-  __decorateParam(0, Param("key"))
-], FeatureFlagController.prototype, "deleteFlag", 1);
-__decorateClass([
-  Post(":key/override"),
-  __decorateParam(0, Param("key")),
-  __decorateParam(1, Body("value"))
-], FeatureFlagController.prototype, "setOverride", 1);
-__decorateClass([
-  Delete(":key/override"),
-  __decorateParam(0, Param("key"))
-], FeatureFlagController.prototype, "removeOverride", 1);
-__decorateClass([
-  Get(),
-  __decorateParam(0, Query("environment"))
-], FeatureFlagController.prototype, "getAllFeatureFlags", 1);
-__decorateClass([
-  Get(":key/rules"),
-  __decorateParam(0, Param("key"))
-], FeatureFlagController.prototype, "getFlagRules", 1);
-__decorateClass([
-  Post("refresh")
-], FeatureFlagController.prototype, "refreshCache", 1);
-FeatureFlagController = __decorateClass([
-  Controller("feature-flags")
-], FeatureFlagController);
+
+// src/backend/featureFlags/feature-flag.service.ts
 var FeatureFlagService = class {
   constructor(featureFlagRepository) {
     this.featureFlagRepository = featureFlagRepository;
@@ -3265,7 +4720,35 @@ var FeatureFlagService = class {
   logger = new Logger(FeatureFlagService.name);
   provider;
   /**
-   * Initializes the service on module startup.
+   * **FIRST METHOD CALLED** - NestJS lifecycle hook for module initialization
+   *
+   * **EXECUTION ORDER:**
+   * 1. NestJS creates FeatureFlagModule
+   * 2. NestJS instantiates FeatureFlagService
+   * 3. **THIS METHOD CALLED AUTOMATICALLY** ← YOU ARE HERE
+   * 4. → initializeProvider() called
+   * 5. → Configuration loaded from .env.local
+   * 6. → Database provider created and initialized
+   * 7. → Database connection established
+   * 8. → Initial data loaded from database
+   * 9. System ready to serve requests
+   *
+   * @throws {Error} If provider initialization fails
+   *
+   * @example What happens during initialization:
+   * ```typescript
+   * // 1. Load config from environment
+   * const config = FeatureFlagConfigFactory.fromEnvironment();
+   *
+   * // 2. Create database provider
+   * this.provider = FeatureFlagProviderFactory.create(config, FEATURES);
+   *
+   * // 3. Initialize database connection
+   * await this.provider.initialize();
+   *
+   * // 4. Load flags and rules from database
+   * const { flags, rules } = await this.provider.fetchData();
+   * ```
    */
   async onModuleInit() {
     try {
@@ -3284,36 +4767,115 @@ var FeatureFlagService = class {
     this.logger.log("Feature flag service disposed");
   }
   /**
-   * Initializes the feature flag provider.
+   * **SECOND METHOD CALLED** - Initializes the feature flag provider
+   *
+   * **EXECUTION FLOW:**
+   * 1. onModuleInit() called by NestJS
+   * 2. **THIS METHOD CALLED** ← YOU ARE HERE
+   * 3. → FeatureFlagConfigFactory.fromEnvironment() - Loads .env.local
+   * 4. → FeatureFlagProviderFactory.create() - Creates database provider
+   * 5. → provider.initialize() - Establishes database connection
+   *
+   * @private
+   * @throws {Error} If configuration is invalid or database connection fails
+   *
+   * @example Configuration Loading Process:
+   * ```typescript
+   * // Reads from .env.local:
+   * // SUPABASE_URL=https://your-project.supabase.co
+   * // FEATURE_FLAG_PROVIDER=database
+   * // FEATURE_FLAG_CACHE_ENABLED=true
+   *
+   * const config = {
+   *   provider: 'database',
+   *   isCacheEnabled: true,
+   *   databaseConfig: {
+   *     connectionString: 'https://your-project.supabase.co',
+   *     tableName: 'feature_flags'
+   *   }
+   * };
+   * ```
    */
   async initializeProvider() {
-    const DEFAULT_CACHE_TTL = 300;
-    const config = {
-      provider: process.env.FEATURE_FLAG_PROVIDER ?? "database",
-      isCacheEnabled: process.env.FEATURE_FLAG_CACHE_ENABLED === "true",
-      cacheTtl: Number(process.env.FEATURE_FLAG_CACHE_TTL) || DEFAULT_CACHE_TTL,
-      refreshInterval: Number(process.env.FEATURE_FLAG_REFRESH_INTERVAL) || 0,
-      shouldFallbackToDefaults: true,
-      isLoggingEnabled: process.env.NODE_ENV === "development"
-    };
-    this.provider = FeatureFlagProviderFactory.create(config, FEATURES);
-    await this.provider.initialize();
+    try {
+      const config = FeatureFlagConfigFactory.fromEnvironment();
+      this.provider = FeatureFlagProviderFactory.create(config, FEATURES);
+      await this.provider.initialize();
+      this.logger.log(`Feature flag provider initialized: ${config.provider}`);
+    } catch (error) {
+      this.logger.error("Failed to initialize feature flag provider", error);
+      throw new BaseError(
+        ERROR_CODES.CLIENT_INITIALIZATION_FAILED,
+        HTTP_STATUS.INTERNAL_SERVER_ERROR,
+        "Failed to initialize feature flag provider"
+      );
+    }
   }
   /**
    * Gets the current provider instance.
    */
   getProvider() {
     if (!this.provider) {
-      throw new Error("Feature flag provider not initialized");
+      throw new BaseError(
+        ERROR_CODES.ERROR_SYSTEM_NOT_INITIALIZED,
+        HTTP_STATUS.INTERNAL_SERVER_ERROR,
+        "Feature flag provider not initialized"
+      );
     }
     return this.provider;
   }
   /**
-   * Evaluates a feature flag for the given context.
+   * **MAIN RUNTIME METHOD** - Evaluates a feature flag for the given context
    *
-   * @param key - Feature flag key
-   * @param context - Evaluation context
-   * @returns Feature flag evaluation result
+   * **RUNTIME EXECUTION FLOW:**
+   * 1. Client makes HTTP request to controller
+   * 2. Controller calls **THIS METHOD** ← RUNTIME ENTRY POINT
+   * 3. → getProvider() - Gets initialized provider
+   * 4. → provider.getFlag() - Evaluates flag with context
+   * 5. → Provider checks cache, rules, overrides
+   * 6. → Database query if needed
+   * 7. ← Returns evaluation result
+   *
+   * @param key - Feature flag key (e.g., 'PREMIUM_FEATURE', 'NEW_UI')
+   * @param context - Evaluation context for targeting rules
+   * @returns Feature flag evaluation result with value, reason, and metadata
+   *
+   * @example Simple Usage:
+   * ```typescript
+   * const evaluation = await this.featureFlagService.evaluateFlag('NEW_CHECKOUT');
+   * console.log(evaluation.isEnabled); // true/false
+   * console.log(evaluation.reason);    // 'default_value' | 'rule_match' | 'override'
+   * ```
+   *
+   * @example With User Context (for targeting rules):
+   * ```typescript
+   * const evaluation = await this.featureFlagService.evaluateFlag('BETA_FEATURE', {
+   *   userId: 'user123',
+   *   userRole: 'premium',
+   *   environment: 'production',
+   *   customAttributes: {
+   *     subscriptionTier: 'pro',
+   *     region: 'us-east'
+   *   }
+   * });
+   *
+   * // Provider will:
+   * // 1. Check for user-specific overrides
+   * // 2. Evaluate targeting rules against context
+   * // 3. Return appropriate value with reason
+   * ```
+   *
+   * @example Evaluation Result:
+   * ```typescript
+   * {
+   *   key: 'BETA_FEATURE',
+   *   isEnabled: true,
+   *   value: { enabled: true, variant: 'blue' },
+   *   reason: 'rule_match',
+   *   ruleId: 'premium-users-rule',
+   *   evaluatedAt: '2024-01-15T10:30:00Z'
+   * }
+   * ```
    */
   async evaluateFlag(key, context) {
     try {
@@ -3492,10 +5054,8 @@ var FeatureFlagService = class {
   async getHealthStatus() {
     return {
       isInitialized: !!this.provider,
-      provider: "database",
-      // or get from config
+      provider: FEATURE_FLAG_PROVIDERS$1.DATABASE,
       isCacheEnabled: true
-      // or get from config
     };
   }
 };
@@ -3734,8 +5294,8 @@ var FeatureFlagModule = class {
    * @Module({
    *   imports: [
    *     FeatureFlagModule.forRoot({
-   *       provider: 'redis',
-   *       cacheEnabled: true,
+   *       provider: 'database',
+   *       isCacheEnabled: true,
    *       cacheTtl: 600,
    *     })
    *   ],
@@ -3744,12 +5304,14 @@ var FeatureFlagModule = class {
    * ```
    */
   static forRoot(options) {
+    const config = FeatureFlagConfigFactory.fromEnvironment();
+    const mergedConfig = { ...config, ...options };
     return {
       module: FeatureFlagModule,
       providers: [
         {
           provide: "FEATURE_FLAG_CONFIG",
-          useValue: options ?? {}
+          useValue: mergedConfig
         },
         FeatureFlagService,
         FeatureFlagRepository
@@ -3807,20 +5369,193 @@ FeatureFlagModule = __decorateClass([
     exports: [FeatureFlagService, FeatureFlagRepository]
   })
 ], FeatureFlagModule);
+function FeatureFlag(key, expected = true) {
+  return SetMetadata(FEATURE_FLAG_METADATA.FLAG_CHECK, { key, expected });
+}
+__name(FeatureFlag, "FeatureFlag");
 
-// src/backend/featureFlags/index.ts
-function FeatureFlagGuard() {
-  return function(_target, _propertyName, descriptor) {
-    return descriptor;
-  };
+// src/backend/featureFlags/decorators/feature-disabled.decorator.ts
+function FeatureDisabled(key) {
+  return FeatureFlag(key, false);
+}
+__name(FeatureDisabled, "FeatureDisabled");
+
+// src/backend/featureFlags/decorators/feature-enabled.decorator.ts
+function FeatureEnabled(key) {
+  return FeatureFlag(key, true);
 }
+__name(FeatureEnabled, "FeatureEnabled");
+var FeatureFlagGuard = class {
+  constructor(reflector, featureFlagService) {
+    this.reflector = reflector;
+    this.featureFlagService = featureFlagService;
+  }
+  logger = new Logger(FeatureFlagGuard.name);
+  async canActivate(context) {
+    const meta = this.reflector.get(
+      FEATURE_FLAG_METADATA.FLAG_CHECK,
+      context.getHandler()
+      // to get keys
+    );
+    if (!meta) return true;
+    const { key, expected } = meta;
+    const evaluation = await this.featureFlagService.evaluateFlag(key);
+    const actual = evaluation.value ?? evaluation.isEnabled;
+    if (!this.matches(expected, actual)) {
+      this.logger.log(
+        `FeatureFlagGuard denied: key=${key}, expected=${expected}, actual=${actual}`
+      );
+      throw new BaseError(
+        ERROR_CODES.AUTH_FORBIDDEN,
+        HTTP_STATUS.FORBIDDEN,
+        `Feature ${key} not in required state`
+      );
+    }
+    return true;
+  }
+  /**
+   * Compare expected vs actual values.
+   */
+  matches(expected, actual) {
+    if (expected === void 0 || expected === null) return Boolean(actual);
+    if (typeof actual !== "object" || actual === null) {
+      return String(actual) === String(expected);
+    }
+    return JSON.stringify(actual) === JSON.stringify(expected);
+  }
+};
 __name(FeatureFlagGuard, "FeatureFlagGuard");
-function FeatureFlag() {
-  return function(_target, _propertyName, descriptor) {
-    return descriptor;
-  };
+FeatureFlagGuard = __decorateClass([
+  Injectable()
+], FeatureFlagGuard);
+function isFeatureFlagKey(value) {
+  return Object.keys(FEATURES).includes(value);
 }
-__name(FeatureFlag, "FeatureFlag");
+__name(isFeatureFlagKey, "isFeatureFlagKey");
+var FeatureFlagMiddleware = class {
+  constructor(featureFlagService) {
+    this.featureFlagService = featureFlagService;
+  }
+  logger = new Logger(FeatureFlagMiddleware.name);
+  /**
+   * Main middleware execution method
+   *
+   * @description Processes incoming requests to evaluate and attach feature flags.
+   * Handles flag key extraction from multiple sources and graceful error handling.
+   *
+   * @param {FeatureFlagRequest} req - Express request object with feature flag extensions
+   * @param {unknown} res - Express response object (not used in this middleware)
+   * @param {Function} next - Next middleware function in the chain
+   *
+   * @throws {BaseError} When flag key is invalid or evaluation fails
+   *
+   * @example Request Processing Flow
+   * ```typescript
+   * // 1. Extract flag key from request
+   * const flagKey = req.query.flag || req.headers['x-feature-flag'] || 'AUTH_GOOGLE';
+   *
+   * // 2. Validate flag key exists in system
+   * if (!isFeatureFlagKey(flagKey)) {
+   *   throw new Error('Invalid flag key');
+   * }
+   *
+   * // 3. Evaluate flag using service
+   * const evaluation = await this.featureFlagService.evaluateFlag(flagKey);
+   *
+   * // 4. Attach to request object
+   * req.featureFlags = { [flagKey]: evaluation.isEnabled };
+   *
+   * // 5. Continue to next middleware
+   * next();
+   * ```
+   */
+  // Use a simple next type to avoid conflicts with differing framework types across environments
+  async use(req, res, next) {
+    try {
+      const flagKey = (
+        // Prefer query param -> header -> default
+        (req.query instanceof URLSearchParams ? req.query.get("flag") : req.query?.["flag"]) ?? req.headers?.["x-feature-flag"] ?? "AUTH_GOOGLE"
+      );
+      if (!isFeatureFlagKey(flagKey)) {
+        throw new BaseError(
+          ERROR_CODES.RETRY_FAILED,
+          HTTP_STATUS$1.NOT_FOUND,
+          `Invalid feature flag key: ${flagKey}`
+        );
+      }
+      const flagEvaluation = await this.featureFlagService.evaluateFlag(flagKey);
+      req.featureFlags = {
+        ...req.featureFlags,
+        [flagKey]: flagEvaluation.isEnabled
+      };
+      this.logger.debug(`Feature flags attached to request: ${JSON.stringify(req.featureFlags)}`);
+      next();
+    } catch (error) {
+      this.logger.error("Error evaluating feature flags", error);
+      throw new BaseError(
+        ERROR_CODES.RETRY_FAILED,
+        HTTP_STATUS$1.SERVICE_UNAVAILABLE,
+        "Failed to evaluate feature flag"
+      );
+    }
+  }
+};
+__name(FeatureFlagMiddleware, "FeatureFlagMiddleware");
+FeatureFlagMiddleware = __decorateClass([
+  Injectable()
+], FeatureFlagMiddleware);
+var FeatureFlagLoggingInterceptor = class {
+  logger = new Logger(FeatureFlagLoggingInterceptor.name);
+  intercept(context, next) {
+    const request = context.switchToHttp().getRequest();
+    const path2 = request.url;
+    const flags = request.featureFlags ?? {};
+    const featureToTrack = request.headers?.["x-feature-flag"];
+    if (featureToTrack && flags[featureToTrack]) {
+      this.trackFeatureUsage(featureToTrack, path2);
+    } else {
+      for (const [flag, enabled] of Object.entries(flags)) {
+        if (enabled) this.trackFeatureUsage(flag, path2);
+      }
+    }
+    return next.handle().pipe(
+      tap(() => {
+        this.logger.log(`Completed request: ${path2}`);
+      })
+    );
+  }
+  trackFeatureUsage(flag, path2) {
+    this.logger.log(`Feature "${flag}" used on endpoint "${path2}"`);
+  }
+};
+__name(FeatureFlagLoggingInterceptor, "FeatureFlagLoggingInterceptor");
+FeatureFlagLoggingInterceptor = __decorateClass([
+  Injectable()
+], FeatureFlagLoggingInterceptor);
+var ErrorHandlingInterceptor = class {
+  logger = new Logger(ErrorHandlingInterceptor.name);
+  intercept(context, next) {
+    const req = context.switchToHttp().getRequest();
+    const path2 = req.url;
+    const flags = req.featureFlags ?? {};
+    const featureToCheck = req.headers?.["x-feature-flag"] ?? "GLOBAL_FEATURE";
+    if (!flags[featureToCheck]) {
+      this.logger.warn(`Request to ${path2} blocked: ${featureToCheck} is disabled`);
+      throw new BaseError("RETRY_FAILED", HTTP_STATUS.FORBIDDEN);
+    }
+    this.logger.debug(`Request to ${path2} allowed: ${featureToCheck} is enabled`);
+    return next.handle().pipe(
+      catchError((error) => {
+        this.logger.error(`Error processing request to ${path2}`, error);
+        throw new BaseError("INTERNAL_SERVER_ERROR", HTTP_STATUS.INTERNAL_SERVER_ERROR, error);
+      })
+    );
+  }
+};
+__name(ErrorHandlingInterceptor, "ErrorHandlingInterceptor");
+ErrorHandlingInterceptor = __decorateClass([
+  Injectable()
+], ErrorHandlingInterceptor);
 var FeatureFlagContext = createContext(
   null
 );
@@ -4306,7 +6041,312 @@ function useFeatureFlagHelpers() {
   );
 }
 __name(useFeatureFlagHelpers, "useFeatureFlagHelpers");
+var MIN_RETRY_ATTEMPTS_PRODUCTION = 3;
+function getConfigForEnvironment(env) {
+  switch (env) {
+    case "production":
+      return PRODUCTION_CONFIG;
+    case "staging":
+      return STAGING_CONFIG;
+    case "development":
+    case "test":
+    default:
+      return DEVELOPMENT_CONFIG;
+  }
+}
+__name(getConfigForEnvironment, "getConfigForEnvironment");
+function validateBaseURL(mergedConfig, errors) {
+  if (!mergedConfig.baseURL) {
+    errors.push("baseURL is required in API configuration (apiConfig parameter)");
+  }
+}
+__name(validateBaseURL, "validateBaseURL");
+function validateProductionEncryption(mergedConfig, errors, warnings) {
+  if (mergedConfig.encryption?.enabled) {
+    if (!mergedConfig.encryption?.key) {
+      errors.push(
+        'encryption.key is REQUIRED when encryption is enabled in production. Pass it in apiConfig: { encryption: { key: { id: "prod-key-v1", key: process.env.ENCRYPTION_KEY!, algorithm: "AES-GCM", format: "raw" } } }'
+      );
+    }
+  } else {
+    warnings.push(
+      "[SECURITY WARNING] Encryption is disabled in production. This is not recommended for handling sensitive data (PII, payment info, etc.)."
+    );
+  }
+}
+__name(validateProductionEncryption, "validateProductionEncryption");
+function validateProductionPerformance(mergedConfig, warnings) {
+  if (!mergedConfig.networkAware?.enabled) {
+    warnings.push(
+      "[PERFORMANCE WARNING] networkAware is disabled in production. Enable it for better user experience on varying network conditions."
+    );
+  }
+  if (!mergedConfig.tracking?.telemetry) {
+    warnings.push(
+      "[MONITORING WARNING] telemetry is disabled in production. Enable it for production monitoring and alerting."
+    );
+  }
+  if (mergedConfig.retry && mergedConfig.retry.attempts !== void 0 && mergedConfig.retry.attempts < MIN_RETRY_ATTEMPTS_PRODUCTION) {
+    warnings.push(
+      `[RELIABILITY WARNING] Only ${mergedConfig.retry.attempts} retry attempts configured. Consider increasing to 3-5 for better reliability in production.`
+    );
+  }
+}
+__name(validateProductionPerformance, "validateProductionPerformance");
+function validateStagingEncryption(mergedConfig, errors, warnings) {
+  if (mergedConfig.encryption?.enabled) {
+    if (!mergedConfig.encryption?.key) {
+      errors.push(
+        'encryption.key is REQUIRED in staging (aligned with production). Pass it in apiConfig: { encryption: { key: { id: "staging-key-v1", key: process.env.ENCRYPTION_KEY!, algorithm: "AES-GCM", format: "raw" } } }'
+      );
+    }
+  } else {
+    warnings.push(
+      "[SECURITY WARNING] Encryption is disabled in staging. Staging should mirror production for accurate testing."
+    );
+  }
+  if (!mergedConfig.tracking?.telemetry) {
+    warnings.push(
+      "[MONITORING WARNING] telemetry is disabled in staging. Enable it to test monitoring before production deployment."
+    );
+  }
+}
+__name(validateStagingEncryption, "validateStagingEncryption");
+function validateDevelopmentEncryption(mergedConfig, warnings) {
+  if (mergedConfig.encryption?.enabled && !mergedConfig.encryption?.key) {
+    warnings.push(
+      "[DEV INFO] Encryption is enabled but no key provided in apiConfig. Encryption will be skipped in development (this is normal)."
+    );
+  }
+}
+__name(validateDevelopmentEncryption, "validateDevelopmentEncryption");
+function mapEnvironmentMetadata(envConfig, envDefaults) {
+  const mapped = {};
+  if (envConfig.apiKey) {
+    const existingStatic = envDefaults.headers && typeof envDefaults.headers === "object" && "static" in envDefaults.headers && typeof envDefaults.headers.static === "object" ? envDefaults.headers.static : {};
+    mapped.headers = {
+      static: { ...existingStatic ?? {}, "X-API-Key": envConfig.apiKey }
+    };
+  }
+  return mapped;
+}
+__name(mapEnvironmentMetadata, "mapEnvironmentMetadata");
+function applyDefaultClientSetting(client, envConfig) {
+  const shouldSetAsDefault = envConfig.setAsDefault !== false;
+  if (shouldSetAsDefault) {
+    setDefaultApiClient(client);
+  }
+}
+__name(applyDefaultClientSetting, "applyDefaultClientSetting");
+function validateEnvironmentConfig(envConfig, mergedConfig) {
+  const errors = [];
+  const warnings = [];
+  validateBaseURL(mergedConfig, errors);
+  if (envConfig.env === "production") {
+    validateProductionEncryption(mergedConfig, errors, warnings);
+    validateProductionPerformance(mergedConfig, warnings);
+  } else if (envConfig.env === "staging") {
+    validateStagingEncryption(mergedConfig, errors, warnings);
+  } else if (envConfig.env === "development") {
+    validateDevelopmentEncryption(mergedConfig, warnings);
+  }
+  if (warnings.length > 0) {
+    globalThis.console.warn("[ApiClientService] Configuration warnings:", warnings);
+  }
+  if (errors.length > 0) {
+    throw new ApiPackageError(
+      "service.validation.failed",
+      PACKAGE_STATUS_CODES.INVALID_CONFIGURATION,
+      API_ERROR_CODES.CONFIG_VALIDATION_FAILED,
+      {
+        context: {
+          operation: OPERATIONS.VALIDATION,
+          // Ensure error details conform to ErrorDetail shape (include errorCode)
+          errors: errors.map((err) => ({
+            field: "config",
+            message: err,
+            errorCode: String(API_ERROR_CODES.CONFIG_VALIDATION_FAILED)
+          })),
+          i18n: {
+            errors: errors.join("; "),
+            warnings: warnings.join("; ")
+          }
+        }
+      }
+    );
+  }
+}
+__name(validateEnvironmentConfig, "validateEnvironmentConfig");
+var ApiClientService = class {
+  static {
+    __name(this, "ApiClientService");
+  }
+  static instance = null;
+  static isInitializing = false;
+  static initPromise = null;
+  /**
+   * Initialize the API client with environment config and API options
+   *
+   * @param envConfig - Environment metadata (env, apiKey)
+   * @param apiConfig - API configuration (baseURL, encryption, timeout, event handlers, etc.)
+   * @returns Promise that resolves to the initialized client
+   */
+  static async init(envConfig, apiConfig) {
+    if (this.instance) {
+      globalThis.console.warn(
+        "[ApiClientService] Client already initialized. Returning existing instance."
+      );
+      return this.instance;
+    }
+    if (this.isInitializing && this.initPromise) {
+      await this.initPromise;
+      return this.instance;
+    }
+    this.isInitializing = true;
+    this.initPromise = this.createClient(envConfig, apiConfig);
+    try {
+      await this.initPromise;
+      return this.instance;
+    } finally {
+      this.isInitializing = false;
+      this.initPromise = null;
+    }
+  }
+  /**
+   * Internal initialization logic
+   * Merges environment-specific defaults with API configuration
+   *
+   * Merge Priority (lowest to highest):
+   * 1. Environment defaults (PRODUCTION_CONFIG / STAGING_CONFIG / DEVELOPMENT_CONFIG)
+   * 2. Environment metadata (envConfig - apiKey)
+   * 3. API configuration (apiConfig - baseURL, encryption, timeout, etc.)
+   */
+  static async createClient(envConfig, apiConfig) {
+    try {
+      const envDefaults = getConfigForEnvironment(envConfig.env);
+      const envMetadataMapped = mapEnvironmentMetadata(envConfig, envDefaults);
+      const mergedOptions = mergeConfigs(
+        envDefaults,
+        // Environment defaults (lowest priority)
+        envMetadataMapped,
+        // Environment metadata (medium priority)
+        apiConfig ?? {}
+        // API configuration (highest priority - includes baseURL, encryption, etc.)
+      );
+      validateEnvironmentConfig(envConfig, mergedOptions);
+      this.instance = await createApiClient(mergedOptions);
+      applyDefaultClientSetting(this.instance, envConfig);
+    } catch (error) {
+      throw new ApiPackageError(
+        "service.initialization.failed",
+        PACKAGE_STATUS_CODES.INITIALIZATION_FAILED,
+        API_ERROR_CODES.CLIENT_INITIALIZATION_FAILED,
+        {
+          cause: error instanceof Error ? error : void 0,
+          context: {
+            operation: OPERATIONS.INITIALIZATION,
+            originalError: error instanceof Error ? error.message : String(error),
+            i18n: {
+              error: error instanceof Error ? error.message : String(error)
+            }
+          }
+        }
+      );
+    }
+  }
+  /**
+   * Get the initialized client instance
+   *
+   * @throws {ApiPackageError} If client not initialized
+   */
+  static getClient() {
+    if (!this.instance) {
+      throw new ApiPackageError(
+        "service.not_initialized",
+        PACKAGE_STATUS_CODES.INITIALIZATION_FAILED,
+        API_ERROR_CODES.CLIENT_INITIALIZATION_FAILED,
+        {
+          context: {
+            operation: OPERATIONS.INITIALIZATION,
+            i18n: {
+              hint: "Call ApiClientService.init(envConfig, apiConfig) before accessing the client"
+            }
+          }
+        }
+      );
+    }
+    return this.instance;
+  }
+  /**
+   * Check if client is initialized
+   */
+  static isInitialized() {
+    return this.instance !== null;
+  }
+  /**
+   * Reinitialize with new config and options
+   */
+  static async reinitialize(envConfig, apiConfig) {
+    this.dispose();
+    return this.init(envConfig, apiConfig);
+  }
+  /**
+   * Dispose of the client instance
+   */
+  static dispose() {
+    if (this.instance && "dispose" in this.instance) {
+      this.instance.dispose?.();
+    }
+    this.instance = null;
+    this.isInitializing = false;
+    this.initPromise = null;
+  }
+};
+var getApiClient = /* @__PURE__ */ __name(() => ApiClientService.getClient(), "getApiClient");
+var initApiClient = /* @__PURE__ */ __name((envConfig, apiConfig) => ApiClientService.init(envConfig, apiConfig), "initApiClient");
+function ApiProvider({
+  children,
+  envConfig,
+  apiConfig,
+  loadingComponent,
+  errorComponent,
+  onInitialized,
+  onError
+}) {
+  const [isReady, setIsReady] = useState(false);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    ApiClientService.init(envConfig, apiConfig).then(() => {
+      setIsReady(true);
+      onInitialized?.();
+    }).catch((err) => {
+      const error2 = err instanceof Error ? err : new Error(String(err));
+      setError(error2);
+      onError?.(error2);
+      globalThis.console.error("[ApiProvider] Failed to initialize API client:", error2);
+    });
+    return () => {
+    };
+  }, []);
+  if (error) {
+    if (errorComponent) {
+      return /* @__PURE__ */ jsx(Fragment, { children: errorComponent(error) });
+    }
+    return /* @__PURE__ */ jsxs("div", { style: { padding: "20px", color: "red" }, children: [
+      /* @__PURE__ */ jsx("h2", { children: "API Client Initialization Failed" }),
+      /* @__PURE__ */ jsx("p", { children: error.message })
+    ] });
+  }
+  if (!isReady) {
+    if (loadingComponent) {
+      return /* @__PURE__ */ jsx(Fragment, { children: loadingComponent });
+    }
+    return /* @__PURE__ */ jsx("div", { style: { padding: "20px" }, children: /* @__PURE__ */ jsx("p", { children: "Initializing API client..." }) });
+  }
+  return /* @__PURE__ */ jsx(Fragment, { children });
+}
+__name(ApiProvider, "ApiProvider");
 
-export { ApiFeatureFlagProvider, CacheManager, ConditionUtils, ContextUtils, DEFAULT_FEATURE_FLAG_CONFIG, DatabaseFeatureFlagProvider, FeatureFlag, FeatureFlagAppProvider, FeatureFlagContext, FeatureFlagContextBuilder, FeatureFlagController, FeatureFlagEngine, FeatureFlagGuard, FeatureFlagModule, FeatureFlagProvider, FeatureFlagProviderFactory, FeatureFlagRepository, FeatureFlagService, FeatureFlagSystem, FileFeatureFlagProvider, HashUtils, MemoryFeatureFlagProvider, RedisFeatureFlagProvider, ValueUtils, createBackendContext, createFeatureFlagProvider, createFrontendContext, createRolloutIdentifier, evaluateArrayOperator, evaluateConditionOperator, evaluateEqualityOperator, evaluateNumericOperator, evaluateStringOperator, hashString, isArrayOperator, isEqualityOperator, isInRollout, isNumericOperator, isStringOperator, isTruthy, toBoolean, useFeatureFlag, useFeatureFlagEnabled, useFeatureFlagHelpers, useFeatureFlagProvider, useFeatureFlagProviderStatus, useFeatureFlagValue, useMultipleFeatureFlags };
+export { ApiClientService, ApiFeatureFlagProvider, ApiProvider, CacheManager, Caching, ConditionUtils, ContextUtils, DEFAULT_FEATURE_FLAG_CONFIG, DatabaseConnectionManager, DatabaseFeatureFlagProvider, ErrorHandlingInterceptor, FeatureDisabled, FeatureEnabled, FeatureFlagAppProvider, FeatureFlagConfigFactory, FeatureFlagConfigValidator, FeatureFlagContext, FeatureFlagContextBuilder, FeatureFlagController, FeatureFlagDatabaseRepository, FeatureFlagEngine, FeatureFlagGuard, FeatureFlagLoggingInterceptor, FeatureFlagMiddleware, FeatureFlagModule, FeatureFlagProvider, FeatureFlagProviderFactory, FeatureFlagRepository, FeatureFlagService, FeatureFlagSystem, FileFeatureFlagProvider, HashUtils, MemoryFeatureFlagProvider, RedisFeatureFlagProvider, ValueUtils, createBackendContext, createFeatureFlagProvider, createFrontendContext, createRolloutIdentifier, evaluateArrayOperator, evaluateConditionOperator, evaluateEqualityOperator, evaluateNumericOperator, evaluateStringOperator, getApiClient, getValidProviders, hashString, initApiClient, isArrayOperator, isDefined, isEqualityOperator, isInRollout, isNumber, isNumericOperator, isString, isStringOperator, isTruthy, toBoolean, useFeatureFlag, useFeatureFlagEnabled, useFeatureFlagHelpers, useFeatureFlagProvider, useFeatureFlagProviderStatus, useFeatureFlagValue, useMultipleFeatureFlags };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map