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 — admin (jwt + TRIP permission)
• GET /v1/itinerary/:id/customer-price-details — customer (booking-jwt); alias GET /v1/itinerary/:id/price-details-booking
• PUT /v1/itinerary/:id/pricing-table — admin pricing master update
• POST /v1/bookings with required pricingSelection — customer booking create

Now supports optional query params on GET price-details:

• adults, children / childrenWithoutBed (alias), extraMattressCount / childrenWithBed (alias)
• selectedCategory
• selectedTransferId
• selectedVehicleName
• selectedCapacityMin, selectedCapacityMax
• includeDinnerSupplement
• channel (b2b or b2c; defaults to b2b if omitted)

Purpose split:

• Admin GET /price-details (channel=b2b): category locked to tripType; markup fields shown separately in summary.
• Customer GET /customer-price-details (auto channel=b2c): markup folded into price; selectedCategory honored.
• Admin PUT /pricing-table: updates bundle/activity pricing configuration for itinerary.
• Customer POST /bookings + pricingSelection: validates channel must be b2c, snapshots computed price into booking.priceDetails.

availableCategories in price-details response:

• For hotel_transfer and hotel_only: always returns all five HotelCategoryEnum values [1,2,3,4,5].
• For transfer_only and activities_only: returns only categories present in bundle pricing + tripType category.

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 requires pricingSelection (b2c), including 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) Upsert Pricing Table (all scenarios in one endpoint)

• PUT /v1/itinerary/:id/pricing-table
• Body DTO: PricingTableUpsertDto (src/modules/itinerary/dto/pricing-table.dto.ts)
• Replaces the former separate bundle-pricing and default-category endpoints (those were never shipped to the live controller).
• Supports four scenarios via scenario field: hotel_transfer, hotel_only, transfer_only, activities_only.

Note: The previously documented PUT /v1/itinerary/:id/default-category, PUT /v1/itinerary/:id/bundle-pricing, and GET /v1/itinerary/:id/bundle-pricing endpoints were never added to the controller and do not exist in the live codebase. Do not call them.

B) Full Import API (Single Call)

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

This API is designed for the "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 (bundlePricing)

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.
• PUT /v1/itinerary/:id/default-category, PUT /v1/itinerary/:id/bundle-pricing, and GET /v1/itinerary/:id/bundle-pricing were listed in earlier drafts of this doc but were never added to the controller. Use PUT /v1/itinerary/:id/pricing-table instead.
• Booking create (POST /v1/bookings) enforces pricingSelection.channel = "b2c" — sending "b2b" returns ERR_BOOKING_PRICING_CHANNEL_MUST_BE_B2C.
• GST and Markup are both sourced from the Markup entity (differentiated by category field: 'markup' vs 'gst'). Neither is a hardcoded constant. When no markup/GST is configured, the price is returned at base cost and gstPercent/gstAmount are null in the summary.

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).