@plyaz/core 1.8.3 → 1.9.0

package/dist/entry-backend.mjs

@@ -1,10 +1,10 @@
 import { TIME_CONSTANTS, FORMAT_CONSTANTS, FILE_CHECK_INTERVAL_DEFAULT, FEATURE_FLAG_CACHE_TTL_DEFAULT, FEATURE_FLAG_FILE_PATHS, FEATURE_FLAG_PROVIDERS, NUMERIC_CONSTANTS, HTTP_STATUS as HTTP_STATUS$1, MATH_CONSTANTS, ISO_STANDARDS, CACHE_MAX_SIZE_DEFAULT, CACHE_CLEANUP_INTERVAL_DEFAULT, DEVELOPMENT_CONFIG, STAGING_CONFIG, PRODUCTION_CONFIG, FNV_CONSTANTS, FEATURES, HASH_SEED_CONSTANTS } from '@plyaz/config';
-import { ERROR_CODES as ERROR_CODES$1, HTTP_STATUS, NODE_ENVIRONMENTS, BACKEND_RUNTIMES, FRONTEND_RUNTIMES, ERROR_CATEGORY, CORE_EVENTS as CORE_EVENTS$1, PACKAGE_STATUS_CODES, API_ERROR_CODES, OPERATIONS, FEATURE_FLAG_PROVIDERS as FEATURE_FLAG_PROVIDERS$2, FEATURE_FLAG_METADATA } from '@plyaz/types';
+import { ERROR_CODES as ERROR_CODES$1, HTTP_STATUS, NODE_ENVIRONMENTS, BACKEND_RUNTIMES, FRONTEND_RUNTIMES, ERROR_CATEGORY as ERROR_CATEGORY$1, CORE_EVENTS as CORE_EVENTS$1, PACKAGE_STATUS_CODES, API_ERROR_CODES, OPERATIONS, FEATURE_FLAG_PROVIDERS as FEATURE_FLAG_PROVIDERS$2, FEATURE_FLAG_METADATA } from '@plyaz/types';
 import { EventEmitter } from 'events';
 import { evaluateAllFeatureFlags, createFeatureFlag, updateFeatureFlag, deleteFeatureFlag, fetchFeatureFlagRules, createApiClient, mergeConfigs, ApiPackageError, setDefaultApiClient } from '@plyaz/api/frontend';
 import { CorePackageError, StoragePackageError, NotificationPackageError, BaseError, DatabasePackageError, ValidationError, initializeErrorSystem, generateRequestId, ValidateAndFormatErrors, SuccessResponseStandard } from '@plyaz/errors';
 import { CoreLogger, PackageLogger } from '@plyaz/logger';
-import { ERROR_CODES, STORAGE_ERROR_CODES, NOTIFICATION_ERROR_CODES, DATABASE_ERROR_CODES, API_ERROR_CODES as API_ERROR_CODES$1 } from '@plyaz/types/errors';
+import { ERROR_CODES, STORAGE_ERROR_CODES, NOTIFICATION_ERROR_CODES, DATABASE_ERROR_CODES, ERROR_CATEGORY, API_ERROR_CODES as API_ERROR_CODES$1 } from '@plyaz/types/errors';
 import { OBSERVABILITY_METRICS } from '@plyaz/types/observability';
 import { clearEventEmitter, setEventEmitter, initializeGlobalErrorHandler } from '@plyaz/errors/middleware';
 import { STORE_KEYS, useRootStore, createStandaloneFeatureFlagStore } from '@plyaz/store';
@@ -621,7 +621,7 @@ function validateEnvironmentConfig(envConfig, mergedConfig) {
     );
   }
 }
