nesthub 1.0.0

package/package.json

@@ -0,0 +1,229 @@
+{
+  "name": "nesthub",
+  "version": "1.0.0",
+  "description": "All-in-one modular toolkit for NestJS",
+  "keywords": [
+    "nestjs",
+    "nest",
+    "typeorm",
+    "cache",
+    "redis",
+    "valkey",
+    "bullmq",
+    "queue",
+    "notification",
+    "firebase",
+    "telegram",
+    "sms",
+    "email",
+    "crud"
+  ],
+  "author": "Wind Blade <vn.chemgio@yahoo.com> (https://github.com/Vn-ChemGio)",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/Vn-ChemGio"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vn-ChemGio/nesthub.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Vn-ChemGio/nesthub/issues"
+  },
+  "homepage": "https://github.com/Vn-ChemGio/nesthub#readme",
+  "private": false,
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./typeorm": {
+      "types": "./dist/typeorm/index.d.ts",
+      "import": "./dist/typeorm/index.js",
+      "require": "./dist/typeorm/index.js"
+    },
+    "./cache": {
+      "types": "./dist/cache/index.d.ts",
+      "import": "./dist/cache/index.js",
+      "require": "./dist/cache/index.js"
+    },
+    "./queue": {
+      "types": "./dist/queue/index.d.ts",
+      "import": "./dist/queue/index.js",
+      "require": "./dist/queue/index.js"
+    },
+    "./notification": {
+      "types": "./dist/notification/index.d.ts",
+      "import": "./dist/notification/index.js",
+      "require": "./dist/notification/index.js"
+    },
+    "./excel": {
+      "types": "./dist/excel/index.d.ts",
+      "import": "./dist/excel/index.js",
+      "require": "./dist/excel/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "typeorm": [
+        "./dist/typeorm/index.d.ts"
+      ],
+      "cache": [
+        "./dist/cache/index.d.ts"
+      ],
+      "queue": [
+        "./dist/queue/index.d.ts"
+      ],
+      "notification": [
+        "./dist/notification/index.d.ts"
+      ],
+      "excel": [
+        "./dist/excel/index.d.ts"
+      ]
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "src/typeorm/README.md",
+    "src/cache/README.md",
+    "src/queue/README.md",
+    "src/notification/README.md",
+    "src/excel/README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node -e \"require('fs').copyFileSync('src/typeorm/README.md','dist/typeorm/README.md');require('fs').copyFileSync('src/cache/README.md','dist/cache/README.md');require('fs').copyFileSync('src/queue/README.md','dist/queue/README.md');require('fs').copyFileSync('src/notification/README.md','dist/notification/README.md');require('fs').copyFileSync('src/excel/README.md','dist/excel/README.md')\"",
+    "clean": "rimraf dist",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "lint": "eslint \"{src,test}/**/*.ts\" --fix",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:cov": "jest --coverage",
+    "prepublishOnly": "npm run build",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-sns": "^3.750.0",
+    "@keyv/redis": "^5.1.6",
+    "@keyv/valkey": "^1.0.11",
+    "@nestjs/bullmq": "^11.0.0",
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/config": "^4.0.4",
+    "@nestjs/core": "^11.0.1",
+    "@nestjs/typeorm": "^11.0.1",
+    "bullmq": "^5.44.0",
+    "exceljs": "^4.4.0",
+    "firebase-admin": "^13.0.2",
+    "handlebars": "^4.7.8",
+    "nodemailer": "8.0.5",
+    "rxjs": "^7.8.1",
+    "twilio": "^5.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/typeorm": {
+      "optional": true
+    },
+    "@nestjs/config": {
+      "optional": true
+    },
+    "@keyv/valkey": {
+      "optional": true
+    },
+    "@keyv/redis": {
+      "optional": true
+    },
+    "@nestjs/bullmq": {
+      "optional": true
+    },
+    "bullmq": {
+      "optional": true
+    },
+    "handlebars": {
+      "optional": true
+    },
+    "nodemailer": {
+      "optional": true
+    },
+    "twilio": {
+      "optional": true
+    },
+    "@aws-sdk/client-sns": {
+      "optional": true
+    },
+    "firebase-admin": {
+      "optional": true
+    },
+    "exceljs": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "cacheable": "^2.3.5",
+    "keyv": "^5.6.0",
+    "reflect-metadata": "^0.2.2"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-sns": "^3.750.0",
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.18.0",
+    "@keyv/redis": "^5.1.6",
+    "@keyv/valkey": "^1.0.11",
+    "@nestjs/bullmq": "^11.0.0",
+    "@nestjs/common": "^11.0.1",
+    "@nestjs/config": "^4.0.4",
+    "@nestjs/core": "^11.0.1",
+    "@nestjs/testing": "^11.0.1",
+    "@nestjs/typeorm": "^11.0.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.0",
+    "bullmq": "^5.44.0",
+    "eslint": "^9.18.0",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.2.2",
+    "exceljs": "^4.4.0",
+    "firebase-admin": "^13.0.2",
+    "globals": "^17.0.0",
+    "handlebars": "^4.7.8",
+    "jest": "^30.0.0",
+    "nodemailer": "8.0.5",
+    "prettier": "^3.4.2",
+    "rimraf": "^6.0.1",
+    "rxjs": "^7.8.1",
+    "ts-jest": "^29.2.5",
+    "twilio": "^5.4.0",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.20.0"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  }
+}

