@servicelabsco/nestjs-utility-services 2.0.15 → 3.0.1

package/dist/system/services/upload.service.js

@@ -16,21 +16,30 @@ exports.UploadService = void 0;
 const common_1 = require("@nestjs/common");
 const axios_1 = __importDefault(require("axios"));
 const fs_1 = require("fs");
+const operation_exception_1 = require("../../common/exceptions/operation.exception");
 const common_service_1 = require("../../common/libraries/common.service");
+const public_exposed_decorator_1 = require("../../common/decorators/public.exposed.decorator");
+const upload_allow_list_1 = require("../constants/upload.allow.list");
 const file_type_detector_1 = require("../libraries/file.type.detector");
 const storage_service_1 = require("./storage.service");
 let UploadService = class UploadService extends common_service_1.CommonService {
     constructor(storageService) {
         super();
         this.storageService = storageService;
-        this.publicExposed = true;
     }
     async upload(file, options = {}) {
-        const result = await this.storageService.put({
-            buffer: file.buffer,
-            url: file.url,
-            originalname: file.originalname,
-        }, options);
+        const buffer = file.buffer ?? (file.url ? await this.getBufferFromUrl(file.url) : null);
+        if (!buffer) {
+            throw new operation_exception_1.OperationException('upload requires a buffer or a url');
+        }
+        const isPublic = options.acl === 'public-read';
+        const { mime, extension } = this.validateAndDetect(buffer, file.originalname ?? '', file.mimetype, isPublic);
+        const result = await this.storageService.put({ buffer, url: file.url, originalname: file.originalname }, {
+            ...options,
+            contentType: mime,
+            extension,
+            contentDisposition: isPublic ? 'attachment' : options.contentDisposition,
+        });
         return result.url;
     }
     async uploadWithStats(file, options = {}) {
@@ -147,6 +156,50 @@ let UploadService = class UploadService extends common_service_1.CommonService {
     detectFileType(buffer, filename) {
         return file_type_detector_1.FileTypeDetector.detect(buffer, filename);
     }
+    validateAndDetect(buffer, originalname, claimedMime, isPublic) {
+        if (!buffer || buffer.length === 0) {
+            throw new operation_exception_1.OperationException('empty upload buffer');
+        }
+        const detected = file_type_detector_1.FileTypeDetector.detect(buffer, originalname);
+        const allowList = isPublic ? upload_allow_list_1.UploadAllowList.PUBLIC : upload_allow_list_1.UploadAllowList.PRIVATE;
+        if (!allowList.has(detected)) {
+            throw new operation_exception_1.OperationException(`upload rejected: ${detected} is not on the ${isPublic ? 'public' : 'private'} allow-list`);
+        }
+        if (claimedMime && claimedMime !== detected) {
+            global.console.warn(`upload-mime-mismatch: claimed=${claimedMime} detected=${detected} name=${originalname}`);
+        }
+        return { mime: detected, extension: this.mimeToExtension(detected) };
+    }
+    mimeToExtension(mime) {
+        const map = {
+            'image/jpeg': '.jpg',
+            'image/png': '.png',
+            'image/gif': '.gif',
+            'image/webp': '.webp',
+            'image/bmp': '.bmp',
+            'image/tiff': '.tiff',
+            'application/pdf': '.pdf',
+            'application/msword': '.doc',
+            'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',
+            'application/vnd.ms-excel': '.xls',
+            'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',
+            'application/vnd.ms-powerpoint': '.ppt',
+            'application/vnd.openxmlformats-officedocument.presentationml.presentation': '.pptx',
+            'application/zip': '.zip',
+            'application/x-rar-compressed': '.rar',
+            'application/x-7z-compressed': '.7z',
+            'audio/mpeg': '.mp3',
+            'audio/wav': '.wav',
+            'audio/mp4': '.m4a',
+            'video/mp4': '.mp4',
+            'video/avi': '.avi',
+            'video/quicktime': '.mov',
+            'text/plain': '.txt',
+            'application/json': '.json',
+            'text/csv': '.csv',
+        };
+        return map[mime] ?? '';
+    }
     async getBufferFromUrl(url) {
         const response = await axios_1.default.get(url, { responseType: 'arraybuffer' });
         return Buffer.from(response.data, 'utf-8');
@@ -154,6 +207,7 @@ let UploadService = class UploadService extends common_service_1.CommonService {
 };
 exports.UploadService = UploadService;
 exports.UploadService = UploadService = __decorate([
+    (0, public_exposed_decorator_1.PublicExposed)(),
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [storage_service_1.StorageService])
 ], UploadService);

package/dist/system/services/upload.service.js.map

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

package/dist/system/system.module.js

@@ -22,7 +22,7 @@ exports.SystemModule = SystemModule = __decorate([
     (0, common_1.Module)({
         imports: [typeorm_1.TypeOrmModule.forFeature(es6_classes_1.default.entities), (0, common_1.forwardRef)(() => auth_module_1.AuthModule), (0, common_1.forwardRef)(() => platform_utility_module_1.PlatformUtilityModule)],
         controllers: es6_classes_1.default.controllers,
-        providers: [...es6_classes_1.default.services, ...es6_classes_1.default.subscribers, ...es6_classes_1.default.jobs],
+        providers: [...es6_classes_1.default.services, ...es6_classes_1.default.jobs],
         exports: [...es6_classes_1.default.services, ...es6_classes_1.default.jobs],
     })
 ], SystemModule);

package/dist/system/system.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"system.module.js","sourceRoot":"","sources":["../../src/system/system.module.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAAoD;AACpD,qDAAiD;AACjD,wFAAmF;AACnF,gEAAuC;AACvC,6CAAgD;AAQzC,IAAM,YAAY,GAAlB,MAAM,YAAY;CAAG,CAAA;AAAf,oCAAY;uBAAZ,YAAY;IANxB,IAAA,eAAM,EAAC;QACJ,OAAO,EAAE,CAAC,uBAAa,CAAC,UAAU,CAAC,qBAAU,CAAC,QAAQ,CAAC,EAAE,IAAA,mBAAU,EAAC,GAAG,EAAE,CAAC,wBAAU,CAAC,EAAE,IAAA,mBAAU,EAAC,GAAG,EAAE,CAAC,+CAAqB,CAAC,CAAC;QAC/H,WAAW,EAAE,qBAAU,CAAC,WAAW;QACnC,SAAS,EAAE,CAAC,GAAG,qBAAU,CAAC,QAAQ,EAAE,GAAG,qBAAU,CAAC,WAAW,EAAE,GAAG,qBAAU,CAAC,IAAI,CAAC;QAClF,OAAO,EAAE,CAAC,GAAG,qBAAU,CAAC,QAAQ,EAAE,GAAG,qBAAU,CAAC,IAAI,CAAC;KACxD,CAAC;GACW,YAAY,CAAG"}
+{"version":3,"file":"system.module.js","sourceRoot":"","sources":["../../src/system/system.module.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAAoD;AACpD,qDAAiD;AACjD,wFAAmF;AACnF,gEAAuC;AACvC,6CAAgD;AAQzC,IAAM,YAAY,GAAlB,MAAM,YAAY;CAAG,CAAA;AAAf,oCAAY;uBAAZ,YAAY;IANxB,IAAA,eAAM,EAAC;QACJ,OAAO,EAAE,CAAC,uBAAa,CAAC,UAAU,CAAC,qBAAU,CAAC,QAAQ,CAAC,EAAE,IAAA,mBAAU,EAAC,GAAG,EAAE,CAAC,wBAAU,CAAC,EAAE,IAAA,mBAAU,EAAC,GAAG,EAAE,CAAC,+CAAqB,CAAC,CAAC;QAC/H,WAAW,EAAE,qBAAU,CAAC,WAAW;QACnC,SAAS,EAAE,CAAC,GAAG,qBAAU,CAAC,QAAQ,EAAE,GAAG,qBAAU,CAAC,IAAI,CAAC;QACvD,OAAO,EAAE,CAAC,GAAG,qBAAU,CAAC,QAAQ,EAAE,GAAG,qBAAU,CAAC,IAAI,CAAC;KACxD,CAAC;GACW,YAAY,CAAG"}

package/dist/worker.js

@@ -2,10 +2,37 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@nestjs/core");
 const app_module_1 = require("./app.module");
+const queue_service_1 = require("./platformUtility/services/queue.service");
+const REDIS_PING_TIMEOUT_MS = 5000;
 async function bootstrap() {
+    const isWorker = process.env.BULL_QUEUE_WORKER === 'true';
+    global.console.log(`worker bootstrap: BULL_QUEUE_WORKER=${isWorker}`);
     const app = await core_1.NestFactory.create(app_module_1.AppModule);
     app.enableShutdownHooks();
-    app.init();
+    await app.init();
+    await assertRedisReachable(app.get(queue_service_1.QueueService));
+    global.console.log('worker ready');
 }
-bootstrap();
+async function assertRedisReachable(queueService) {
+    try {
+        const queue = queueService.getQueueInstance();
+        const client = await queue.client;
+        const info = await Promise.race([
+            client.info(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`timed out after ${REDIS_PING_TIMEOUT_MS}ms`)), REDIS_PING_TIMEOUT_MS)),
+        ]);
+        if (!info) {
+            throw new Error(`unexpected INFO response: ${String(info)}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        global.console.error(`[worker bootstrap] Redis ping failed: ${message}`);
+        process.exit(1);
+    }
+}
+bootstrap().catch((error) => {
+    global.console.error('worker bootstrap failed:', error);
+    process.exit(1);
+});
 //# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -1 +1 @@
-{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":";;AAAA,uCAA2C;AAC3C,6CAAyC;AAEzC,KAAK,UAAU,SAAS;IACpB,MAAM,GAAG,GAAG,MAAM,kBAAW,CAAC,MAAM,CAAC,sBAAS,CAAC,CAAC;IAEhD,GAAG,CAAC,mBAAmB,EAAE,CAAC;IAC1B,GAAG,CAAC,IAAI,EAAE,CAAC;AACf,CAAC;AAED,SAAS,EAAE,CAAC"}
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":";;AAAA,uCAA2C;AAC3C,6CAAyC;AACzC,4EAAwE;AAOxE,MAAM,qBAAqB,GAAG,IAAI,CAAC;AAEnC,KAAK,UAAU,SAAS;IACpB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,MAAM,CAAC;IAC1D,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,uCAAuC,QAAQ,EAAE,CAAC,CAAC;IAEtE,MAAM,GAAG,GAAG,MAAM,kBAAW,CAAC,MAAM,CAAC,sBAAS,CAAC,CAAC;IAEhD,GAAG,CAAC,mBAAmB,EAAE,CAAC;IAC1B,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAQjB,MAAM,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,4BAAY,CAAC,CAAC,CAAC;IAElD,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;AACvC,CAAC;AAED,KAAK,UAAU,oBAAoB,CAAC,YAA0B;IAC1D,IAAI,CAAC;QACD,MAAM,KAAK,GAAG,YAAY,CAAC,gBAAgB,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC;QAKlC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;YAC5B,MAAM,CAAC,IAAI,EAAE;YACb,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC7B,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,mBAAmB,qBAAqB,IAAI,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAC3G;SACJ,CAAC,CAAC;QAEH,IAAI,CAAC,IAAI,EAAE,CAAC;YACR,MAAM,IAAI,KAAK,CAAC,6BAA6B,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjE,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,yCAAyC,OAAO,EAAE,CAAC,CAAC;QACzE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpB,CAAC;AACL,CAAC;AAED,SAAS,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACxB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}

package/docs/sentry-reporting.md

@@ -0,0 +1,147 @@
+# Sentry reporting (consuming applications)
+
+`@servicelabsco/nestjs-utility-services` ships a unified Sentry layer that combines
+`@sentry/nestjs` (Nest integrations, global exception capture, tracing) with this
+package's security defaults:
+
+- `LogRedactor` on every outbound event (`beforeSend`)
+- `includeLocalVariables: false`, `sendDefaultPii: false`
+- Redacted request context and auth user (`id` + `email` only)
+- HTTP **5xx** reporting (4xx `HttpException` values stay out of Sentry)
+- **No reporting from queue worker processes** (`worker.ts` entrypoint)
+- Quiet one-line **ERROR** logs in local/dev (full stacks still go to Sentry)
+
+Peer dependencies `@sentry/nestjs`, `@sentry/node`, and `@sentry/core` are bundled
+with this package — you do not install them separately unless you call the SDK
+directly.
+
+## 1. Environment variables
+
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `SENTRY_DSN` | Yes (to enable) | Project DSN. Never commit; inject via env / secrets manager. |
+| `NODE_ENV` or `APP_ENV` | Recommended | Sentry `environment` tag. |
+| `SERVER_ENV=local` | Optional | Enables quiet terminal error lines (no instrumentation stack dump). |
+| `HTTP_EXCEPTION_VERBOSE_LOG=true` | Optional | Force full local stack traces even in local/dev. |
+| `HTTP_EXCEPTION_QUIET_LOG=true` | Optional | Force quiet logs in any environment. |
+| `SENTRY_DEBUG=true` | Optional | SDK transport debug lines in the terminal. |
+
+Workers may share the same `.env` file. Sentry stays off when the process is started
+via `worker.ts` / `dist/worker.js`, regardless of `SENTRY_DSN`.
+
+## 2. Early init (`instrument.ts`)
+
+Sentry must initialize **before** Nest bootstraps. Create `src/instrument.ts` in your
+application:
+
+```typescript
+import { initSentry } from '@servicelabsco/nestjs-utility-services';
+
+initSentry();
+```
+
+Import it as the **first line** of `main.ts`:
+
+```typescript
+import './instrument';
+
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+    const app = await NestFactory.create(AppModule);
+    // ...
+}
+bootstrap();
+```
+
+Do **not** import `./instrument` from `worker.ts`. Queue workers should never call
+`initSentry()`.
+
+## 3. Nest module wiring
+
+Add `SentryReportingModule` to your root `AppModule` imports (alongside
+`PlatformUtilityModule`, `AuthModule`, `SystemModule`, etc.):
+
+```typescript
+import { Module } from '@nestjs/common';
+import {
+    AuthModule,
+    PlatformUtilityModule,
+    SentryReportingModule,
+    SystemModule,
+} from '@servicelabsco/nestjs-utility-services';
+
+@Module({
+    imports: [
+        SentryReportingModule.forRoot(),
+        PlatformUtilityModule,
+        AuthModule,
+        SystemModule,
+        // your app modules…
+    ],
+})
+export class AppModule {}
+```
+
+When `SENTRY_DSN` is unset, `forRoot()` registers nothing — safe for tests and local
+runs without Sentry.
+
+`SentryReportingModule.forRoot()` registers, in order:
+
+1. `SentryModule.forRoot()` — official Nest SDK integration + HTTP transaction naming
+2. `SentryReportingFilter` — global exception filter (must stay ahead of custom filters)
+3. `SentryUserScopeInterceptor` — per-request user + redacted request on the Sentry scope
+
+If you define your own global `APP_FILTER`, register `SentryReportingModule` **before**
+any custom exception filters, or compose filters explicitly so Sentry still runs first.
+
+## 4. Manual `captureException`
+
+Existing manual captures inside services/jobs continue to work. Prefer
+`@sentry/core` or re-exported SDK symbols; events pass through the same
+`beforeSend` redaction configured in `initSentry()`.
+
+```typescript
+import { captureException } from '@sentry/core';
+
+captureException(error);
+```
+
+On HTTP requests, `SentryUserScopeInterceptor` already attaches the authenticated user
+(from `Auth.user()`) and a redacted request snapshot to the isolation scope.
+
+## 5. Workers
+
+| Process | `initSentry()` | `SentryReportingModule` |
+| --- | --- | --- |
+| `main.ts` (API) | Yes (`instrument.ts`) | Yes |
+| `worker.ts` (BullMQ) | **No** | Harmless if imported via shared `AppModule`, but init stays off on worker entrypoint |
+
+Job failures should be logged/handled in worker code; they are **not** auto-reported to
+Sentry by design.
+
+## 6. Verify
+
+1. Set `SENTRY_DSN` on the API process.
+2. Start the API (`main.ts`), not the worker.
+3. Trigger an unhandled 500 (or use a temporary debug route).
+4. Confirm the issue in the Sentry dashboard.
+5. Locally, expect a single red line: `HTTP 500: … (reported to Sentry)`.
+
+Optional: `SENTRY_DEBUG=true` to print ingest lines in the terminal.
+
+## 7. Source maps (production)
+
+For readable stack traces in Sentry, upload source maps from your **deployed**
+application build (not from this library's `dist/` alone). Follow the
+[Sentry Node source maps guide](https://docs.sentry.io/platforms/javascript/guides/node/sourcemaps/)
+for your CI/CD pipeline.
+
+## Reference (this repo)
+
+The standalone dev app in this repository follows the same pattern:
+
+- `src/instrument.ts` → `initSentry()`
+- `src/main.ts` → `import './instrument'` first
+- `src/app.module.ts` → `SentryReportingModule.forRoot()`

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicelabsco/nestjs-utility-services",
-    "version": "2.0.15",
+    "version": "3.0.1",
     "description": "NestJS generic packages to support development",
     "author": "Hemant Kumar Sah <hemantanshu@gmail.com>",
     "license": "MIT",
@@ -8,7 +8,10 @@
     "main": "dist/index.js",
     "files": [
         "dist/**/*",
-        "*.md"
+        "README.md",
+        "CHANGELOG.md",
+        "LICENSE",
+        "docs/sentry-reporting.md"
     ],
     "types": "dist/index.d.ts",
     "scripts": {
@@ -19,6 +22,7 @@
         "start:debug": "nest start --debug --watch",
         "start:prod": "node dist/main",
         "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+        "lint:codebase": "ts-node --project scripts/tsconfig.json scripts/lint-codebase.ts",
         "test": "jest",
         "test:watch": "jest --watch",
         "test:cov": "jest --coverage",
@@ -31,13 +35,15 @@
         "m:c": "./node_modules/.bin/ts-node ./node_modules/.bin/typeorm migration:create -d src/config/orm.config.ts",
         "m:rev": "./node_modules/.bin/ts-node ./node_modules/.bin/typeorm migration:revert -d src/config/orm.config.ts",
         "runtime-check": "curl -s http://localhost:${SERVER_PORT:-4000}/health/runtime-check | jq . 2>/dev/null || curl -s http://localhost:${SERVER_PORT:-4000}/health/runtime-check",
+        "verify:publish": "node scripts/verify-publish-artifacts.js",
+        "prepublishOnly": "node scripts/verify-publish-artifacts.js",
         "save": "bash ./commit.sh"
     },
     "keywords": [
         "nestjs"
     ],
     "engines": {
-        "node": "^22.0.0 || ^24.11.0"
+        "node": "^24.11.0"
     },
     "publishConfig": {
         "access": "public"
@@ -68,6 +74,7 @@
         "@nestjs/typeorm": "^11.0.0",
         "@nestjs/websockets": "^11.0.0",
         "@sentry/core": "^10.34.0",
+        "@sentry/nestjs": "^10.34.0",
         "@sentry/node": "^10.34.0",
         "@socket.io/redis-adapter": "^8.2.1",
         "axios": "^1.7.9",
@@ -77,6 +84,7 @@
         "class-validator": "^0.15.1",
         "cron-parser": "^5.5.0",
         "date-fns": "^4.1.0",
+        "decimal.js": "^10.6.0",
         "dotenv": "^17.2.3",
         "exceljs": "^4.4.0",
         "express-http-context2": "^1.0.0",
@@ -85,7 +93,6 @@
         "helmet": "^8.1.0",
         "html-to-text": "^10.0.0",
         "ioredis": "^5.9.2",
-        "js-yaml": "^4.1.1",
         "mongodb": "^7.1.0",
         "nodemailer": "^8.0.2",
         "pg": "^8.17.1",
@@ -114,6 +121,7 @@
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-prettier": "^5.5.5",
         "jest": "^30.2.0",
+        "js-yaml": "^4.1.1",
         "prettier": "^3.8.0",
         "supertest": "^7.2.2",
         "ts-jest": "^29.4.6",

package/AGENTS.md

@@ -1,189 +0,0 @@
-# AGENTS.md
-
-This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
-
-## Repository nature
-
-This is a **publishable npm library** (`@servicelabsco/nestjs-utility-services`) that ships compiled output from `dist/` (`main: dist/index.js`). The `src/index.ts`-equivalent (see `dist/index.d.ts`) re-exports `auth`, `common`, `platformUtility`, `security`, `system`, and `worker.service`. Consuming apps install this package and import its modules/services/entities.
-
-It is also runnable as a **standalone NestJS app** (`main.ts` / `worker.ts`) for local development of the library itself — running migrations, exercising endpoints, validating wiring. Treat changes as library changes first: anything exported is part of the public API.
-
-## Common commands
-
-```bash
-yarn build                # nest build → dist/
-yarn start:dev            # watch mode standalone app (main.ts)
-yarn start:prod           # node dist/main
-yarn lint                 # eslint --fix on src/, apps/, libs/, test/
-yarn format               # prettier on src/ and test/
-yarn test                 # jest (rootDir=src, *.spec.ts)
-yarn test -- path/to/file.spec.ts          # run a single test file
-yarn test -- -t "matches test name"        # run tests by name
-yarn test:cov             # coverage → ../coverage
-yarn test:e2e             # jest --config ./test/jest-e2e.json (*.e2e-spec.ts)
-
-# Migrations (TypeORM, src/config/orm.config.ts)
-yarn m:g <name>           # generate from entity diff
-yarn m:c <name>           # create empty
-yarn m:r                  # run pending (ts-node, dev)
-yarn m:rd                 # run pending against compiled dist
-yarn m:rev                # revert last
-
-yarn runtime-check        # curl /health/runtime-check (cron-parser + cache sanity)
-yarn save                 # repo-specific commit helper (see commit.sh)
-```
-
-`yarn save` runs `commit.sh`: pulls, optionally builds, optionally runs `slnu syncClassess`, prettier-formats, then commits as `<JIRA-ID> #comment <message>` extracting the JIRA ID from the current branch name. The recent commit history follows this pattern — preserve it for any commits made through this script.
-
-## High-level architecture
-
-### Five top-level NestJS modules under `src/`
-
-- **`auth/`** — users, sessions, JWT, refresh tokens, social login, device tokens, role/permission assignment. Owns `JwtMiddleware`, `BasicAuthMiddleware`, `InternalMiddleware`, `RestrictedMiddleware`.
-- **`common/`** — framework-level base classes and utilities. The module itself is empty (`@Module({})`); its value is the exported classes. Most other modules and consumers extend these. **`CommonEntity`** (audit/who-columns, soft delete, `firstOrNew`, helpers — all postgres entities extend this), `CommonMongoEntity`, `CommonService`, `CommonSubscriber`, `CommonJob`, `CommonConsumer`, `CommonMapperJob`, `MigrationUtility` / `BaseMigrationUtility` / `ReverseMigrationUtility` (wrap TypeORM migrations), `Auth` (static accessor over express-http-context2 — `Auth.user()`, `Auth.check()`, `Auth.id()`, `Auth.login()`), exception classes (`OperationException`, `AccessException`, `FormException`, `MaintenanceException`, `NoLoggedUserException`, `SubscriptionException`), and pure helpers (`Hash`, `CustomCrypt`, `DateUtil`, `PlatformUtility`, `JsonEvaluator`, `EntityEvaluator`, `DatabaseEventEvaluator`, `GenericIndexParser`, `GenericShowParser`, `ReportBodyParser`, `DataManager`, `RecordManager`, `ListManager`, `ReportListManager`, `ReportDataManager`, `ClassMapper`, `CustomLogger`, `SeederUtility`).
-- **`platformUtility/`** — infra-adjacent services: `S3Service`, `SqsService`, `DynamoService`, `RedisService`, `CacheService` (Redis-backed), `QueueService` (BullMQ), `MailService` (with SMTP/SES variants in `libraries/`), `SmsService`, `FcmNotificationService`, `RemoteRequestService`, `AwsConfigService`, `AwsSecretService`, `SqlService`, `ZipService`, `MaintenanceService`, `AuditService`, `StartupService`, `ShutdownService`. Hosts `JobConsumer` (the BullMQ consumer), `MaintenanceMiddleware`, `TrimPipe`.
-- **`security/`** — registers security-related entities (TypeORM `forFeature`); module is otherwise pass-through.
-- **`system/`** — the bulk of the domain: ~70 entities for menus, roles, permissions, models, columns, relationships, properties, lookups, forms, reports, charts, scripts, scheduled events, mail/sms/whatsapp templates, document storage. Controllers (`BaseController`, `DataController`, `FormController`, `MenuController`, `PreferenceController`, `ReportController`, `UploadController`, `UserPreferenceController`), services for each domain area, jobs that drive recurring/material-view/code-fix/scheduled execution, subscribers that react to entity events, and a `SentryInterceptor`.
-
-### Module wiring convention — `es6.classes.ts`
-
-Every module folder has an `es6.classes.ts` that imports every controller/service/dto/entity/job/subscriber/middleware/library/consumer in that module and exports a single object with arrays. The module file then spreads those arrays into `@Module({ providers, controllers, exports, imports: [TypeOrmModule.forFeature(es6Classes.entities), ...] })`. **When adding a new class to a module, you must register it in that module's `es6.classes.ts` — otherwise it will not be wired into Nest's DI.** The `slnu syncClassess` step in `commit.sh` regenerates these files via libraries in `platformUtility/libraries/create.es6.*.ts` and `create.entity.constants.file.ts`; prefer running it instead of editing by hand when you've added several files.
-
-### `app.module.ts` composition
-
-Top-level wiring:
-- Three TypeORM connections: **`default`** (postgres write — `src/config/typeorm.config.ts`), **`read`** (postgres read replica — `src/config/read.typeorm.config.ts`), **`mongodb`** (`src/config/mongo.config.ts`).
-- BullMQ via `src/config/queue.config.ts`; queue name from `BULL_QUEUE_NAME`. `PlatformUtilityModule` registers consumers only when `BULL_QUEUE_WORKER=true` (otherwise `es6Classes.consumers = []`).
-- TerminusModule for `/health` (master + read replica + redis + filesystem checks in `health.check.controller.ts`; `/health/runtime-check` validates cron-parser v5 and cache round-trip).
-- Middleware order applied to all routes: `MaintenanceMiddleware` → `JwtMiddleware` → `BasicAuthMiddleware`. `RestrictedMiddleware` on `api/*` (rejects unauthenticated). `InternalMiddleware` on `internal/*` (validates `x-internal-token` against `internal.server.key` property, then logs in user id 2).
-
-### Entity / migration discovery
-
-Both `typeorm.config.ts` (write) and `mongo.config.ts` glob entities from **the current build dir AND `node_modules/@servicelabsco/**`**:
-
-```ts
-entities: [
-  join(__dirname, '/../**/**/*.entity.{ts,js}'),
-  join(__dirname, '..', '..', 'node_modules/@servicelabsco/**/*.entity.{ts,js}'),
-],
-```
-
-Mongo uses `*.mentity.{ts,js}` and `*.mongo.subscriber.{ts,js}`. Migrations are similarly merged from this repo's `src/migrations/` and any `@servicelabsco/*` package's `migrations/` dir. `migrationsTableName` is `sys_migrations`. **This means migrations from sibling packages run in this app's database** — be aware when generating new ones, and don't duplicate names across packages.
-
-A snake_case naming strategy (`typeorm-naming-strategies`) maps camelCase entity columns to snake_case in postgres. Postgres `bigint` (oid 20) and `decimal` (oid 1700) are auto-cast to JS `number`/`float` in `pg.types.setTypeParser`.
-
-### Worker vs API
-
-`main.ts` is the HTTP entrypoint (helmet, CORS, rate limit, compression, sentry, global ValidationPipe with `whitelist: true, transform: true`, optional graceful shutdown via `SERVER_COOL_DOWN_PERIOD`). `worker.ts` is the queue-worker entrypoint — same `AppModule`, no `listen()`, just `init()` + shutdown hooks; in this mode `BULL_QUEUE_WORKER=true` is required for consumers to register. `WorkerService.onModuleInit` calls `MaintenanceService.disableQueueIfRequired()` before processing starts.
-
-### Auth context
-
-Request-scoped user is stored via `express-http-context2` and accessed everywhere through the static `Auth` class (`src/common/libraries/auth.ts`). `JwtMiddleware` sets it from a Bearer token; `InternalMiddleware` sets it to user id 2 after validating the internal token. **Never inject the user from the request manually** — use `Auth.user()` / `Auth.id()` / `Auth.check()` so behavior is consistent with the rest of the codebase, and so it works in jobs/consumers that propagate the context.
-
-### Tests
-
-Jest config lives in `package.json` (`rootDir: src`, `testRegex: .*\\.spec\\.ts$`, `ts-jest`). E2E uses `test/jest-e2e.json` with `*.e2e-spec.ts`. Tests sit alongside source as `*.spec.ts` (e.g. `auth.service.spec.ts`, `cache.service.spec.ts`, `zip.service.spec.ts`, all of `common/libraries/`, all of `common/exceptions/`).
-
-## Conventions to follow
-
-- **4-space indent, single quotes, 150-char line width** (`.prettierrc`). Run `yarn format` before committing.
-- New entities extend `CommonEntity` (or `CommonMongoEntity` for mongo) — never `BaseEntity` directly. Filename suffix is `.entity.ts` (postgres) or `.mentity.ts` (mongo) — the loader globs depend on this.
-- New subscribers: filename `*.subscriber.ts` (postgres) or `*.mongo.subscriber.ts` (mongo).
-- New services extend `CommonService`. New jobs extend `CommonJob` / `CommonMapperJob`. New consumers extend `CommonConsumer`.
-- Throw the project's exception classes (`OperationException`, `AccessException`, etc.) rather than raw `HttpException` / `Error` — they integrate with the response shape and (where applicable) sentry.
-- Migrations: instantiate `MigrationUtility` (or `ReverseMigrationUtility`) in the generated migration class so the `up`/`down` semantics handle the reverse-migration flag correctly. Migration filenames follow `<timestamp>-<PascalCaseDescription>.ts`.
-- After adding files to a module, regenerate or update that module's `es6.classes.ts` so DI picks it up.
-- Library/exported public API: anything added under the five top-level modules is reachable by consumer apps via `@servicelabsco/nestjs-utility-services`. Avoid breaking renames/removals of exports without considering downstream impact, and rebuild (`yarn build`) before publishing.
-
-## File and class naming conventions
-
-These rules are not merely stylistic — the `slnu syncClassess` dev CLI walks every module subdirectory and emits `import { ClassName } from './${dir}/${file}'` for every file it finds. If a file does not export a named symbol matching its filename, the generated `es6.classes.ts` will not compile. Honour the conventions even when you think they don't matter.
-
-### Filename ↔ export name match
-
-The filename basename (dot-separated lowercase) maps to PascalCase + a suffix derived from the file's last segment:
-
-| Filename                         | Required named export             |
-|----------------------------------|-----------------------------------|
-| `aws.s3.service.ts`              | `AwsS3Service`                    |
-| `create.user.dto.ts`             | `CreateUserDto`                   |
-| `user.entity.ts`                 | `UserEntity`                      |
-| `object.ref.interface.ts`        | `ObjectRefInterface`              |
-| `scheduled.event.subscriber.ts`  | `ScheduledEventSubscriber`        |
-| `recurring.query.job.ts`         | `RecurringQueryJob`               |
-| `storage.constants.ts`           | `StorageConstants` (object — see below) |
-
-Single primary export per file. Helpers tightly coupled to the primary (e.g. `storage.upload.options.dto.ts` exports `StorageSseOptions` next to the primary `StorageUploadOptionsDto`) may co-locate, but **peer types must each live in their own file** — do not stuff multiple unrelated interfaces in one file.
-
-### Interfaces and types live in `interfaces/`, not `dtos/`
-
-`dtos/` is for class-based DTOs (often with `class-validator` decorators). Pure TypeScript `interface` / `type` declarations belong under a sibling `interfaces/` directory:
-
-```
-src/system/dtos/file.upload.dto.ts          # class FileUploadDto {}
-src/system/interfaces/object.ref.interface.ts   # interface ObjectRefInterface {}
-src/system/interfaces/storage.ref.interface.ts  # type StorageRefInterface = string | ObjectRefInterface
-```
-
-File suffix `.interface.ts`, type name suffix `Interface`. One type per file when types are peers.
-
-### Constants: single-bag object pattern
-
-Constants files are exempt from "one class per file" but still must match the filename↔export rule. Use a **named object export** (not `export = ...`, which breaks the dev CLI's named-import generation):
-
-```ts
-// src/system/constants/storage.constants.ts
-export const StorageConstants = {
-    ENGINE_S3: 's3',
-    ENGINE_R2: 'r2',
-};
-```
-
-Consumers: `import { StorageConstants } from '...'; StorageConstants.ENGINE_S3`.
-
-`src/config/source.hash.ts` uses the older `export = SourceHash` + `import SourceHash = require(...)` pattern — that's legacy. New constants files should use `export const Foo = {...}`.
-
-### No "bag of functions" files
-
-Do not create files (like the now-removed `sql.safety.ts`) whose only purpose is to `export function ...`. The convention is one class/object per file; bare functions don't fit it. Fold helpers into the class that owns the responsibility — e.g. SQL safety helpers (`isSafeOrderBy`, `escapeSqlString`, `detectSqlInjectionSignature`, `detectHighConfidenceInjection`) live as **instance methods** on `SqlService`.
-
-When the helper needs to be reached from a manually-instantiated (non-DI) class like `GenericIndexParser` or `GetReportQuery`, thread the owning service through the constructor:
-
-```ts
-new GenericIndexParser(query, this.sqlService).process();
-new GetReportQuery(this.report, this.sqlService).process(...);
-```
-
-### Prefer instance methods over static
-
-Service methods should be instance methods (`this.sqlService.isSafeOrderBy(x)`), not static (`SqlService.isSafeOrderBy(x)`). Instance methods give consistent DI/mocking semantics and stay testable via the injected instance. Reserve `static` for genuinely class-level concerns like factories or singletons.
-
-### Module wiring lives in `es6.classes.ts`, not inline in module files
-
-The dev CLI regenerates each module's `es6.classes.ts` from filesystem contents. Module files (`system.module.ts`, `platform.utility.module.ts`, etc.) should be minimal:
-
-```ts
-@Module({
-    imports: [TypeOrmModule.forFeature(es6Classes.entities), ...],
-    controllers: es6Classes.controllers,
-    providers: [...es6Classes.services, ...es6Classes.subscribers, ...es6Classes.jobs],
-    exports: [...es6Classes.services, ...es6Classes.jobs],
-})
-export class SystemModule {}
-```
-
-Avoid inline `{ provide: SOME_TOKEN, useFactory: ... }` provider blocks. If a service consumes a set of adapter classes, **inject the adapter classes directly** rather than introducing a DI token + factory:
-
-```ts
-// Good — wiring is automatic via es6Classes.services
-constructor(private readonly s3: AwsS3Service, private readonly r2: CloudflareR2Service) {
-    this.registry = new Map([[s3.engineId, s3], [r2.engineId, r2]]);
-}
-
-// Avoid — pulls bespoke wiring into the module file
-constructor(@Inject(STORAGE_ENGINE_ADAPTERS) adapters: CommonStorageService[]) { ... }
-```
-
-### Fixing CLI fallout
-
-If `slnu syncClassess` emits a broken import, the source file violates the naming convention — fix the source file (rename, add the missing export, move it to the right directory). Do not hand-edit `es6.classes.ts` as a permanent workaround; the next CLI run will overwrite your edit.