@findhotel/sapi 1.5.0 → 1.6.1

package/README.md

@@ -20,6 +20,7 @@ hotels, hotels\' offers and rooms.
     - [Get hotel](#get-hotel)
     - [Get hotels](#get-hotels)
     - [Get hotel offers](#get-hotel-offers)
+    - [Get hotel(s) availability (aka price calendar)](#get-hotels-availability-aka-price-calendar)
 - [API Reference](#api-reference)
   - [SAPI client](#sapi-client)
     - [Supported options](#supported-options)
@@ -27,6 +28,7 @@ hotels, hotels\' offers and rooms.
     - [Response](#response)
   - [`search()` method](#search-method)
     - [Search parameters](#search-parameters)
+      - [Split Booking Configuration](#split-booking-configuration)
       - [Filters](#filters)
         - [Facilities](#facilities)
         - [Property types](#property-types)
@@ -48,6 +50,10 @@ hotels, hotels\' offers and rooms.
   - [`offers()` method](#offers-method)
     - [Offers parameters](#offers-parameters)
     - [Response](#response-6)
+  - [`hotelAvailability()` method](#hotelavailability-method)
+    - [Hotel(s) availability search parameters](#hotels-availability-search-parameters)
+    - [Callbacks](#callbacks-1)
+    - [Response](#response-7)
   - [Rooms configuration](#rooms-configuration)
       - [Examples](#examples)
   - [How to generate `searchId`?](#how-to-generate-searchid)
@@ -244,7 +250,6 @@ const hotel = await sapiClient.hotel('1196472')
 For full documentation, check [hotel method api](#hotel-method).
 
 ### Get hotels
-<a id="tutorial-get-hotels"></a>
 
 Get hotels by ids:
 
@@ -255,7 +260,6 @@ const hotels = await sapiClient.hotels(['1714808','1380416','1710829'])
 For full documentation, check [hotels method api](#hotels-method).
 
 ### Get hotel offers
-<a id="tutorial-get-offers"></a>
 
 Get offers for a single hotel:
 
@@ -281,6 +285,36 @@ const offers = await sapiClient.offers(parameters, callbacks)
 
 For full documentation, check [offers method api](#offers-method).
 
+### Get hotel(s) availability (aka price calendar)
+
+Get hotel(s) availability:
+
+```js
+const parameters = {
+  hotelIds: ['1380416','1359951'],
+  startDate: '2023-08-05',
+  endDate: '2023-08-12',
+  nights: 2,
+  rooms: '2',
+}
+
+const callbacks = {
+  onStart: (response) => {
+    log('Availability request started', response)
+  },
+  onAvailabilityReceived: (response) => {
+    log('Availability received', response)
+  },
+  onComplete: (response) => {
+    log('Availability completed', response)
+  }
+}
+
+const response = await sapiClient.hotelAvailability(parameters, callbacks)
+```
+
+For full documentation, check [availability method api](#hotel-availability-method).
+
 # API Reference
 
 ## SAPI client
@@ -392,7 +426,7 @@ const search = await sapiClient.search(searchParameters, callbacks)
 All parameters are optional.
 
 | name            | type                                            | description                                                                                              | example                                                             |
-| --------------- | ----------------------------------------------- |----------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
+| --------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
 | `hotelId`       | `string`                                        | Hotel Id for hotel search                                                                                | `1371626`                                                           |
 | `placeId`       | `string`                                        | Place Id for place search                                                                                | `47319`                                                             |
 | `geolocation`   | `{lat: number, lon: number, precision: string}` | Geolocation query                                                                                        | `{lat: 36.114303, lon: -115.178312}`                                |
@@ -1098,10 +1132,10 @@ const offers = await sapiClient.offers(parameters, callbacks)
 ```
 
 ### Offers parameters
-<a id="hotel-parameters"></a>
+<a id="offers-parameters"></a>
 
 | name               | type                     | description                                                                                                                                                | required | example                                    |
-| ------------------ |--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- | ------------------------------------------ |
+| ------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------ |
 | `hotelId`          | `string`                 | Hotel Id                                                                                                                                                   | yes      | `1196472`                                  |
 | `checkIn`          | `string`                 | Check in date (YYYY-MM-DD) (SDK generates default date if no provided)                                                                                     | no       | `2022-10-10`                               |
 | `checkOut`         | `string`                 | Check out date (YYYY-MM-DD)) (SDK generates default date if no provided)                                                                                   | no       | `2022-10-11`                               |
@@ -1119,7 +1153,7 @@ const offers = await sapiClient.offers(parameters, callbacks)
 | `offersSort`       | `string`                 | If present, sorts offers by price (see [explanation](#sort-offers))                                                                                        | no       |                                            |
 | `getAllOffers`     | `boolean`                | If `true` SAPI returns all (up to 23) offers for the hotel (by default or if it's `false` SAPI returns only up to 3 top offers)                            | no       |                                            |
 | `optimizeRooms`    | `boolean`                | If `true` then rooms optimization logic is enabled. Rooms optimization tries to find best offer across possible rooms configurations for a given occupancy | no       |                                            |
-| `sbc`              | `string`                 | [Split Booking Configuration](#splitbookingconfiguration). If present, searches for split booking offers                                                   | no       |  `sbc: '2~3'`                              |
+| `sbc`              | `string`                 | [Split Booking Configuration](#splitbookingconfiguration). If present, searches for split booking offers                                                   | no       | `sbc: '2~3'`                               |
 
 <a id="sort-offers"></a>
 Offer sorting by one parameter for now. It is `price`, but there are different variants of sorting by price.:
@@ -1178,6 +1212,183 @@ const parameters = {
 
 The response with the detailed description can be found in the [Offers Response](./docs/offers.md)
 
+
+## `hotelAvailability()` method
+<a id="hotel-availability-method"></a>
+
+Returns availability of the provided hotels for different dates (aka price calendar)
+
+```js
+const parameters = {
+  hotelIds: ['1380416','1359951'],
+  startDate: '2023-08-05',
+  endDate: '2023-08-12',
+  nights: 2,
+  rooms: '2',
+}
+
+const callbacks = {
+  onStart: (response) => {
+    log('Availability request started', response)
+  },
+  onAvailabilityReceived: (response) => {
+    log('Availability received', response)
+  },
+  onComplete: (response) => {
+    log('Availability completed', response)
+  }
+}
+
+const response = await sapiClient.hotelAvailability(parameters, callbacks)
+```
+
+### Hotel(s) availability search parameters
+<a id="availability-search-parameters"></a>
+
+| name        | type               | description                                                                                  | required | example                    |
+| ----------- | ------------------ | -------------------------------------------------------------------------------------------- | -------- | -------------------------- |
+| `hotelIds`  | `string, string[]` | Hotel id(s) to retrieve offers for                                                           | yes      | `['1380416','1359951']`    |
+| `startDate` | `string`           | Date of first check in (YYYY-MM-DD)                                                          | yes      | `'2023-10-10'`             |
+| `endDate`   | `string`           | Date of last check in (including). Can't be further than 61 days from StartDate (YYYY-MM-DD) | yes      | `'2023-10-11'`             |
+| `nights`    | `number`           | Nights is length of stay                                                                     | yes      | `3`                        |
+| `rooms`     | `string`           | [Rooms configuration](#rooms-configuration)                                                  | yes      | `'2'`                      |
+| `cugDeals`  | `string[]`         | Codes of closed user group deals to retrieve offers                                          | no       | `['signed_in', 'offline']` |
+| `tier`      | `string`           | User tier                                                                                    | no       | `'member'`                 |
+| `originId`  | `string`           | Identifier of origin where the request was originated                                        | no       | `'c3po6twr70'`             |
+
+### Callbacks
+<a id="availability-callbacks"></a>
+
+Object with callbacks:
+
+```js
+const callbacks =  {
+  onStart: (response) => {
+    log('Availability request started', response)
+  },
+  onAvailabilityReceived: (response) => {
+    log('Availability received', response)
+  },
+  onComplete: (response) => {
+    log('Availability completed', response)
+  }
+}
+```
+
+1.  ### onStart()
+
+    Runs at the beginning of each new availability request.\
+    Returns adjusted and validated availability search parameters.
+
+2.  ### onAvailabilityReceived()
+
+    Runs on every received batch of availability.\
+    Returns availability with offers (incomplete response).
+
+3.  ### onComplete()
+
+    Runs after availability request is completed.\
+    Returns availability with offers (complete response).
+
+### Response
+<a id="availability-response"></a>
+
+An example of the response:
+
+```json
+{
+  "1380416": {
+    "2023-08-05": {
+      "hotelID": "1380416",
+      "cheapestRate": {
+        "base": 531.9901869159,
+        "taxes": 34.7298130841,
+        "hotelFees": 0
+      },
+      "offers": [
+        {
+          "id": "oEfGbUTje2BE",
+          "currency": "EUR",
+          "availableRooms": null,
+          "url": "https://r.vio.com?lbl=providerRateType%3Dmember&ofd=...",
+          "rate": {
+            "base": 531.9901869159,
+            "taxes": 34.7298130841,
+            "hotelFees": 0
+          },
+          "accessTier": "sensitive",
+          "providerCode": "WTM",
+          "intermediaryProvider": "FHT",
+          "package": {
+            "amenities": [
+              "breakfast"
+            ],
+            "canPayLater": false
+          },
+          "cancellationPenalties": [
+            {
+              "start": "2023-07-30T10:00:00Z",
+              "end": "2023-08-02T09:59:00Z",
+              "amount": 0,
+              "currency": "EUR"
+            }
+          ],
+          "tags": [
+            "top_offer",
+            "exclusive_cheapest_offer"
+          ],
+          "metadata": {
+            "providerRateType": "member",
+            "feedID": ""
+          },
+          "roomName": "STANDARD DOUBLE/TWIN"
+        },
+      ]
+    },
+    "2023-08-06": {
+      "hotelID": "1380416",
+      "cheapestRate": {
+        "base": 493.9438317757,
+        "taxes": 32.2961682243,
+        "hotelFees": 0
+      },
+      "offers": [
+        {
+          "id": "omVVqhCXEbIw",
+          "currency": "EUR",
+          "availableRooms": null,
+          "url": "https://r.vio.com?lbl=providerRateType%3Dmember&ofd=book_uri...",
+          "rate": {
+            "base": 493.9438317757,
+            "taxes": 32.2961682243,
+            "hotelFees": 0
+        },
+          "accessTier": "sensitive",
+          "providerCode": "WTM",
+          "intermediaryProvider": "FHT",
+          "package": {
+            "amenities": [
+              "breakfast"
+            ],
+            "canPayLater": false
+          },
+          "cancellationPenalties": [],
+          "tags": [
+            "top_offer",
+            "exclusive_cheapest_offer"
+          ],
+          "metadata": {
+            "providerRateType": "member",
+            "feedID": ""
+          },
+          "roomName": "STANDARD DOUBLE/TWIN"
+        }
+      ]
+    }
+  }
+}
+```
+
 ## Rooms configuration
 <a id="rooms-configuration"></a>
 `rooms` is a string that encodes the configuration of rooms requested by the user and follows the next rules: