@plyaz/core 1.1.1 → 1.2.1

package/dist/services/DbService.d.ts

@@ -0,0 +1,391 @@
+/**
+ * DbService - Singleton Database Connection Manager
+ *
+ * @description Manages database connections for the entire application using a singleton pattern.
+ * This service wraps @plyaz/db and provides a centralized way to initialize and access
+ * the database across all domains (feature flags, users, campaigns, backoffice, etc.).
+ *
+ * **Architecture:**
+ * - Uses `createDatabaseService()` from @plyaz/db which builds an adapter chain
+ * - Supports Drizzle (direct PostgreSQL), Supabase (REST API), or raw SQL adapters
+ * - Extension layers: Encryption → SoftDelete → Caching → Audit → ReadReplica
+ *
+ * **Adapter Configuration:**
+ * - **Drizzle**: Requires `connectionString` (PostgreSQL URL)
+ * - **Supabase**: Requires `supabaseUrl`, `supabaseServiceKey`, `supabaseAnonKey`
+ * - **SQL**: Requires `connectionString`
+ *
+ * **Required Environment Variables (Drizzle with Supabase):**
+ * - DATABASE_URL: PostgreSQL connection string (from Supabase Dashboard > Database > URI)
+ *
+ * **Required Environment Variables (Supabase REST API):**
+ * - SUPABASE_URL: Your Supabase project URL
+ * - SUPABASE_SERVICE_ROLE_KEY: Service role key for admin operations
+ * - SUPABASE_ANON_PUBLIC_KEY: Anonymous key for public operations
+ *
+ * @example Using with Core.initialize() (Recommended)
+ * ```typescript
+ * import { Core } from '@plyaz/core';
+ *
+ * // Core.initialize() handles loading env and passing to DbService
+ * await Core.initialize({
+ *   envPath: '.env',
+ *   db: {
+ *     adapter: 'sql',
+ *     cache: { enabled: true, ttl: 60 },
+ *   },
+ * });
+ *
+ * // Access via Core.db
+ * const db = Core.db.getDatabase();
+ * const result = await db.list('users', { pagination: { limit: 10, offset: 0 } });
+ * ```
+ *
+ * @example Direct Usage (requires explicit config)
+ * ```typescript
+ * // Direct usage requires explicit connectionString
+ * await DbService.initialize({
+ *   adapter: 'drizzle',
+ *   drizzle: {
+ *     connectionString: 'postgresql://user:pass@localhost:5432/db',
+ *     poolSize: 20,
+ *   },
+ * });
+ * ```
+ *
+ * @example With Extensions
+ * ```typescript
+ * await Core.initialize({
+ *   envPath: '.env',
+ *   db: {
+ *     adapter: 'drizzle',
+ *     softDelete: {
+ *       enabled: true,
+ *       field: 'deleted_at',
+ *       excludeTables: ['audit_logs', 'feature_flag_evaluations'],
+ *     },
+ *     cache: {
+ *       enabled: true,
+ *       provider: 'memory',
+ *       ttl: 300,
+ *     },
+ *     audit: {
+ *       enabled: true,
+ *       retentionDays: 90,
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example Using with BaseRepository
+ * ```typescript
+ * import { BaseRepository } from '@plyaz/db';
+ * import { DbService } from '@plyaz/core';
+ *
+ * class UserRepository extends BaseRepository<User> {
+ *   constructor() {
+ *     super(DbService.getInstance().getDatabase(), 'users');
+ *   }
+ * }
+ * ```
+ *
+ * @module services
+ */
+import { type DatabaseServiceInterface, type Transaction } from '@plyaz/types/db';
+/**
+ * Default fields to encrypt per table
+ * Contains sensitive PII and financial data that should be encrypted at rest
+ *
+ * @see docs/db-schemas/dbdiagram_schema.dbml for field definitions
+ */
+export declare const DEFAULT_ENCRYPTION_FIELDS: Record<string, string[]>;
+export type { CoreDbServiceConfig } from '@plyaz/types/core';
+import type { CoreDbServiceConfig as DbServiceConfig } from '@plyaz/types/core';
+/**
+ * Complete table registry from database migrations
+ * Maps logical table names to their ID columns
+ *
+ * @see docs/db-schemas/migrations/ for schema definitions
+ * @see docs/db-schemas/dbdiagram_schema.dbml for full schema
+ */
+/**
+ * TABLE_REGISTRY - Custom ID Column and Schema Registry
+ *
+ * ONLY register tables with:
+ * 1. Custom ID columns (anything other than 'id')
+ * 2. Custom database schemas (anything other than 'public')
+ *
+ * Tables with standard 'id' column in 'public' schema do NOT need registration.
+ * You can also override ID column and schema per-query using OperationConfig.
+ *
+ * Schema can be defined in the table key or in the config object (or both):
+ * - 'schema.table': { idColumn: 'key' }              ← Schema in key only
+ * - 'schema.table': { idColumn: 'key', schema: 'schema' } ← Redundant but allowed
+ * - 'schema.table': {}                                ← Empty config, schema in key
+ * - 'table': { idColumn: 'key', schema: 'schema' }   ← Schema in config only
+ *
+ * @example
+ * ```typescript
+ * // Using registry
+ * await db.get('feature_flags', 'my-flag-key'); // Uses 'key' column from registry
+ *
+ * // Per-query override
+ * await db.get('custom_table', 'some-key', { idColumn: 'custom_id' });
+ *
+ * // Schema override
+ * await db.get('logs', '123', { schema: 'logging' });
+ * ```
+ */
+export declare const TABLE_REGISTRY: Record<string, {
+    idColumn?: string;
+    schema?: string;
+}>;
+/**
+ * DbService - Singleton Database Connection Manager
+ *
+ * Provides centralized database connection management for all domains.
+ * Uses @plyaz/db under the hood with configurable adapters and extensions.
+ */
+export declare class DbService {
+    private static instance;
+    private databaseService;
+    private namedAdapters;
+    private config;
+    private initialized;
+    private constructor();
+    /**
+     * Emits a database error event via CoreEventManager.
+     * Called when database operations fail to integrate with global error handling.
+     *
+     * @param error - The error that occurred
+     * @param operation - The operation that failed (e.g., 'transaction', 'query', 'healthCheck')
+     * @param table - Optional table name involved in the operation
+     * @param query - Optional query string that failed
+     * @param recoverable - Whether the error is recoverable (default: false)
+     */
+    private emitDatabaseError;
+    /**
+     * Gets the singleton instance of DbService
+     *
+     * @returns {DbService} The singleton instance
+     */
+    static getInstance(): DbService;
+    /**
+     * Checks if the database service has been initialized
+     *
+     * @returns {boolean} True if initialized
+     */
+    static isInitialized(): boolean;
+    /**
+     * Resets the database service by closing connections and clearing the singleton instance
+     *
+     * @description Properly closes the database connection and clears the singleton.
+     * Useful for testing or when you need to reinitialize with different configuration.
+     *
+     * @example
+     * ```typescript
+     * await DbService.reset();
+     * await DbService.initialize({ adapter: 'sql', ... });
+     * ```
+     */
+    static reset(): Promise<void>;
+    /**
+     * Initializes the database connection
+     *
+     * @description Sets up the database connection using the provided configuration
+     * or environment variables. This method is idempotent - calling it multiple
+     * times won't create additional connections.
+     *
+     * **Environment Variables:**
+     * - `DATABASE_URL` - PostgreSQL connection string (for sql/drizzle adapters)
+     * - `ENCRYPTION_KEY` - 32-byte encryption key for field encryption (optional)
+     * - `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_ANON_PUBLIC_KEY` - For supabase adapter
+     *
+     * **Encryption:** If `ENCRYPTION_KEY` env is set, encryption is auto-enabled
+     * using `DEFAULT_ENCRYPTION_FIELDS`. Override via config.encryption.
+     *
+     * @param {DbServiceConfig} [config] - Optional configuration
+     * @returns {Promise<DbService>} The initialized DbService instance
+     * @throws {DatabasePackageError} When configuration is invalid or connection fails
+     *
+     * @example
+     * ```typescript
+     * // Minimal - uses DATABASE_URL env, auto-enables encryption if ENCRYPTION_KEY set
+     * await DbService.initialize();
+     *
+     * // With explicit encryption
+     * await DbService.initialize({
+     *   adapter: 'sql',
+     *   encryption: {
+     *     enabled: true,
+     *     key: 'your-32-byte-encryption-key-here!!',
+     *     fields: DEFAULT_ENCRYPTION_FIELDS,
+     *   },
+     * });
+     *
+     * // Or via Core.initialize() with env:
+     * await Core.initialize({
+     *   env: { ENCRYPTION_KEY: '...' },
+     *   db: { adapter: 'sql' },
+     * });
+     * ```
+     */
+    /** Build encryption config from user config */
+    private static buildEncryptionConfig;
+    /** Merge user config with defaults */
+    private static mergeConfig;
+    /** Initialize named adapters */
+    private initializeNamedAdapters;
+    static initialize(config?: DbServiceConfig): Promise<DbService>;
+    /**
+     * Builds the DatabaseServiceConfig based on the adapter type
+     * @private
+     */
+    /** Builds adapter-specific config based on adapter type */
+    private buildAdapterConfig;
+    /** Builds soft delete extension config */
+    private buildSoftDeleteExtension;
+    /** Builds cache extension config */
+    private buildCacheExtension;
+    /** Builds audit extension config */
+    private buildAuditExtension;
+    /** Builds encryption extension config */
+    private buildEncryptionExtension;
+    private buildDatabaseConfig;
+    /**
+     * Builds Drizzle adapter configuration
+     * @private
+     */
+    private buildDrizzleConfig;
+    /**
+     * Builds Supabase adapter configuration
+     * @private
+     */
+    private buildSupabaseConfig;
+    /**
+     * Builds SQL adapter configuration
+     * @private
+     */
+    private buildSqlConfig;
+    /**
+     * Builds table ID column mappings from TABLE_REGISTRY
+     * @private
+     * @returns Record of table names to ID column names
+     */
+    private buildTableIdColumns;
+    /**
+     * Gets the initialized database service instance
+     *
+     * @param {string} [adapterName] - Optional named adapter to use instead of default
+     * @returns {DatabaseServiceInterface} The database service instance
+     * @throws {DatabasePackageError} When database is not initialized or named adapter not found
+     */
+    getDatabase(adapterName?: string): DatabaseServiceInterface;
+    /**
+     * Gets a named adapter by name
+     *
+     * @param {string} name - The name of the adapter
+     * @returns {DatabaseServiceInterface} The named adapter instance
+     * @throws {DatabasePackageError} When adapter not found
+     */
+    getAdapter(name: string): DatabaseServiceInterface;
+    /**
+     * Lists all available named adapters
+     *
+     * @returns {string[]} Array of adapter names
+     */
+    getAvailableAdapters(): string[];
+    /**
+     * Executes a database transaction with automatic rollback on failure
+     *
+     * @template T The return type of the transaction callback
+     * @param {Function} callback - Function that receives transaction object
+     * @returns {Promise<T>} The result of the transaction callback
+     * @throws {DatabasePackageError} When transaction fails
+     */
+    transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;
+    /**
+     * Sets audit context for subsequent operations
+     *
+     * @param context - Audit context (userId, requestId, etc.)
+     */
+    setAuditContext(context: {
+        userId?: string;
+        requestId?: string;
+        ipAddress?: string;
+        userAgent?: string;
+    }): Promise<void>;
+    /**
+     * Performs a health check on the database connection
+     *
+     * @returns Health check result
+     */
+    healthCheck(): Promise<{
+        isHealthy: boolean;
+        responseTime?: number;
+        error?: string;
+    }>;
+    /**
+     * Gets the table registry with all known tables and their ID columns
+     *
+     * @returns The complete table registry
+     */
+    static getTableRegistry(): typeof TABLE_REGISTRY;
+    /**
+     * Gets ID column for a specific table
+     *
+     * @param tableName - Name of the table
+     * @returns ID column name or 'id' as default
+     */
+    static getTableIdColumn(tableName: string): string;
+    /**
+     * Reinitializes the database connection with new config
+     *
+     * @param {DbServiceConfig} [config] - New configuration
+     * @returns {Promise<DbService>} The reinitialized DbService instance
+     */
+    static reinitialize(config?: DbServiceConfig): Promise<DbService>;
+    /**
+     * Closes the database connection and cleans up resources
+     */
+    close(): Promise<void>;
+    /**
+     * Gets the current configuration
+     *
+     * @returns {DbServiceConfig | null} Current config or null if not initialized
+     */
+    getConfig(): DbServiceConfig | null;
+    /**
+     * Gets the current adapter type
+     *
+     * @returns The adapter type or null if not initialized
+     */
+    getAdapterType(): 'drizzle' | 'supabase' | 'sql' | null;
+    /**
+     * Creates a dedicated database service instance (NOT the singleton)
+     *
+     * Use this when you need an isolated database connection with its own configuration
+     * that doesn't affect or get affected by the shared singleton instance.
+     *
+     * @param config - Database service configuration
+     * @returns Promise that resolves to a new dedicated DbService instance
+     *
+     * @example
+     * ```typescript
+     * // Create a dedicated instance for analytics database
+     * const analyticsDb = await DbService.createInstance({
+     *   adapter: 'sql',
+     *   sql: { connectionString: process.env.ANALYTICS_DB_URL },
+     *   cache: { enabled: false }, // No caching for analytics
+     * });
+     *
+     * // This instance is independent from DbService.getInstance()
+     * const data = await analyticsDb.getDatabase().list('events');
+     *
+     * // Clean up when done
+     * await analyticsDb.close();
+     * ```
+     */
+    static createInstance(config: DbServiceConfig): Promise<DbService>;
+}
+//# sourceMappingURL=DbService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DbService.d.ts","sourceRoot":"","sources":["../../src/services/DbService.ts"],"names":[],"mappings":"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"}

