@plyaz/core 1.8.4 → 1.9.0

package/dist/entry-frontend-browser.mjs

@@ -1,10 +1,10 @@
 import { HTTP_STATUS as HTTP_STATUS$1, CACHE_MAX_SIZE_DEFAULT, CACHE_CLEANUP_INTERVAL_DEFAULT, TIME_CONSTANTS, DEVELOPMENT_CONFIG, STAGING_CONFIG, PRODUCTION_CONFIG, MATH_CONSTANTS, ISO_STANDARDS, FNV_CONSTANTS } from '@plyaz/config';
 import { HTTP_STATUS, ERROR_CATEGORY, ERROR_CODES, CORE_EVENTS, PACKAGE_STATUS_CODES, API_ERROR_CODES, OPERATIONS, BACKEND_RUNTIMES, FRONTEND_RUNTIMES } from '@plyaz/types';
-import { generateRequestId, CorePackageError, initializeErrorSystem, BaseError, ValidateAndFormatErrors, ValidationError } from '@plyaz/errors';
+import { generateRequestId, CorePackageError, BaseError, initializeErrorSystem, ValidateAndFormatErrors, ValidationError } from '@plyaz/errors';
 import { PackageLogger } from '@plyaz/logger';
 import { mergeConfigs, createApiClient, ApiPackageError, setDefaultApiClient, evaluateAllFeatureFlags, createFeatureFlag, updateFeatureFlag, deleteFeatureFlag, fetchFeatureFlagRules, ApiProvider as ApiProvider$1 } from '@plyaz/api/frontend';
 import { EventEmitter } from 'events';
