M&M Travels: Architecture and API Change Log (So Far)

This document summarizes what has been implemented so far for the M&M bundle-pricing architecture, what changed in existing APIs, and what new APIs were introduced.

1) Architecture: Old vs New

Old Architecture

• Pricing was primarily tied to resource-level values (hotel/activity/flight/transfer pricing in legacy flow).
• Day-wise resource mapping had stronger influence on pricing logic.
• Hotels and transfers were often consumed in day-wise structures.

New Architecture (Implemented Direction)

• Pricing model is bundle-based and category-driven.
• Itinerary now supports a default hotel category used for pricing selection.
• Bundle pricing is modeled with two levels:
  • category-level row
  • dynamic capacity-range price rows
• Transfer pricing is capacity-range based (shared by capacity range, not by transfer name).
• Day mapping is still used for itinerary composition/logistics, while pricing reads from bundle pricing data.
• Publish-time validation is enforced before allowing itinerary publish.

Data Model Changes Introduced

• New enum: src/shared/enums/hotel-category.enum.ts
• New entities:
  • src/shared/entity/itinerary-bundle-pricing.entity.ts
  • src/shared/entity/itinerary-bundle-capacity-price.entity.ts
• Updated itinerary entity:
  • src/shared/entity/itinerary.entity.ts
  • Category source aligned to tripType
  • Added relation bundlePricing
• Updated hotel-itinerary mapping:
  • src/shared/entity/hotel-itinerary-mapping.entity.ts
  • Added mapping scope fields category and locationId

2) Existing API Changes

Itinerary Price Details APIs (Enhanced)

Updated controller: src/modules/itinerary/itinerary.controller.ts

• GET /v1/itinerary/:id/price-details
• GET /v1/itinerary/:id/customer-price-details
• PUT /v1/itinerary/:id/pricing-table (admin)
• PUT /v1/itinerary/:id/customer-pricing-selection (customer)

Now supports optional query params:

• selectedCategory
• selectedVehicleName
• selectedCapacityMin
• selectedCapacityMax
• includeDinnerSupplement
• channel

Purpose split:

• Admin PUT updates pricing master table scenario-wise.
• Customer PUT stores selection and recalculates totals.

Persistence split:

• Admin PUT updates bundle/activity pricing configuration for itinerary.
• Customer PUT stores computed snapshot in booking.priceDetails (latest booking for booking user + itinerary).

Hotel-to-Itinerary Mapping API (Payload Enhanced)

Updated DTO/controller/service:

• src/modules/hotel/dto/map-hotel-itinerary.dto.ts
• src/modules/hotel/hotel.controller.ts
• src/modules/hotel/hotel.service.ts

Existing endpoint:

• POST /v1/hotel/map-itinerary

New optional payload fields added:

• category
• locationId

Purpose: support primary scoping and category-aware hotel mapping for itinerary bundle architecture.

Booking Create API (Payload Enhanced)

Updated DTO/service:

• src/modules/bookings/dto/create-booking.dto.ts
• src/modules/bookings/bookings.service.ts

Existing endpoint: booking create flow now accepts bundle selectors:

• selectedCategory
• selectedCapacityMin
• selectedCapacityMax
• includeDinnerSupplement
• childrenWithBed
• childrenWithoutBed

Purpose: booking calculation can be performed from bundle matrix + selected capacity bucket.

Day-wise Itinerary Details Response Shape (Changed)

Updated service: src/modules/days/days.service.ts

Existing endpoint behavior changed to:

• data.itineraryDetails.days
• data.itineraryDetails.hotels
• data.itineraryDetails.transfers

instead of embedding hotels/transfers inside each day.

3) New APIs Introduced

All added in src/modules/itinerary/itinerary.controller.ts.

A) Set Itinerary Default Category

• PUT /v1/itinerary/:id/default-category
• Body DTO: SetDefaultCategoryDto
• Files:
  • src/modules/itinerary/dto/bundle-pricing.dto.ts
  • src/modules/itinerary/itinerary.service.ts
  • src/modules/itinerary/itinerary.repository.ts

B) Upsert Bundle Pricing Row

• PUT /v1/itinerary/:id/bundle-pricing
• Body DTO: UpsertBundlePricingDto
• Includes category row + dynamic capacity price rows.

C) Get Bundle Pricing

• GET /v1/itinerary/:id/bundle-pricing
• Returns itinerary default category and configured bundle rows.

D) Full Import API (Single Call)

• POST /v1/itinerary/import-itinerary-full
• Body DTO: ImportItineraryFullDto
• New DTO file: src/modules/itinerary/dto/import-itinerary-full.dto.ts

This API is designed for your "import all at once" requirement and supports:

• itinerary core details
• transfer inventory ID list (transferIds)
• hotel inventory ID list (hotelIds)
• hotel day-wise mapping list (hotelDayMappings)
• day-wise activities (activities with dayOrder, mandatory startTime, optional duration)
• bundle pricing list

4) Import Behavior Implemented (Full Import API)

Implemented in src/modules/itinerary/itinerary.service.ts:

• Transfer mapping:

  • validates transfer inventory IDs (transferIds)
  • maps existing transfer records to itinerary

• Hotel mapping:

  • validates hotel inventory IDs (hotelIds)
  • maps existing hotel records to itinerary using hotel city/category scope (combination of location + category)
  • maps hotel to days explicitly via hotelDayMappings (hotelId + dayOrder)
  • validates day location matches hotel location
  • backward compatibility: if hotelDayMappings not provided, maps hotel to all itinerary days with matching location

• Activity mapping:

  • creates activity records first
  • stores startTime (required) and duration (optional) in activity_other_details
  • maps created activities day-wise via day_resource_mapping using dayOrder

• Transfer mapping:

  • validates transfer inventory IDs (transferIds)
  • maps existing transfer records to itinerary only (not day-wise)

• Bundle pricing rows can be created in same import request.

5) Publish Validation (New Architecture)

Implemented in publish toggle flow (src/modules/itinerary/itinerary.service.ts + src/modules/itinerary/itinerary.repository.ts).

Validation now follows scenario-specific rules:

• hotel + transfer (+activities):
  • category/default category required
  • hotel pricing required for selected/default category
  • primary transfer required
  • transfer pricing required
• hotel-only:
  • category/default category required
  • hotel pricing required for selected/default category
• transfer-only:
  • primary transfer required
  • transfer pricing required
• activities-only:
  • adultPrice required

Also aligned:

• itinerary tripType, hotel category, and bundle pricing category now use the same category enum semantics.
• itinerary tripType is treated as canonical category source.
• legacy BASIC behavior is treated as STANDARD for compatibility handling.

6) Supporting Internal Behavior Updates

• Transfer mapping defaults:

  • first mapped transfer for itinerary auto-sets isPrimary=true
  • file: src/modules/transfer/transfer.repository.ts

• Traveler/pricing interfaces extended for bundle selectors:

  • src/shared/interfaces/traveler-counts.interface.ts
  • src/modules/itinerary/interface/traveler-details.interface.ts

7) Notes for Consumers

• Frontend consumers should move to category/capacity-driven pricing selection.
• Existing clients using old payloads can continue, but new fields should be adopted for bundle-pricing accuracy.
• Day-wise itinerary consumers must read hotels/transfers from itineraryDetails.hotels and itineraryDetails.transfers.

8) Current Status

• Core architecture scaffolding and API contracts are in place.
• Build is passing after these changes.
• This document reflects implementation state so far (not a final migration sign-off doc).