@dv4resi/dvss-backend-module-offering-im 0.0.14 → 0.0.15

package/README.md

@@ -1,72 +1,316 @@
-# dvss-backend-module-offering-im
+# @dv4resi/dvss-backend-module-offering-im
 
-Offering Integration Manager module for UIF. This app consumes shared
-integration packages and provides the offering integration runtime.
+Offering Integration Manager module for UIF. This app aggregates and bundles the internal integration packages into a single publishable npm package that consuming microservices install.
 
-## Dependencies
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [What Gets Bundled](#what-gets-bundled)
+- [How Consuming Microservices Use This](#how-consuming-microservices-use-this)
+- [Bundling Configuration](#bundling-configuration)
+- [Scripts](#scripts)
+- [Local Development](#local-development)
+- [Local Linking with yarn link](#local-linking-with-yarn-link)
+- [Release Checklist](#release-checklist)
+- [Dependencies](#dependencies)
+
+---
+
+## Overview
 
-Development dependencies include:
+This is the **published app** for the offering integration domain. It acts as an aggregator module that:
 
-- `@dvss/dvss-integration-libs`
-- `@dvss/dvss-integration-trybe`
+1. Imports `IntegrationLibsModule` and `IntegrationTrybeModule`
+2. Re-exports both modules and all their public APIs
+3. Bundles the internal packages into `dist/` using `tsup` so consumers only install this single package
+
+```mermaid
+graph TB
+    subgraph "UIF Monorepo (Internal)"
+        libs["@dvss/dvss-integration-libs"]
+        trybe["@dvss/dvss-integration-trybe"]
+    end
+
+    subgraph "This Package"
+        offering["@dv4resi/dvss-backend-module-offering-im<br/><b>OfferingIntegrationManager</b>"]
+    end
+
+    subgraph "Consuming Microservices"
+        booking["dvss-backend-capability-offering-booking-ms"]
+        hooks["dvss-backend-hooks-ms"]
+        others["Other microservices"]
+    end
+
+    libs -->|bundled into| offering
+    trybe -->|bundled into| offering
+    offering -->|"npm install"| booking
+    offering -->|"npm install"| hooks
+    offering -->|"npm install"| others
+```
 
-## Build output
+---
 
-- Compiled artifacts are emitted to `dist/` via `tsup`
-- Internal UIF packages are bundled into `dist/` so consumers only install
-  `@dv4resi/dvss-backend-module-offering-im`
+## What Gets Bundled
 
-## Bundling behavior
+At build time, `tsup` bundles the following internal packages into `dist/`:
+
+| Internal Package               | What It Provides                                     |
+| ------------------------------ | ---------------------------------------------------- |
+| `@dvss/dvss-integration-libs`  | Base classes, DAOs, traffic router, common utilities |
+| `@dvss/dvss-integration-trybe` | Trybe-specific capability implementations            |
+
+The following are kept **external** (not bundled) and must be present in the consuming microservice:
+
+- `@nestjs/*` packages
+- `@dv4resi/dvss-backend-module-datastore`
+- `@dv4resi/dvss-backend-module-utility`
+- `rxjs`, `reflect-metadata`, `class-transformer`, `class-validator`
+- `drizzle-orm`
+
+---
+
+## How Consuming Microservices Use This
+
+### Installation
+
+```bash
+# Install in the consuming microservice
+npm install @dv4resi/dvss-backend-module-offering-im
+# or
+yarn add @dv4resi/dvss-backend-module-offering-im
+```
+
+### Importing `OfferingIntegrationManager`
+
+The primary export is `OfferingIntegrationManager` -- a NestJS module that wraps and re-exports both `IntegrationTrybeModule` and `IntegrationLibsModule`. Consuming microservices only need this single import to get access to all integration services:
+
+```typescript
+import { OfferingIntegrationManager } from '@dv4resi/dvss-backend-module-offering-im';
+
+@Module({
+    imports: [
+        OfferingIntegrationManager, // brings in all Trybe + Libs services
+        // ... other modules
+    ],
+})
+export class SomeFeatureModule {}
+```
+
+Once imported, all exported services from both internal packages are available for injection:
+
+```typescript
+import {
+    TrybeAuthService,
+    TrybeCustomerManagement,
+    TrybeCreditBooking,
+    TrybeWellnessManagement,
+    TrybeIntegrationConfigurationService,
+    TrybeIntegrationResourceManagementService,
+    // ... any other exported service or model
+} from '@dv4resi/dvss-backend-module-offering-im';
+```
+
+### What `OfferingIntegrationManager` provides under the hood
+
+```typescript
+// apps/dvss-backend-module-offering-im/src/app.module.ts
+@Module({
+    imports: [IntegrationTrybeModule, IntegrationLibsModule],
+    exports: [IntegrationTrybeModule, IntegrationLibsModule],
+})
+export class OfferingIntegrationManager {}
+```
+
+```typescript
+// apps/dvss-backend-module-offering-im/src/index.ts
+export { AppModule as OfferingIntegrationManager } from './app.module';
+export { IntegrationTrybeModule } from '@dvss/dvss-integration-trybe';
+export { IntegrationLibsModule } from '@dvss/dvss-integration-libs';
+export * from '@dvss/dvss-integration-libs'; // all libs services, models, utils
+export * from '@dvss/dvss-integration-trybe'; // all trybe services, models, utils
+```
+
+### Real-world example
+
+Here is how `dvss-backend-capability-offering-configuration-ms` uses it:
+
+```typescript
+import { OfferingIntegrationManager } from '@dv4resi/dvss-backend-module-offering-im';
+
+@Module({
+    imports: [
+        LoggerModule,
+        DatastoreModule,
+        GraphQLIntercommunicationModule,
+        HttpModule,
+        PubSubModule,
+        OfferingIntegrationManager, // <-- single import for all integration services
+        forwardRef(() => IntegrationsModule),
+        forwardRef(() => OfferingIntegrationManagementModule),
+    ],
+    // ...
+})
+export class OfferingManagementModule {}
+```
 
-- Bundled: `@dvss/dvss-integration-libs`, `@dvss/dvss-integration-trybe`
-- Externalized: NestJS, RxJS, and other runtime dependencies listed in
-  `package.json`
-- Build-time requirement: `@swc/core` (installed at the monorepo root)
+```mermaid
+graph TB
+    subgraph "OfferingIntegrationManager (single import)"
+        direction TB
+        TrybeModule["IntegrationTrybeModule"]
+        LibsModule["IntegrationLibsModule"]
+    end
+
+    subgraph "Trybe Services (available for injection)"
+        TrybeAuth["TrybeAuthService"]
+        TrybeCust["TrybeCustomerManagement"]
+        TrybeCredit["TrybeCreditBooking"]
+        TrybeWellness["TrybeWellnessManagement"]
+        TrybeConfig["TrybeIntegrationConfigurationService"]
+        TrybeResource["TrybeIntegrationResourceManagementService"]
+    end
+
+    subgraph "Libs Services (available for injection)"
+        Gateway["TrafficGatewayService"]
+        Logger["IntegrationRequestLoggerService"]
+        ConfigDao["IntegrationConfigurationDao"]
+        ResourceDao["IntegrationResourceManagementDao"]
+    end
+
+    TrybeModule --> TrybeAuth
+    TrybeModule --> TrybeCust
+    TrybeModule --> TrybeCredit
+    TrybeModule --> TrybeWellness
+    TrybeModule --> TrybeConfig
+    TrybeModule --> TrybeResource
+    LibsModule --> Gateway
+    LibsModule --> Logger
+    LibsModule --> ConfigDao
+    LibsModule --> ResourceDao
+```
+
+---
+
+## Bundling Configuration
+
+The `tsup.config.ts` handles:
+
+- **Internal package resolution** - Resolves `@dvss/dvss-integration-libs` and `@dvss/dvss-integration-trybe` to their source files and bundles them
+- **Path resolution** - Fixes `__dirname` references for `.env` file resolution so it works in both monorepo and installed contexts
+- **Output format** - CommonJS (for NestJS compatibility)
+- **Type declarations** - Generates `.d.ts` files for TypeScript consumers
+- **Source maps** - Enabled for debugging
+- **SWC** - Used for decorator metadata support
+- **Tree-shaking** - Enabled to remove unused code
+
+---
 
 ## Scripts
 
 ```bash
 # Start in dev mode with watch on dependent packages
-# This picks up changes from libs and trybe
+# Watches: ./src, ../../packages/dvss-integration-libs/src, ../../packages/dvss-integration-trybe/src
 yarn run start:dev
 
-# Build the package
+# Build the package (tsup)
 yarn run build
 
 # Watch builds (tsup)
 yarn run build:dev
 
-# Build all local dependencies before building
+# Build all local dependencies first, then build this package
 yarn run build:with-deps
 
 # Tests
 yarn run test
+yarn run test:cov
+yarn run test:watch
 ```
 
-## Local usage
+---
+
+## Local Development
 
 From the monorepo root:
 
 ```bash
-yarn --cwd apps/dvss-backend-module-offering-im run build
+# Build this app with all its internal deps in order
+yarn --cwd apps/dvss-backend-module-offering-im run build:with-deps
+
+# Watch mode - auto-rebuilds when libs or trybe source files change
+yarn --cwd apps/dvss-backend-module-offering-im run start:dev
+```
+
+The `start:dev` script uses `nodemon` to watch source files across three locations:
+
+- `./src` (this app)
+- `../../packages/dvss-integration-libs/src`
+- `../../packages/dvss-integration-trybe/src`
+
+Any `.ts` file change in these directories triggers a `tsup` rebuild.
+
+---
+
+## Local Linking with yarn link
+
+To test local changes in a consuming microservice without publishing:
+
+```bash
+# 1. Build with deps
+yarn --cwd apps/dvss-backend-module-offering-im run build:with-deps
+
+# 2. Register the link (from the app directory)
+cd apps/dvss-backend-module-offering-im
+yarn link
+
+# 3. Use the link in the consuming microservice
+cd /path/to/consuming-microservice
+yarn link "@dv4resi/dvss-backend-module-offering-im"
+
+# 4. Unlink when done
+yarn unlink "@dv4resi/dvss-backend-module-offering-im"
+yarn install --force
 ```
 
-## Setup notes
-
-- Install all workspace dependencies from the repo root with `yarn install`
-- When working on dependent packages (e.g., trybe or libs), use `yarn run start:dev` here to pick up their changes
-
-## Release checklist
-
-- Bump `package.json` version in `apps/dvss-backend-module-offering-im` before release
-- Lint and tests run automatically on commit via Husky
-- Merge to `master` to trigger the initial lint/build pipeline
-- After the initial pipeline passes, trigger the publish pipeline from the latest
-  merged commit on `master`
-- Tag format must match the version script in `scripts/validate-tag-and-publish.sh`:
-  - Tag pattern: `dvss-backend-module-offering-im-vX.Y.Z`
-  - Version must be exactly the next patch/minor/major from npm (no skipping)
-  - The tag prefix must be allowlisted in `ALLOWED_APP_NAMES`
-- Example: if current published version is `0.0.3`, valid tags are
-  `dvss-backend-module-offering-im-v0.0.4`, `...-v0.1.0`, or `...-v1.0.0`
-  - Also the package.json version should be the next valid version.
+> **Tip:** Run `start:dev` in the UIF monorepo while linked so changes to `libs` or `trybe` automatically rebuild this package, and the consuming microservice picks them up.
+
+---
+
+## Release Checklist
+
+1. Bump the `version` field in this app's `package.json`
+2. Lint and tests run automatically on commit via Husky
+3. Merge to `master` to trigger the CI lint/build pipeline
+4. After the pipeline passes, trigger the publish pipeline from the latest merged commit on `master`
+5. Tag format: `dvss-backend-module-offering-im-vX.Y.Z`
+    - Version must be exactly the next patch/minor/major from npm (no skipping)
+    - The tag prefix must be in the `ALLOWED_APP_NAMES` allowlist in `scripts/validate-tag-and-publish.sh`
+
+**Example:** If current published version is `0.0.14`, valid next versions are:
+
+- `dvss-backend-module-offering-im-v0.0.15` (patch)
+- `dvss-backend-module-offering-im-v0.1.0` (minor)
+- `dvss-backend-module-offering-im-v1.0.0` (major)
+
+> The `package.json` version must match the tag version.
+
+---
+
+## Dependencies
+
+**Runtime** (must be present in consuming microservice):
+
+| Dependency                                                   | Purpose             |
+| ------------------------------------------------------------ | ------------------- |
+| `@nestjs/common`, `@nestjs/core`, `@nestjs/platform-express` | NestJS framework    |
+| `rxjs`                                                       | Reactive extensions |
+| `reflect-metadata`                                           | Decorator metadata  |
+
+**Dev / Bundled** (bundled into `dist/`, not required by consumers):
+
+| Dependency                     | Purpose                                      |
+| ------------------------------ | -------------------------------------------- |
+| `@dvss/dvss-integration-libs`  | Internal: base classes, DAOs, traffic router |
+| `@dvss/dvss-integration-trybe` | Internal: Trybe capability implementations   |