@plyaz/core 1.1.1 → 1.2.1

package/dist/services/ApiClientService.d.ts

@@ -0,0 +1,178 @@
+/**
+ * API Client Singleton Service (@plyaz/core)
+ * Manages the API client with environment-specific configurations and intelligent defaults
+ *
+ * The app reads process.env and constructs ApiClientOptions, then passes to this service.
+ * Service never touches process.env directly - all env reading happens in the app layer.
+ *
+ * @module services/ApiClientService
+ */
+import type { ApiClientWithEvents, ApiClientOptions } from '@plyaz/types/api';
+import { type ClientEventManager, type EndpointsList } from '@plyaz/api';
+import type { CoreApiEnvironmentConfig } from '@plyaz/types/core';
+/**
+ * API Client Singleton Service
+ * Manages API client instance lifecycle with environment-specific configurations
+ *
+ * @example
+ * ```typescript
+ * // In your app initialization (Next.js, React, etc.)
+ * import { ApiClientService } from '@plyaz/core';
+ *
+ * // Environment metadata
+ * const envConfig = {
+ *   env: process.env.NODE_ENV as 'production',
+ *   apiKey: process.env.API_KEY,
+ * };
+ *
+ * // API configuration with event handlers
+ * await ApiClientService.init(envConfig, {
+ *   baseURL: process.env.API_URL!,
+ *   encryption: {
+ *     key: {
+ *       id: 'prod-key-v1',
+ *       key: process.env.ENCRYPTION_KEY!,
+ *       algorithm: 'AES-GCM'
+ *     }
+ *   },
+ *   clientEvents: {
+ *     onRequestStart: (event) => apiStore.trackRequest(event),
+ *   },
+ * });
+ *
+ * // Later, anywhere in your app
+ * const client = ApiClientService.getClient();
+ * ```
+ */
+export declare class ApiClientService {
+    private static instance;
+    private static isInitializing;
+    private static initPromise;
+    /**
+     * 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 init(envConfig: CoreApiEnvironmentConfig, apiConfig?: Partial<ApiClientOptions>): Promise<ApiClientWithEvents<ClientEventManager, EndpointsList>>;
+    /**
+     * 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.)
+     */
+    private static createClient;
+    /**
+     * Get the initialized client instance
+     *
+     * @throws {ApiPackageError} If client not initialized
+     */
+    static getClient(): ApiClientWithEvents<ClientEventManager, EndpointsList>;
+    /**
+     * Check if client is initialized
+     */
+    static isInitialized(): boolean;
+    /**
+     * Reinitialize with new config and options
+     */
+    static reinitialize(envConfig: CoreApiEnvironmentConfig, apiConfig?: Partial<ApiClientOptions>): Promise<ApiClientWithEvents<ClientEventManager, EndpointsList>>;
+    /**
+     * Dispose of the client instance
+     */
+    static dispose(): void;
+    /**
+     * Emits an API error event via CoreEventManager.
+     * Called when API operations fail to integrate with global error handling.
+     *
+     * **CRITICAL**: This event emission triggers automatic error state updates.
+     * The global error store MUST subscribe to CORE_EVENTS.API.REQUEST_ERROR to:
+     * 1. Capture all API errors automatically
+     * 2. Update global error state for UI display
+     * 3. Ensure individual domain stores remain error-free (only domain data)
+     *
+     * This is the unified error hook that:
+     * - On frontend: Emits event that global error store subscribes to
+     * - On backend: Emits event for logging/monitoring (can be configured to rethrow)
+     *
+     * @param error - The error that occurred
+     * @param options - Additional context for the error
+     * @param options.method - HTTP method (GET, POST, etc.)
+     * @param options.url - Request URL
+     * @param options.requestId - Unique request identifier
+     * @param options.status - HTTP status code (if available)
+     * @param options.duration - Request duration in ms
+     * @param options.rethrow - Whether to rethrow the error after emitting (default: false)
+     *
+     * @example
+     * ```typescript
+     * // Global error store setup (in @plyaz/store)
+     * CoreEventManager.on(CORE_EVENTS.API.REQUEST_ERROR, (payload) => {
+     *   errorStore.setError({
+     *     message: payload.error.message,
+     *     status: payload.status,
+     *     url: payload.url,
+     *     requestId: payload.requestId,
+     *   });
+     * });
+     *
+     * // Frontend usage - emit to store
+     * ApiClientService.emitApiError(error, {
+     *   method: 'GET',
+     *   url: '/api/users',
+     *   requestId: '123',
+     *   duration: 500,
+     * });
+     *
+     * // Backend usage - emit and rethrow
+     * ApiClientService.emitApiError(error, {
+     *   method: 'POST',
+     *   url: '/api/orders',
+     *   requestId: '456',
+     *   duration: 1200,
+     *   rethrow: true,
+     * });
+     * ```
+     */
+    static emitApiError(error: unknown, options: {
+        method: string;
+        url: string;
+        requestId: string;
+        status?: number;
+        duration: number;
+        rethrow?: boolean;
+    }): void;
+    /**
+     * Create a dedicated API client instance (NOT the singleton)
+     *
+     * Use this when you need an isolated client with its own configuration
+     * that doesn't affect or get affected by the shared singleton instance.
+     *
+     * @param envConfig - Environment metadata (env, apiKey)
+     * @param apiConfig - API configuration (baseURL, encryption, timeout, etc.)
+     * @returns Promise that resolves to a new dedicated client instance
+     *
+     * @example
+     * ```typescript
+     * // Create a dedicated client for feature flags service
+     * const flagsClient = await ApiClientService.createInstance(
+     *   { env: 'production' },
+     *   {
+     *     baseURL: 'https://flags.example.com',
+     *     timeout: 5000,
+     *   }
+     * );
+     *
+     * // This client is independent from ApiClientService.getClient()
+     * flagsClient.updateConfig({ timeout: 3000 }); // Only affects this instance
+     * ```
+     */
+    static createInstance(envConfig: CoreApiEnvironmentConfig, apiConfig?: Partial<ApiClientOptions>): Promise<ApiClientWithEvents<ClientEventManager, EndpointsList>>;
+}
+export declare const getApiClient: () => ApiClientWithEvents<ClientEventManager, EndpointsList>;
+export declare const initApiClient: (envConfig: CoreApiEnvironmentConfig, apiConfig?: Partial<ApiClientOptions>) => Promise<ApiClientWithEvents<ClientEventManager, EndpointsList>>;
+export declare const createApiClientInstance: (envConfig: CoreApiEnvironmentConfig, apiConfig?: Partial<ApiClientOptions>) => Promise<ApiClientWithEvents<ClientEventManager, EndpointsList>>;
+//# sourceMappingURL=ApiClientService.d.ts.map