package/dist/services/NotificationService.d.ts

@@ -0,0 +1,151 @@
+/**
+ * NotificationService - Singleton Notification Manager
+ *
+ * @description Manages notification delivery for the entire application using a singleton pattern.
+ * This service wraps @plyaz/notifications and provides a centralized way to initialize and access
+ * notification capabilities across all domains (transactional, marketing, system alerts, etc.).
+ *
+ * **Architecture:**
+ * - Uses `NotificationService` from @plyaz/notifications which supports multi-provider setup
+ * - Supports email (Infobip primary, SendGrid fallback), SMS, and push notifications
+ * - Automatic failover between providers based on health status
+ * - Event-driven architecture for tracking delivery, opens, clicks
+ * - **Proxy-based method forwarding**: All methods from the underlying service are
+ *   automatically available with error handling - no manual wrapping needed
+ *
+ * **Provider Configuration:**
+ * - **Infobip**: Primary email provider (unified omnichannel platform)
+ * - **SendGrid**: Fallback email provider for transactional emails
+ *
+ * **Required Environment Variables (Infobip):**
+ * - INFOBIP_API_KEY: Your Infobip API key
+ * - INFOBIP_BASE_URL: Infobip API base URL
+ * - FROM_EMAIL: Default sender email address
+ *
+ * **Required Environment Variables (SendGrid):**
+ * - SENDGRID_API_KEY: Your SendGrid API key
+ * - FROM_EMAIL: Default sender email address
+ *
+ * @example Using with Core.initialize() (Recommended)
+ * ```typescript
+ * import { Core } from '@plyaz/core';
+ *
+ * await Core.initialize({
+ *   notifications: {
+ *     providers: {
+ *       email: [infobipAdapter, sendGridAdapter],
+ *       sms: [],
+ *       push: [],
+ *     },
+ *     events: {
+ *       onSent: (event) => console.log('Notification sent:', event),
+ *       onFailed: (event) => console.error('Notification failed:', event),
+ *     },
+ *   },
+ * });
+ *
+ * // Access via Core.notifications - all methods automatically available
+ * await Core.notifications.sendEmail({
+ *   recipientId: 'user-123',
+ *   to: 'user@example.com',
+ *   templateId: 'welcome',
+ *   templateData: { userName: 'John' },
+ * });
+ * ```
+ *
+ * @module services
+ */
+import { NotificationService as NotificationServiceImpl } from '@plyaz/notifications';
+import type { CoreNotificationConfig } from '@plyaz/types/core';
+export type { CoreNotificationConfig } from '@plyaz/types/core';
+/**
+ * NotificationService - Singleton Notification Manager with Proxy-based method forwarding
+ *
+ * Provides centralized notification management for all domains.
+ * Uses @plyaz/notifications under the hood with configurable providers and templates.
+ *
+ * All methods from the underlying NotificationServiceImpl are automatically available
+ * via Proxy - when new methods are added to @plyaz/notifications, they're instantly
+ * accessible here with automatic error handling.
+ */
+export declare class NotificationService {
+    private static instance;
+    private notificationService;
+    private config;
+    private initialized;
+    private constructor();
+    /**
+     * Emits a notification error event via CoreEventManager.
+     * Called when notification operations fail to integrate with global error handling.
+     */
+    private emitNotificationError;
+    /**
+     * Gets the singleton instance of NotificationService
+     */
+    static getInstance(): NotificationService;
+    /**
+     * Checks if the notification service has been initialized
+     */
+    static isInitialized(): boolean;
+    /**
+     * Resets the notification service by clearing the singleton instance
+     */
+    static reset(): Promise<void>;
+    /**
+     * Initializes the notification service
+     *
+     * @param config - Notification service configuration
+     * @returns The initialized NotificationService instance
+     */
+    static initialize(config: CoreNotificationConfig): Promise<NotificationService>;
+    /**
+     * Gets the raw underlying notification service instance without error handling wrapper.
+     * Use this only if you need direct access to the underlying service.
+     *
+     * @returns The raw NotificationService instance from @plyaz/notifications
+     * @throws {NotificationsPackageError} When notifications is not initialized
+     */
+    private getRawNotifications;
+    /**
+     * Gets the notification service with automatic error handling.
+     * All method calls are wrapped with try/catch and emit error events on failure.
+     * Any method added to @plyaz/notifications will be automatically available.
+     *
+     * @example
+     * ```typescript
+     * const notifications = NotificationService.getInstance().getNotifications();
+     * await notifications.sendEmail({ to: 'user@example.com', templateId: 'welcome' });
+     * await notifications.sendSMS({ to: '+1234567890', message: 'Hello!' });
+     * ```
+     *
+     * @returns NotificationServiceImpl with automatic error handling
+     */
+    getNotifications(): NotificationServiceImpl;
+    /**
+     * Performs a health check on the notification service.
+     * This method has special handling to transform the response format.
+     */
+    healthCheck(): Promise<{
+        isHealthy: boolean;
+        providers?: unknown[];
+        error?: string;
+    }>;
+    /**
+     * Gets the current configuration
+     */
+    getConfig(): CoreNotificationConfig | null;
+    /**
+     * Closes the notification service and cleans up resources
+     */
+    close(): Promise<void>;
+    /**
+     * Creates a dedicated notification service instance (NOT the singleton)
+     *
+     * Use this when you need an isolated notification service with its own configuration.
+     *
+     * @param config - Notification service configuration
+     * @returns Promise that resolves to a new dedicated NotificationService instance
+     */
+    static createInstance(config: CoreNotificationConfig): Promise<NotificationService>;
+}
+//# sourceMappingURL=NotificationService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationService.d.ts","sourceRoot":"","sources":["../../src/services/NotificationService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,OAAO,EAAE,mBAAmB,IAAI,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEtF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAMhE,YAAY,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAShE;;;;;;;;;GASG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAoC;IAC3D,OAAO,CAAC,mBAAmB,CAAwC;IACnE,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO;IAMP;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAmB7B;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,mBAAmB;IAKzC;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,OAAO;IAI/B;;OAEG;WACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IASnC;;;;;OAKG;WACU,UAAU,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAcrF;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAc3B;;;;;;;;;;;;;OAaG;IACH,gBAAgB,IAAI,uBAAuB;IA6C3C;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAyB3F;;OAEG;IACH,SAAS,IAAI,sBAAsB,GAAG,IAAI;IAI1C;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAM5B;;;;;;;OAOG;WACU,cAAc,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAO1F"}

