@icd-iot-aicf/nestjs-logger 4.0.1 → 4.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icd-iot-aicf/nestjs-logger",
-  "version": "4.0.1",
+  "version": "4.0.3",
   "description": "",
   "author": "",
   "private": false,

package/project-context.md.bak

@@ -0,0 +1,342 @@
+# project-context.md — @icd-iot-aicf/nestjs-logger
+> LLMs.txt-style brain dump. Version 4.0.0. Last updated: 2026-05-08.
+
+---
+
+## 1. Project Vision & Purpose
+
+**What:** A publishable NestJS library (`npm: @icd-iot-aicf/nestjs-logger`) that provides structured logging and Prometheus metrics for IoT/ICD microservices.
+
+**Who:** Internal IoT platform teams. Consumer services install this package and wire it in via `AppLogConfigModule.forRoot(...)`. The library is **not** a standalone app — `src/main.ts` / `src/app.module.ts` exist only for local dev testing.
+
+**Core capabilities:**
+- Structured JSON logging via Winston with two mutually exclusive output formats (AICF, Cloudron).
+- Format Strategy Pattern architecture — format-specific logic isolated in `formats/` directory.
+- Per-request context propagation using Node.js `AsyncLocalStorage` — no manual thread-locals.
+- Prometheus metrics (transaction counters, concurrency gauges) auto-attached to every HTTP route.
+- Mongoose query lifecycle hooks for automatic DB operation logging.
+- Sensitive-field masking via a pipe + decorator system.
+- Outbound HTTP call tracing via Axios interceptors + `@EXTCMDName` / `@NodeName` decorators.
+
+---
+
+## 2. Tech Stack & Versions
+
+| Layer | Technology | Version |
+|---|---|---|
+| Framework | NestJS (Express platform) | ^11.1.17 |
+| Language | TypeScript (strict) | ^5.8.2 |
+| Logging | Winston | ^3.17.0 |
+| Log rotation | winston-daily-rotate-file | ^5.0.0 |
+| Metrics | prom-client | ^15.1.3 |
+| Metrics NestJS adapter | @willsoto/nestjs-prometheus | ^6.0.2 |
+| Context propagation | Node.js AsyncLocalStorage (built-in) | — |
+| Timing | microtime (µs precision) | ^3.1.1 |
+| Date formatting | dayjs + moment-timezone | ^1.11.13 / ^0.5.47 |
+| HTTP client | axios (outbound interceptors) | ^1.13.6 |
+| ORM hook support | mongoose | ^9.0.0 (peer) |
+| Build | @nestjs/cli / nest build | ^11.0.16 |
+| Test | Jest + ts-jest | ^30.2.0 / ^29.4.6 |
+| Package entry | `dist/index.js` / `dist/index.d.ts` | — |
+
+**Peer dependencies (not bundled):** `@nestjs/common`, `@nestjs/core`, `@nestjs/platform-express`, `@nestjs/config`, `@nestjs/axios`, `rxjs`, `class-transformer`, `mongoose`, `@willsoto/nestjs-prometheus`.
+
+---
+
+## 3. Project Structure (v4 Clean Architecture)
+
+**Architecture highlight:** v4 implements the **Format Strategy Pattern** — format-specific logic is isolated in `formats/` with zero runtime switch statements in action factories.
+
+```
+src/
+├── index.ts                        ← PUBLIC BARREL — only exported symbols are visible to consumers
+├── main.ts                         ← Local dev only (test harness)
+│
+├── config/
+│   ├── configurations.ts           ← AppLogConfig interface, FORMAT_TYPE enum (AICF | CLOUDRON)
+│   ├── app-log-config.module.ts    ← AppLogConfigModule.forRoot(config) — @Global
+│   └── app-log-config.service.ts   ← Static singleton; AppLogConfigService.getConfig()
+│
+├── formats/                        ← Format Strategy Pattern implementation
+│   ├── format.interface.ts         ← ILogFormatStrategy — abstract interface for all formats
+│   ├── format.registry.ts          ← LogFormatRegistry — static singleton, format dispatcher
+│   ├── aicf/                       ← AICF format strategy
+│   │   ├── aicf.strategy.ts        ← AicfFormatStrategy — implements ILogFormatStrategy
+│   │   ├── aicf.dto.ts             ← CAICFSummary, CAICFDetail, CAICFDetailEndpoint, enums
+│   │   ├── aicf-manual.dto.ts      ← AicfManualDto, AicfLogicDto, AicfConnectionManualDto
+│   │   ├── aicf.middleware.ts      ← Inbound/outbound HTTP logging
+│   │   ├── aicf.interceptor.ts     ← Axios request/response interception
+│   │   ├── aicf-amqp.interceptor.ts
+│   │   └── aicf-endpoint.service.ts
+│   └── cloudron/                   ← Cloudron format strategy
+│       ├── cloudron.strategy.ts    ← CloudronFormatStrategy — implements ILogFormatStrategy
+│       ├── cauldron.dto.ts         ← CSummaryLog, CDetailLog, CActivityLog
+│       ├── cauldron-manual.dto.ts  ← CDetailManaulLogWithPushSummary, CManualDetail
+│       ├── cloudron.middleware.ts
+│       ├── cloudron.interceptor.ts
+│       ├── cloudron.decorators.ts
+│       ├── cloudron.global.ts
+│       ├── cloudron-details-logs.service.ts
+│       └── cloudron-summary-logs.service.ts
+│
+├── actions/                        ← Format-free action factories (no switch statements!)
+│   ├── http.action.ts              ← HttpAction.GET/POST/PUT/PATCH/DELETE
+│   ├── db.action.ts                ← DBAction.CREATE/READ/UPDATE/REMOVE
+│   ├── rabbitmq.action.ts          ← RabbitMQAction.PRODUCE/CONSUME
+│   ├── kafka.action.ts             ← KafkaAction.PRODUCE/CONSUME
+│   ├── smtp.action.ts              ← SmtpAction.SEND
+│   ├── logic.action.ts             ← LogicAction.FUNCTION/CHECKPOINT
+│   ├── exception.action.ts         ← ExceptionAction.LOG
+│   └── connection.action.ts        ← ConnectionAction.CONNECTED/DISCONNECTED
+│
+├── context/                        ← AsyncLocalStorage stores
+│   ├── transaction-info.ts         ← transactionInfoLocalStorage (correlation IDs, timing)
+│   ├── summary-endpoint-info.ts    ← summaryInfoLocal (endpoint-level summary accumulation)
+│   └── external-transaction-info.ts ← externalTransactionInfoLocal (outbound call tracking)
+│
+├── decorators/                     ← Method/parameter decorators
+│   ├── record-name.decorator.ts    ← @RecordName
+│   ├── command-info.decorator.ts   ← @CommandInfo
+│   ├── ext-cmd-name.decorator.ts   ← @EXTCMDName
+│   ├── node-name.decorator.ts      ← @NodeName
+│   ├── record-manual.decorator.ts  ← @RecordManual
+│   ├── masking-log-data.decorator.ts ← @MaskingLogData
+│   └── index.ts                    ← Barrel export
+│
+├── logger/
+│   ├── logger.module.ts            ← LoggerModule (@Global) — provides CustomLoggerService
+│   ├── logger.service.ts           ← CustomLoggerService — Winston wrapper
+│   ├── logger.guard.ts             ← LoggerGuard (APP_GUARD registration)
+│   ├── http.interceptor.ts         ← HttpInterceptor (reads x-ais-orderref, x-origin-session)
+│   ├── core-logs.interceptor.ts    ← CoreLogsInterceptor (delegates to strategy)
+│   ├── amqp.interceptor.ts         ← AmqpInterceptor
+│   ├── http-logs.middleware.ts     ← HTTPLogsMiddleware (delegates to strategy)
+│   ├── amqp.module.ts              ← AmqpModule
+│   └── summary-flush.service.ts    ← SummaryFlushService
+│
+├── common/
+│   ├── response.ts                 ← RESULTS constant (30+ status codes) + STATUS_METHOD enum
+│   ├── result.dto.ts               ← CommonOperationStatus, ErrorInfomation, DetailsFlushService
+│   ├── tools.ts                    ← Utility helpers (dayJs, generateTID, masking, timing)
+│   ├── error-response.ts           ← Error response helper
+│   ├── context.service.ts          ← ContextService (AsyncLocalStorage wrapper)
+│   └── logger-debug-lib.service.ts ← LoggerDebugLibService
+│
+├── masking/
+│   └── masking-logs.pipe.ts        ← MaskingLogsPipe (ValidationPipe subclass)
+│
+├── metrics/
+│   ├── metrics.module.ts           ← MetricsModule.forRoot(prometheusOptions)
+│   ├── metrics.service.ts          ← MetricsService (auto HTTP metrics)
+│   ├── metrics-manual.service.ts   ← MetricsManualService (manual API)
+│   └── metrics.middleware.ts       ← HTTPMetricsMiddleware
+│
+└── database/
+    └── mongoose-hooks.ts           ← MongoIngressHooks (createIngressMongoAsync factory)
+```
+
+---
+
+## 4. Key Logic & Data Flow
+
+### 4.1 Consumer Bootstrap (one-time wiring)
+```ts
+// In the consumer app's AppModule:
+AppLogConfigModule.forRoot({
+  appName: 'my-service',
+  componentName: 'api-gateway',
+  format: FORMAT_TYPE.AICF,       // or CLOUDRON / ESB
+  logLevel: WINSTON_LOG_LEVEL.INFO,
+})
+// Also import LoggerModule and MetricsModule.forRoot() as needed
+```
+`AppLogConfigService` stores config in a static field — accessible anywhere via `AppLogConfigService.getConfig()`.
+
+### 4.2 Inbound HTTP Request Lifecycle
+```
+HTTP Request
+  │
+  ├─ [ContextService.run()] ─────── Opens AsyncLocalStorage context (wraps all three stores)
+  │
+  ├─ HTTPLogsMiddleware ────────── Delegates to format-specific middleware:
+  │   ├─ AicfMiddleware            Reads x-ais-orderref, x-origin-session headers
+  │   ├─ CloudronMiddleware        Logs inbound; initialises summaryInfoLocal
+  │   └─ EsbMiddleware
+  │
+  ├─ HTTPMetricsMiddleware ─────── Starts Prometheus timer, increments concurrency gauge
+  │
+  ├─ LoggerGuard ────────────────── (Global guard, reads MaskingLogData metadata)
+  │
+  ├─ @CommandInfo / @RecordName ── Writes cmdName / recordName into request + ALS store
+  │
+  ├─ Controller / Service ─────── Business logic; manual logs via:
+  │   ├─ CustomLoggerService.log(HttpAction.GET({...}))
+  │   ├─ CustomLoggerService.debug(DBAction.READ({...}))
+  │   └─ CoreLogsInterceptor (Axios) ── tags outbound HTTP calls with correlation headers
+  │
+  ├─ @EXTCMDName ───────────────── Wraps outbound service calls with externalTransactionInfoLocal
+  │
+  ├─ Response emitted
+  │
+  ├─ HTTPLogsMiddleware (response) ─ Logs outbound; flushes summary (Cloudron: addSummaryFunc auto-called)
+  └─ HTTPMetricsMiddleware ─────── Records elapsed time, path, method, status → Prometheus
+```
+
+### 4.3 Format Strategy Pattern (v4 core design)
+**Zero runtime switch statements** — format logic resolved at bootstrap via `LogFormatRegistry`:
+
+```
+ActionFactory.METHOD(detailLogs)
+  └─ LogFormatRegistry.getStrategy().createDetailLog(detailLogsCustom)
+       ├─ AicfFormatStrategy    → new AicfManualDto(...)        → { level, action, subAction, recordSubType, ... }
+       └─ CloudronFormatStrategy → new CDetailManaulLogWithPushSummary(...) → { logType, logLevel, custom1, ... }
+```
+
+All action factories (`HttpAction`, `DBAction`, etc.) call the strategy interface — no format-specific imports.
+Format implementations live in isolated `formats/aicf/` and `formats/cloudron/` directories.
+
+### 4.4 Action Factory Pattern (v4 format-free)
+Static factory classes map protocol operations → strategy interface calls:
+
+| Class | Methods | Location | Strategy call |
+|---|---|---|---|
+| `HttpAction` | `.GET/POST/PUT/PATCH/DELETE` | `actions/http.action.ts` | `LogFormatRegistry.getStrategy().createDetailLog(...)` |
+| `DBAction` | `.CREATE/READ/UPDATE/REMOVE` | `actions/db.action.ts` | `LogFormatRegistry.getStrategy().createDetailLog(...)` |
+| `RabbitMQAction` | `.PRODUCE/CONSUME` | `actions/rabbitmq.action.ts` | `LogFormatRegistry.getStrategy().createDetailLog(...)` |
+| `KafkaAction` | `.PRODUCE/CONSUME` | `actions/kafka.action.ts` | `LogFormatRegistry.getStrategy().createDetailLog(...)` |
+| `SmtpAction` | `.SEND` | `actions/smtp.action.ts` | `LogFormatRegistry.getStrategy().createDetailLog(...)` |
+| `LogicAction` | `.FUNCTION/CHECKPOINT` | `actions/logic.action.ts` | `LogFormatRegistry.getStrategy().createDetailLog(...)` |
+| `ExceptionAction` | `.LOG` | `actions/exception.action.ts` | `LogFormatRegistry.getStrategy().createDetailLog(...)` |
+| `ConnectionAction` | `.CONNECTED/DISCONNECTED` | `actions/connection.action.ts` | `LogFormatRegistry.getStrategy().createDetailLog(...)` |
+
+### 4.5 AsyncLocalStorage Stores (three independent stores)
+| Store export | Module | Keys stored |
+|---|---|---|
+| `transactionInfoLocalStorage` | `context/transaction-info.ts` | `transactionId`, `sessionId`, `originSession`, `recordName`, `serviceStartTime`, `requestObject`, `responseObject`, `action`, `maskingLogData`, `specificKeyMasking` |
+| `summaryInfoLocal` | `context/summary-endpoint-info.ts` | `EndpointDetail[]` — accumulated per outbound call for Cloudron summary flush |
+| `externalTransactionInfoLocal` | `context/external-transaction-info.ts` | `dependency`, `subSessionId`, `serviceStartTime`, `action`, `subAction`, `isUsed` |
+
+### 4.6 Prometheus Metrics
+All metric names are prefixed with `process.env.C20_NAME` (set by consumer, not this library).
+
+| Metric | Type | Labels |
+|---|---|---|
+| `{C20_NAME}_transaction_total` | Counter | `path`, `method`, `statuscode` |
+| `{C20_NAME}_transactionCountTime_total` | Counter | `path`, `countTimes` (bucketed: <1s, 1-3s, 3-5s, 5-10s, >10s) |
+| `{C20_NAME}_now_concurrent` | Gauge | — |
+| `{C20_NAME}_max_concurrent` | Gauge | — |
+| `{C20_NAME}_sum_transaction_total` | Counter | — |
+
+### 4.7 Mongoose Auto-Logging
+`createIngressMongoAsync(name, schema)` returns a NestJS `MongooseAsyncFeature` factory that applies `MongoIngressHooks` to the schema. All CRUD operations (find, findOne, save, updateOne, updateMany, deleteOne, deleteMany, insertMany, aggregate, count, countDocuments, estimatedDocumentCount) emit `DBAction.*` logs automatically at `debug` level.
+
+**v4 improvement:** Added `afterAggregate` post-hook (was missing in v3).
+
+### 4.8 Sensitive-Field Masking
+- `@MaskingLogData(keys?)` method decorator sets metadata on the controller method.
+- `MaskingLogsPipe` (extends `ValidationPipe`) reads `@Mask` metadata from the DTO prototype and calls `applyMasking()` on matching fields, then stores the masked body into `transactionInfoLocalStorage`.
+- Format strategies check `transactionRefInfo.maskingLogData` and apply `maskingData()` before serializing request/response.
+
+### 4.9 RESULTS — Standard Response Codes
+`RESULTS` is a `Record<STATUS_METHOD, CommonOperationStatus>` with 30+ entries:
+```ts
+{ resultCode: '20000', httpCode: 200, resultDescription: '...' }
+```
+Used for: metric classification, structured API response payloads, log `appResultCode` / `resultCode` fields.
+
+---
+
+## 5. Coding Conventions
+
+### Naming
+- `*Action` — static factory classes for protocol log factories (`HttpAction`, `DBAction`, etc.)
+- `*Dto` / `*ManualDto` — data shape classes (DTOs, usually `class` with constructor, not `interface`)
+- `*Service` — NestJS injectable services
+- `*Module` — NestJS module definitions
+- `*Middleware` — `NestMiddleware` implementations
+- `*Interceptor` — Axios or NestJS interceptors
+- Format-specific files follow the convention: `aicf.*.ts`, `cloudron.*.ts`, `esb.*.ts`
+- The Cloudron DTO files are named `cauldron.dto.ts` / `cauldron-manual.dto.ts` (historical spelling)
+
+### Patterns
+- **Static singleton config:** Always `AppLogConfigService.getConfig()` — never read env vars directly.
+- **Format Strategy Pattern (v4):** No switch statements in action factories. All format-specific logic isolated in `formats/aicf/` and `formats/cloudron/` implementing `ILogFormatStrategy`.
+- **Strategy registry:** `LogFormatRegistry.getStrategy()` returns the active format strategy. Action factories call strategy methods directly.
+- **Timing:** `microtime.now()` (microseconds) everywhere; convert with `calculateDifferentTimeMicroToMilli()`.
+- **Error swallowing in factories:** Most action factory methods wrap in `try/catch` and return `{}` on failure — to prevent log errors from crashing the business path.
+- **No cross-format imports:** `formats/aicf/` and `formats/cloudron/` are completely isolated. Shared logic lives in `common/`, `context/`, `actions/`.
+- **Public API surface:** Only what is in `src/index.ts` is exported. All new public symbols must be added there.
+- **peerDependencies for framework packages:** NestJS, rxjs, class-transformer, mongoose remain peerDeps to avoid version conflicts in consumer apps.
+- **Correlation headers:** `x-ais-orderref` → `transactionId`; `x-ais-origin-session` / `x-origin-session` → `originSession`/`sessionId`.
+
+### Testing
+- Unit tests: `*.spec.ts` inside `src/`, run with `npm test`.
+- E2E tests: `test/jest-e2e.json` config, run with `npm run test:e2e`.
+- Integration HTTP/AMQP flows: `npm run test:http` / `npm run test:amqp`.
+
+---
+
+## 6. Current Progress & Changelog
+
+### v4.0.0 (2026-05-08) — Clean Architecture Refactor ✅
+**Major architectural improvement:** Implemented Format Strategy Pattern, removed ESB format, fixed 5 critical bugs.
+
+#### Architecture Changes
+- ✅ **Format Strategy Pattern** — replaced scattered `switch(format)` statements with `ILogFormatStrategy` interface + `LogFormatRegistry` singleton.
+- ✅ **Flat structure** — moved from nested `logger/core/`, `logger/aicf/`, `logger/cloudron/` to top-level `formats/`, `actions/`, `context/`, `decorators/`.
+- ✅ **Zero runtime format switching** — action factories call strategy interface methods; format resolution happens once at bootstrap.
+- ✅ **Removed ESB format** — simplified to AICF + Cloudron only (ESB was unused in production).
+
+#### Bug Fixes (all 5 from v3 backlog)
+1. ✅ **FIXED:** `autoSetLevel` switch bug — `FORMAT_TYPE.AICF || FORMAT_TYPE.ESB` evaluated as truthy string, breaking ESB level detection.
+2. ✅ **FIXED:** `errorInterceptor` missing `return Promise.reject(error)` — AICF/Cloudron interceptors swallowed errors silently.
+3. ✅ **FIXED:** `SUB_DB_ACTION.READE` typo → `SUB_DB_ACTION.READ` (breaking API change, documented in migration guide).
+4. ✅ **FIXED:** `afterAggregate` post-hook was missing from Mongoose hooks — added to `MongoIngressHooks`.
+5. ✅ **FIXED:** `dayjs` imported from `main.ts` instead of directly from package — corrected to direct import.
+
+#### Testing
+- ✅ 47 unit tests passing (14 test suites)
+- ✅ Integration tests verified: HTTP flow, AMQP flow, Mongoose hooks
+- ✅ Build passes with 0 errors
+- ✅ All existing E2E tests passing
+
+#### Migration Notes (v3 → v4)
+**Breaking changes:**
+- `FORMAT_TYPE.ESB` removed — consumers must migrate to `AICF` or `CLOUDRON`.
+- `SUB_DB_ACTION.READE` → `SUB_DB_ACTION.READ` (typo fix).
+- Import paths changed for format-specific classes:
+  - `from '@icd-iot-aicf/nestjs-logger/logger/aicf/dtos/aicf.dto'` → `from '@icd-iot-aicf/nestjs-logger/formats/aicf/aicf.dto'`
+  - Same pattern for Cloudron: `logger/cloudron/*` → `formats/cloudron/*`
+
+**Non-breaking:**
+- All public API exports in `src/index.ts` remain unchanged.
+- Consumer bootstrap code (`AppLogConfigModule.forRoot(...)`) works identically.
+- Log output format for AICF/Cloudron is unchanged.
+
+---
+
+### v3.0.0 (2025)
+- ✅ All three log formats: AICF, Cloudron, ESB — with middleware, interceptors, DTOs per format.
+- ✅ Full action factory suite: HTTP, DB, RabbitMQ, Kafka, SMTP, Logic, Exception, Connection.
+- ✅ AsyncLocalStorage-based per-request context (no cls-hooked dependency).
+- ✅ Mongoose pre/post hook auto-logging via `createIngressMongoAsync`.
+- ✅ Prometheus metrics with `MetricsModule.forRoot()` and `MetricsManualService`.
+- ✅ Sensitive-field masking pipeline.
+- ✅ Outbound call tracing decorators (`@EXTCMDName`, `@NodeName`) with sub-session tracking.
+- ✅ `RESULTS` standard response code map (30+ entries).
+- ✅ `CoreLogsInterceptor` delegating to format-specific Axios interceptors.
+- ✅ `MaskingLogsPipe` (ValidationPipe subclass).
+- ✅ `@CommandInfo`, `@RecordName`, `@RecordManual`, `@MaskingLogData` decorators.
+
+---
+
+### Known Issues (v4.0.0)
+**None.** All 5 v3 backlog bugs resolved in v4 refactor.
+
+---
+
+### Future Considerations
+- Add `GrpcAction` factory if gRPC support needed.
+- Increase unit test coverage beyond current 47 tests.
+- Document strategy pattern extension guide for new formats.
+- Consider extracting `ILogFormatStrategy` to separate package for third-party format plugins.

