@revolugo/common 6.14.6 → 6.15.0-rc.0

package/package.json

@@ -1,14 +1,22 @@
 {
   "name": "@revolugo/common",
-  "version": "6.14.6",
+  "version": "6.15.0-rc.0",
   "private": false,
   "description": "Revolugo common",
   "author": "Revolugo",
   "type": "module",
+  "engines": {
+    "node": ">=20.18.1 <25"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  },
   "files": [
     "src"
   ],
   "exports": {
+    "./amenities": "./src/amenities/index.ts",
+    "./assets": "./src/assets/index.ts",
     "./cancellation-policies": "./src/cancellation-policies.ts",
     "./countries": "./src/countries/index.ts",
     "./constants": "./src/constants/index.ts",
@@ -17,21 +25,18 @@
     "./icons": "./src/icons/index.ts",
     "./map": "./src/map/index.ts",
     "./models": "./src/models/index.ts",
+    "./schemas": "./src/schemas/index.ts",
     "./types": "./src/types/index.ts",
     "./utils": "./src/utils/index.ts"
   },
   "dependencies": {
     "change-case": "5.4.4",
     "dayjs": "1.11.19",
-    "ky": "1.14.0",
+    "ky": "1.14.1",
     "slugify": "1.6.6",
-    "uuid": "13.0.0"
-  },
-  "engines": {
-    "node": ">=20.18.1 <25"
-  },
-  "volta": {
-    "extends": "../../package.json"
+    "type-fest": "5.3.0",
+    "uuid": "13.0.0",
+    "zod": "3.25.76"
   },
   "scripts": {
     "test": "vitest"

package/src/amenities/index.ts

@@ -0,0 +1,51 @@
+export const AMENITY_TO_ICONS = Object.freeze({
+  AirConditioning: 'wind',
+  AirportTransportation: 'planeTakeOff',
+  BusinessCenter: 'building',
+  CarRentDesk: 'car',
+  ChildrenAllowed: 'baby',
+  ClothingIron: 'shirt',
+  CoffeeTeaMaker: 'coffee',
+  Combination: 'buildings',
+  ContinentalBreakfast: 'egg',
+  DataPorts: 'deviceTablet',
+  DryCleaning: 'shirt',
+  ElectronicRoomKeys: 'key',
+  ExteriorRoomEntrance: 'doorOpen',
+  FamilyRooms: 'usersThree',
+  FitnessFacility: 'gym',
+  GameRoom: 'gameController',
+  GolfCourse: 'golf',
+  HairDryer: 'hairDryer',
+  HandicapAccessible: 'wheelchair',
+  InHouseBar: 'champagne',
+  InHouseDining: 'forkKnife',
+  InRoomMovies: 'filmReel',
+  IndoorPool: 'swimmingPool',
+  InteriorRoomEntrance: 'doorOpen',
+  Kitchen: 'forkKnife',
+  Map: 'mapPin',
+  MeetingRooms: 'chalkboard',
+  MiniBarInRoom: 'wine',
+  NonSmokingRooms: 'noSmoking',
+  OutdoorPool: 'swimmingPool',
+  ParkingGarage: 'parkingSign',
+  PetsAllowed: 'pawPrint',
+  RestrictedAccess: 'lock',
+  RoomService: 'bell',
+  Safe: 'vault',
+  Sauna: 'thermometerHot',
+  TennisCourt: 'tennisBall',
+  TvInRoom: 'monitor',
+  TwentyFourHourSecurity: 'shield',
+  ValetParking: 'car',
+  VideoCheckOut: 'filmReel',
+  VoiceMail: 'phone',
+  WakeUpService: 'clock',
+  Whirpool: 'swimmingPool',
+  Wifi: 'wifiHigh',
+})
+
+export const AMENITY_NAMES = Object.keys(AMENITY_TO_ICONS)
+
+export type HotelRoomAmenityNames = keyof typeof AMENITY_TO_ICONS

package/src/assets/index.ts

@@ -0,0 +1,3 @@
+export { default as hotelImagePlaceholder } from './placeholder-hotel.png'
+
+export { default as roomImagePlaceholder } from './placeholder-room.png'

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

@@ -0,0 +1,11 @@
+export enum HotelRoomOfferType {
+  HotelRoom = 'HOTEL_ROOM',
+  Package = 'PACKAGE',
+}
+
+export enum PackageType {
+  BestMatch = 'BEST_MATCH',
+  Cheapest = 'CHEAPEST',
+  MatchingRoomCount = 'MATCHING_ROOM_COUNT',
+  Regular = 'REGULAR',
+}

package/src/constants/index.ts

@@ -1,12 +1,13 @@
 export * from '../countries/constants.ts'
 export * from '../currencies/constants.ts'
-
 export * from './environment.ts'
 export * from './hotel.ts'
 export * from './hotel-offers.ts'
+export * from './hotel-room-offer.ts'
 export * from './locales.ts'
 export * from './measurement.ts'
 export * from './poller.ts'
+export * from './tax.ts'
 export * from './time.ts'
 export * from './stay-taxes-info.ts'
 export * from './venue.ts'

package/src/constants/locales.ts

@@ -33,11 +33,11 @@ export function langFromString(langStr: string): Lang | undefined {
 export const LANG_TO_LOCALE: Record<Lang, Locale> = {
   [Lang.EN]: Locale.en_US,
   [Lang.FR]: Locale.fr_FR,
-  [Lang.DE]: Locale.en_US,
-  [Lang.ES]: Locale.en_US,
-  [Lang.IT]: Locale.en_US,
-  [Lang.NL]: Locale.en_US,
-  [Lang.PT]: Locale.en_US,
+  [Lang.DE]: Locale.de_DE,
+  [Lang.ES]: Locale.es_ES,
+  [Lang.IT]: Locale.it_IT,
+  [Lang.NL]: Locale.nl_NL,
+  [Lang.PT]: Locale.pt_PT,
 }
 
 /* @__PURE__ */

package/src/constants/tax.ts

@@ -0,0 +1,9 @@
+export enum TaxFrequency {
+  PerNight = 'PER_NIGHT',
+  PerStay = 'PER_STAY',
+}
+
+export enum TaxMode {
+  PerAdult = 'PER_ADULT',
+  PerBooking = 'PER_BOOKING',
+}

package/src/icons/index.ts

@@ -2,7 +2,9 @@ export const ICONS_NAME = Object.freeze({
   airplane: 'ph:airplane',
   archive: 'ph:archive',
   arrowDown: 'ph:arrow-down',
+  arrowHorizontal: 'ph:arrows-horizontal',
   arrowRight: 'ph:arrow-right',
+  arrowsLeftRight: 'ph:arrows-left-right',
   baby: 'ph:baby',
   bag: 'ph:bag',
   bank: 'ph:bank',
@@ -85,7 +87,6 @@ export const ICONS_NAME = Object.freeze({
   gear: 'ph:gear',
   globe: 'ph:globe',
   golf: 'ph:golf',
-  googleColored: 'flat-color-icons:google',
   graph: 'ph:graph',
   gym: 'ph:barbell',
   hairDryer: 'ph:hair-dryer',

package/src/schemas/cancellation-policies.ts

@@ -0,0 +1,18 @@
+/* eslint-disable camelcase */
+import { z } from 'zod'
+
+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.',
+  }),
+})
+/* eslint-enable camelcase */

package/src/schemas/currency.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod'
+
+import { STRIPE_CURRENCY_CODES } from '../currencies/index.ts'
+
+export const CURRENCY_SCHEMA = z
+  .enum(STRIPE_CURRENCY_CODES)
+  .openapi({ description: 'ISO 4217 currency code.' })

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

@@ -0,0 +1,43 @@
+import { z } from 'zod'
+
+import { CountryIso2Code } from '../constants/index.ts'
+
+export const ADULT_COUNT_SCHEMA = z.number().int().min(1).max(200).openapi({
+  description:
+    'The total number of adults who will be staying in the property.',
+})
+
+export const CHECK_IN_DATE_SCHEMA = z
+  .string()
+  .regex(/^(19|20)\d\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])$/u)
+  .openapi({ description: 'Date of check-in formatted as YYYY-MM-DD.' })
+
+export const CHECK_OUT_DATE_SCHEMA = z
+  .string()
+  .regex(/^(19|20)\d\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01])$/u)
+  .openapi({ 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({
+    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 COUNTRY_ISO2_CODE_SCHEMA = z
+  .nativeEnum(CountryIso2Code)
+  .refine(check => Object.values(CountryIso2Code).includes(check), {
+    message: 'Invalid ISO Alpha-2 country code.',
+  })
+  .openapi({
+    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.',
+  },
+)

package/src/schemas/hotel-offer.ts

@@ -0,0 +1,58 @@
+/* eslint-disable camelcase */
+import { z } from 'zod'
+
+import { CURRENCY_SCHEMA } from './currency.ts'
+import {
+  ADULT_COUNT_SCHEMA,
+  CHECK_IN_DATE_SCHEMA,
+  CHECK_OUT_DATE_SCHEMA,
+  CHILDREN_SCHEMA,
+} from './hotel-offer-request.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'
+import { TAGS_SCHEMA } from './tag.ts'
+
+export const HOTEL_OFFER_SCHEMA = HOTEL_SCHEMA.extend({
+  hotel_images: HOTEL_IMAGES.openapi({
+    description: `⚠️ Cached images of the hotel. May be empty, use the endpoint /hotels/{id}/images to get the latest images.
+
+List of hotel images in various sizes featuring an indicator for the primary (hero) image
+`,
+  }),
+  hotel_room_offers: z.array(HOTEL_ROOM_OFFER_SCHEMA),
+  tags: TAGS_SCHEMA,
+  venues: VENUES_SCHEMA,
+})
+
+export const HOTEL_OFFERS_SCHEMA = z.array(HOTEL_OFFER_SCHEMA)
+
+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**',
+    }),
+  }),
+  event: z.any().optional(),
+  meta: LIST_POLLING_META_SCHEMA.extend({
+    total_count: z.number(),
+  }),
+})

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