package/dist/services/StorageService.d.ts

@@ -0,0 +1,144 @@
+/**
+ * StorageService - Singleton File Storage Manager
+ *
+ * @description Manages file storage operations for the entire application using a singleton pattern.
+ * This service wraps @plyaz/storage and provides a centralized way to initialize and access
+ * file storage across all domains (media uploads, compliance documents, user avatars, etc.).
+ *
+ * **Architecture:**
+ * - Uses `StorageService` from @plyaz/storage which supports multi-provider setup
+ * - Supports Cloudflare R2 (compliance documents) and Supabase Storage (assets/media)
+ * - Automatic failover between providers based on health status
+ * - Event-driven architecture with 40+ event types
+ * - **Proxy-based method forwarding**: All methods from the underlying service are
+ *   automatically available with error handling - no manual wrapping needed
+ *
+ * **Provider Configuration:**
+ * - **Cloudflare R2**: For compliance documents (tax, invoices, KYC) with zero egress fees
+ * - **Supabase Storage**: For assets like images, user avatars, media files
+ *
+ * **Required Environment Variables (Cloudflare R2):**
+ * - CLOUDFLARE_ACCOUNT_ID: Your Cloudflare account ID
+ * - R2_ACCESS_KEY_ID: R2 access key
+ * - R2_SECRET_ACCESS_KEY: R2 secret key
+ * - R2_BUCKET_NAME: Default bucket name
+ *
+ * **Required Environment Variables (Supabase Storage):**
+ * - SUPABASE_URL: Your Supabase project URL
+ * - SUPABASE_SERVICE_ROLE_KEY: Service role key for storage operations
+ *
+ * @example Using with Core.initialize() (Recommended)
+ * ```typescript
+ * import { Core } from '@plyaz/core';
+ *
+ * await Core.initialize({
+ *   storage: {
+ *     adapters: [r2Adapter, supabaseAdapter],
+ *     plugins: [virusScanPlugin, sharpImagePlugin],
+ *   },
+ * });
+ *
+ * // Access via Core.storage - all methods automatically available
+ * const result = await Core.storage.uploadFile({
+ *   file: buffer,
+ *   filename: 'document.pdf',
+ *   category: FILE_CATEGORY.COMPLIANCE_DOCUMENT,
+ * });
+ * ```
+ *
+ * @module services
+ */
+import { StorageService as StorageServiceImpl } from '@plyaz/storage';
+import type { CoreStorageConfig } from '@plyaz/types/core';
+export type { CoreStorageConfig } from '@plyaz/types/core';
+/**
+ * StorageService - Singleton File Storage Manager with Proxy-based method forwarding
+ *
+ * Provides centralized file storage management for all domains.
+ * Uses @plyaz/storage under the hood with configurable providers and plugins.
+ *
+ * All methods from the underlying StorageServiceImpl are automatically available
+ * via Proxy - when new methods are added to @plyaz/storage, they're instantly
+ * accessible here with automatic error handling.
+ */
+export declare class StorageService {
+    private static instance;
+    private storageService;
+    private config;
+    private initialized;
+    private constructor();
+    /**
+     * Emits a storage error event via CoreEventManager.
+     * Called when storage operations fail to integrate with global error handling.
+     */
+    private emitStorageError;
+    /**
+     * Gets the singleton instance of StorageService
+     */
+    static getInstance(): StorageService;
+    /**
+     * Checks if the storage service has been initialized
+     */
+    static isInitialized(): boolean;
+    /**
+     * Resets the storage service by clearing the singleton instance
+     */
+    static reset(): Promise<void>;
+    /**
+     * Initializes the storage service
+     *
+     * @param config - Storage service configuration
+     * @returns The initialized StorageService instance
+     */
+    static initialize(config: CoreStorageConfig): Promise<StorageService>;
+    /**
+     * Gets the raw underlying storage service instance without error handling wrapper.
+     * Use this only if you need direct access to the underlying service.
+     *
+     * @returns The raw StorageService instance from @plyaz/storage
+     * @throws {StoragePackageError} When storage is not initialized
+     */
+    private getRawStorage;
+    /**
+     * Gets the storage service with automatic error handling.
+     * All method calls are wrapped with try/catch and emit error events on failure.
+     * Any method added to @plyaz/storage will be automatically available.
+     *
+     * @example
+     * ```typescript
+     * const storage = StorageService.getInstance().getStorage();
+     * await storage.uploadFile({ file, filename: 'doc.pdf' });
+     * await storage.deleteFile({ fileId: '123' });
+     * ```
+     *
+     * @returns StorageServiceImpl with automatic error handling
+     */
+    getStorage(): StorageServiceImpl;
+    /**
+     * Performs a health check on the storage service by checking all adapter health.
+     * This method has special handling to transform the response format.
+     */
+    healthCheck(): Promise<{
+        isHealthy: boolean;
+        responseTime?: number;
+        error?: string;
+    }>;
+    /**
+     * Gets the current configuration
+     */
+    getConfig(): CoreStorageConfig | null;
+    /**
+     * Closes the storage service and cleans up resources
+     */
+    close(): Promise<void>;
+    /**
+     * Creates a dedicated storage service instance (NOT the singleton)
+     *
+     * Use this when you need an isolated storage connection with its own configuration.
+     *
+     * @param config - Storage service configuration
+     * @returns Promise that resolves to a new dedicated StorageService instance
+     */
+    static createInstance(config: CoreStorageConfig): Promise<StorageService>;
+}
+//# sourceMappingURL=StorageService.d.ts.map