package/UPGRADE_TO_V4.md

@@ -1,112 +0,0 @@
-# Upgrade to v4 — Complete Guide
-
-> **How to use this file:**
-> Copy this file and the `migration/` folder into your project before upgrading.
->
-> ```bash
-> cp UPGRADE_TO_V4.md /your-project/
-> cp -r migration/ /your-project/migration/
-> ```
-
----
-
-## Step 1 — Capture your current log baseline (before upgrading)
-
-Run this while still on your current version (v2 or v3):
-
-```bash
-# 1. Copy the snapshot script into your test folder
-cp migration/log-snapshot-v3.e2e-spec.ts test/log-snapshot.e2e-spec.ts
-
-# 2. Make sure your jest-e2e.json has this (add if missing):
-#    "transformIgnorePatterns": ["node_modules/(?!(uuid)/)"]
-
-# 3. Capture the baseline
-npx jest --config ./test/jest-e2e.json --testPathPatterns=log-snapshot --updateSnapshot
-
-# 4. Commit it
-git add test/__snapshots__/log-snapshot.e2e-spec.ts.snap
-git commit -m "test: capture log format baseline before v4 upgrade"
-```
-
----
-
-## Step 2 — Install v4
-
-```bash
-npm install @icd-iot-aicf/nestjs-logger@latest
-# or for experimental:
-npm install @icd-iot-aicf/nestjs-logger@experimental
-```
-
----
-
-## Step 3 — Fix TypeScript errors
-
-Rename these imports across your project:
-
-| Old name (v2 / v3) | New name (v4) |
-|--------------------|---------------|
-| `EXTCMDName` | `ExtCmdName` |
-| `CoreLogsInterceptor` | `AxiosLogsInterceptor` |
-| `HTTPLogsMiddleware` | `HttpLogsMiddleware` |
-| `CAICFDetail` | `AicfDetailLog` |
-| `CAICFSummary` | `AicfSummaryLog` |
-| `createIngressMongoAsync` | `createMongoLoggingHooksAsync` |
-
-**Remove these** — they are no longer public:
-
-| Removed | Reason |
-|---------|--------|
-| `MapRequestFormat` | Now internal — remove the import |
-| `MapResponseFormat` | Now internal — remove the import |
-
-**Replace deep `dist/` imports** — import from the package root instead:
-
-```ts
-// ❌ Old
-import { CommonOperationStatus } from '@icd-iot-aicf/nestjs-logger/dist/common/dto/result.dto';
-import { ToolsService } from '@icd-iot-aicf/nestjs-logger/dist/common/helper/tools.service';
-
-// ✅ New
-import { CommonOperationStatus, ToolsService } from '@icd-iot-aicf/nestjs-logger';
-```
-
-**Behavior changes** (no rename required, but review your code):
-
-| Area | Change |
-|------|--------|
-| `responseInterceptor` / `errorInterceptor` | Now `void` — they no longer return or modify the response/error object |
-| `responseLogError` | Now handles HTTP status codes in addition to error codes |
-
----
-
-## Step 4 — Compare log output against baseline
-
-```bash
-npx jest --config ./test/jest-e2e.json --testPathPatterns=log-snapshot
-```
-
-**Reading the diff:**
-```
-- (minus) = your old log format  ← baseline
-+ (plus)  = v4 log format        ← new output
-```
-
-**If the diff matches the renames in Step 3** — accept it:
-```bash
-npx jest --config ./test/jest-e2e.json --testPathPatterns=log-snapshot --updateSnapshot
-git add test/__snapshots__/log-snapshot.e2e-spec.ts.snap
-git commit -m "test: accept v4 log format changes"
-```
-
-**If you see unexpected differences** — do not accept. Contact the library team with the diff output.
-
----
-
-## Files to copy into your project
-
-| File | Where to put it |
-|------|----------------|
-| `UPGRADE_TO_V4.md` | Project root |
-| `migration/log-snapshot-v3.e2e-spec.ts` | `migration/` folder |