@@ -0,0 +1,99 @@
+/* eslint-disable camelcase */
+import { z } from 'zod'
+
+import {
+  BreakfastOption,
+  HotelRoomOfferType,
+  PackageType,
+} from '../constants/index.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 { HOTEL_ROOMS_SCHEMA } from './hotel-room.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 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 HOTEL_ROOM_OFFER_SCHEMA = z
+  .object({
+    breakfast_count: z.number().min(0).optional().nullish().openapi({
+      description:
+        'Quantity of breakfast per night included in the given **Hotel Room Offer**',
+    }),
+    breakfast_option: z.nativeEnum(BreakfastOption).openapi({
+      description: BREAKFAST_OPTION_DESCRIPTION,
+    }),
+    breakfast_price_per_guest_per_night: z
+      .number()
+      .optional()
+      .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>',
+      }),
+    breakfast_unit_price: z.number().optional().nullish().openapi({
+      description:
+        'Price of breakfast per guest per night for the given **Hotel Room Offer**, expressed in the requested **currency**, when applicable.',
+    }),
+    cancellation_policies: z
+      .array(CANCELLATION_POLICY_SCHEMA)
+      .openapi('cancellationPoliciesApi', {
+        description:
+          'The list of cancellation policies applied to the given **Hotel Room Offer**.',
+      }),
+    count: z
+      .number()
+      .optional()
+      .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.`,
+      }),
+    currency: CURRENCY_SCHEMA,
+    hotel_id: z
+      .string()
+      .openapi({ description: 'id of the associated Hotel.' }),
+    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(),
+    package_type: z
+      .nativeEnum(PackageType)
+      .openapi({
+        description: PACKAGE_TYPES_DESCRIPTION,
+      })
+      .nullish()
+      .optional(),
+    price: z.number().openapi({
+      description:
+        'Price with taxes NOT INCLUDED of the given **Hotel Room Offer** including breakfast(s) when applicable, expressed in the requested **currency**.',
+    }),
+    source_market: SOURCE_MARKET_SCHEMA,
+    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}**.`,
+    }),
+    taxes: TAXES_SCHEMA,
+    type: z
+      .nativeEnum(HotelRoomOfferType)
+      .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.`,
+      })
+      .nullish()
+      .optional(),
+  })
+  .openapi('hotelRoomOfferApi', {
+    description: 'Description of the Hotel Room Offer.',
+  })
+/* eslint-enable camelcase */

package/src/schemas/hotel-room.ts

@@ -0,0 +1,106 @@
+/* eslint-disable camelcase */
+import { z } from 'zod'
+
+import { HOTEL_IMAGE } from './hotel.ts'
+
+export const BED_SCHEMA = z
+  .object({
+    count: z.number().openapi({
+      description: 'Number of beds of the given type in the room.',
+    }),
+    name: z.string().openapi({ description: 'Bed name.' }),
+    occupancy: z.number().openapi({ description: 'Bed occupancy.' }),
+  })
+  .openapi('bedApi')
+
+export const BEDS_SCHEMA = z
+  .array(z.array(BED_SCHEMA))
+  .openapi({
+    description: `Beds list.
+Each nested array of beds represents a single combination of possible beds.
+e.g.: The following object represents **1 double bed or 1 sofa bed and 1 double bed or 1 single bed**:
+\`\`\`
+[
+  [
+    { count: 1, name: 'double', occupancy: 2 },
+    { count: 1, name: 'sofa', occupancy: 1 }
+  ],
+  [
+    { count: 1, name: 'double', occupancy: 2 },
+    { count: 1, name: 'single', occupancy: 1 }
+  ]
+]
+\`\`\`
+`,
+  })
+  .openapi('bedsApi')
+
+export const HOTEL_ROOM_SCHEMA = z
+  .object({
+    amenities: z
+      .array(z.string().openapi('amenity'))
+      .openapi({
+        description:
+          'List of amenities in the room. May be subject to changes at the Hotel.',
+      })
+      .nullish(),
+    beds: BEDS_SCHEMA,
+    beds_pretty: z
+      .string()
+      .openapi({ description: 'Prettified and localized list of beds' }),
+    count: z.number().openapi({
+      description: 'Hotel Room count included in the Hotel Room Offer.',
+    }),
+    description: z.string().openapi({ description: 'Hotel Room description.' }),
+    highres_images: z
+      .boolean()
+      .openapi({ description: 'Whether high resolution images are available.' })
+      .optional()
+      .nullish(),
+    id: z
+      .string()
+      .optional()
+      .openapi({ description: 'Hotel Room id, when applicable.' }),
+    image_indexes: z.array(z.number()).optional().nullish().openapi({
+      description:
+        'List of indexes corresponding to image names for the given Hotel Room among the related hotel images.',
+    }),
+    images: z
+      .array(HOTEL_IMAGE)
+      .openapi({
+        description: 'Hotel Room images.',
+      })
+      .optional()
+      .nullish(),
+    lowres_images: z
+      .boolean()
+      .openapi({ description: 'Whether low resolution images are available.' })
+      .optional()
+      .nullish(),
+    occupancy: z
+      .number()
+      .openapi({ description: 'Total occupancy of a single hotel room.' }),
+    rich_description: z.string().optional().nullish().openapi({
+      description: 'Rich Hotel Room description. May contain HTML tags markup.',
+    }),
+    room_square_feet: z.number().optional().nullish().openapi({
+      description:
+        'Room surface in square feet. May be subject to changes at the Hotel.',
+    }),
+    room_square_meters: z.number().optional().nullish().openapi({
+      description:
+        'Room surface in square meters. May be subject to changes at the Hotel.',
+    }),
+    thumb_images: z
+      .boolean()
+      .openapi({
+        description:
+          'Whether thumb resolution images are available (in order to display them as image carousel navigation for instance).',
+      })
+      .optional()
+      .nullish(),
+  })
+  .openapi({ description: 'Hotel Room details.' })
+
+export const HOTEL_ROOMS_SCHEMA = z.array(HOTEL_ROOM_SCHEMA)
+/* eslint-enable camelcase */