package/dist/services/ApiClientService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiClientService.d.ts","sourceRoot":"","sources":["../../src/services/ApiClientService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAa,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,aAAa,EAAmB,MAAM,YAAY,CAAC;AAW1F,OAAO,KAAK,EAA8B,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AA+c9F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAuE;IAC9F,OAAO,CAAC,MAAM,CAAC,cAAc,CAAS;IACtC,OAAO,CAAC,MAAM,CAAC,WAAW,CAA8B;IAExD;;;;;;OAMG;WACU,IAAI,CACf,SAAS,EAAE,wBAAwB,EACnC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACpC,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;IA4BlE;;;;;;;;OAQG;mBAEkB,YAAY;IAuIjC;;;;OAIG;IACH,MAAM,CAAC,SAAS,IAAI,mBAAmB,CAAC,kBAAkB,EAAE,aAAa,CAAC;IAmB1E;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,OAAO;IAI/B;;OAEG;WACU,YAAY,CACvB,SAAS,EAAE,wBAAwB,EACnC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACpC,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;IAKlE;;OAEG;IACH,MAAM,CAAC,OAAO,IAAI,IAAI;IAStB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoDG;IACH,MAAM,CAAC,YAAY,CACjB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,GACA,IAAI;IAkBP;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;WACU,cAAc,CACzB,SAAS,EAAE,wBAAwB,EACnC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACpC,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC;CA2CnE;AAGD,eAAO,MAAM,YAAY,QAAO,mBAAmB,CAAC,kBAAkB,EAAE,aAAa,CACvD,CAAC;AAE/B,eAAO,MAAM,aAAa,GACxB,WAAW,wBAAwB,EACnC,YAAY,OAAO,CAAC,gBAAgB,CAAC,KACpC,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,aAAa,CAAC,CACpB,CAAC;AAE9C,eAAO,MAAM,uBAAuB,GAClC,WAAW,wBAAwB,EACnC,YAAY,OAAO,CAAC,gBAAgB,CAAC,KACpC,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,aAAa,CAAC,CACV,CAAC"}

