Merge pull request #952 from duffelhq/introduces-v2

Introduces API v2

Author: igorp1

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duffel/api",
-  "version": "2.14.4",
+  "version": "3.0.0",
   "description": "Javascript client library for the Duffel API",
   "main": "dist/index.js",
   "module": "dist/index.es.js",

src/Client.ts

@@ -36,6 +36,8 @@ export class DuffelError extends Error {
   }
 }
 
+const CURRENT_API_VERSION = 'v2'
+
 export class Client {
   private token: string
   private basePath: string
@@ -46,7 +48,7 @@ export class Client {
   constructor({ token, basePath, apiVersion, debug, source }: Config) {
     this.token = token
     this.basePath = basePath || 'https://api.duffel.com'
-    this.apiVersion = apiVersion || 'v1'
+    this.apiVersion = apiVersion || CURRENT_API_VERSION
     this.debug = debug
     this.source = source
   }

src/Stays/Stays.spec.ts

@@ -21,7 +21,7 @@ describe('Stays', () => {
       },
       check_in_date: '2023-10-20',
       check_out_date: '2023-10-24',
-      adults: 2,
+      guests: [{ type: 'adult' }, { type: 'adult' }, { type: 'child', age: 5 }],
       rooms: 1,
     }
 
@@ -44,7 +44,7 @@ describe('Stays', () => {
       },
       check_in_date: '2023-10-20',
       check_out_date: '2023-10-24',
-      adults: 2,
+      guests: [{ type: 'adult' }, { type: 'adult' }, { type: 'child', age: 5 }],
       rooms: 1,
     }
 

src/Stays/StaysTypes.ts

@@ -159,11 +159,6 @@ export interface StaysRate {
    */
   total_currency: string
 
-  /**
-    Deprecated. Refer to available_payment_methods instead.
-  */
-  payment_method: StaysPaymentType
-
   /**
    * The methods available for payment of this rate.
 
@@ -335,20 +330,10 @@ export interface StaysAccommodation {
   } | null
 
   /**
-   * Deprecated: Instructions to access the accommodation in the booking
+   * The key collection details for the accommodation.
    */
   key_collection: StaysBookingKeyCollection | null
 
-  /**
-   * The total currency for the cheapest rate for this accommodation, as an ISO 4217 currency code. If rooms data is available, this is equivalent to the cheapest rate for the cheapest room.
-   */
-  cheapest_rate_currency: string
-
-  /**
-   * The total amount for the cheapest rate for this accommodation. If rooms data is available, this is equivalent to the cheapest rate for the cheapest room.
-   */
-  cheapest_rate_total_amount: string
-
   /**
    * The accommodation’s description
    */
@@ -418,7 +403,7 @@ export interface StaysQuote {
   /**
    * The id of the stay quote.
    *
-   * Example: "quo_0000AS0NZdKjjnnHZmSUbI"
+   * @example: "quo_0000AS0NZdKjjnnHZmSUbI"
    */
   id: string
 
@@ -526,17 +511,6 @@ export interface StaysQuote {
    */
   supported_loyalty_programme: StaysLoyaltyProgrammeReference | null
 
-  /**
-   * A client key to authenticate with Duffel's Card Component when creating a tokenised card.
-   * This value will be `null` if your organisation does not have this feature enabled,
-   */
-  card_component_key: string | null
-
-  /*
-   * The number of adult guests this quote is for.
-   */
-  adults: number
-
   /*
    * The number of rooms this quote is for
    */
@@ -644,14 +618,12 @@ type Child = { type: 'child'; age: number }
 
 export type Guest = Adult | Child
 
-type OccupancyCriteria = {
-  rooms: number
-} & ({ adults: number } | { guests: Array<Guest> })
-
-type CommonStaysSearchParams = {
+interface CommonStaysSearchParams {
   check_in_date: string
   check_out_date: string
-} & OccupancyCriteria
+  rooms: number
+  guests: Array<Guest>
+}
 
 export type LocationParams = {
   radius: number
@@ -679,9 +651,10 @@ export interface StaysSearchResult {
   check_in_date: string
   check_out_date: string
   accommodation: StaysAccommodation
-  adults: number
   rooms: number
   guests: Array<Guest>
+  cheapest_rate_total_amount: string
+  cheapest_rate_currency: string
 }
 
 export interface StaysLoyaltyProgramme {

src/Stays/mocks.ts

@@ -51,7 +51,6 @@ export const MOCK_ACCOMMODATION: StaysAccommodation = {
           fee_amount: '40.00',
           cancellation_timeline: [],
           board_type: 'room_only',
-          payment_method: 'balance', // Deprecated. Refer to available_payment_methods instead.
           available_payment_methods: ['balance'],
           quantity_available: 1,
           supported_loyalty_programme: null,
@@ -83,7 +82,6 @@ export const MOCK_ACCOMMODATION: StaysAccommodation = {
           fee_amount: '40.00',
           cancellation_timeline: [],
           board_type: 'room_only',
-          payment_method: 'card', // Deprecated. Refer to available_payment_methods instead.
           available_payment_methods: ['card'],
           quantity_available: 1,
           supported_loyalty_programme: 'duffel_hotel_group_rewards',
@@ -145,8 +143,6 @@ export const MOCK_ACCOMMODATION: StaysAccommodation = {
   key_collection: {
     instructions: 'Key is at the property. Collect from the lock box.',
   },
-  cheapest_rate_total_amount: '799.00',
-  cheapest_rate_currency: 'GBP',
   chain: {
     name: 'The Ritz-Carlton',
   },
@@ -158,9 +154,10 @@ export const MOCK_SEARCH_RESULT: StaysSearchResult = {
   id: 'sta_something',
   check_in_date: '2023-03-24',
   check_out_date: '2023-03-28',
-  adults: 2,
   rooms: 1,
   guests: [{ type: 'adult' }, { type: 'adult' }],
+  cheapest_rate_total_amount: '799.00',
+  cheapest_rate_currency: 'GBP',
 }
 
 export const MOCK_BOOKING: StaysBooking = {
@@ -221,8 +218,6 @@ export const MOCK_QUOTE: StaysQuote = {
   due_at_accommodation_amount: null,
   due_at_accommodation_currency: 'USD',
   supported_loyalty_programme: 'duffel_hotel_group_rewards',
-  card_component_key: null,
-  adults: 2,
   rooms: 1,
   guests: [{ type: 'adult' }, { type: 'adult' }],
 }

src/booking/AirlineInitiatedChanges/mockAirlineInitiatedChanges.ts

@@ -123,7 +123,6 @@ export const mockAirlineInitiatedChange: AirlineInitiatedChange = {
         city_name: 'Barcelona',
         city: null,
       },
-      changeable: null,
     },
   ],
   order_id: 'ord_00009hthhsUZ8W4LxQgkjo',
@@ -250,7 +249,6 @@ export const mockAirlineInitiatedChange: AirlineInitiatedChange = {
         city_name: 'Barcelona',
         city: null,
       },
-      changeable: false,
     },
   ],
   action_taken_at: null,

src/booking/Offers/OfferTypes.ts

@@ -1,29 +1,23 @@
 import {
-  CabinClass,
-  FlightsConditions,
-  LoyaltyProgrammeAccount,
-  PassengerIdentityDocumentType,
-  Place,
-  PlaceType,
   Aircraft,
   Airline,
   Airport,
-  PaginationMeta,
+  CabinClass,
+  CreateOfferRequestPassengerFareType,
   DuffelPassengerType,
+  FlightsConditions,
+  LoyaltyProgrammeAccount,
   OfferSliceConditions,
+  PaginationMeta,
+  Place,
+  PlaceType,
 } from '../../types'
 
 /**
  * Each offer represents flights you can buy from an airline at a particular price that meet your search criteria.
  * @link https://duffel.com/docs/api/offers/schema
  */
 export interface Offer {
-  /**
-   * The types of identity documents that may be provided for the passengers when creating an order based on this offer.
-   * If this is `[]`, then you must not provide identity documents.
-   */
-  allowed_passenger_identity_document_types: PassengerIdentityDocumentType[]
-
   /**
    * The services that can be booked along with the offer but are not included by default, for example an additional checked bag.
    * This field is only returned in the Get single offer endpoint.
@@ -141,8 +135,29 @@ export interface Offer {
    * Partial offers are only ever returned through the multi-step search flow.
    */
   partial: boolean
+
+  /**
+   * A list of airline IATA codes whose loyalty programmes are supported when booking the offer.
+   * Loyalty programmes present within the offer passengers that are not present in this field shall be ignored at booking.
+   * If this is an empty list ([]), no loyalty programmes are supported for the offer and shall be ignored if provided.
+   * @example: ["AF","KL","DL"]
+   */
+  supported_loyalty_programmes: string[]
+
+  /**
+   * The types of identity documents supported by the airline and may be provided for the
+   * passengers when creating an order based on this offer. Currently, possible types are `passport`,
+   * `tax_id`, `known_traveler_number`, and `passenger_redress_number`.
+   */
+  supported_passenger_identity_document_types: OfferSupportedPassengerIdentityDocumentTypes[]
 }
 
+export type OfferSupportedPassengerIdentityDocumentTypes =
+  | 'passport'
+  | 'tax_id'
+  | 'known_traveler_number'
+  | 'passenger_redress_number'
+
 export interface OfferAvailableServiceBaggageMetadata {
   /**
    * The maximum weight that the baggage can have in kilograms.
@@ -354,6 +369,12 @@ export interface OfferPassenger {
    * Optionally providing one has been deprecated.
    */
   id: string
+
+  /**
+   * The fare type of the passenger
+   * Example: "contract_bulk"
+   */
+  fare_type: CreateOfferRequestPassengerFareType | null
 }
 
 export interface OfferSlice {

src/booking/Offers/mockOffer.ts

@@ -180,6 +180,7 @@ export const mockOffer: Offer = {
           airline_iata_code: 'BA',
         },
       ],
+      fare_type: null,
     },
   ],
   passenger_identity_documents_required: false,
@@ -244,7 +245,8 @@ export const mockOffer: Offer = {
       type: 'cancel_for_any_reason',
     },
   ],
-  allowed_passenger_identity_document_types: ['passport'],
+  supported_passenger_identity_document_types: ['passport'],
+  supported_loyalty_programmes: [],
 }
 
 export const mockUpdatedOffer = {

src/booking/Offers/mockPartialOffer.ts

@@ -180,6 +180,7 @@ export const mockPartialOffer: Offer = {
           airline_iata_code: 'BA',
         },
       ],
+      fare_type: null,
     },
   ],
   passenger_identity_documents_required: false,
@@ -244,7 +245,8 @@ export const mockPartialOffer: Offer = {
       type: 'cancel_for_any_reason',
     },
   ],