-var MIN_RETRY_ATTEMPTS_PRODUCTION, ApiClientService, getApiClient, initApiClient, createApiClientInstance;
+var MIN_RETRY_ATTEMPTS_PRODUCTION, ApiClientService, getApiClient, initApiClient, createApiClientInstance, createStandaloneApiClient;
 var init_ApiClientService = __esm({
   "src/services/ApiClientService.ts"() {
     init_CoreEventManager();
@@ -648,6 +648,80 @@ var init_ApiClientService = __esm({
       static {
         this.initPromise = null;
       }
+      /**
+       * Build the core error handler for API clients.
+       * This handler emits errors to CoreEventManager for global error handling.
+       *
+       * Handles:
+       * - Single errors (network, timeout)
+       * - Array of errors from API responses (validation, business logic)
+       * - Serialization to unified SerializedError format
+       * - Event emission to CORE_EVENTS.SYSTEM.ERROR and CORE_EVENTS.API.REQUEST_ERROR
+       *
+       * @returns Error handler function compatible with ApiClientOptions.onError
+       */
+      static buildCoreErrorHandler() {
+        return async (error) => {
+          const requestId = generateRequestId();
+          const method = error.config?.method ?? "UNKNOWN";
+          const url = error.config?.url ?? "unknown";
+          try {
+            const errorDetails = Array.isArray(error.response?.data) ? error.response.data : [];
+            if (errorDetails.length === 0) {
+              const serializedError = {
+                id: requestId,
+                code: ERROR_CODES$1.CORE_API_CLIENT_REQUEST_FAILED,
+                message: error.message ?? "API request failed",
+                status: error.status,
+                category: ERROR_CATEGORY$1.Network,
+                timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+                isRetryable: error.status ? error.status >= HTTP_STATUS.INTERNAL_SERVER_ERROR : false,
+                source: "api-client",
+                dismissed: false,
+                context: {
+                  method,
+                  url,
+                  requestId
+                }
+              };
+              CoreEventManager.emit(CORE_EVENTS$1.SYSTEM.ERROR, { errors: [serializedError] });
+            } else {
+              const serializedErrors = errorDetails.map(
+                (detail, index) => ({
+                  id: `${requestId}-${index}`,
+                  code: detail.errorCode ?? ERROR_CODES$1.CORE_API_CLIENT_REQUEST_FAILED,
+                  message: detail.message ?? error.message ?? "API request failed",
+                  status: error.status,
+                  category: ERROR_CATEGORY$1.Network,
+                  timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+                  isRetryable: error.status ? error.status >= HTTP_STATUS.INTERNAL_SERVER_ERROR : false,
+                  source: "api-client",
+                  dismissed: false,
+                  context: {
+                    method,
+                    url,
+                    requestId,
+                    field: detail.field,
+                    valueGiven: detail.valueGiven,
+                    allowedValues: detail.allowedValues,
+                    constraints: detail.constraints
+                  }
+                })
+              );
+              CoreEventManager.emit(CORE_EVENTS$1.SYSTEM.ERROR, { errors: serializedErrors });
+            }
+          } catch (e) {
+            console.error("[ApiClientService] Failed to emit error event:", e);
+          }
+          _ApiClientService.emitApiError(error, {
+            method,
+            url,
+            requestId,
+            status: error.status,
+            duration: 0
+          });
+        };
+      }
       /**
        * Initialize the API client with environment config and API options
        *
@@ -685,71 +759,12 @@ var init_ApiClientService = __esm({
        * 2. Environment metadata (envConfig - apiKey)
        * 3. API configuration (apiConfig - baseURL, encryption, timeout, etc.)
        */
-      // eslint-disable-next-line max-lines-per-function, complexity
+      // eslint-disable-next-line complexity
       static async createClient(envConfig, apiConfig) {
         try {
           const envDefaults = getConfigForEnvironment(envConfig.env);
           const envMetadataMapped = mapEnvironmentMetadata(envConfig, envDefaults);
-          const coreErrorHandler = /* @__PURE__ */ __name(async (error) => {
-            const requestId = generateRequestId();
-            const method = error.config?.method ?? "UNKNOWN";
-            const url = error.config?.url ?? "unknown";
-            try {
-              const errorDetails = Array.isArray(error.response?.data) ? error.response.data : [];
-              if (errorDetails.length === 0) {
-                const serializedError = {
-                  id: requestId,
-                  code: ERROR_CODES$1.CORE_API_CLIENT_REQUEST_FAILED,
-                  message: error.message ?? "API request failed",
-                  status: error.status,
-                  category: ERROR_CATEGORY.Network,
-                  timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-                  isRetryable: error.status ? error.status >= HTTP_STATUS.INTERNAL_SERVER_ERROR : false,
-                  source: "api-client",
-                  dismissed: false,
-                  context: {
-                    method,
-                    url,
-                    requestId
-                  }
-                };
-                CoreEventManager.emit(CORE_EVENTS$1.SYSTEM.ERROR, { errors: [serializedError] });
-              } else {
-                const serializedErrors = errorDetails.map(
-                  (detail, index) => ({
-                    id: `${requestId}-${index}`,
-                    code: detail.errorCode ?? ERROR_CODES$1.CORE_API_CLIENT_REQUEST_FAILED,
-                    message: detail.message ?? error.message ?? "API request failed",
-                    status: error.status,
-                    category: ERROR_CATEGORY.Network,
-                    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-                    isRetryable: error.status ? error.status >= HTTP_STATUS.INTERNAL_SERVER_ERROR : false,
-                    source: "api-client",
-                    dismissed: false,
-                    context: {
-                      method,
-                      url,
-                      requestId,
-                      field: detail.field,
-                      valueGiven: detail.valueGiven,
-                      allowedValues: detail.allowedValues,
-                      constraints: detail.constraints
-                    }
-                  })
-                );
-                CoreEventManager.emit(CORE_EVENTS$1.SYSTEM.ERROR, { errors: serializedErrors });
-              }
-            } catch (e) {
-              console.error("[ApiClientService] Failed to emit error event:", e);
-            }
-            _ApiClientService.emitApiError(error, {
-              method,
-              url,
-              requestId,
-              status: error.status,
-              duration: 0
-            });
-          }, "coreErrorHandler");
+          const coreErrorHandler = _ApiClientService.buildCoreErrorHandler();
           const userOnError = apiConfig?.onError;
           const combinedOnError = userOnError ? Array.isArray(userOnError) ? [...userOnError, coreErrorHandler] : [userOnError, coreErrorHandler] : coreErrorHandler;
           const mergedOptions = mergeConfigs(
@@ -924,11 +939,13 @@ var init_ApiClientService = __esm({
         try {
           const envDefaults = getConfigForEnvironment(envConfig.env);
           const envMetadataMapped = mapEnvironmentMetadata(envConfig, envDefaults);
-          const mergedOptions = mergeConfigs(
-            envDefaults,
-            envMetadataMapped,
-            apiConfig ?? {}
-          );
+          const coreErrorHandler = _ApiClientService.buildCoreErrorHandler();
+          const userOnError = apiConfig?.onError;
+          const combinedOnError = userOnError ? Array.isArray(userOnError) ? [...userOnError, coreErrorHandler] : [userOnError, coreErrorHandler] : coreErrorHandler;
+          const mergedOptions = mergeConfigs(envDefaults, envMetadataMapped, {
+            ...apiConfig ?? {},
+            onError: combinedOnError
+          });
           validateEnvironmentConfig(envConfig, mergedOptions);
           const dedicatedClient = await createApiClient(mergedOptions);
           return dedicatedClient;
@@ -950,10 +967,66 @@ var init_ApiClientService = __esm({
           );
         }
       }
+      /**
+       * Create a standalone API client with Core error handling.
+       *
+       * This is a simpler alternative to `createInstance()` that doesn't require
+       * environment config. Use this when you just need the error handling without
+       * environment-specific defaults (production validation, etc.).
+       *
+       * **Use cases:**
+       * - Domain services that need their own API client
+       * - Testing with isolated API clients
+       * - Simple client creation without environment setup
+       *
+       * @param apiConfig - API configuration (baseURL, timeout, etc.)
+       * @returns Promise that resolves to a client with Core error handling
+       *
+       * @example
+       * ```typescript
+       * // In BaseDomainService or any service
+       * const client = await ApiClientService.createStandaloneClient({
+       *   baseURL: '/api/examples',
+       *   timeout: 10000,
+       * });
+       *
+       * // Errors are automatically emitted to CoreEventManager
+       * const response = await client.get('/items');
+       * ```
+       */
+      static async createStandaloneClient(apiConfig) {
+        try {
+          const coreErrorHandler = _ApiClientService.buildCoreErrorHandler();
+          const userOnError = apiConfig.onError;
+          const combinedOnError = userOnError ? Array.isArray(userOnError) ? [...userOnError, coreErrorHandler] : [userOnError, coreErrorHandler] : coreErrorHandler;
+          const client = await createApiClient({
+            ...apiConfig,
+            onError: combinedOnError
+          });
+          return client;
+        } catch (error) {
+          throw new ApiPackageError(
+            "service.standalone_client_creation.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)
+                }
+              }
+            }
+          );
+        }
+      }
     };
     getApiClient = /* @__PURE__ */ __name(() => ApiClientService.getClient(), "getApiClient");
     initApiClient = /* @__PURE__ */ __name((envConfig, apiConfig) => ApiClientService.init(envConfig, apiConfig), "initApiClient");
     createApiClientInstance = /* @__PURE__ */ __name((envConfig, apiConfig) => ApiClientService.createInstance(envConfig, apiConfig), "createApiClientInstance");
+    createStandaloneApiClient = /* @__PURE__ */ __name((apiConfig) => ApiClientService.createStandaloneClient(apiConfig), "createStandaloneApiClient");
   }
 });
 var BaseAdapter, NoopAdapter;
@@ -2696,6 +2769,7 @@ var init_CoreInitializer = __esm({
     init_ObservabilityService();
     init_LoggerAdapter();
     init_runtime();
+    init_common();
     init_dependencies();
     DEFAULT_MAX_ERRORS = 100;
     _getCoreDomainServices = null;
@@ -3572,6 +3646,7 @@ var init_CoreInitializer = __esm({
           _Core._errorHandler.destroy();
           _Core._errorHandler = null;
           clearEventEmitter();
+          BaseError.clearEventEmitter();
         }
         _Core._errorConfig = {};
         _Core._httpErrorHandler = null;
@@ -3760,6 +3835,28 @@ var init_CoreInitializer = __esm({
           };
         }
       }
+      /**
+       * Serialize a PackageErrorLike to SerializedError format.
+       * Used by BaseError.setEventEmitter() to convert errors for the store.
+       */
+      static serializePackageError(error) {
+        const serviceName = typeof error.context?.service === "string" ? error.context.service : "core";
+        return {
+          id: generateId(),
+          code: error.errorCode ?? ERROR_CODES$1.UNKNOWN_ERROR,
+          message: error.message,
+          status: error.statusCode,
+          category: error.category ?? ERROR_CATEGORY.Server,
+          timestamp: error.timestamp ?? (/* @__PURE__ */ new Date()).toISOString(),
+          isRetryable: error.retryable ?? false,
+          source: serviceName,
+          dismissed: false,
+          context: {
+            correlationId: error.correlationId,
+            ...error.context
+          }
+        };
+      }
       /** Get error store actions from root store */
       static getErrorStoreActions() {
         if (!_Core._rootStore) {
@@ -3771,12 +3868,17 @@ var init_CoreInitializer = __esm({
         return _Core._rootStore.getState().errors;
       }
       /** Build global error handler config */
-      // eslint-disable-next-line complexity
       static buildErrorHandlerConfig(config) {
+        const baseErrorFilter = /* @__PURE__ */ __name((error) => {
+          if (error instanceof BaseError) {
+            return false;
+          }
+          return config?.filter ? config.filter(error) : true;
+        }, "baseErrorFilter");
         return {
           source: config?.source ?? "global",
           maxErrors: config?.maxErrors ?? DEFAULT_MAX_ERRORS,
-          filter: config?.filter,
+          filter: baseErrorFilter,
           onError: config?.onError,
           logToConsole: config?.logToConsole ?? false
         };
@@ -3797,6 +3899,15 @@ var init_CoreInitializer = __esm({
         });
         await _Core.initializeRootStore(_Core._errorConfig, verbose);
         setEventEmitter(CoreEventManager.emit.bind(CoreEventManager));
+        BaseError.setEventEmitter((error) => {
+          const serializedError = _Core.serializePackageError(error);
+          const serviceName = serializedError.source ?? "core";
+          CoreEventManager.emit(CORE_EVENTS.SYSTEM.ERROR, {
+            errors: [serializedError],
+            context: serviceName,
+            recoverable: error.retryable ?? false
+          });
+        });
         const errorStore = _Core.getErrorStoreActions();
         _Core._errorHandler = initializeGlobalErrorHandler(
           errorStore,
@@ -3892,9 +4003,15 @@ var init_CoreInitializer = __esm({
       }
       /**
        * Subscribe to CoreEventManager error events
-       * Forwards system, entity, API, validation, database, and auth errors to the global error handler.
+       * Forwards entity, API, validation, database, and auth errors to the global error handler.
+       *
+       * NOTE: SYSTEM.ERROR is NOT subscribed here - it's handled in initializeErrorHandler()
+       * via the BaseError.setEventEmitter() + addErrors() pattern to avoid duplicate subscriptions.
        *
-       * Note: Database errors (DATABASE.ERROR) are only subscribed on backend runtimes since
+       * For non-BaseError errors, domain-specific events (ENTITY.ERROR, API.REQUEST_ERROR, etc.)
+       * are captured here. BaseError instances are skipped (they already auto-emit via SYSTEM.ERROR).
+       *
+       * Database errors (DATABASE.ERROR) are only subscribed on backend runtimes since
        * DbService is backend-only (skipDb: true on frontend).
        */
       static subscribeToErrorEvents(verbose) {
@@ -3902,78 +4019,36 @@ var init_CoreInitializer = __esm({
           return;
         }
         _Core.log("Subscribing to error events...", verbose);
-        const cleanupSystemError = CoreEventManager.on(CORE_EVENTS.SYSTEM.ERROR, (event) => {
-          if (_Core._errorHandler && event.data?.errors?.length) {
-            for (const err of event.data.errors) {
-              _Core._errorHandler.captureError(err, "system");
-            }
-          }
-        });
-        const cleanupEntityError = CoreEventManager.on(CORE_EVENTS.ENTITY.ERROR, (event) => {
-          if (_Core._errorHandler && event.data) {
-            _Core._errorHandler.captureError(event.data.error, "entity");
-          }
-        });
-        const cleanupApiError = CoreEventManager.on(CORE_EVENTS.API.REQUEST_ERROR, (event) => {
-          if (_Core._errorHandler && event.data) {
-            _Core._errorHandler.captureError(event.data.error, "api");
-          }
-        });
-        const cleanupValidationError = CoreEventManager.on(CORE_EVENTS.VALIDATION.FAILED, (event) => {
-          if (_Core._errorHandler && event.data) {
-            _Core._errorHandler.captureError(event.data.error, "validation");
-          }
-        });
-        const cleanupAuthUnauthorized = CoreEventManager.on(CORE_EVENTS.AUTH.UNAUTHORIZED, (event) => {
-          if (_Core._errorHandler && event.data?.error) {
-            _Core._errorHandler.captureError(event.data.error, "auth");
-          }
-        });
-        const cleanupAuthSessionExpired = CoreEventManager.on(
-          CORE_EVENTS.AUTH.SESSION_EXPIRED,
-          (event) => {
-            if (_Core._errorHandler && event.data?.error) {
-              _Core._errorHandler.captureError(event.data.error, "auth");
+        const subscribeError = /* @__PURE__ */ __name((event, source) => {
+          return CoreEventManager.on(event, (e) => {
+            if (_Core._errorHandler && e.data?.error && !(e.data.error instanceof BaseError)) {
+              _Core._errorHandler.captureError(e.data.error, source);
             }
-          }
-        );
+          });
+        }, "subscribeError");
         _Core._eventCleanupFns.push(
-          cleanupSystemError,
-          cleanupEntityError,
-          cleanupApiError,
-          cleanupValidationError,
-          cleanupAuthUnauthorized,
-          cleanupAuthSessionExpired
+          subscribeError(CORE_EVENTS.ENTITY.ERROR, "entity"),
+          subscribeError(CORE_EVENTS.API.REQUEST_ERROR, "api"),
+          subscribeError(CORE_EVENTS.VALIDATION.FAILED, "validation"),
+          subscribeError(CORE_EVENTS.AUTH.UNAUTHORIZED, "auth"),
+          subscribeError(CORE_EVENTS.AUTH.SESSION_EXPIRED, "auth")
         );
         if (_Core.isRuntimeCompatible("backend")) {
-          const cleanupDatabaseError = CoreEventManager.on(CORE_EVENTS.DATABASE.ERROR, (event) => {
-            if (_Core._errorHandler && event.data) {
-              _Core._errorHandler.captureError(event.data.error, "database");
-            }
-          });
-          _Core._eventCleanupFns.push(cleanupDatabaseError);
-          const cleanupStorageError = CoreEventManager.on(CORE_EVENTS.STORAGE.ERROR, (event) => {
-            if (_Core._errorHandler && event.data) {
-              _Core._errorHandler.captureError(event.data.error, "storage");
-            }
-          });
-          _Core._eventCleanupFns.push(cleanupStorageError);
-          const cleanupNotificationError = CoreEventManager.on(
-            CORE_EVENTS.NOTIFICATION.ERROR,
-            (event) => {
-              if (_Core._errorHandler && event.data) {
-                _Core._errorHandler.captureError(event.data.error, "notification");
-              }
-            }
+          _Core._eventCleanupFns.push(
+            subscribeError(CORE_EVENTS.DATABASE.ERROR, "database"),
+            subscribeError(CORE_EVENTS.STORAGE.ERROR, "storage"),
+            subscribeError(CORE_EVENTS.NOTIFICATION.ERROR, "notification"),
+            subscribeError(CORE_EVENTS.CACHE.ERROR, "cache")
+          );
+          _Core.log(
+            "Subscribed to backend error events (database, storage, notification, cache)",
+            verbose
           );
-          _Core._eventCleanupFns.push(cleanupNotificationError);
-          _Core.log("Subscribed to backend error events (database, storage, notification)", verbose);
-        }
-        const eventTypes = ["system", "entity", "api", "validation", "auth"];
-        if (_Core.isRuntimeCompatible("backend")) {
-          eventTypes.push("database", "storage", "notification");
         }
-        _Core.log(`Subscribed to error events: ${eventTypes.join(", ")}`, verbose);
+        const eventTypes = ["entity", "api", "validation", "auth"];
+        if (_Core.isRuntimeCompatible("backend"))
+          eventTypes.push("database", "storage", "notification", "cache");
+        _Core.log(`Subscribed to domain error events: ${eventTypes.join(", ")}`, verbose);
       }
       /** Handle fetch flags error and return empty flags */
       static handleFetchFlagsError(error, config, verbose) {
@@ -4051,6 +4126,7 @@ var BaseDomainService;
 var init_BaseDomainService = __esm({
   "src/domain/base/BaseDomainService.ts"() {
     init_CoreInitializer();
+    init_ApiClientService();
     BaseDomainService = class {
       // ─────────────────────────────────────────────────────────────────────────
       // Constructor
@@ -4226,6 +4302,11 @@ var init_BaseDomainService = __esm({
       /**
        * Initialize API client asynchronously
        * Called from constructor if apiClientConfig is provided
+       *
+       * Uses ApiClientService.createStandaloneClient() which includes:
+       * - Automatic error handling (single errors and arrays)
+       * - Event emission to CORE_EVENTS.SYSTEM.ERROR and CORE_EVENTS.API.REQUEST_ERROR
+       * - Serialization to unified SerializedError format
        */
       initializeApiClient() {
         if (this._clientInitPromise || !this._apiClientConfig) {
@@ -4233,7 +4314,7 @@ var init_BaseDomainService = __esm({
         }
         this._clientInitPromise = (async () => {
           try {
-            this._apiClient = await createApiClient(this._apiClientConfig);
+            this._apiClient = await ApiClientService.createStandaloneClient(this._apiClientConfig);
             if (this._setAsDefaultClient) {
               setDefaultApiClient(this._apiClient);
             }
@@ -7830,7 +7911,7 @@ var init_FrontendExampleDomainService = __esm({
       // Constructor
       // ─────────────────────────────────────────────────────────────────────────
       constructor(config = {}, options) {
-        const apiBasePath = config.apiBasePath ?? "/api/examples";
+        const apiBasePath = config.apiBasePath || "/api/examples";
         super({
           serviceName: "ExampleFrontendService",
           supportedRuntimes: ["frontend"],
@@ -7934,7 +8015,11 @@ var init_FrontendExampleDomainService = __esm({
       static async create(config, options) {
         const mergedConfig = {
           ...config,
-          apiBasePath: config.apiBasePath ?? options?.apiClient?.options?.baseURL ?? "/api/examples"
+          // Use || instead of ?? because api.baseURL may be '' (empty string) for same-origin requests.
+          // The ?? operator only falls through on null/undefined, not empty strings.
+          // An empty string is not a valid API path, so we treat it as "not provided" and fall through to default.
+          // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+          apiBasePath: config.apiBasePath || options?.apiClient?.options?.baseURL || "/api/examples"
         };
         const service = new _FrontendExampleDomainService(mergedConfig, options);
         if (mergedConfig.autoFetch) {
@@ -9410,6 +9495,7 @@ init_DbService();
 
 // src/services/CacheService.ts
 init_cache();
+init_CoreEventManager();
 var CacheService = class _CacheService {
   /** Private constructor to enforce singleton */
   constructor() {
@@ -9427,6 +9513,22 @@ var CacheService = class _CacheService {
     /** Singleton instance */
     this.instance = null;
   }
+  // ─────────────────────────────────────────────────────────────────
+  // Error Handling
+  // ─────────────────────────────────────────────────────────────────
+  /**
+   * Emits a cache error event via CoreEventManager.
+   * Called when cache operations fail to integrate with global error handling.
+   */
+  emitCacheError(error, operation, options) {
+    const payload = {
+      error,
+      operation,
+      key: options?.key,
+      recoverable: options?.recoverable ?? true
+    };
+    CoreEventManager.emit(CORE_EVENTS.CACHE.ERROR, payload);
+  }
   /**
    * Initialize the cache service with configuration
    *
@@ -9471,6 +9573,7 @@ var CacheService = class _CacheService {
       });
     } catch (error) {
       service.logger.error("[CacheService] Failed to initialize cache", { error });
+      service.emitCacheError(error, "initialize", { recoverable: false });
       throw new CorePackageError(
         `Failed to initialize cache: ${error instanceof Error ? error.message : String(error)}`,
         ERROR_CODES.VALIDATION_ERROR,
@@ -13947,7 +14050,10 @@ var DEFAULT_REFRESH_INTERVAL_MS = 6e4;
   }
   /** Build API client for feature flags */
   static async buildApiClient(config, options) {
-    const apiBasePath = config.apiBasePath ?? options?.apiClient?.options?.baseURL ?? "/feature-flags";
+    const apiBasePath = (
+      // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+      config.apiBasePath || options?.apiClient?.options?.baseURL || "/feature-flags"
+    );
     return createApiClient({ ...options?.apiClient?.options, baseURL: apiBasePath });
   }
   /** Build feature flag provider */
@@ -15391,6 +15497,6 @@ setCoreDependencies({
 });
 setGetCoreDomainServices(getCoreDomainServices);
 
-export { ApiClientService, BACKEND_EXAMPLE_DOMAIN_SERVICE, BackendExampleDomainService, BaseBackendDomainService, BaseDomainService, BaseMapper, BaseValidator, CORE_DB_SERVICE, CORE_ENV, CORE_OPTIONS, CacheKeyBuilder, CacheManager, CacheService, Caching, ConditionUtils, ContextUtils, Core, CoreEventManager, CoreModule, DEFAULT_ENCRYPTION_FIELDS, DbService, ErrorHandlingInterceptor, ExampleController, ExampleModule, FeatureDisabled, FeatureEnabled, FeatureFlagConfigFactory, FeatureFlagConfigValidator, FeatureFlagContextBuilder, FeatureFlagController, FeatureFlagDatabaseRepository, FeatureFlagDomainService, FeatureFlagEngine, FeatureFlagGuard, FeatureFlagLoggingInterceptor, FeatureFlagMiddleware, FeatureFlagModule, FeatureFlagService, FeatureFlagServiceFactory, HashUtils, IdUtils, NotificationService, ObjectUtils, PACKAGE_NAME, ServiceRegistry, StorageService, TABLE_REGISTRY, VERSION, ValueUtils, backendExampleDomainService, backendExampleDomainService as backendExampleService, camelToSnake, clearCoreDependencies, createApiClientInstance, createBackendContext, createFrontendContext, createHandler, createRolloutIdentifier, detectRuntime, evaluateArrayOperator, evaluateConditionOperator, evaluateEqualityOperator, evaluateNumericOperator, evaluateStringOperator, backendExampleDomainService as exampleService, formatDate, generateCorrelationId, generateId, generateShortId, generateSpanId, generateTraceId, getApiClient, getCacheService, getCoreDependencies, getCoreDependency, getNestedProperty, getPackageVersion, getValidProviders, hasCoreDependency, hasNestedProperty, hashString, initApiClient, isArrayOperator, isDefined, isEqualityOperator, isInRollout, isNumber, isNumericOperator, isString, isStringOperator, isTruthy, keysToCamel, keysToSnake, loadEnvFile, createHandler as nextHandler, parseDate, pickDefined, setCoreDependencies, setNestedProperty, snakeToCamel, toBoolean, trimString };
+export { ApiClientService, BACKEND_EXAMPLE_DOMAIN_SERVICE, BackendExampleDomainService, BaseBackendDomainService, BaseDomainService, BaseMapper, BaseValidator, CORE_DB_SERVICE, CORE_ENV, CORE_OPTIONS, CacheKeyBuilder, CacheManager, CacheService, Caching, ConditionUtils, ContextUtils, Core, CoreEventManager, CoreModule, DEFAULT_ENCRYPTION_FIELDS, DbService, ErrorHandlingInterceptor, ExampleController, ExampleModule, FeatureDisabled, FeatureEnabled, FeatureFlagConfigFactory, FeatureFlagConfigValidator, FeatureFlagContextBuilder, FeatureFlagController, FeatureFlagDatabaseRepository, FeatureFlagDomainService, FeatureFlagEngine, FeatureFlagGuard, FeatureFlagLoggingInterceptor, FeatureFlagMiddleware, FeatureFlagModule, FeatureFlagService, FeatureFlagServiceFactory, HashUtils, IdUtils, NotificationService, ObjectUtils, PACKAGE_NAME, ServiceRegistry, StorageService, TABLE_REGISTRY, VERSION, ValueUtils, backendExampleDomainService, backendExampleDomainService as backendExampleService, camelToSnake, clearCoreDependencies, createApiClientInstance, createBackendContext, createFrontendContext, createHandler, createRolloutIdentifier, createStandaloneApiClient, detectRuntime, evaluateArrayOperator, evaluateConditionOperator, evaluateEqualityOperator, evaluateNumericOperator, evaluateStringOperator, backendExampleDomainService as exampleService, formatDate, generateCorrelationId, generateId, generateShortId, generateSpanId, generateTraceId, getApiClient, getCacheService, getCoreDependencies, getCoreDependency, getNestedProperty, getPackageVersion, getValidProviders, hasCoreDependency, hasNestedProperty, hashString, initApiClient, isArrayOperator, isDefined, isEqualityOperator, isInRollout, isNumber, isNumericOperator, isString, isStringOperator, isTruthy, keysToCamel, keysToSnake, loadEnvFile, createHandler as nextHandler, parseDate, pickDefined, setCoreDependencies, setNestedProperty, snakeToCamel, toBoolean, trimString };
 //# sourceMappingURL=entry-backend.mjs.map
 //# sourceMappingURL=entry-backend.mjs.map