package/dist/services/CacheService.d.ts

@@ -0,0 +1,176 @@
+/**
+ * CacheService - Singleton Cache Manager
+ *
+ * @description Manages cache instance for the entire application using a singleton pattern.
+ * This service wraps the CacheManager from @plyaz/core/base/cache and provides a centralized
+ * way to initialize and access caching across all backend services.
+ *
+ * **Architecture:**
+ * - Supports multiple strategies: Memory (in-process), Redis (distributed)
+ * - Configurable TTL, key prefixing, and strategy-specific options
+ * - Singleton pattern ensures single cache instance across application
+ *
+ * **Strategy Configuration:**
+ * - **Memory**: In-process LRU cache, no external dependencies
+ * - **Redis**: Distributed cache using ioredis, requires Redis server
+ *
+ * **Required Environment Variables (Redis):**
+ * - REDIS_URL: Redis connection string (e.g., redis://localhost:6379)
+ * - Or REDIS_HOST, REDIS_PORT, REDIS_PASSWORD for individual config
+ *
+ * @example Using with Core.initialize() (Recommended)
+ * ```typescript
+ * import { Core } from '@plyaz/core';
+ *
+ * await Core.initialize({
+ *   envPath: '.env',
+ *   cache: {
+ *     strategy: 'memory',
+ *     isEnabled: true,
+ *     ttl: 300, // 5 minutes default
+ *   },
+ * });
+ *
+ * // Access via Core.cache
+ * const cache = Core.cache.getCacheManager();
+ * await cache.set('user:123', userData, 600); // 10 minutes TTL
+ * const cached = await cache.get('user:123');
+ * ```
+ *
+ * @example With Redis Strategy
+ * ```typescript
+ * await Core.initialize({
+ *   envPath: '.env',
+ *   cache: {
+ *     strategy: 'redis',
+ *     isEnabled: true,
+ *     ttl: 300,
+ *     prefix: 'myapp',
+ *     redis: {
+ *       url: process.env.REDIS_URL,
+ *       // Or individual options:
+ *       // host: process.env.REDIS_HOST,
+ *       // port: parseInt(process.env.REDIS_PORT),
+ *       // password: process.env.REDIS_PASSWORD,
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example Direct Usage
+ * ```typescript
+ * import { CacheService } from '@plyaz/core/services';
+ *
+ * await CacheService.initialize({
+ *   strategy: 'memory',
+ *   isEnabled: true,
+ *   ttl: 300,
+ * });
+ *
+ * const cache = CacheService.getInstance().getCacheManager();
+ * await cache.set('key', value);
+ * ```
+ *
+ * @example Skip Cache (Disable Caching)
+ * ```typescript
+ * await Core.initialize({
+ *   skipCache: true, // Cache will not be initialized
+ * });
+ * ```
+ *
+ * @fileoverview Cache service singleton
+ * @module services/CacheService
+ */
+import { CacheManager } from '../base/cache';
+import type { CoreCacheConfig } from '@plyaz/types/core';
+/**
+ * Singleton service for managing application-wide cache
+ *
+ * Provides centralized access to cache functionality across all backend services.
+ * Automatically integrates with BaseBackendDomainService when initialized.
+ */
+export declare class CacheService {
+    /** Singleton instance */
+    private static instance;
+    /** Cache manager instance */
+    private cacheManager;
+    /** Configuration used to initialize cache */
+    private config;
+    /** Logger instance */
+    private logger;
+    /** Private constructor to enforce singleton */
+    private constructor();
+    /**
+     * Initialize the cache service with configuration
+     *
+     * @param config - Cache configuration
+     * @throws {CorePackageError} If already initialized or config is invalid
+     *
+     * @example
+     * ```typescript
+     * await CacheService.initialize({
+     *   strategy: 'redis',
+     *   isEnabled: true,
+     *   ttl: 300,
+     *   prefix: 'app',
+     *   redis: { url: process.env.REDIS_URL },
+     * });
+     * ```
+     */
+    static initialize(config: CoreCacheConfig): Promise<void>;
+    /**
+     * Get the singleton instance
+     *
+     * @throws {CorePackageError} If not initialized
+     * @returns CacheService singleton instance
+     *
+     * @example
+     * ```typescript
+     * const cacheService = CacheService.getInstance();
+     * const cache = cacheService.getCacheManager();
+     * ```
+     */
+    static getInstance(): CacheService;
+    /**
+     * Get the cache manager instance
+     *
+     * @throws {CorePackageError} If cache not initialized
+     * @returns CacheManager instance
+     *
+     * @example
+     * ```typescript
+     * const cache = CacheService.getInstance().getCacheManager();
+     * await cache.set('user:123', userData);
+     * const user = await cache.get('user:123');
+     * ```
+     */
+    getCacheManager(): CacheManager;
+    /**
+     * Get current cache configuration
+     *
+     * @returns Current cache configuration or null if not initialized
+     */
+    getConfig(): CoreCacheConfig | null;
+    /**
+     * Check if cache is initialized and enabled
+     *
+     * @returns True if cache is ready to use
+     */
+    isInitialized(): boolean;
+    /**
+     * Reset the cache service (useful for testing)
+     *
+     * @internal
+     */
+    static reset(): void;
+    /**
+     * Validate cache configuration
+     *
+     * @param config - Configuration to validate
+     * @throws {CorePackageError} If configuration is invalid
+     * @private
+     */
+    private validateConfig;
+}
+export declare const getCacheService: () => CacheService;
+//# sourceMappingURL=CacheService.d.ts.map

package/dist/services/CacheService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheService.d.ts","sourceRoot":"","sources":["../../src/services/CacheService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMzD;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,yBAAyB;IACzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA6B;IAEpD,6BAA6B;IAC7B,OAAO,CAAC,YAAY,CAA6B;IAEjD,6CAA6C;IAC7C,OAAO,CAAC,MAAM,CAAgC;IAE9C,sBAAsB;IACtB,OAAO,CAAC,MAAM,CAA+C;IAE7D,+CAA+C;IAC/C,OAAO;IAEP;;;;;;;;;;;;;;;;OAgBG;WACU,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IA0C/D;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,WAAW,IAAI,YAAY;IAUlC;;;;;;;;;;;;OAYG;IACH,eAAe,IAAI,YAAY;IAU/B;;;;OAIG;IACH,SAAS,IAAI,eAAe,GAAG,IAAI;IAInC;;;;OAIG;IACH,aAAa,IAAI,OAAO;IAIxB;;;;OAIG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;IAWpB;;;;;;OAMG;IAEH,OAAO,CAAC,cAAc;CA6BvB;AAGD,eAAO,MAAM,eAAe,QAAO,YAA0C,CAAC"}