-import { ERROR_CODES as ERROR_CODES$1, API_ERROR_CODES as API_ERROR_CODES$1 } from '@plyaz/types/errors';
+import { ERROR_CODES as ERROR_CODES$1, ERROR_CATEGORY as ERROR_CATEGORY$1, 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';
@@ -244,6 +244,14 @@ var HEX_RADIX = 16;
 var HEX_SLICE_START = 2;
 var HEX_SLICE_END = 18;
 var SPAN_ID_LENGTH = 16;
+function generateId() {
+  const cryptoApi = globalThis.crypto;
+  if (cryptoApi?.randomUUID) {
+    return cryptoApi.randomUUID();
+  }
+  return `${Date.now()}-${Math.random().toString(RANDOM_ID_RADIX).slice(RANDOM_ID_SLICE_START)}`;
+}
+__name(generateId, "generateId");
 function generateShortId() {
   const cryptoApi = globalThis.crypto;
   if (cryptoApi?.randomUUID) {
@@ -556,6 +564,80 @@ var ApiClientService = class _ApiClientService {
   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.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.SYSTEM.ERROR, { errors: [serializedError] });
+        } else {
+          const serializedErrors = errorDetails.map(
+            (detail, index) => ({
+              id: `${requestId}-${index}`,
+              code: detail.errorCode ?? ERROR_CODES.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.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
    *
@@ -593,71 +675,12 @@ var ApiClientService = class _ApiClientService {
    * 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.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.SYSTEM.ERROR, { errors: [serializedError] });
-          } else {
-            const serializedErrors = errorDetails.map(
-              (detail, index) => ({
-                id: `${requestId}-${index}`,
-                code: detail.errorCode ?? ERROR_CODES.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.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(
@@ -832,11 +855,13 @@ var ApiClientService = class _ApiClientService {
     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;
@@ -858,6 +883,61 @@ var ApiClientService = class _ApiClientService {
       );
     }
   }
+  /**
+   * 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)
+            }
+          }
+        }
+      );
+    }
+  }
 };
 var BaseAdapter = class {
   constructor() {
@@ -3414,6 +3494,7 @@ var Core = class _Core {
       _Core._errorHandler.destroy();
       _Core._errorHandler = null;
       clearEventEmitter();
+      BaseError.clearEventEmitter();
     }
     _Core._errorConfig = {};
     _Core._httpErrorHandler = null;
@@ -3602,6 +3683,28 @@ var Core = class _Core {
       };
     }
   }
+  /**
+   * 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.UNKNOWN_ERROR,
+      message: error.message,
+      status: error.statusCode,
+      category: error.category ?? ERROR_CATEGORY$1.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) {
@@ -3613,12 +3716,17 @@ var Core = class _Core {
     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
     };
@@ -3639,6 +3747,15 @@ var Core = class _Core {
     });
     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$1.SYSTEM.ERROR, {
+        errors: [serializedError],
+        context: serviceName,
+        recoverable: error.retryable ?? false
+      });
+    });
     const errorStore = _Core.getErrorStoreActions();
     _Core._errorHandler = initializeGlobalErrorHandler(
       errorStore,
@@ -3734,9 +3851,15 @@ var Core = class _Core {
   }
   /**
    * 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: Database errors (DATABASE.ERROR) are only subscribed on backend runtimes since
+   * NOTE: SYSTEM.ERROR is NOT subscribed here - it's handled in initializeErrorHandler()
+   * via the BaseError.setEventEmitter() + addErrors() pattern to avoid duplicate subscriptions.
+   *
+   * 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) {
@@ -3744,78 +3867,36 @@ var Core = class _Core {
       return;
     }
     _Core.log("Subscribing to error events...", verbose);
-    const cleanupSystemError = CoreEventManager.on(CORE_EVENTS$1.SYSTEM.ERROR, (event) => {
-      if (_Core._errorHandler && event.data?.errors?.length) {
-        for (const err of event.data.errors) {
-          _Core._errorHandler.captureError(err, "system");
+    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);
         }
-      }
-    });
-    const cleanupEntityError = CoreEventManager.on(CORE_EVENTS$1.ENTITY.ERROR, (event) => {
-      if (_Core._errorHandler && event.data) {
-        _Core._errorHandler.captureError(event.data.error, "entity");
-      }
-    });
-    const cleanupApiError = CoreEventManager.on(CORE_EVENTS$1.API.REQUEST_ERROR, (event) => {
-      if (_Core._errorHandler && event.data) {
-        _Core._errorHandler.captureError(event.data.error, "api");
-      }
-    });
-    const cleanupValidationError = CoreEventManager.on(CORE_EVENTS$1.VALIDATION.FAILED, (event) => {
-      if (_Core._errorHandler && event.data) {
-        _Core._errorHandler.captureError(event.data.error, "validation");
-      }
-    });
-    const cleanupAuthUnauthorized = CoreEventManager.on(CORE_EVENTS$1.AUTH.UNAUTHORIZED, (event) => {
-      if (_Core._errorHandler && event.data?.error) {
-        _Core._errorHandler.captureError(event.data.error, "auth");
-      }
-    });
-    const cleanupAuthSessionExpired = CoreEventManager.on(
-      CORE_EVENTS$1.AUTH.SESSION_EXPIRED,
-      (event) => {
-        if (_Core._errorHandler && event.data?.error) {
-          _Core._errorHandler.captureError(event.data.error, "auth");
-        }
-      }
-    );
+      });
+    }, "subscribeError");
     _Core._eventCleanupFns.push(
-      cleanupSystemError,
-      cleanupEntityError,
-      cleanupApiError,
-      cleanupValidationError,
-      cleanupAuthUnauthorized,
-      cleanupAuthSessionExpired
+      subscribeError(CORE_EVENTS$1.ENTITY.ERROR, "entity"),
+      subscribeError(CORE_EVENTS$1.API.REQUEST_ERROR, "api"),
+      subscribeError(CORE_EVENTS$1.VALIDATION.FAILED, "validation"),
+      subscribeError(CORE_EVENTS$1.AUTH.UNAUTHORIZED, "auth"),
+      subscribeError(CORE_EVENTS$1.AUTH.SESSION_EXPIRED, "auth")
     );
     if (_Core.isRuntimeCompatible("backend")) {
-      const cleanupDatabaseError = CoreEventManager.on(CORE_EVENTS$1.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$1.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$1.NOTIFICATION.ERROR,
-        (event) => {
-          if (_Core._errorHandler && event.data) {
-            _Core._errorHandler.captureError(event.data.error, "notification");
-          }
-        }
+      _Core._eventCleanupFns.push(
+        subscribeError(CORE_EVENTS$1.DATABASE.ERROR, "database"),
+        subscribeError(CORE_EVENTS$1.STORAGE.ERROR, "storage"),
+        subscribeError(CORE_EVENTS$1.NOTIFICATION.ERROR, "notification"),
+        subscribeError(CORE_EVENTS$1.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) {
@@ -4062,6 +4143,11 @@ var BaseDomainService = class {
   /**
    * 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) {
@@ -4069,7 +4155,7 @@ var BaseDomainService = class {
     }
     this._clientInitPromise = (async () => {
       try {
-        this._apiClient = await createApiClient(this._apiClientConfig);
+        this._apiClient = await ApiClientService.createStandaloneClient(this._apiClientConfig);
         if (this._setAsDefaultClient) {
           setDefaultApiClient(this._apiClient);
         }
@@ -7978,7 +8064,11 @@ async function initializeCore(config) {
       apiKey: config.api.apiKey,
       setAsDefault: true,
       ...apiConfig
-    }
+    },
+    // Feature flags config (passed to Core for memory provider setup)
+    featureFlags: config.featureFlags
+    // Error handler is auto-initialized by Core.initialize()
+    // Store (Zustand) is auto-connected via useRootStore in Core.initializeRootStore()
   });
 }
 __name(initializeCore, "initializeCore");