feat(booking): add private fares types (#692)

* refactor(booking): add CreateOfferRequestPassenger interface

* feat(booking): add private_fares field to CreateOfferRequest interface

* feat(booking): add fare_type field to CreateOfferRequestPassenger interface

* feat(booking): add private_fares field to Offer interface

* fix(booking): update field types to be optional

* test(booking): add test for private fares

Author: matthewp5

src/booking/OfferRequests/OfferRequests.spec.ts

@@ -1,8 +1,9 @@
 import nock from 'nock'
 import { Client } from '../../Client'
-import { CreateOfferRequest } from './OfferRequestsTypes'
+import { CreateOfferRequest, OfferRequest } from './OfferRequestsTypes'
 import { mockCreateOfferRequest, mockOfferRequest } from './mockOfferRequest'
 import { OfferRequests } from './OfferRequests'
+import { OfferPrivateFare } from 'types'
 
 describe('OfferRequests', () => {
   afterEach(() => {
@@ -127,4 +128,77 @@ describe('OfferRequests', () => {
     // In this case, `offers` won't be in the response, but the offer request's id will still be returned and can be used with the List Offers endpoint to retrieve the offers.
     expect(response.data?.id).toBe(mockOfferRequest.id)
   })
+
+  test('should create an offer request and return an offer with corporate private fares', async () => {
+    const mockCorporatePrivateFare: OfferPrivateFare = {
+      corporate_code: 'FLX53',
+      tracking_reference: 'ABN:2345678',
+      type: 'corporate',
+    }
+
+    const mockResponseWithCorporatePrivateFares: OfferRequest = {
+      ...mockOfferRequest,
+      offers: [
+        {
+          ...mockOfferRequest.offers[0],
+          private_fares: [mockCorporatePrivateFare],
+        },
+      ],
+    }
+
+    nock(/(.*)/)
+      .post(`/air/offer_requests/`)
+      .reply(200, { data: mockResponseWithCorporatePrivateFares })
+
+    const response = await new OfferRequests(
+      new Client({ token: 'mockToken ' })
+    ).create({
+      ...mockCreateOfferRequest,
+      private_fares: {
+        QF: [
+          {
+            corporate_code: 'FLX53',
+            tracking_reference: 'ABN:2345678',
+          },
+        ],
+      },
+    })
+
+    expect(response.data.offers[0].private_fares).toHaveLength(1)
+    expect(response.data.offers[0].private_fares[0].type).toBe('corporate')
+  })
+
+  test('should create an offer request and return an offer with lesuire private fares', async () => {
+    const mockLeisurePrivateFare: OfferPrivateFare = {
+      type: 'leisure',
+    }
+
+    const mockResponseWithLeisurePrivateFare: OfferRequest = {
+      ...mockOfferRequest,
+      offers: [
+        {
+          ...mockOfferRequest.offers[0],
+          private_fares: [mockLeisurePrivateFare],
+        },
+      ],
+    }
+
+    nock(/(.*)/)
+      .post(`/air/offer_requests/`)
+      .reply(200, { data: mockResponseWithLeisurePrivateFare })
+
+    const response = await new OfferRequests(
+      new Client({ token: 'mockToken ' })
+    ).create({
+      ...mockCreateOfferRequest,
+      passengers: [
+        {
+          fare_type: 'teacher',
+        },
+      ],
+    })
+
+    expect(response.data.offers[0].private_fares).toHaveLength(1)
+    expect(response.data.offers[0].private_fares[0].type).toBe('leisure')
+  })
 })

src/booking/OfferRequests/OfferRequestsTypes.ts

@@ -34,6 +34,117 @@ export interface OfferRequestSlice {
   destination_type: PlaceType
 }
 
+interface CreateOfferRequestPassengerCommon {
+  /**
+   * The passenger's family name. Only `space`, `-`, `'`, and letters from the
+   * `ASCII`, `Latin-1 Supplement` and `Latin Extended-A` (with the exceptions
+   * of `Æ`, `æ`, `IJ`, `ij`, `Œ`, `œ`, `Þ`, and `ð`) Unicode charts are accepted.
+   * All other characters will result in a validation error. The minimum length
+   * is 1 character, and the maximum is 20 characters.
+   *
+   * This is only required if you're also including
+   * **Loyalty Programme Accounts**.
+   */
+  family_name?: string
+
+  /**
+   * The passenger's given name. Only `space`, `-`, `'`, and letters from the
+   * `ASCII`, `Latin-1 Supplement` and `Latin Extended-A` (with the exceptions
+   * of `Æ`, `æ`, `IJ`, `ij`, `Œ`, `œ`, `Þ`, and `ð`) Unicode charts are accepted.
+   * All other characters will result in a validation error. The minimum length
+   * is 1 character, and the maximum is 20 characters.
+   *
+   * This is only required if you're also including
+   * **Loyalty Programme Accounts**.
+   */
+  given_name?: string
+
+  /**
+   * The **Loyalty Programme Accounts** for this passenger.
+   */
+  loyalty_programme_accounts?: LoyaltyProgrammeAccount[]
+}
+
+interface CreateOfferRequestAdultPassenger
+  extends CreateOfferRequestPassengerCommon {
+  age?: never
+  fare_type?: never
+  /**
+   * The type of the passenger. If the passenger is aged 18 or over, you should
+   * specify a `type` of `adult`. If a passenger is aged under 18, you should
+   * specify their `age` instead of a `type`. A passenger can have only a type
+   * or an age, but not both.
+   */
+  type: Extract<DuffelPassengerType, 'adult'>
+}
+
+interface CreateOfferRequestNonAdultPassenger
+  extends CreateOfferRequestPassengerCommon {
+  /**
+   * The age of the passenger on the `departure_date` of the final slice. e.g.
+   * if you a searching for a round trip and the passenger is 15 years old at
+   * the time of the outbound flight, but they then have their birthday and are
+   * 16 years old for the inbound flight, you must set the age to 16. You should
+   * specify an `age` for passengers who are under 18 years old. A passenger can
+   * have only a type or an age, but not both. You can optionally pass age with
+   * `fare_type` though.
+   */
+  age: number
+  fare_type?: never
+  type?: never
+}
+
+export type CreateOfferRequestPassengerFareType =
+  | 'accompanying_adult'
+  | 'contract_bulk'
+  | 'contract_bulk_child'
+  | 'contract_bulk_infant_with_seat'
+  | 'contract_bulk_infant_without_seat'
+  | 'frequent_flyer'
+  | 'group_inclusive_tour'
+  | 'group_inclusive_tour_child'
+  | 'humanitarian'
+  | 'individual_inclusive_tour_child'
+  | 'marine'
+  | 'seat_only'
+  | 'student'
+  | 'teacher'
+  | 'tour_operator_inclusive'
+  | 'tour_operator_inclusive_infant'
+  | 'unaccompanied_child'
+  | 'visiting_friends_and_family'
+
+interface CreateOfferRequestPassengerWithFareType
+  extends CreateOfferRequestPassengerCommon {
+  /**
+   * The age of the passenger on the `departure_date` of the final slice. e.g.
+   * if you a searching for a round trip and the passenger is 15 years old at
+   * the time of the outbound flight, but they then have their birthday and are
+   * 16 years old for the inbound flight, you must set the age to 16. You should
+   * specify an `age` for passengers who are under 18 years old. A passenger can
+   * have only a type or an age, but not both. You can optionally pass age with
+   * `fare_type` though.
+   */
+  age?: number
+
+  /**
+   * The fare type of the passenger. If the passenger is aged less than 18, you
+   * should pass in age as well.
+   */
+  fare_type: CreateOfferRequestPassengerFareType
+  type?: never
+}
+
+export type CreateOfferRequestPassenger =
+  | CreateOfferRequestAdultPassenger
+  | CreateOfferRequestNonAdultPassenger
+  | CreateOfferRequestPassengerWithFareType
+
+export interface CreateOfferRequestPrivateFare {
+  corporate_code: string
+  tracking_reference: string
+}
+
 /**
  * The passengers who want to travel. A passenger will have only a type or an age.
  */
@@ -143,27 +254,44 @@ export interface OfferRequest {
 
 export interface CreateOfferRequest {
   /**
-   * The cabin that the passengers want to travel in
+   * The cabin that the passengers want to travel in.
    */
   cabin_class?: CabinClass
 
   /**
-   * The passengers who want to travel.
-   * If you specify an age for a passenger, the type may differ for the same passenger in different offers due to airline's different rules. e.g. one airline may treat a 14 year old as an adult, and another as a young adult.
+   * The maximum number of connections within any slice of the offer. For
+   * example 0 means a direct flight which will have a single segment within
+   * each slice and 1 means a maximum of two segments within each slice of the
+   * offer.
    */
-  passengers: Omit<OfferRequestPassenger, 'id'>[]
+  max_connections?: 0 | 1 | 2
 
   /**
-   * The [slices](https://duffel.com/docs/api/overview/key-principles) that make up this offer request.
-   * One-way journeys can be expressed using one slice, whereas return trips will need two.
+   * The passengers who want to travel. If you specify an `age` for a passenger,
+   * the `type` may differ for the same passenger in different offers due to
+   * airline's different rules. E.g. one airline may treat a 14 year old as an
+   * adult, and another as a young adult. You may only specify an `age` or a
+   * `type` – not both.
    */
-  slices: Omit<OfferRequestSlice, 'origin_type' | 'destination_type'>[]
+  passengers: CreateOfferRequestPassenger[]
 
   /**
-   * The maximum number of connections within any slice of the offer.
-   * For example 0 means a direct flight which will have a single segment within each slice and 1 means a maximum of two segments within each slice of the offer.
+   * The private fare codes for this Offer Request. You can pass in multiple
+   * airlines with their specific private fare codes. The key is the airline's
+   * IATA code that provided the private fare code. The `corporate_code` is
+   * provided to you by the airline and the `tracking_reference` is to identify
+   * your business by the airlines.
    */
-  max_connections?: 0 | 1 | 2
+  private_fares?: {
+    [iataCode: string]: CreateOfferRequestPrivateFare[]
+  }
+
+  /**
+   * The [slices](https://duffel.com/docs/api/overview/key-principles) that make
+   * up this offer request. One-way journeys can be expressed using one slice,
+   * whereas return trips will need two.
+   */
+  slices: Omit<OfferRequestSlice, 'origin_type' | 'destination_type'>[]
 }
 
 export interface CreateOfferRequestQueryParameters {

src/booking/Offers/OfferTypes.ts

@@ -91,6 +91,11 @@ export interface Offer {
    */
   payment_requirements: PaymentRequirements
 
+  /**
+   * The private fares applied on this offer.
+   */
+  private_fares: OfferPrivateFare[]
+
   /**
    * The slices that make up this offer. Each slice will include one or more segments,
    * the specific flights that the airline is offering to take the passengers from the slice's `origin` to its `destination`.
@@ -291,6 +296,23 @@ export interface PaymentRequirements {
   requires_instant_payment: boolean
 }
 
+export interface OfferPrivateFare {
+  /**
+   * The corporate code that was applied, if any.
+   */
+  corporate_code?: string
+
+  /**
+   * The tracking reference that was applied, if any.
+   */
+  tracking_reference?: string
+
+  /**
+   * The type of private fare applied.
+   */
+  type: 'corporate' | 'leisure' | 'negotiated'
+}
+
 export interface OfferPassenger {
   /**
    * The age of the passenger on the departure_date of the final slice.

src/booking/Offers/mockOffer.ts

@@ -140,6 +140,7 @@ export const mockOffer: Offer = {
     price_guarantee_expires_at: '2020-01-17T10:42:14.545Z',
     payment_required_by: '2020-01-17T10:42:14.545Z',
   },
+  private_fares: [],
   partial: false,
   passengers: [
     {

src/booking/Offers/mockPartialOffer.ts

@@ -140,6 +140,7 @@ export const mockPartialOffer: Offer = {
     price_guarantee_expires_at: '2020-01-17T10:42:14.545Z',
     payment_required_by: '2020-01-17T10:42:14.545Z',
   },
+  private_fares: [],
   partial: true,
   passengers: [
     {