-  allowed_passenger_identity_document_types: ['passport'],
+  supported_passenger_identity_document_types: ['passport'],
+  supported_loyalty_programmes: [],
 }
 
 export const mockUpdatedOffer = {

src/booking/OrderCancellations/OrderCancellationsTypes.ts

@@ -40,15 +40,19 @@ export interface OrderCancellation {
    */
   order_id: string
   /**
-   * The amount that will be returned to the original payment method if the order is cancelled, determined according to the fare conditions. This may be `0.00` if the fare is non-refundable. It will include the refund amount of the flights and the services booked.
+   * The amount that will be returned to the original payment method if the order is cancelled, determined according
+   * to the fare conditions. This may be 0.00 if the fare is non-refundable. It will include the refund amount
+   * of the flights and the services booked. This may be null in cases where the refund amount is unknown.
+   * This only applies in cases where we are unable to get a refund quote from the carrier.
    */
-  refund_amount: string
+  refund_amount: string | null
   /**
-   * The currency of the `refund_amount`, as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.
-   * It will match your organisation's billing currency unless you're using Duffel as an accredited IATA agent, in which case it will be in the currency provided by the airline (which will usually be based on the country where your IATA agency is registered).
-   * For pay later orders that are awaiting payment, the refund amount will always be 0.00.
+   * The currency of the refund_amount, as an ISO 4217 currency code.
+   * It will match your organisation's billing currency unless you’re using Duffel as an accredited IATA agent,
+   * in which case it will be in the currency provided by the airline (which will usually be based on the
+   * country where your IATA agency is registered). For hold orders that are awaiting payment, the refund amount will always be 0.00.
    */
-  refund_currency: string
+  refund_currency: string | null
   /**
    * Where the refund, once confirmed, will be sent. `card` is currently a restricted feature. `awaiting_payment` is for pay later orders where no payment has been made yet.
    */