db-backup-logging 1.0.0

package/README.md

@@ -0,0 +1,257 @@
+# notice-utility
+
+Production-ready NPM package for **database backup**, **request/response logging**, and **exception tracking**.  
+Written in TypeScript. Supports CommonJS + ESM.
+
+---
+
+## Installation
+
+```bash
+npm install notice-utility
+```
+
+**Peer dependencies** (must exist in your project):
+```bash
+npm install mongoose express
+```
+
+**Optional** (only if using S3 backups):
+```bash
+npm install @aws-sdk/client-s3
+```
+
+---
+
+## Quick Start
+
+### 1. Initialize (after `mongoose.connect()`)
+
+```ts
+import { initializeNoticePackage } from 'notice-utility'
+
+initializeNoticePackage({
+  dbType: 'mongodb',
+  dbUri: 'mongodb://localhost:27017/mydb',
+  serviceName: 'my-api',
+  environment: 'production',
+  tables: {
+    requestLogs: 'request_logs',
+    errorLogs: 'error_logs',
+    backupLogs: 'backup_logs',
+  },
+  // Optional — S3 backup
+  aws: {
+    enabled: true,
+    bucketName: 'my-backups',
+    region: 'ap-south-1',
+    accessKeyId: 'YOUR_KEY',
+    secretAccessKey: 'YOUR_SECRET',
+  },
+  // Optional — local backup
+  local: {
+    enabled: true,
+    backupPath: './backups',
+  },
+})
+```
+
+### 2. Add Request Logger Middleware
+
+```ts
+import { requestLogger } from 'notice-utility'
+
+// Add BEFORE your routes
+app.use(requestLogger())
+```
+
+Logs: HTTP method, URL, headers, request body, response status, response body, response time (ms), user ID, IP, service name, environment, timestamp.
+
+### 3. Add Error Middleware
+
+```ts
+import { errorMiddleware } from 'notice-utility'
+
+// Add AFTER all routes
+app.use(errorMiddleware())
+```
+
+This also automatically registers `uncaughtException` and `unhandledRejection` handlers on initialization.
+
+### 4. Trigger Manual Backup
+
+```ts
+import { manualBackupTrigger } from 'notice-utility'
+
+await manualBackupTrigger()
+```
+
+> **Note:** Requires `mongodump` CLI installed on the machine.
+
+### 5. Log Custom Errors
+
+```ts
+import { logCustomError } from 'notice-utility'
+
+logCustomError(new Error('Payment failed'), {
+  userId: 'user_123',
+  requestContext: {
+    method: 'POST',
+    url: '/api/payments',
+  },
+})
+```
+
+---
+
+## Full Config Reference
+
+```ts
+interface NoticeConfig {
+  dbType: 'mongodb' | 'postgres' | 'mysql'
+  dbUri: string                    // MongoDB connection URI
+  schema?: string                  // Schema name (for SQL databases)
+  serviceName?: string             // Your service/app name
+  environment?: string             // e.g. 'production', 'staging'
+  tables: {
+    requestLogs: string            // Collection name for request logs
+    errorLogs: string              // Collection name for error logs
+    backupLogs: string             // Collection name for backup logs
+  }
+  aws?: {
+    enabled: boolean
+    bucketName: string
+    region: string
+    accessKeyId: string
+    secretAccessKey: string
+  }
+  local?: {
+    enabled: boolean
+    backupPath: string             // Relative or absolute path
+  }
+}
+```
+
+---
+
+## Exported Modules
+
+| Export | Type | Description |
+|---|---|---|
+| `initializeNoticePackage(config)` | Function | Initialize the package (call once at startup) |
+| `requestLogger()` | Middleware | Express middleware for request/response logging |
+| `errorMiddleware()` | Middleware | Express error-handling middleware |
+| `logCustomError(error, context?)` | Function | Manually log any error |
+| `manualBackupTrigger()` | Async Function | Trigger a database backup on demand |
+
+All types are also exported: `NoticeConfig`, `AWSConfig`, `LocalConfig`, `NoticeTables`, `RequestLogEntry`, `ErrorLogEntry`, `BackupLogEntry`.
+
+---
+
+## Testing Locally (Before Publishing)
+
+### Step 1: Build the package
+
+```bash
+cd /path/to/db-backup-logging
+npm install
+npm run build
+```
+
+Verify `dist/` contains: `index.js`, `index.mjs`, `index.d.ts`.
+
+### Step 2: Link the package locally
+
+```bash
+cd /path/to/db-backup-logging
+npm link
+```
+
+### Step 3: Use in your project
+
+```bash
+cd /path/to/your-project
+npm link notice-utility
+```
+
+Now you can import it:
+
+```ts
+import { initializeNoticePackage, requestLogger } from 'notice-utility'
+```
+
+### Step 4: Verify it works
+
+Add this to your Express app's entry file (e.g. `server.js` or `app.ts`):
+
+```ts
+import mongoose from 'mongoose'
+import express from 'express'
+import {
+  initializeNoticePackage,
+  requestLogger,
+  errorMiddleware,
+} from 'notice-utility'
+
+const app = express()
+app.use(express.json())
+
+// Connect to MongoDB first
+await mongoose.connect('mongodb://localhost:27017/test_notice')
+
+// Initialize the package
+initializeNoticePackage({
+  dbType: 'mongodb',
+  dbUri: 'mongodb://localhost:27017/test_notice',
+  serviceName: 'test-app',
+  environment: 'development',
+  tables: {
+    requestLogs: 'test_request_logs',
+    errorLogs: 'test_error_logs',
+    backupLogs: 'test_backup_logs',
+  },
+  local: { enabled: true, backupPath: './test-backups' },
+})
+
+// Add middleware
+app.use(requestLogger())
+
+app.get('/test', (req, res) => {
+  res.json({ message: 'Hello from notice-utility test!' })
+})
+
+app.use(errorMiddleware())
+
+app.listen(3000, () => console.log('Test server running on port 3000'))
+```
+
+### Step 5: Test endpoints
+
+```bash
+# Hit the test endpoint
+curl http://localhost:3000/test
+
+# Check MongoDB for logged request
+mongosh test_notice --eval "db.test_request_logs.find().pretty()"
+```
+
+You should see a request log entry with method, URL, response status, response time, etc.
+
+### Step 6: Unlink when done
+
+```bash
+cd /path/to/your-project
+npm unlink notice-utility
+
+cd /path/to/db-backup-logging
+npm unlink
+```
+
+---
+
+## Notes
+
+- **Dedicated Connection**: `notice-utility` establishes its own dedicated database connection using `config.dbUri` to ensure logging operations never compete with your main application's query pool (and to avoid `npm link` Mongoose duplication issues).
+- Logging failures are **silently handled** — the host app will never crash due to a logging error.
+- Exception handlers **chain** with existing handlers — they don't override them.
+- `mongodump` must be installed on the machine for the backup feature to work.