package/src/cache/README.md

@@ -0,0 +1,91 @@
+# nesthub/cache
+
+A global NestJS cache module using [Keyv](https://keyv.org/) + [Cacheable](https://github.com/jaredwray/cacheable) with Valkey or Redis backend.
+
+## Installation
+
+```bash
+npm install nesthub keyv cacheable
+```
+
+Depending on your store:
+
+- **Valkey**: `npm install @keyv/valkey`
+- **Redis**: `npm install @keyv/redis`
+
+## Quick start
+
+### Valkey (reads `VALKEY_URL` from env)
+
+```typescript
+// app.module.ts
+import { CacheModule } from 'nesthub/cache'
+
+@Module({
+  imports: [
+    CacheModule.forRoot({ store: 'valkey' }),
+    // Requires VALKEY_URL in your .env:
+    // VALKEY_URL=valkey://localhost:6379
+  ],
+})
+export class AppModule {}
+```
+
+### Redis (reads `REDIS_URL` from env)
+
+```typescript
+CacheModule.forRoot({ store: 'redis' })
+// Requires REDIS_URL in .env:
+// REDIS_URL=redis://localhost:6379
+```
+
+### Direct URL (no env vars needed)
+
+```typescript
+CacheModule.forRoot({
+  store: 'valkey',
+  url: 'valkey://user:pass@host:6379',
+})
+```
+
+## Usage in a service
+
+```typescript
+import { Inject } from '@nestjs/common'
+import { CACHE_MANAGER } from 'nesthub/cache'
+import { Cacheable } from 'cacheable'
+
+@Injectable()
+export class MyService {
+  constructor(
+    @Inject(CACHE_MANAGER) private readonly cache: Cacheable,
+  ) {}
+
+  async getData(key: string) {
+    return this.cache.get(key)
+  }
+
+  async setData(key: string, value: unknown, ttl?: number) {
+    await this.cache.set(key, value, ttl)
+  }
+}
+```
+
+## CacheModuleOptions
+
+| Option | Default | Description |
+|---|---|---|
+| `store` | `'valkey'` | Backend store: `'valkey'` or `'redis'` |
+| `namespace` | `'{default}'` | Cache namespace prefix |
+| `url` | — | Connection URL. If omitted, reads `VALKEY_URL` or `REDIS_URL` from env |
+
+## How it works
+
+```
+Cacheable  →  Keyv  →  KeyvValkey / KeyvRedis  →  Valkey / Redis
+```
+
+- `KeyvValkey` / `KeyvRedis` connects to the backend
+- `Keyv` wraps it with a uniform API
+- `Cacheable` adds TTL, namespace, and caching logic
+- The module is `@Global()`, so `CACHE_MANAGER` is available everywhere

package/src/excel/README.md

@@ -0,0 +1,132 @@
+# nesthub/excel
+
+Export JSON data to Excel (.xlsx) — fast, zero boilerplate.
+
+## Installation
+
+```bash
+npm install nesthub exceljs
+```
+
+## Functions
+
+### `exportToBuffer(data, options?)`
+
+Returns a `Buffer` of the .xlsx file.
+
+```typescript
+import { exportToBuffer } from 'nesthub/excel';
+
+const data = [
+  { name: 'Alice', age: 30 },
+  { name: 'Bob', age: 25 },
+];
+
+const buffer = await exportToBuffer(data);
+```
+
+### `exportToFile(data, filePath, options?)`
+
+Writes the .xlsx directly to disk.
+
+```typescript
+import { exportToFile } from 'nesthub/excel';
+
+await exportToFile(data, './reports/users.xlsx');
+```
+
+### `exportToResponse(data, res, filename?, options?)`
+
+Sends the .xlsx as a download response in a NestJS/Express controller.
+
+```typescript
+import { exportToResponse } from 'nesthub/excel';
+import { Response } from 'express';
+import { Controller, Get, Res } from '@nestjs/common';
+
+@Controller('reports')
+export class ReportController {
+  @Get('users')
+  async downloadUsers(@Res() res: Response) {
+    const data = await this.userService.findAll();
+    await exportToResponse(data, res, 'users.xlsx');
+  }
+}
+```
+
+## Options
+
+| Param | Type | Default |
+|-------|------|---------|
+| `data` | `Record<string, unknown>[]` | — |
+| `options.sheetName` | `string` | `'Sheet1'` |
+| `options.columns` | `(string \| ExcelColumn)[]` | All keys from the first data object |
+| `options.useAutoFilter` | `boolean` | `true` |
+| `options.headerFont` | `{ name, size, bold }` | `{ name: 'Calibri', size: 11, bold: true }` |
+| `options.headerBg` | `string` (ARGB hex) | `'4472C4'` |
+| `options.borderColor` | `string` (ARGB hex) | `'B0B0B0'` |
+| `options.formatters` | `Record<string, (value, row) => any>` | — |
+
+### `ExcelColumn`
+
+```typescript
+interface ExcelColumn {
+  key: string;                                         // field name in data
+  header?: string;                                     // default: capitalize(key)
+  width?: number;                                      // default: 18
+  formatter?: (value: unknown, row: object) => unknown; // transform cell value
+}
+```
+
+## Examples
+
+### Pick fields to export
+
+```typescript
+await exportToBuffer(data, {
+  columns: ['name', 'email'],
+});
+```
+
+### Custom header + column width
+
+```typescript
+await exportToBuffer(data, {
+  columns: [
+    { key: 'name',   header: 'Full Name', width: 25 },
+    { key: 'salary', header: 'Salary',    width: 15 },
+  ],
+});
+```
+
+### Format displayed values
+
+**Per-column formatter:**
+```typescript
+await exportToBuffer(data, {
+  columns: [
+    { key: 'name' },
+    {
+      key: 'salary',
+      header: 'Salary',
+      formatter: (v) => `$${(v as number).toLocaleString()}`,
+    },
+  ],
+});
+```
+
+**Global formatters:**
+```typescript
+await exportToBuffer(data, {
+  columns: ['name', 'active'],
+  formatters: {
+    active: (v) => (v ? 'Active' : 'Inactive'),
+  },
+});
+```
+
+### Disable auto filter
+
+```typescript
+await exportToBuffer(data, { useAutoFilter: false });
+```

package/src/notification/README.md

@@ -0,0 +1,237 @@
+# nesthub/notification
+
+Multi-channel notification module for NestJS with support for email, SMS, Firebase Cloud Messaging, and Telegram.
+
+## Features
+
+- **4 channels**: Email, SMS, Firebase, Telegram
+- **Multiple providers**: Configure many SMTP servers / SMS gateways per channel (failover chain)
+- **Template engine**: Handlebars (`.hbs`) for dynamic content
+- **Queue support**: Optional BullMQ integration with expiry check
+- **Persistence**: Optional TypeORM-based notification logging (snake_case columns)
+- **Optional dependencies**: Only install what you use
+
+## Installation
+
+```bash
+npm install nesthub
+```
+
+### Optional channel dependencies
+
+Only install the libraries for channels you use:
+
+```bash
+# For email (SMTP)
+npm install nodemailer
+
+# For SMS (choose your provider)
+npm install twilio
+# or
+npm install @aws-sdk/client-sns
+
+# For Firebase
+npm install firebase-admin
+
+# For templates
+npm install handlebars
+
+# For queue
+npm install @nestjs/bullmq bullmq
+
+# For persistence (TypeORM)
+npm install @nestjs/typeorm typeorm
+```
+
+## Quick Start
+
+```typescript
+import { Module } from '@nestjs/common';
+import { NotificationModule } from 'nesthub/notification';
+
+@Module({
+  imports: [
+    NotificationModule.forRoot({
+      channels: {
+        email: {
+          smtp: { host: 'smtp.example.com', port: 587, user: 'user', pass: 'pass' },
+          defaults: { from: 'noreply@example.com' },
+        },
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## SMTP Configuration
+
+Two ways to configure email:
+
+### Explicit SMTP fields
+```typescript
+email: {
+  smtp: {
+    host: 'smtp.example.com',
+    port: 587,
+    secure: false,      // true for port 465
+    user: 'username',
+    pass: 'password',
+  },
+  defaults: { from: 'noreply@example.com' },
+}
+```
+
+### Connection string (nodemailer transport)
+```typescript
+email: {
+  transport: 'smtp://user:pass@smtp.example.com:587',
+  defaults: { from: 'noreply@example.com' },
+}
+```
+
+## Multi-Provider Failover
+
+Pass an array of configs per channel. On failure, the next provider is tried automatically:
+
+```typescript
+channels: {
+  email: [
+    { smtp: { host: 'smtp1.example.com', port: 587, user: 'u1', pass: 'p1' } },
+    { smtp: { host: 'smtp2.example.com', port: 587, user: 'u2', pass: 'p2' } },
+  ],
+}
+```
+
+## Usage
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { NotificationService } from 'nesthub/notification';
+
+@Injectable()
+export class UserService {
+  constructor(private readonly notification: NotificationService) {}
+
+  async welcomeUser(email: string, name: string) {
+    await this.notification.send({
+      channel: 'email',
+      to: email,
+      subject: 'Welcome!',
+      template: 'welcome',
+      context: { name },
+    });
+  }
+}
+```
+
+## API
+
+### `NotificationModule.forRoot(options)`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `channels.email` | `EmailChannelConfig \| EmailChannelConfig[]` | Email channel config(s) |
+| `channels.sms` | `SmsChannelConfig \| SmsChannelConfig[]` | SMS channel config(s) |
+| `channels.firebase` | `FirebaseChannelConfig \| FirebaseChannelConfig[]` | Firebase channel config(s) |
+| `channels.telegram` | `TelegramChannelConfig \| TelegramChannelConfig[]` | Telegram channel config(s) |
+| `templates.dir` | `string` | Directory containing `.hbs` template files |
+| `queue` | `QueueConfig` | BullMQ queue configuration |
+| `storage.enabled` | `boolean` | Enable notification persistence |
+
+### `NotificationModule.forRootAsync(options)`
+
+Use with `ConfigService` to read config from environment variables:
+
+```typescript
+NotificationModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    channels: {
+      email: {
+        smtp: {
+          host: config.get('SMTP_HOST'),
+          port: config.get('SMTP_PORT'),
+          user: config.get('SMTP_USER'),
+          pass: config.get('SMTP_PASS'),
+        },
+      },
+    },
+    queue: {
+      enabled: true,
+      connection: { url: config.get('VALKEY_URL') ?? 'valkey://localhost:6379' },
+    },
+    templates: { dir: config.get('TEMPLATE_DIR', './templates') },
+    storage: { enabled: config.get('NOTIFICATION_STORAGE', false) },
+  }),
+})
+```
+
+### `NotificationService`
+
+| Method | Description |
+|--------|-------------|
+| `send(input)` | Send notification immediately (tries providers in order) |
+| `enqueue(input)` | Queue notification for async processing |
+
+## Template Engine
+
+Place `.hbs` files in the configured template directory:
+
+```hbs
+<!-- templates/welcome.hbs -->
+<h1>Welcome, {{name}}!</h1>
+<p>Thank you for joining us.</p>
+```
+
+## Queue with Expiry Check
+
+```typescript
+NotificationModule.forRoot({
+  channels: { email: { smtp: { host: '...', port: 587 } } },
+  queue: {
+    enabled: true,
+    name: 'notifications',
+    connection: { url: 'valkey://localhost:6379' },
+    defaultJobOptions: { attempts: 3 },
+  },
+})
+```
+
+Expired notifications (those with `expiresAt` in the past) are automatically skipped.
+
+## Persistence with TypeORM
+
+The `NotificationLog` entity uses snake_case column names.
+
+```typescript
+import { NotificationLog, NOTIFICATION_LOG_REPOSITORY } from 'nesthub/notification';
+import { TypeOrmModule, getRepositoryToken } from '@nestjs/typeorm';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([NotificationLog]),
+    NotificationModule.forRoot({
+      channels: { email: { smtp: { host: '...', port: 587 } } },
+      storage: { enabled: true },
+    }),
+  ],
+  providers: [{
+    provide: NOTIFICATION_LOG_REPOSITORY,
+    useFactory: (repo) => repo,
+    inject: [getRepositoryToken(NotificationLog)],
+  }],
+})
+export class AppModule {}
+```
+
+### Column naming
+
+| Entity property | DB column |
+|----------------|-----------|
+| `to` | `recipient_to` |
+| `messageId` | `message_id` |
+| `createdAt` | `created_at` |
+| `updatedAt` | `updated_at` |
+| `sentAt` | `sent_at` |