node-server-engine 1.10.14 → 1.11.0

package/README.md

@@ -17,7 +17,8 @@ Framework used to develop Node backend services. This package ships with a lot o
 - 🌐 **i18n** - Internationalization with translation management
 - 🔍 **ElasticSearch** - Full-text search integration (v9.2) with auto-migrations
 - 💾 **Redis** - Advanced Redis client with retry logic, TLS support (ioredis v5.8)
-- 📝 **API Documentation** - Swagger/OpenAPI documentation support
+- � **Secret Manager** - GCP Secret Manager integration for secure credential management
+- �📝 **API Documentation** - Swagger/OpenAPI documentation support
 - 📤 **File Uploads** - Single and chunked file upload middleware with validation
 - 🧪 **TypeScript** - Written in TypeScript with full type definitions
 - ✅ **Modern Tooling** - ESLint, Prettier, and automated versioning
@@ -59,6 +60,7 @@ Framework used to develop Node backend services. This package ships with a lot o
       - [Properties](#properties)
     - [Message Handler](#message-handler)
     - [Redis](#redis)
+    - [SecretManager](#secretmanager)
     - [Sequelize](#sequelize)
     - [Pub/Sub](#pubsub)
     - [PushNotification](#pushnotification)
@@ -214,6 +216,7 @@ server.init();
 | cron              | Array\<Object>                                                     | List of cronjob that are called on server start                                                                                                                                    | []                 |
 | shutdownCallbacks | Array\<Function>                                                   | List of functions that are called on server shutdown                                                                                                                               | []                 |
 | checkEnvironment  | Object                                                             | [Schema against which verify the environment variables](#environment-variables-verification), will cause server termination if the environment variables are not properly set.     | {}                 |
+| secretManager     | [SecretManagerOptions](#secretmanager)                             | Configuration for GCP Secret Manager integration. Loads secrets at startup before any other initialization.                                                                        | undefined          |
 | webSocket.server  | Object                                                             | Settings to create a WebSocket server. See the [ws package documentation](https://github.com/websockets/ws/blob/master/doc/ws.md#new-websocketserveroptions-callback) for details. |                    |
 | webSocket.client  | Object                                                             | Settings passed down to [SocketClient](#socket-client) when a new socket connection is established.                                                                                |                    |
 
@@ -653,6 +656,202 @@ const client = createRedisClient({
 
 ---
 
+### SecretManager
+
+The SecretManager entity provides seamless integration with GCP Secret Manager for secure credential management in production environments. It automatically loads secrets at startup, writes file-based secrets (like certificates) to secure temp locations, and falls back to environment variables in development.
+
+```javascript
+import { SecretManager } from 'node-server-engine';
+
+// Initialize (can be done automatically via Server configuration)
+await SecretManager.init({
+  enabled: process.env.NODE_ENV === 'production',
+  projectId: process.env.GCP_PROJECT_ID,
+  cache: true,
+  fallbackToEnv: true,
+  secrets: [
+    'SQL_PASSWORD',          // Simple env variable
+    'JWT_SECRET',
+    {
+      name: 'PRIVATE_KEY',   // File-based secret
+      type: 'file',
+      targetEnvVar: 'PRIVATE_KEY_PATH',
+      filename: 'private-key.pem'
+    }
+  ]
+});
+
+// Get a cached secret value
+const password = SecretManager.getSecret('SQL_PASSWORD');
+
+// Fetch a secret on-demand (useful for rotation)
+const apiKey = await SecretManager.fetchSecret('API_KEY');
+
+// Reload all secrets
+await SecretManager.reload();
+
+// Check initialization status
+if (SecretManager.isInitialized()) {
+  console.log('Secrets loaded');
+}
+```
+
+#### Features
+
+- **Automatic Loading**: Secrets loaded during server initialization
+- **Environment Fallback**: Uses `process.env` in development or when secrets are unavailable
+- **File Support**: Writes certificates and keys to temp files with secure permissions (0o600)
+- **Caching**: Optional caching of secret values for performance
+- **Secret Rotation**: On-demand fetching for runtime secret updates
+- **Lifecycle Management**: Automatic cleanup of temp files on shutdown
+
+#### Server Integration
+
+SecretManager can be configured directly in Server options:
+
+```javascript
+import { Server, SecretManagerOptions } from 'node-server-engine';
+
+const server = new Server({
+  endpoints: [...],
+  secretManager: {
+    enabled: process.env.NODE_ENV === 'production',
+    projectId: process.env.GCP_PROJECT_ID,
+    cache: true,
+    fallbackToEnv: true,
+    secrets: [
+      'SQL_PASSWORD',
+      'JWT_SECRET',
+      {
+        name: 'PRIVATE_KEY',
+        type: 'file',
+        targetEnvVar: 'PRIVATE_KEY_PATH',
+        filename: 'private-key.pem'
+      }
+    ]
+  }
+});
+
+await server.init(); // Secrets loaded before app starts
+```
+
+#### Configuration Options
+
+| Property      | Type                          | Description                                                    | Default       |
+|---------------|-------------------------------|----------------------------------------------------------------|---------------|
+| enabled       | boolean                       | Enable Secret Manager (typically only in production)            | false         |
+| projectId     | string                        | GCP project ID                                                 | Required      |
+| cache         | boolean                       | Cache secret values in memory                                  | true          |
+| fallbackToEnv | boolean                       | Fall back to `process.env` if secret loading fails             | true          |
+| tempDir       | string                        | Directory for file-based secrets                               | `os.tmpdir()` |
+| secrets       | Array<string \| SecretConfig> | List of secrets to load                                        | []            |
+
+#### Secret Configuration
+
+Secrets can be specified as strings (simple env variables) or objects for advanced configuration:
+
+**String format** (simple env variable):
+```javascript
+'SQL_PASSWORD'  // Loads GCP secret "SQL_PASSWORD" → process.env.SQL_PASSWORD
+```
+
+**Object format** (advanced configuration):
+```javascript
+{
+  name: 'PRIVATE_KEY',              // Secret name in GCP Secret Manager
+  type: 'env' | 'file',             // Type: 'env' for variables, 'file' for certificates
+  targetEnvVar: 'PRIVATE_KEY_PATH', // Env var name (optional for 'env' type)
+  filename: 'private-key.pem',      // Filename for 'file' type (optional)
+  version: 'latest'                 // Secret version (default: 'latest')
+}
+```
+
+#### Secret Types
+
+**Environment Variable Secrets** (`type: 'env'`):
+- Loaded directly into `process.env`
+- Good for passwords, API keys, tokens
+- Example: `'SQL_PASSWORD'` → `process.env.SQL_PASSWORD`
+
+**File-based Secrets** (`type: 'file'`):
+- Written to temp files with secure permissions (0o600)
+- Good for certificates, private keys, JSON credentials
+- Environment variable points to file path
+- Example: `PRIVATE_KEY` → `/tmp/private-key.pem` → `process.env.PRIVATE_KEY_PATH`
+
+#### Environment Variables
+
+| Variable         | Description                           | Required |
+|------------------|---------------------------------------|----------|
+| GCP_PROJECT_ID   | GCP project containing secrets        | ✓        |
+| NODE_ENV         | Environment (production/development)  | -        |
+
+#### Load Results
+
+The `init()` and `reload()` methods return load statistics:
+
+```javascript
+const result = await SecretManager.init({...});
+console.log(result);
+// {
+//   loaded: 3,      // Successfully loaded from Secret Manager
+//   failed: 0,      // Failed to load
+//   fallback: 1,    // Used fallback environment variables
+//   details: [...]  // Detailed information per secret
+// }
+```
+
+#### Security Features
+
+- **Secure File Permissions**: File-based secrets written with 0o600 (owner read/write only)
+- **Automatic Cleanup**: Temp files deleted on server shutdown
+- **No Logging**: Secret values never logged (only metadata)
+- **Lifecycle Integration**: Registered with LifecycleController for proper cleanup
+
+#### Example: Multiple Secrets
+
+```javascript
+const secretConfig = {
+  enabled: process.env.NODE_ENV === 'production',
+  projectId: 'my-gcp-project',
+  secrets: [
+    // Database credentials
+    'SQL_PASSWORD',
+    'SQL_USER',
+    
+    // API keys
+    'STRIPE_API_KEY',
+    'SENDGRID_API_KEY',
+    
+    // Certificate files
+    {
+      name: 'TLS_CERT',
+      type: 'file',
+      targetEnvVar: 'TLS_CERT_PATH',
+      filename: 'tls.crt'
+    },
+    {
+      name: 'TLS_KEY',
+      type: 'file',
+      targetEnvVar: 'TLS_KEY_PATH',
+      filename: 'tls.key'
+    },
+    
+    // Service account key
+    {
+      name: 'GCP_SERVICE_ACCOUNT',
+      type: 'file',
+      targetEnvVar: 'GOOGLE_APPLICATION_CREDENTIALS',
+      filename: 'service-account.json'
+    }
+  ]
+};
+
+await SecretManager.init(secretConfig);
+```
+
+---
+
 ### AWSS3
 
 The AWSS3 entity is a generic wrapper around AWS S3 (and S3-compatible services like MinIO, LocalStack). It supports uploads, downloads, streaming, metadata, and deletion with size validation and UUID-based path generation.

package/dist/entities/PubSub/handleMessage/handleMessage.js

@@ -41,7 +41,7 @@ async function handleMessage(message, subscription, handlers, isDebezium = false
         }
       });
     }
-  } catch (error) {
+  } catch {
     (0, _utils.reportError)(new _EngineError.EngineError({
       severity: _const.LogSeverity.WARNING,
       message: `Pub/Sub message is not valid JSON ${subscription.name}`,

package/dist/entities/PubSub/handleMessage/handleMessage.js.map

@@ -1 +1 @@
-{"version":3,"file":"handleMessage.js","names":["_const","require","_EngineError","_utils","namespace","handleMessage","message","subscription","handlers","isDebezium","reportDebug","name","payload","JSON","parse","data","toString","before","after","diff","Object","keys","filter","key","EngineError","severity","LogSeverity","WARNING","error","reportError","ack","hasError","handler","attributes","publishTime","nack"],"sources":["../../../../src/entities/PubSub/handleMessage/handleMessage.ts"],"sourcesContent":["import { Subscription, Message } from '@google-cloud/pubsub';\nimport { PubSubMessageHandler, PubSubDebeziumPayload } from '../PubSub.types';\nimport { LogSeverity } from 'const';\nimport { EngineError } from 'entities/EngineError';\nimport { reportDebug, reportError } from 'utils';\n\nconst namespace = 'engine:PubSub:handleMessage';\n\n/**\n * handle the pubSubClients on message event\n * @param message - Message to parse and handle\n * @param subscription - The related Pub/Sub subscription object\n * @param handlers - Message handlers\n * @param isDebezium - Indicates that the subscription from Debezium events\n */\nexport async function handleMessage(\n  message: Message,\n  subscription: Subscription,\n  handlers: Array<PubSubMessageHandler<unknown>>,\n  isDebezium = false\n): Promise<void> {\n  reportDebug({\n    namespace,\n    message: `Received message from Pub/Sub [${subscription.name}]`\n  });\n\n  let payload;\n  try {\n    payload = JSON.parse(message.data.toString()) as unknown;\n\n    // When handling Debezium message, we calculate automatically the keys that have changed between the previous and current state\n    if (isDebezium) {\n      payload = payload as PubSubDebeziumPayload<Record<string, unknown>>;\n      const { before, after } = payload;\n      if (before && after)\n        payload.diff = Object.keys(after).filter(\n          (key) => after[key] !== before[key]\n        );\n      else if (before) payload.diff = Object.keys(before);\n      else if (after) payload.diff = Object.keys(after);\n      else\n        throw new EngineError({\n          severity: LogSeverity.WARNING,\n          message: `Debezium Pub/Sub message did not include before nor after value [${subscription.name}]`,\n          data: { subscription, message: message.data.toString() }\n        });\n    }\n  } catch (error) {\n    reportError(\n      new EngineError({\n        severity: LogSeverity.WARNING,\n        message: `Pub/Sub message is not valid JSON ${subscription.name}`,\n        data: { subscription, message: message.data.toString() }\n      })\n    );\n    // Acknowledge invalid messages to prevent redelivery\n    message.ack();\n    return;\n  }\n\n  // Process all handlers\n  let hasError = false;\n  for (const handler of handlers) {\n    try {\n      await handler(payload, message.attributes, message.publishTime);\n    } catch (error) {\n      hasError = true;\n      reportError(error);\n    }\n  }\n\n  // Acknowledge message only after successful processing\n  // If there was an error, nack the message so it can be redelivered\n  if (hasError) {\n    reportDebug({\n      namespace,\n      message: `Nacking message due to handler errors [${subscription.name}]`\n    });\n    message.nack();\n  } else {\n    message.ack();\n  }\n}\n"],"mappings":";;;;;;AAEA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,YAAA,GAAAD,OAAA;AACA,IAAAE,MAAA,GAAAF,OAAA;AAEA,MAAMG,SAAS,GAAG,6BAA6B;;AAE/C;AACA;AACA;AACA;AACA;AACA;AACA;AACO,eAAeC,aAAaA,CACjCC,OAAgB,EAChBC,YAA0B,EAC1BC,QAA8C,EAC9CC,UAAU,GAAG,KAAK,EACH;EACf,IAAAC,kBAAW,EAAC;IACVN,SAAS;IACTE,OAAO,EAAE,kCAAkCC,YAAY,CAACI,IAAI;EAC9D,CAAC,CAAC;EAEF,IAAIC,OAAO;EACX,IAAI;IACFA,OAAO,GAAGC,IAAI,CAACC,KAAK,CAACR,OAAO,CAACS,IAAI,CAACC,QAAQ,CAAC,CAAC,CAAY;;IAExD;IACA,IAAIP,UAAU,EAAE;MACdG,OAAO,GAAGA,OAAyD;MACnE,MAAM;QAAEK,MAAM;QAAEC;MAAM,CAAC,GAAGN,OAAO;MACjC,IAAIK,MAAM,IAAIC,KAAK,EACjBN,OAAO,CAACO,IAAI,GAAGC,MAAM,CAACC,IAAI,CAACH,KAAK,CAAC,CAACI,MAAM,CACrCC,GAAG,IAAKL,KAAK,CAACK,GAAG,CAAC,KAAKN,MAAM,CAACM,GAAG,CACpC,CAAC,CAAC,KACC,IAAIN,MAAM,EAAEL,OAAO,CAACO,IAAI,GAAGC,MAAM,CAACC,IAAI,CAACJ,MAAM,CAAC,CAAC,KAC/C,IAAIC,KAAK,EAAEN,OAAO,CAACO,IAAI,GAAGC,MAAM,CAACC,IAAI,CAACH,KAAK,CAAC,CAAC,KAEhD,MAAM,IAAIM,wBAAW,CAAC;QACpBC,QAAQ,EAAEC,kBAAW,CAACC,OAAO;QAC7BrB,OAAO,EAAE,oEAAoEC,YAAY,CAACI,IAAI,GAAG;QACjGI,IAAI,EAAE;UAAER,YAAY;UAAED,OAAO,EAAEA,OAAO,CAACS,IAAI,CAACC,QAAQ,CAAC;QAAE;MACzD,CAAC,CAAC;IACN;EACF,CAAC,CAAC,OAAOY,KAAK,EAAE;IACd,IAAAC,kBAAW,EACT,IAAIL,wBAAW,CAAC;MACdC,QAAQ,EAAEC,kBAAW,CAACC,OAAO;MAC7BrB,OAAO,EAAE,qCAAqCC,YAAY,CAACI,IAAI,EAAE;MACjEI,IAAI,EAAE;QAAER,YAAY;QAAED,OAAO,EAAEA,OAAO,CAACS,IAAI,CAACC,QAAQ,CAAC;MAAE;IACzD,CAAC,CACH,CAAC;IACD;IACAV,OAAO,CAACwB,GAAG,CAAC,CAAC;IACb;EACF;;EAEA;EACA,IAAIC,QAAQ,GAAG,KAAK;EACpB,KAAK,MAAMC,OAAO,IAAIxB,QAAQ,EAAE;IAC9B,IAAI;MACF,MAAMwB,OAAO,CAACpB,OAAO,EAAEN,OAAO,CAAC2B,UAAU,EAAE3B,OAAO,CAAC4B,WAAW,CAAC;IACjE,CAAC,CAAC,OAAON,KAAK,EAAE;MACdG,QAAQ,GAAG,IAAI;MACf,IAAAF,kBAAW,EAACD,KAAK,CAAC;IACpB;EACF;;EAEA;EACA;EACA,IAAIG,QAAQ,EAAE;IACZ,IAAArB,kBAAW,EAAC;MACVN,SAAS;MACTE,OAAO,EAAE,0CAA0CC,YAAY,CAACI,IAAI;IACtE,CAAC,CAAC;IACFL,OAAO,CAAC6B,IAAI,CAAC,CAAC;EAChB,CAAC,MAAM;IACL7B,OAAO,CAACwB,GAAG,CAAC,CAAC;EACf;AACF","ignoreList":[]}
+{"version":3,"file":"handleMessage.js","names":["_const","require","_EngineError","_utils","namespace","handleMessage","message","subscription","handlers","isDebezium","reportDebug","name","payload","JSON","parse","data","toString","before","after","diff","Object","keys","filter","key","EngineError","severity","LogSeverity","WARNING","reportError","ack","hasError","handler","attributes","publishTime","error","nack"],"sources":["../../../../src/entities/PubSub/handleMessage/handleMessage.ts"],"sourcesContent":["import { Subscription, Message } from '@google-cloud/pubsub';\nimport { PubSubMessageHandler, PubSubDebeziumPayload } from '../PubSub.types';\nimport { LogSeverity } from 'const';\nimport { EngineError } from 'entities/EngineError';\nimport { reportDebug, reportError } from 'utils';\n\nconst namespace = 'engine:PubSub:handleMessage';\n\n/**\n * handle the pubSubClients on message event\n * @param message - Message to parse and handle\n * @param subscription - The related Pub/Sub subscription object\n * @param handlers - Message handlers\n * @param isDebezium - Indicates that the subscription from Debezium events\n */\nexport async function handleMessage(\n  message: Message,\n  subscription: Subscription,\n  handlers: Array<PubSubMessageHandler<unknown>>,\n  isDebezium = false\n): Promise<void> {\n  reportDebug({\n    namespace,\n    message: `Received message from Pub/Sub [${subscription.name}]`\n  });\n\n  let payload;\n  try {\n    payload = JSON.parse(message.data.toString()) as unknown;\n\n    // When handling Debezium message, we calculate automatically the keys that have changed between the previous and current state\n    if (isDebezium) {\n      payload = payload as PubSubDebeziumPayload<Record<string, unknown>>;\n      const { before, after } = payload;\n      if (before && after)\n        payload.diff = Object.keys(after).filter(\n          (key) => after[key] !== before[key]\n        );\n      else if (before) payload.diff = Object.keys(before);\n      else if (after) payload.diff = Object.keys(after);\n      else\n        throw new EngineError({\n          severity: LogSeverity.WARNING,\n          message: `Debezium Pub/Sub message did not include before nor after value [${subscription.name}]`,\n          data: { subscription, message: message.data.toString() }\n        });\n    }\n  } catch {\n    reportError(\n      new EngineError({\n        severity: LogSeverity.WARNING,\n        message: `Pub/Sub message is not valid JSON ${subscription.name}`,\n        data: { subscription, message: message.data.toString() }\n      })\n    );\n    // Acknowledge invalid messages to prevent redelivery\n    message.ack();\n    return;\n  }\n\n  // Process all handlers\n  let hasError = false;\n  for (const handler of handlers) {\n    try {\n      await handler(payload, message.attributes, message.publishTime);\n    } catch (error) {\n      hasError = true;\n      reportError(error);\n    }\n  }\n\n  // Acknowledge message only after successful processing\n  // If there was an error, nack the message so it can be redelivered\n  if (hasError) {\n    reportDebug({\n      namespace,\n      message: `Nacking message due to handler errors [${subscription.name}]`\n    });\n    message.nack();\n  } else {\n    message.ack();\n  }\n}\n"],"mappings":";;;;;;AAEA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,YAAA,GAAAD,OAAA;AACA,IAAAE,MAAA,GAAAF,OAAA;AAEA,MAAMG,SAAS,GAAG,6BAA6B;;AAE/C;AACA;AACA;AACA;AACA;AACA;AACA;AACO,eAAeC,aAAaA,CACjCC,OAAgB,EAChBC,YAA0B,EAC1BC,QAA8C,EAC9CC,UAAU,GAAG,KAAK,EACH;EACf,IAAAC,kBAAW,EAAC;IACVN,SAAS;IACTE,OAAO,EAAE,kCAAkCC,YAAY,CAACI,IAAI;EAC9D,CAAC,CAAC;EAEF,IAAIC,OAAO;EACX,IAAI;IACFA,OAAO,GAAGC,IAAI,CAACC,KAAK,CAACR,OAAO,CAACS,IAAI,CAACC,QAAQ,CAAC,CAAC,CAAY;;IAExD;IACA,IAAIP,UAAU,EAAE;MACdG,OAAO,GAAGA,OAAyD;MACnE,MAAM;QAAEK,MAAM;QAAEC;MAAM,CAAC,GAAGN,OAAO;MACjC,IAAIK,MAAM,IAAIC,KAAK,EACjBN,OAAO,CAACO,IAAI,GAAGC,MAAM,CAACC,IAAI,CAACH,KAAK,CAAC,CAACI,MAAM,CACrCC,GAAG,IAAKL,KAAK,CAACK,GAAG,CAAC,KAAKN,MAAM,CAACM,GAAG,CACpC,CAAC,CAAC,KACC,IAAIN,MAAM,EAAEL,OAAO,CAACO,IAAI,GAAGC,MAAM,CAACC,IAAI,CAACJ,MAAM,CAAC,CAAC,KAC/C,IAAIC,KAAK,EAAEN,OAAO,CAACO,IAAI,GAAGC,MAAM,CAACC,IAAI,CAACH,KAAK,CAAC,CAAC,KAEhD,MAAM,IAAIM,wBAAW,CAAC;QACpBC,QAAQ,EAAEC,kBAAW,CAACC,OAAO;QAC7BrB,OAAO,EAAE,oEAAoEC,YAAY,CAACI,IAAI,GAAG;QACjGI,IAAI,EAAE;UAAER,YAAY;UAAED,OAAO,EAAEA,OAAO,CAACS,IAAI,CAACC,QAAQ,CAAC;QAAE;MACzD,CAAC,CAAC;IACN;EACF,CAAC,CAAC,MAAM;IACN,IAAAY,kBAAW,EACT,IAAIJ,wBAAW,CAAC;MACdC,QAAQ,EAAEC,kBAAW,CAACC,OAAO;MAC7BrB,OAAO,EAAE,qCAAqCC,YAAY,CAACI,IAAI,EAAE;MACjEI,IAAI,EAAE;QAAER,YAAY;QAAED,OAAO,EAAEA,OAAO,CAACS,IAAI,CAACC,QAAQ,CAAC;MAAE;IACzD,CAAC,CACH,CAAC;IACD;IACAV,OAAO,CAACuB,GAAG,CAAC,CAAC;IACb;EACF;;EAEA;EACA,IAAIC,QAAQ,GAAG,KAAK;EACpB,KAAK,MAAMC,OAAO,IAAIvB,QAAQ,EAAE;IAC9B,IAAI;MACF,MAAMuB,OAAO,CAACnB,OAAO,EAAEN,OAAO,CAAC0B,UAAU,EAAE1B,OAAO,CAAC2B,WAAW,CAAC;IACjE,CAAC,CAAC,OAAOC,KAAK,EAAE;MACdJ,QAAQ,GAAG,IAAI;MACf,IAAAF,kBAAW,EAACM,KAAK,CAAC;IACpB;EACF;;EAEA;EACA;EACA,IAAIJ,QAAQ,EAAE;IACZ,IAAApB,kBAAW,EAAC;MACVN,SAAS;MACTE,OAAO,EAAE,0CAA0CC,YAAY,CAACI,IAAI;IACtE,CAAC,CAAC;IACFL,OAAO,CAAC6B,IAAI,CAAC,CAAC;EAChB,CAAC,MAAM;IACL7B,OAAO,CAACuB,GAAG,CAAC,CAAC;EACf;AACF","ignoreList":[]}

package/dist/entities/Redis/Redis.d.ts

@@ -1,27 +1,69 @@
-import { Redis as RedisClient, RedisOptions } from 'ioredis';
+import { Redis as RedisClient } from 'ioredis';
 import { RedisCreateOptions } from './Redis.types';
-export declare let redisClient: undefined | RedisClient;
 /**
- * Factory function to create a new Redis instance (exported for testing)
+ * Generic Redis wrapper for caching and data storage
+ * Provides methods for initialization, connection management, and cleanup
+ *
+ * @example
+ * ```typescript
+ * // Initialize Redis connection
+ * Redis.init();
+ *
+ * // Use Redis client
+ * await Redis.set('key', 'value');
+ * const value = await Redis.get('key');
+ *
+ * // Get underlying client for advanced operations
+ * const client = Redis.getClient();
+ * ```
  */
-export declare function createRedisInstance(config: RedisOptions): RedisClient;
-/**
- * We use a proxy to extend the Redis behavior and allow initialization of the client only when needed while keeping the same interface
- */
-export declare const Redis: never;
-/**
- * Get the underlying Redis client (for advanced use cases)
- */
-export declare function getClient(): RedisClient | undefined;
-/**
- * On init create client and connect
- */
-export declare function init(): void;
-/**
- * On shutdown close connection and clear client
- */
-export declare function shutdown(): Promise<void>;
-/**
- * Create Redis client with enhanced configuration
- */
-export declare function createRedisClient(options?: RedisCreateOptions): RedisClient;
+export declare const Redis: {
+    /** Redis client instance */
+    client: RedisClient | undefined;
+    /**
+     * Initialize Redis connection
+     * @param options - Redis configuration options
+     */
+    init(options?: RedisCreateOptions): void;
+    /**
+     * Shutdown Redis connection and cleanup
+     * @returns Promise that resolves when shutdown is complete
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get the underlying Redis client
+     * @returns Redis client instance or undefined
+     */
+    getClient(): RedisClient | undefined;
+    /**
+     * Create Redis client with configuration
+     * @param options - Redis creation options
+     * @returns Redis client instance
+     * @private
+     */
+    createRedisClient(options?: RedisCreateOptions): RedisClient;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string | number | Buffer, ...args: unknown[]): Promise<"OK" | null>;
+    del(...keys: string[]): Promise<number>;
+    exists(...keys: string[]): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    ttl(key: string): Promise<number>;
+    incr(key: string): Promise<number>;
+    decr(key: string): Promise<number>;
+    hget(key: string, field: string): Promise<string | null>;
+    hset(key: string, field: string, value: string | number | Buffer): Promise<number>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    lpush(key: string, ...values: (string | Buffer | number)[]): Promise<number>;
+    rpush(key: string, ...values: (string | Buffer | number)[]): Promise<number>;
+    lpop(key: string, count?: number): Promise<string | string[] | null>;
+    rpop(key: string, count?: number): Promise<string | string[] | null>;
+    lrange(key: string, start: number, stop: number): Promise<string[]>;
+    sadd(key: string, ...members: (string | Buffer | number)[]): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+    sismember(key: string, member: string | Buffer | number): Promise<number>;
+};
+export declare const createRedisClient: (options?: RedisCreateOptions) => RedisClient;
+export declare const getClient: () => RedisClient | undefined;
+export declare const init: (options?: RedisCreateOptions) => void;
+export declare const shutdown: () => Promise<void>;
+export declare let redisClient: RedisClient | undefined;