@revolugo/common 7.1.1 → 7.2.0-alpha.0

package/package.json

@@ -1,19 +1,13 @@
 {
   "name": "@revolugo/common",
-  "version": "7.1.1",
+  "version": "7.2.0-alpha.0",
   "private": false,
   "description": "Revolugo common",
   "author": "Revolugo",
-  "type": "module",
-  "engines": {
-    "node": ">=20.18.1 <25"
-  },
-  "volta": {
-    "extends": "../../package.json"
-  },
   "files": [
     "src"
   ],
+  "type": "module",
   "exports": {
     "./amenities": "./src/amenities/index.ts",
     "./cancellation-policies": "./src/cancellation-policies.ts",
@@ -38,6 +32,12 @@
     "uuid": "13.0.0",
     "zod": "4.3.6"
   },
+  "engines": {
+    "node": ">=20.18.1 <25"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  },
   "scripts": {
     "test": "vitest"
   }

package/src/cancellation-policies.ts

@@ -39,9 +39,9 @@ function initReleaseDateUTC({
   releaseDate,
   timezone,
 }: {
+  checkInDate: string
   releaseDate?: string
   timezone: string
-  checkInDate: string
 }): string | undefined {
   if (!releaseDate) {
     return undefined

package/src/constants/hotel-room-offer.ts

@@ -1,8 +1,3 @@
-export enum HotelRoomOfferType {
-  HotelRoom = 'HOTEL_ROOM',
-  Package = 'PACKAGE',
-}
-
 export enum PackageType {
   BestMatch = 'BEST_MATCH',
   Cheapest = 'CHEAPEST',

package/src/constants/poller.ts

@@ -3,9 +3,17 @@ export enum PollerStatus {
   InProgress = 'IN_PROGRESS',
 }
 
+export type PollerStatusType = `${PollerStatus}`
+
 export enum PollerType {
   // eslint-disable-next-line @typescript-eslint/naming-convention
   HOTEL_ROOM_OFFERS = 'HOTEL_ROOM_OFFERS',
   // eslint-disable-next-line @typescript-eslint/naming-convention
   HOTEL_SEARCH_POLLING = 'HOTEL_SEARCH_POLLING',
 }
+
+export enum Status {
+  Complete = 'COMPLETE',
+  Error = 'ERROR',
+  InProgress = 'IN_PROGRESS',
+}

package/src/countries/index.ts

@@ -1,2 +1,3 @@
 export * from './countries.ts'
 export * from './europe.ts'
+export type * from './types.ts'

package/src/currencies/utils.ts

@@ -1,8 +1,9 @@
 import { CURRENCIES } from './currencies.ts'
 
 import type { CurrencyCode } from './constants.ts'
+import type { CurrencyType } from '../types/index.ts'
 
-export function getCurrencySymbol(currency: CurrencyCode): string {
+export function getCurrencySymbol(currency: CurrencyType): string {
   const symbol = CURRENCIES[currency]?.symbol
 
   if (!symbol) {
@@ -12,7 +13,7 @@ export function getCurrencySymbol(currency: CurrencyCode): string {
   return symbol
 }
 
-export function isZeroDecimal(currency: CurrencyCode): boolean {
+export function isZeroDecimal(currency: CurrencyType): boolean {
   return (CURRENCIES[currency] && CURRENCIES[currency].zeroDecimal) || false
 }
 
@@ -27,7 +28,7 @@ export function normalizeAmount({
   currency,
 }: {
   amount: number
-  currency: CurrencyCode
+  currency: CurrencyType
 }): number {
   if (isZeroDecimal(currency)) {
     return amount
@@ -41,7 +42,7 @@ export function denormalizeAmount({
   currency,
 }: {
   amount: number
-  currency: CurrencyCode
+  currency: CurrencyType
 }): number {
   if (isZeroDecimal(currency)) {
     return amount
@@ -81,7 +82,7 @@ export function formatAmount({
 
 export class MoneyCalculator {
   private amount: number
-  private currency: CurrencyCode
+  private currency: CurrencyType
   private isNormalized: boolean
 
   constructor({
@@ -90,7 +91,7 @@ export class MoneyCalculator {
     isNormalized = false,
   }: {
     amount: number
-    currency: CurrencyCode
+    currency: CurrencyType
     isNormalized?: boolean
   }) {
     this.amount = amount
@@ -108,7 +109,7 @@ export class MoneyCalculator {
     currency,
     exchangeRate,
   }: {
-    currency: CurrencyCode
+    currency: CurrencyType
     exchangeRate: number
   }): this {
     if (this.currency === currency || this.amount === 0) {

package/src/models/paginated-queries.ts

@@ -1,10 +1,10 @@
 import type { IPaginatedQueriesConfig } from '../types/index.ts'
 
 /* @__PURE__ */
-export const PAGINATED_QUERY_DEFAULT_CONFIG: IPaginatedQueriesConfig = {
+export const PAGINATED_QUERY_DEFAULT_CONFIG = {
   defaultScope: {
     limit: 20,
     order: 'DESC',
     orderBy: 'createdAt',
   },
-}
+} satisfies Required<IPaginatedQueriesConfig>

package/src/schemas/booking-policy.ts

@@ -0,0 +1,51 @@
+/* eslint-disable camelcase */
+
+import { z } from 'zod'
+
+import { CANCELLATION_POLICY_SCHEMA } from './cancellation-policies.ts'
+import { CURRENCY_SCHEMA } from './currency.ts'
+import {
+  ADULT_COUNT_SCHEMA,
+  CHECK_IN_DATE_SCHEMA,
+  CHECK_OUT_DATE_SCHEMA,
+  CHILDREN_SCHEMA,
+  IS_PRICE_INCREASED,
+} from './global.ts'
+import { HOTEL_ROOM_OFFER_SCHEMA } from './hotel-room-offer.ts'
+
+export const BOOKING_POLICY_SCHEMA = z
+  .object({
+    adult_count: ADULT_COUNT_SCHEMA,
+    cancellation_policies: z.array(CANCELLATION_POLICY_SCHEMA).openapi({
+      description:
+        'The list of cancellation policy date range with their corresponding penalty percentage.',
+    }),
+    check_in_date: CHECK_IN_DATE_SCHEMA,
+    check_out_date: CHECK_OUT_DATE_SCHEMA,
+    children: CHILDREN_SCHEMA.nullish(),
+    currency: CURRENCY_SCHEMA,
+    expires_at: z.coerce.date().nullable().openapi({
+      description:
+        'Expiration date for this **Booking Policy**.\n\nThe returned  **Booking Policy** (price and cancellation policies) is valid bookable policy up to this **expires_at** date, while it may be valid for a longer period in the case of some suppliers, this API call is equivalent to an availability check and it is important not to let long periods between retrieval of this policy and the booking confirmation call itself as this will often reduce the likelihood of a **Hotel Room Offer** being successfully booked.',
+    }),
+    has_rooming_lists: z.boolean().openapi({
+      description:
+        'Indicates whether the **Booking Policy** supports rooming lists, allowing individual guest details to be provided per room.',
+    }),
+    hotel_id: z.string().openapi({
+      description: 'Hotel id',
+    }),
+    hotel_room_offer: HOTEL_ROOM_OFFER_SCHEMA.openapi({
+      description:
+        'The **Hotel Room Offer** associated with this **Booking Policy**.',
+    }),
+    id: z.string().openapi({
+      description: '**Booking Policy** id',
+    }),
+    is_price_increased: IS_PRICE_INCREASED,
+  })
+  .openapi('bookingPoliciesApi', {
+    description:
+      'A **Booking Policy** represents a validated and bookable snapshot of a **Hotel Room Offer**, including its price, cancellation policies, and expiration date.',
+  })
+/* eslint-enable camelcase */

package/src/schemas/breakfast.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod'
+
+import { BreakfastOption } from '../constants/index.ts'
+import { HotelRoomOfferTypeEnum } from '../types/index.ts'
+
+export const BREAKFAST_OPTION_DESCRIPTION = `This parameter describes the breakfast option for the given **Hotel Room Offer**:
+- **breakfast_option = "${BreakfastOption.Included}"**:
+  1. When **HotelRoomOffer.type = "${HotelRoomOfferTypeEnum.Package}"**:
+  the returned **Hotel Room Offer** includes breakfast for the requested **guest count (adult_count + children over 3)**, you cannot choose otherwise, and the returned **price** already includes it,
+  2. When **HotelRoomOffer.type = "${HotelRoomOfferTypeEnum.HotelRoom}"**:
+  the returned **Hotel Room Offer** includes breakfast for the **Hotel Room Offer** maximum occupancy, you cannot choose otherwise, and the returned **price** already includes it,
+-**breakfast_option = "${BreakfastOption.Optional}"**: the returned **Hotel Room Offer** does not include by default the breakfast and so does the returned **price**, but you'll be able to let your customers choose to add it to their booking. In that case, a **breakfast_price_per_guest_per_night** expressed in the requested **currency** will be available in the returned data, and you'll be to perform one of the two following actions: \n - Call **[Create Hotel Room Offer endpoint](/v1/documentation#operation/postV1Hotel_room_offers)** and get a fresh **Hotel Room Offer** with updated price \n - Compute and display the total price of the **Hotel Room Offer** related to the guest_count and night count requested including extra breafasts.,
+- **breakfast_option = "${BreakfastOption.NotIncluded}"**: the returned **Hotel Room Offer** does not include breakfast and you cannot choose otherwise through API. Guest may still be able to add extra breakfast option(s) at the time of check-in directly at the hotel's reception.`
+
+export const BREAKFAST_OPTION_SCHEMA = z
+  .enum(BreakfastOption)
+  .openapi('BreakfastOption', { description: BREAKFAST_OPTION_DESCRIPTION })
+
+export type BreakfastOptionSchema = z.infer<typeof BREAKFAST_OPTION_SCHEMA>
+
+export const ADD_BREAKFAST_SCHEMA = z
+  .boolean()
+  .nullish()
+  .openapi('addBreakfast', {
+    description: `This parameter allows to add breakfast to the booking as long as every requested Hotel Room Offers **breakfast_option = ${BreakfastOption.Optional}** .\n\nThe final breakfast count that will be included in the Hotel Room Offer will be returned in the response and is calculated as follows: \n\n - If the returned Hotel Room Offer **total room count**  > **hotel_room_offer_request.adult_count** then **breakfast_count** will be equal to the **total room count** of the returned Hotel Room Offer, \n\n - Otherwise **breakfast_count** will be equal to the minimum value between related **hotel_room_offer_request.adult_count** and returned Hotel Room Offer **total occupancy**. \n\n <div style="background-color: #ffffef; padding: 20px; border: 1px solid lightgrey; border-radius: 5px;"><b style="color: red; margin-top: 10px;">🛑 DEPRECATED.</b>\n\n <b style="color: orange;">If you already use this field, don't worry as we still support it with the following behaviour:</b>\n- <span style="color: orange;">When **add_breakfast = true** then **breakfast_count = MIN(guest count, total offer occupancy)** where **guest count** is the total number of adult and children over 3.</span>\n- <span style="color: orange;">Otherwise **breakfast_count = 0**.</span></div>`,
+  })
+
+export const BREAKFAST_COUNT = z
+  .number()
+  .optional()
+  .openapi('breakfastCount', {
+    description: `This parameter describes the quantity of breakfast / night that should be included in the **Booking**. When **breakfast_option = ${BreakfastOption.Optional}**, valid **breakfast_count** lower bound is **room count** and upper bound is **guest count**, where **guest count** is the number of adult and children over 3.\n\n⚠️ The actual breakfast count that will be included in the **Booking** is the one that is returned in the response of this endpoint and might be different from this **breakfast_count** paramater in some cases. Please, make sure to check the actual breakfast count included in the **Hotel Room Offer** returned in the response of this endpoint.`,
+  })

package/src/schemas/cancellation-policies.ts

@@ -1,18 +1,23 @@
 /* eslint-disable camelcase */
 import { z } from 'zod'
 
-export const CANCELLATION_POLICY_SCHEMA = z.object({
-  date_from: z.string().openapi({
+export const CANCELLATION_POLICY_SCHEMA = z
+  .object({
+    date_from: z.string().openapi({
+      description:
+        'The start date and time of the cancellation policy, given in the hotel timezone.',
+    }),
+    date_to: z.string().openapi({
+      description:
+        'The end date and time of the cancellation policy, given in the hotel timezone.',
+    }),
+    penalty_percentage: z.number().min(0).max(100).openapi({
+      description:
+        'The penalty percentage that is due in case of cancellation during the **date_from** to **date_to** period range.',
+    }),
+  })
+  .openapi('CancellationPolicyApi', {
     description:
-      'The start date and time of the cancellation policy, given in the hotel timezone.',
-  }),
-  date_to: z.string().openapi({
-    description:
-      'The end date and time of the cancellation policy, given in the hotel timezone.',
-  }),
-  penalty_percentage: z.number().min(0).max(100).openapi({
-    description:
-      'The penalty percentage that is due in case of cancellation during the **date_from** to **date_to** period range.',
-  }),
-})
+      'Defines the cancellation penalty that applies within a specific date and time range, expressed as a percentage of the booking cost.',
+  })
 /* eslint-enable camelcase */

package/src/schemas/currency.ts

@@ -4,4 +4,6 @@ import { STRIPE_CURRENCY_CODES } from '../currencies/index.ts'
 
 export const CURRENCY_SCHEMA = z
   .enum(STRIPE_CURRENCY_CODES)
-  .openapi({ description: 'ISO 4217 currency code.' })
+  .openapi('CurrencyClient', { description: 'ISO 4217 currency code.' })
+
+export type CurrencySchema = z.infer<typeof CURRENCY_SCHEMA>

package/src/schemas/global.ts

@@ -0,0 +1,120 @@
+/* eslint-disable camelcase */
+import { z } from 'zod'
+
+import { CountryIso2Code, Locale, Status } from '../constants/index.ts'
+
+export const validStringDate = (): z.ZodString =>
+  z
+    .string()
+    .regex(/^(19|20)\d\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])$/u)
+
+export const ADULT_COUNT_SCHEMA = z
+  .number()
+  .int()
+  .min(1)
+  .max(200)
+  .openapi('adultCount', {
+    description:
+      'The total number of adults who will be staying in the property.',
+  })
+
+export const CHECK_IN_DATE_SCHEMA = validStringDate().openapi('checkInDate', {
+  description: 'Date of check-in formatted as YYYY-MM-DD.',
+})
+
+export const CHECK_OUT_DATE_SCHEMA = validStringDate().openapi('checkOutDate', {
+  description: 'Date of check-out formatted as YYYY-MM-DD.',
+})
+
+export const CHILDREN_SCHEMA = z
+  .string()
+  .regex(/^(([0-9]{1})|(1[0-7]){1})(,(([0-9]{1})|(1[0-7]){1}))*$|^$/u)
+  .openapi('children', {
+    description:
+      'A comma-separated list of child ages (0 up to 17). e.g.: "3,7" represents 2 children respectively 3 and 7 years old.',
+  })
+
+export const IMAGES_SCHEMA = z
+  .object({
+    count: z.number().openapi({ description: 'Number of images.' }).nullish(),
+    highres: z
+      .boolean()
+      .openapi({ description: 'Whether images exist in highres format.' })
+      .nullish(),
+
+    lowres: z
+      .boolean()
+      .openapi({ description: 'Whether images exist in lowres format.' })
+      .nullish(),
+    prefix: z
+      .string()
+      .openapi({ description: 'Base URL for the images.' })
+      .nullish(),
+    suffix: z
+      .string()
+      .openapi({
+        description:
+          'This parameter usually represents the extension of the image (e.g.: .jpg, .png)',
+      })
+      .nullish(),
+    thumb: z
+      .boolean()
+      .openapi({
+        description:
+          'Whether images exist in thumb format (for thumbnails preview).',
+      })
+      .nullish(),
+  })
+  .openapi({
+    description:
+      '🛑 DEPRECATED - Hotel images details.\n\nIn order to retrieve a specific image you need to construct the complete URL from the images parameters: **[images.prefix][highres|lowres|thumb]/[index]/[images.suffix]**. If **images.count = n**, then index is in [0...n-1] range.\n\ne.g.: https://s3.eu-west-3.amazonaws.com/revolugo/hotels/yhKY/images/highres/0.jpg',
+  })
+
+export const IS_PRICE_INCREASED = z.boolean().openapi({
+  description:
+    'Indicates whether the price of the **Hotel Room Offer** (without breakfast included) has increased compared to the price returned by [Retrieve Hotel Room Offers endpoint](/v1/documentation#operation/getV1Hotel_room_offers).\n\nIn some case, the returned price may increase for various reasons including: Currency rate change between the POST **Booking Policies** call and the GET **Hotel Room Offers** call, **Hotel Room Offer** price has increased since the GET **Hotel Room Offers** call.\n\nIf **is_price_increased** is **true**, it means that the actual/updated price of the **Hotel Room Offer** is greater than the price previously returned by [Retrieve Hotel Room Offers endpoint](/v1/documentation#operation/getV1Hotel_room_offers). If **is_price_increased** is **false**, the price of the **Hotel Room Offer** is equal to the price returned by [Retrieve Hotel Room Offers endpoint](/v1/documentation#operation/getV1Hotel_room_offers).\n\n⚠️ It is strongly advised to clearly inform your customer of any price increase that may occur.',
+})
+
+export const LANG_SCHEMA = z
+  .enum(Locale)
+  .openapi('Locale', {
+    description:
+      'Set the language for the returned content using a valid language code.',
+    enum: Object.values(Locale),
+  })
+  .default(Locale.en_US)
+
+export const META = z
+  .object({
+    status: z
+      .enum(Status)
+      .openapi('Status', { description: 'Status of the response.' }),
+  })
+  .openapi('Meta', { description: 'Meta data of the response' })
+
+export const ROOM_COUNT_SCHEMA = z
+  .number()
+  .min(1)
+  .max(200)
+  .openapi('RoomCount', {
+    description:
+      'The total number of rooms requested for the stay. Results may display offers matching a different room count than the requested one, however those results will always provide enough occupancy for the total guest count needed.\n\nConstraint: The **room_count** cannot be greater than the requested guest count (adult and children guests) and the minimum **room_count** cannot be less than the total guest count (adult and children guests) divided by 4, meaning that the maximum number of guest in a single room cannot be greeater than 4.',
+  })
+
+export const COUNTRY_ISO2_CODE_SCHEMA = z
+  .enum(CountryIso2Code)
+  .refine(check => Object.values(CountryIso2Code).includes(check), {
+    message: 'Invalid ISO Alpha-2 country code.',
+  })
+  .openapi('CountryIso2Code', {
+    description: 'ISO Alpha-2 country code.',
+  })
+
+export const SOURCE_MARKET_SCHEMA = COUNTRY_ISO2_CODE_SCHEMA.openapi(
+  'SourceMarket',
+  {
+    description:
+      'For sourcing availability within certain markets, a source market option may be used to get more accurate prices. You may use any valid ISO Alpha-2 country code, e.g. JP.',
+  },
+)
+/* eslint-enable camelcase */

package/src/schemas/hotel-offer.ts

@@ -7,7 +7,7 @@ import {
   CHECK_IN_DATE_SCHEMA,
   CHECK_OUT_DATE_SCHEMA,
   CHILDREN_SCHEMA,
-} from './hotel-offer-request.ts'
+} from './global.ts'
 import { HOTEL_ROOM_OFFER_SCHEMA } from './hotel-room-offer.ts'
 import { HOTEL_IMAGES, HOTEL_SCHEMA, VENUES_SCHEMA } from './hotel.ts'
 import { LIST_POLLING_META_SCHEMA } from './list-polling-meta.ts'
@@ -23,34 +23,46 @@ List of hotel images in various sizes featuring an indicator for the primary (he
   hotel_room_offers: z.array(HOTEL_ROOM_OFFER_SCHEMA),
   tags: TAGS_SCHEMA,
   venues: VENUES_SCHEMA,
-}).openapi('hotelOfferApi')
+}).openapi('hotelOfferApi', {
+  description:
+    'Hotel Offer combining hotel details with available Hotel Room Offers.',
+})
 
-export const HOTEL_OFFERS_SCHEMA = z.array(HOTEL_OFFER_SCHEMA)
+export const HOTEL_OFFERS_SCHEMA = z.array(HOTEL_OFFER_SCHEMA).openapi({
+  description: 'List of Hotel Offers.',
+})
 
-export const HOTEL_OFFERS_RESPONSE_SCHEMA = z.object({
-  data: z.object({
-    adult_count: ADULT_COUNT_SCHEMA,
-    check_in_date: CHECK_IN_DATE_SCHEMA,
-    check_out_date: CHECK_OUT_DATE_SCHEMA,
-    children: CHILDREN_SCHEMA.optional().nullish(),
-    currency: CURRENCY_SCHEMA,
-    hotel_offers: HOTEL_OFFERS_SCHEMA.openapi({
-      description: 'List of Hotel Offers',
-    }),
-    price_histogram: z
-      .array(z.number())
-      .openapi({
-        description:
-          '**Hotel Offers** price histogram dataset based on the price of the cheapest **Hotel Room Offer** included on each **Hotel Offer** returned. It represents the number of available **Hotel Offers** grouped by price sorted ascendingly. Each item of the list represents a price step based on returned **price_min**, **price_max** and requested **price_histogram_step_count**',
-      })
-      .nullish(),
-    price_max: z.number().nullish().openapi({
-      description: 'Maximum price of available returned **Hotel Offers**',
+export const HOTEL_OFFERS_RESPONSE_SCHEMA = z
+  .object({
+    data: z.object({
+      adult_count: ADULT_COUNT_SCHEMA,
+      check_in_date: CHECK_IN_DATE_SCHEMA,
+      check_out_date: CHECK_OUT_DATE_SCHEMA,
+      children: CHILDREN_SCHEMA.optional().nullish(),
+      currency: CURRENCY_SCHEMA,
+      hotel_offers: HOTEL_OFFERS_SCHEMA.openapi({
+        description: 'List of Hotel Offers',
+      }),
+      price_histogram: z
+        .array(z.number())
+        .openapi({
+          description:
+            '**Hotel Offers** price histogram dataset based on the price of the cheapest **Hotel Room Offer** included on each **Hotel Offer** returned. It represents the number of available **Hotel Offers** grouped by price sorted ascendingly. Each item of the list represents a price step based on returned **price_min**, **price_max** and requested **price_histogram_step_count**',
+        })
+        .nullish(),
+      price_max: z.number().nullish().openapi({
+        description: 'Maximum price of available returned **Hotel Offers**',
+      }),
+      price_min: z.number().nullish().openapi({
+        description: 'Minimum price of available returned **Hotel Offers**',
+      }),
     }),
-    price_min: z.number().nullish().openapi({
-      description: 'Minimum price of available returned **Hotel Offers**',
+    event: z.any().optional().openapi({
+      description:
+        'Event associated with the Hotel Offers response, when applicable.',
     }),
-  }),
-  event: z.any().optional(),
-  meta: LIST_POLLING_META_SCHEMA,
-})
+    meta: LIST_POLLING_META_SCHEMA,
+  })
+  .openapi({
+    description: 'Response envelope for the Hotel Offers polling endpoint.',
+  })

package/src/schemas/hotel-room-offer.ts

@@ -1,31 +1,25 @@
 /* eslint-disable camelcase */
 import { z } from 'zod'
 
-import {
-  BreakfastOption,
-  HotelRoomOfferType,
-  PackageType,
-  StayTaxesInfoEnum,
-} from '../constants/index.ts'
+import { PackageType, StayTaxesInfoEnum } from '../constants/index.ts'
+import { HotelRoomOfferTypeEnum } from '../types/elements/hotel-room-offer-type.ts'
 
+import { BREAKFAST_OPTION_SCHEMA } from './breakfast.ts'
 import { CANCELLATION_POLICY_SCHEMA } from './cancellation-policies.ts'
 import { CURRENCY_SCHEMA } from './currency.ts'
-import { SOURCE_MARKET_SCHEMA } from './hotel-offer-request.ts'
+import { SOURCE_MARKET_SCHEMA } from './global.ts'
 import { HOTEL_ROOMS_SCHEMA } from './hotel-room.ts'
+import { HOTEL_IMAGE } from './hotel.ts'
 import { LIST_POLLING_META_SCHEMA } from './list-polling-meta.ts'
 import { TAGS_SCHEMA } from './tag.ts'
 import { TAXES_SCHEMA } from './taxes.ts'
 
-export const BREAKFAST_OPTION_DESCRIPTION = `This parameter describes the breakfast option for the given **Hotel Room Offer**:
-- **breakfast_option = "${BreakfastOption.Included}"**:
-  1. When **HotelRoomOffer.type = "${HotelRoomOfferType.Package}"**:
-  the returned **Hotel Room Offer** includes breakfast for the requested **guest count (adult_count + children over 3)**, you cannot choose otherwise, and the returned **price** already includes it,
-  2. When **HotelRoomOffer.type = "${HotelRoomOfferType.HotelRoom}"**:
-  the returned **Hotel Room Offer** includes breakfast for the **Hotel Room Offer** maximum occupancy, you cannot choose otherwise, and the returned **price** already includes it,
--**breakfast_option = "${BreakfastOption.Optional}"**: the returned **Hotel Room Offer** does not include by default the breakfast and so does the returned **price**, but you'll be able to let your customers choose to add it to their booking. In that case, a **breakfast_price_per_guest_per_night** expressed in the requested **currency** will be available in the returned data, and you'll be to perform one of the two following actions: \n - Call **[Create Hotel Room Offer endpoint](/v1/documentation#operation/postV1Hotel_room_offers)** and get a fresh **Hotel Room Offer** with updated price \n - Compute and display the total price of the **Hotel Room Offer** related to the guest_count and night count requested including extra breafasts.,
-- **breakfast_option = "${BreakfastOption.NotIncluded}"**: the returned **Hotel Room Offer** does not include breakfast and you cannot choose otherwise through API. Guest may still be able to add extra breakfast option(s) at the time of check-in directly at the hotel's reception.`
+export const HOTEL_ROOM_OFFERS_IMAGES = z.array(z.array(HOTEL_IMAGE)).openapi({
+  description:
+    'List of hotel room offer images in various sizes featuring an indicator for the primary (hero) image',
+})
 
-export const PACKAGE_TYPES_DESCRIPTION = `An **Hotel Room Offer** of type **${HotelRoomOfferType.Package}** can be of **4 types**, described by **package_type** parameter: \n\n - **${PackageType.Cheapest}** : The cheapest combination of hotel rooms that can accommodate the requested guest count. Note that it may not match the requested room count (e.g., 4 guests and 2 rooms requested may return an hotel room package including only 1 room with an occupancy of 4). \n\n -**${PackageType.MatchingRoomCount}** : the cheapest hotel room package that can accommodate the given guest count and that matches exactly the room count given. \n\n -**${PackageType.BestMatch}** : The cheapest hotel room package that matches the given room and guest count with a balanced distribution of guests across the rooms (e.g.; 8 guests and 3 rooms requested may return an **Hotel Room Offer** package including 2 rooms with an occupancy of 3 on each one and 1 room with an occupancy of 2). \n\n -**${PackageType.Regular}** : any other available package.`
+export const PACKAGE_TYPES_DESCRIPTION = `An **Hotel Room Offer** of type **${HotelRoomOfferTypeEnum.Package}** can be of **4 types**, described by **package_type** parameter: \n\n - **${PackageType.Cheapest}** : The cheapest combination of hotel rooms that can accommodate the requested guest count. Note that it may not match the requested room count (e.g., 4 guests and 2 rooms requested may return an hotel room package including only 1 room with an occupancy of 4). \n\n -**${PackageType.MatchingRoomCount}** : the cheapest hotel room package that can accommodate the given guest count and that matches exactly the room count given. \n\n -**${PackageType.BestMatch}** : The cheapest hotel room package that matches the given room and guest count with a balanced distribution of guests across the rooms (e.g.; 8 guests and 3 rooms requested may return an **Hotel Room Offer** package including 2 rooms with an occupancy of 3 on each one and 1 room with an occupancy of 2). \n\n -**${PackageType.Regular}** : any other available package.`
 
 export const HOTEL_ROOM_OFFER_SCHEMA = z
   .object({
@@ -33,9 +27,7 @@ export const HOTEL_ROOM_OFFER_SCHEMA = z
       description:
         'Quantity of breakfast per night included in the given **Hotel Room Offer**',
     }),
-    breakfast_option: z.enum(BreakfastOption).openapi({
-      description: BREAKFAST_OPTION_DESCRIPTION,
-    }),
+    breakfast_option: BREAKFAST_OPTION_SCHEMA,
     breakfast_price_per_guest_per_night: z.number().nullish().openapi({
       description:
         'Price of breakfast per guest per night for the given **Hotel Room Offer**, expressed in the requested **currency**, when applicable.\n\n <div style="background-color: #ffffef; padding: 20px; border: 1px solid lightgrey; border-radius: 5px;"><b style="color: red; margin-top: 10px;">🛑 DEPRECATED.</b>\n\n <b style="color: orange;">Field renamed to "breakfast_unit_price"</div>',
@@ -54,8 +46,8 @@ export const HOTEL_ROOM_OFFER_SCHEMA = z
       .number()
       .nullish()
       .openapi({
-        description: `When **type = ${HotelRoomOfferType.HotelRoom}**: this parameters represents the available quantity for the given **Hotel Room Offer**.
-  When **type = ${HotelRoomOfferType.Package}**: count = 1 always.`,
+        description: `When **type = ${HotelRoomOfferTypeEnum.HotelRoom}**: this parameters represents the available quantity for the given **Hotel Room Offer**.
+  When **type = ${HotelRoomOfferTypeEnum.Package}**: count = 1 always.`,
       }),
     currency: CURRENCY_SCHEMA,
     hotel_id: z
@@ -64,7 +56,7 @@ export const HOTEL_ROOM_OFFER_SCHEMA = z
     hotel_rooms: HOTEL_ROOMS_SCHEMA.openapi({
       description: 'List of Hotel Rooms included in the Hotel Room Offer.',
     }),
-    id: z.string().openapi({ description: 'Hotel Room Offer id.' }).optional(),
+    id: z.string().optional().openapi({ description: 'Hotel Room Offer id.' }),
     package_type: z
       .enum(PackageType)
       .openapi({
@@ -81,13 +73,13 @@ export const HOTEL_ROOM_OFFER_SCHEMA = z
       .openapi({ description: 'Either INCLUDED, NOT_INCLUDED or UNKNOWN' }),
     tags: TAGS_SCHEMA,
     tax_included_price: z.number().openapi({
-      description: `Price of the given **Hotel Room Offer** including breakfast(s) when applicable, and including all taxes from returned **taxes** list parameter expressed in the requested **currency**.\n\nThis data is not returned for a **Hotel Room Offer** of type **${HotelRoomOfferType.HotelRoom}**, you'll need to compute and display the actual tax included price of the final **Hotel Room** package corresponding to the guest count and night count requested, or make a call to the **[Create Hotel Room Offer](/v1/documentation#operation/postV1Hotel_room_offers)** endpoint in order to get a valid and bookable **Hotel Room Offer** where **type = ${HotelRoomOfferType.Package}** based on a packaged list of **Hotel Room Offers** of type **${HotelRoomOfferType.HotelRoom}**.`,
+      description: `Price of the given **Hotel Room Offer** including breakfast(s) when applicable, and including all taxes from returned **taxes** list parameter expressed in the requested **currency**.\n\nThis data is not returned for a **Hotel Room Offer** of type **${HotelRoomOfferTypeEnum.HotelRoom}**, you'll need to compute and display the actual tax included price of the final **Hotel Room** package corresponding to the guest count and night count requested, or make a call to the **[Create Hotel Room Offer](/v1/documentation#operation/postV1Hotel_room_offers)** endpoint in order to get a valid and bookable **Hotel Room Offer** where **type = ${HotelRoomOfferTypeEnum.Package}** based on a packaged list of **Hotel Room Offers** of type **${HotelRoomOfferTypeEnum.HotelRoom}**.`,
     }),
     taxes: TAXES_SCHEMA,
     type: z
-      .enum(HotelRoomOfferType)
+      .enum(HotelRoomOfferTypeEnum)
       .openapi({
-        description: `Hotel Room Offer type.\n\n **Hotel Room Offers** with **type = "${HotelRoomOfferType.Package}"** are **Hotel Room Offers** that are already bookable and you'll be able to follow the next step of the **Booking Flow** calling **[Create Booking Policies endpoint](/v1/documentation#operation/postV1Booking_policies)**. \n\n Otherwise, you'll be able to create a new **Hotel Room Offer** with **type = "${HotelRoomOfferType.Package}"** from multiple **Hotel Room Offers** with **type = "${HotelRoomOfferType.HotelRoom}"**. See **[Create Hotel Room Offer endpoint](/v1/documentation#operation/postV1Hotel_room_offers)** for details.`,
+        description: `Hotel Room Offer type.\n\n **Hotel Room Offers** with **type = "${HotelRoomOfferTypeEnum.Package}"** are **Hotel Room Offers** that are already bookable and you'll be able to follow the next step of the **Booking Flow** calling **[Create Booking Policies endpoint](/v1/documentation#operation/postV1Booking_policies)**. \n\n Otherwise, you'll be able to create a new **Hotel Room Offer** with **type = "${HotelRoomOfferTypeEnum.Package}"** from multiple **Hotel Room Offers** with **type = "${HotelRoomOfferTypeEnum.HotelRoom}"**. See **[Create Hotel Room Offer endpoint](/v1/documentation#operation/postV1Hotel_room_offers)** for details.`,
       })
       .optional(),
   })
@@ -95,10 +87,19 @@ export const HOTEL_ROOM_OFFER_SCHEMA = z
     description: 'Description of the Hotel Room Offer.',
   })
 
-export const HOTEL_ROOM_OFFERS_SCHEMA = z.array(HOTEL_ROOM_OFFER_SCHEMA)
+export const HOTEL_ROOM_OFFERS_SCHEMA = z
+  .array(HOTEL_ROOM_OFFER_SCHEMA)
+  .openapi({
+    description: 'List of Hotel Room Offers.',
+  })
 
-export const HOTEL_ROOM_OFFERS_RESPONSE_SCHEMA = z.object({
-  data: HOTEL_ROOM_OFFERS_SCHEMA,
-  meta: LIST_POLLING_META_SCHEMA,
-})
+export const HOTEL_ROOM_OFFERS_RESPONSE_SCHEMA = z
+  .object({
+    data: HOTEL_ROOM_OFFERS_SCHEMA,
+    meta: LIST_POLLING_META_SCHEMA,
+  })
+  .openapi({
+    description:
+      'Response envelope for the Hotel Room Offers polling endpoint.',
+  })
 /* eslint-enable camelcase */