package/dist/index.d.mts

@@ -0,0 +1,105 @@
+import { Request, Response, NextFunction } from 'express';
+
+interface AWSConfig {
+    enabled: boolean;
+    bucketName: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+}
+interface LocalConfig {
+    enabled: boolean;
+    backupPath: string;
+}
+interface NoticeTables {
+    requestLogs: string;
+    errorLogs: string;
+    backupLogs: string;
+}
+interface NoticeConfig {
+    dbType: 'mongodb' | 'postgres' | 'mysql';
+    dbUri: string;
+    schema?: string;
+    tables: NoticeTables;
+    serviceName?: string;
+    environment?: string;
+    aws?: AWSConfig;
+    local?: LocalConfig;
+}
+interface RequestLogEntry {
+    method: string;
+    url: string;
+    headers?: Record<string, string | string[] | undefined>;
+    requestBody?: unknown;
+    responseStatus: number;
+    responseBody?: unknown;
+    responseTime: number;
+    userId?: string;
+    ipAddress: string;
+    serviceName?: string;
+    environment?: string;
+    createdAt: Date;
+}
+interface ErrorLogEntry {
+    errorMessage: string;
+    stackTrace?: string;
+    requestContext?: {
+        method?: string;
+        url?: string;
+        headers?: Record<string, string | string[] | undefined>;
+        body?: unknown;
+    };
+    userId?: string;
+    serviceName?: string;
+    environment?: string;
+    createdAt: Date;
+}
+interface BackupLogEntry {
+    backupFileName: string;
+    backupType: string;
+    location: 'local' | 's3';
+    fileSize: number;
+    status: 'success' | 'failed';
+    errorMessage?: string;
+    createdAt: Date;
+}
+
+/**
+ * Initialize the notice-utility package.
+ * Must be called once during application startup, after mongoose.connect().
+ *
+ * @param config - Full package configuration
+ */
+declare function initializeNoticePackage(config: NoticeConfig): void;
+
+/**
+ * Express middleware factory for request/response logging.
+ * Captures method, URL, headers, body, response, timing, user, IP.
+ * All logging is non-blocking via the async queue.
+ */
+declare function requestLogger(): (req: Request, res: Response, next: NextFunction) => void;
+
+/**
+ * Public export — trigger a manual database backup.
+ */
+declare function manualBackupTrigger(): Promise<void>;
+
+/**
+ * Express error-handling middleware.
+ * Must be registered AFTER all routes: app.use(errorMiddleware())
+ */
+declare function errorMiddleware(): (err: Error, req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Public export — manually log a custom error with optional context.
+ */
+declare function logCustomError(error: Error | string, context?: {
+    userId?: string;
+    requestContext?: {
+        method?: string;
+        url?: string;
+        headers?: Record<string, string | string[] | undefined>;
+        body?: unknown;
+    };
+}): void;
+
+export { type AWSConfig, type BackupLogEntry, type ErrorLogEntry, type LocalConfig, type NoticeConfig, type NoticeTables, type RequestLogEntry, errorMiddleware, initializeNoticePackage, logCustomError, manualBackupTrigger, requestLogger };

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+import { Request, Response, NextFunction } from 'express';
+
+interface AWSConfig {
+    enabled: boolean;
+    bucketName: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+}
+interface LocalConfig {
+    enabled: boolean;
+    backupPath: string;
+}
+interface NoticeTables {
+    requestLogs: string;
+    errorLogs: string;
+    backupLogs: string;
+}
+interface NoticeConfig {
+    dbType: 'mongodb' | 'postgres' | 'mysql';
+    dbUri: string;
+    schema?: string;
+    tables: NoticeTables;
+    serviceName?: string;
+    environment?: string;
+    aws?: AWSConfig;
+    local?: LocalConfig;
+}
+interface RequestLogEntry {
+    method: string;
+    url: string;
+    headers?: Record<string, string | string[] | undefined>;
+    requestBody?: unknown;
+    responseStatus: number;
+    responseBody?: unknown;
+    responseTime: number;
+    userId?: string;
+    ipAddress: string;
+    serviceName?: string;
+    environment?: string;
+    createdAt: Date;
+}
+interface ErrorLogEntry {
+    errorMessage: string;
+    stackTrace?: string;
+    requestContext?: {
+        method?: string;
+        url?: string;
+        headers?: Record<string, string | string[] | undefined>;
+        body?: unknown;
+    };
+    userId?: string;
+    serviceName?: string;
+    environment?: string;
+    createdAt: Date;
+}
+interface BackupLogEntry {
+    backupFileName: string;
+    backupType: string;
+    location: 'local' | 's3';
+    fileSize: number;
+    status: 'success' | 'failed';
+    errorMessage?: string;
+    createdAt: Date;
+}
+
+/**
+ * Initialize the notice-utility package.
+ * Must be called once during application startup, after mongoose.connect().
+ *
+ * @param config - Full package configuration
+ */
+declare function initializeNoticePackage(config: NoticeConfig): void;
+
+/**
+ * Express middleware factory for request/response logging.
+ * Captures method, URL, headers, body, response, timing, user, IP.
+ * All logging is non-blocking via the async queue.
+ */
+declare function requestLogger(): (req: Request, res: Response, next: NextFunction) => void;
+
+/**
+ * Public export — trigger a manual database backup.
+ */
+declare function manualBackupTrigger(): Promise<void>;
+
+/**
+ * Express error-handling middleware.
+ * Must be registered AFTER all routes: app.use(errorMiddleware())
+ */
+declare function errorMiddleware(): (err: Error, req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Public export — manually log a custom error with optional context.
+ */
+declare function logCustomError(error: Error | string, context?: {
+    userId?: string;
+    requestContext?: {
+        method?: string;
+        url?: string;
+        headers?: Record<string, string | string[] | undefined>;
+        body?: unknown;
+    };
+}): void;
+
+export { type AWSConfig, type BackupLogEntry, type ErrorLogEntry, type LocalConfig, type NoticeConfig, type NoticeTables, type RequestLogEntry, errorMiddleware, initializeNoticePackage, logCustomError, manualBackupTrigger, requestLogger };