@dv4resi/dvss-backend-module-offering-im 0.0.13 → 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   |

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { CONFIGURED_FOR_TYPE_ENUM, MEDIA_PROVIDER_ENUM, DAY_OF_WEEK, OFFERING_RESOURCE_TYPE, STATUS } from '@dv4resi/dvss-backend-module-datastore/dist/datastore/models';
-import { LoggerService, GraphQLContext, AddAPIResponse } from '@dv4resi/dvss-backend-module-utility';
+import { LoggerService, GraphQLContext, IMedia, AddAPIResponse } from '@dv4resi/dvss-backend-module-utility';
 import { HttpService } from '@nestjs/axios';
 import { CAPABILITY_PROVIDER_INTEGRATION_ENUM, CAPABILITY_CATEGORY_ENUM, ICapability } from '@dv4resi/dvss-backend-module-datastore/dist/datastore/models/capability.model';
 import { schema, CommonValidationDatabaseService as CommonValidationDatabaseService$1 } from '@dv4resi/dvss-backend-module-datastore';
@@ -528,8 +528,9 @@ interface ICreateOrderRequest {
 }
 interface ICreateOrderResponse {
     externalBookingId: string;
-    items: (IBookableItem & {
+    items: (Pick<IBookableItem, 'externalId' | 'type' | 'name'> & {
         totalPrice?: number;
+        primaryAsset?: IMedia;
     })[];
 }
 interface IAddItemToOrderItemConfig {
@@ -1166,11 +1167,6 @@ interface ITrybeAddOrderItemResponse {
         net_total?: number;
     };
 }
-interface ITrybeSubmitOrderResponse {
-    data: {
-        id: string;
-    };
-}
 interface ITrybeCancelOrderResponse {
     data: {
         id: string;
@@ -1203,6 +1199,15 @@ interface ITrybeZone {
 interface ITrybeCreateOrderResponse extends ICreateOrderResponse {
     meta: {
         orderReference: string;
+        room?: {
+            id: string;
+            name: string;
+            capacity: number;
+        };
+        total: number;
+        subTotal: number;
+        totalTax: number;
+        discount: number;
     };
 }
 interface ITrybeGetOrderResponse extends IGetOrderResponse {
@@ -1218,6 +1223,149 @@ interface ITrybeUpdateOrderItemResponse {
         id: string;
     };
 }
+interface ITrybeSubmitOrderResponse {
+    data?: {
+        id: string;
+        order_ref: string;
+        guests?: {
+            id: string;
+            name: string;
+            first_name: string;
+            last_name: string;
+            email: string | null;
+            intake_form_complete: boolean;
+            checked_in_at: string | null;
+            checked_out_at: string | null;
+            is_lead_booker: boolean;
+            customer_id: string;
+        }[];
+        labels: [];
+        sales_channel: null;
+        items_status: 'pending_confirmation';
+        booking_items?: {
+            id: string;
+            status: string;
+            item_type: string;
+            date: string;
+            type_id: string;
+            type_name: string;
+            type_product_code: string | null;
+            guests: {
+                id: string;
+                name: string;
+                first_name: string;
+                last_name: string;
+                email: string | null;
+                intake_form_complete: boolean;
+                checked_in_at: string | null;
+                checked_out_at: string | null;
+                is_lead_booker: boolean;
+                customer_id: string;
+            }[];
+            price: number;
+            discount_amount: number;
+            discounts: [];
+            order_discount_amount: number;
+            booking_summary?: {
+                id: string;
+                status: string;
+                offering: {
+                    id: string;
+                    type: string;
+                    name: string;
+                    product_code: string | null;
+                };
+                start_time: string;
+                end_time: string;
+                duration: number;
+                practitioner_ids: string[];
+                practitioners: {
+                    id: string;
+                    name: string;
+                }[];
+                room_id: string;
+                room?: {
+                    id: string;
+                    name: string;
+                    capacity: number;
+                };
+                equipment_ids: string[];
+                equipment: {
+                    id: string;
+                    name: string;
+                }[];
+                practitioner_was_requested: false;
+                room_was_requested: false;
+            };
+            total_cost: number;
+            net_total: number;
+            inclusive_tax_amount: number;
+            exclusive_tax_amount: number;
+            booking_reserved_until: string;
+            guest: {
+                id: string;
+                name: string;
+                first_name: string;
+                last_name: string;
+                email: string | null;
+                intake_form_complete: boolean;
+                checked_in_at: string | null;
+                checked_out_at: string | null;
+                is_lead_booker: boolean;
+                customer_id: string;
+            };
+            is_modifiable: boolean;
+        }[];
+        purchase_items: [];
+        package_items: [];
+        booking_items_start_date: string;
+        booking_items_end_date: string;
+        booking_items_span_multiple_days: false;
+        currency: string;
+        totals?: {
+            subtotal?: number;
+            inclusive_tax?: number;
+            exclusive_tax?: number;
+            order_discount?: number;
+            total?: number;
+        };
+        total_cost: number;
+        discount_total: number;
+        total_tax: number;
+        net_total: number;
+        tip_amount: number;
+        tips: [];
+        service_charge: {
+            amount: number;
+            percentage: number;
+            item_amounts: {
+                item_id: string;
+                amount: number;
+                percentage: number;
+            }[];
+        };
+        submit_payment_amount: number;
+        submit_auth_amount: number;
+        outstanding_payment_amount: number;
+        payment_totals: {
+            paid: number;
+            pending: number;
+            chargeable: number;
+            provided: number;
+            missing: number;
+            unpaid: number;
+        };
+        total_paid_or_authed: number;
+        taxes: [];
+        payments: [];
+        discounts: [];
+        applied_promo_code_id: null;
+        applied_promo_code_discount_total: number;
+        is_promo_code_discount_applied: boolean;
+        coupon_codes: [];
+        voucher_codes: [];
+    };
+}
 
 declare enum TRYBE_SUPPORTED_JOURNEYS_ENUM {
     APPOINTMENT = "APPOINTMENT",
@@ -1301,25 +1449,47 @@ declare class TrybeWellnessManagement implements BaseWellnessManagement {
     createWellnessAppointmentSessionOrder(): Promise<void>;
     addWellnessAppointmentSessionOrderItems(): Promise<void>;
     confirmWellnessAppointmentSessionOrder(): Promise<void>;
+    getOffering(request: {
+        offeringId: string;
+        offeringType: TRYBE_OFFERING_TYPE_ENUM;
+    }, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<{
+        data: ITrybeSession | ITrybeCourse | ITrybeAppointment;
+    }>;
     createOrder(request: ICreateOrderRequest, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<ITrybeCreateOrderResponse>;
     addCustomerToOrder(orderId: string, customerId: string, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<void>;
     getOrder(orderId: string, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<ITrybeGetOrderResponse>;
     private mapOfferingTypeToTrybeApi;
     addItemToOrder(request: IAddItemToOrderRequest, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<IAddItemToOrderResponse>;
     addCustomerCreditsToOrder(orderId: string, customerCreditId: string, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<void>;
-    submitOrder(orderId: string, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<void>;
+    submitOrder(orderId: string, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<ITrybeSubmitOrderResponse>;
     cancelOrder(orderId: string, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<void>;
     updateOrder(request: IUpdateOrderRequest, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<IUpdateOrderResponse>;
     updateOrderItem(orderId: string, itemId: string, request: IUpdateOrderRequest, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<ITrybeUpdateOrderItemResponse>;
     addPaymentToOrder(request: IAddPaymentToOrderRequest, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<void>;
     fetchAppointments(request: IGetAppointmentsRequest, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<ISystemResponse<IBookableItem>>;
+    fetchAppointment(request: {
+        appointmentId: string;
+    }, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<{
+        data: ITrybeAppointment;
+    }>;
     fetchSessions(request: IGetSessionsRequest, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<ISystemResponse<IBookableItem>>;
+    fetchSession(request: {
+        sessionId: string;
+    }, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<{
+        data: ITrybeSession;
+    }>;
     fetchCourses(request: IGetCoursesRequest, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<ISystemResponse<IBookableItem>>;
+    fetchCourse(request: {
+        courseId: string;
+    }, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<{
+        data: ITrybeCourse;
+    }>;
     fetchPractitioners(request: IGetPractitionersRequest, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<ISystemResponse<IOfferingResource>>;
     fetchCategories(request: IGetCategoriesRequest, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<ISystemResponse<IBookableItemCategory>>;
     fetchBookableItemsFromCredit(request: IGetBookableItemsFromCreditRequest, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<ISystemResponse<IBookableItem>>;
     fetchSessionAvailabilityForOffering(request: IFetchOfferingAvailabilityRequest, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<IGetAvailableDatesAndTimeSlotsResponse>;
     fetchAppointmentAvailabilityForOffering(request: IFetchOfferingAvailabilityRequest, integration: ICapabilityIntegration, loggedInUserId: bigint): Promise<IGetAvailableDatesAndTimeSlotsResponse>;
+    mapTrybeOfferingTypeToBookableItemType(offeringType: string): BOOKABLE_ITEM_TYPE_ENUM;
 }
 
 declare function formatDateForTrybe(date: Date, isStartOfDay: boolean): string;