Merge pull request #1066 from duffelhq/add-batch-offer-request

feat: add batch offer requests

Author: SamHutchings

.tool-versions

@@ -1 +1 @@
-nodejs 18.20.8
+nodejs 18.20.8

src/booking/BatchOfferRequests/BatchOfferRequests.spec.ts

@@ -0,0 +1,35 @@
+import nock from 'nock'
+import { Client } from '../../Client'
+import {
+  mockCreateBatchOfferRequest,
+  mockBatchOfferRequest,
+} from './mockBatchOfferRequest'
+import { BatchOfferRequests } from './BatchOfferRequests'
+
+describe('BatchOfferRequests', () => {
+  afterEach(() => {
+    nock.cleanAll()
+  })
+
+  test('should get a single offer request', async () => {
+    nock(/(.*)/)
+      .get(`/air/batch_offer_requests/${mockBatchOfferRequest.id}`)
+      .reply(200, { data: mockBatchOfferRequest })
+
+    const response = await new BatchOfferRequests(
+      new Client({ token: 'mockToken' }),
+    ).get(mockBatchOfferRequest.id)
+    expect(response.data?.id).toBe(mockBatchOfferRequest.id)
+  })
+
+  test('should create an offer request and returns the id', async () => {
+    nock(/(.*)/)
+      .post(`/air/batch_offer_requests/`)
+      .reply(200, { data: mockBatchOfferRequest })
+
+    const response = await new BatchOfferRequests(
+      new Client({ token: 'mockToken' }),
+    ).create(mockCreateBatchOfferRequest)
+    expect(response.data?.id).toBe(mockBatchOfferRequest.id)
+  })
+})

src/booking/BatchOfferRequests/BatchOfferRequests.ts

@@ -0,0 +1,65 @@
+import { Client } from '../../Client'
+import { Resource } from '../../Resource'
+import {
+  BatchOfferRequest,
+  CreateBatchOfferRequest,
+  CreateBatchOfferRequestResponse,
+  CreateBatchOfferRequestQueryParameters,
+  DuffelResponse,
+} from '../../types'
+
+/**
+ * To search for flights, you'll need to create an `offer request`.
+ * The batch offer requests endpoint allows you to retrieve orders as soon as they become available.
+ * They function as long-polling resources that you can repeatedly retrieve after creating them, returning whatever offers are available at the time or waiting for more to become available. Batches are expected to be consumed promptly, and as such, batch offer requests expire after one minute. However, offers remain accessible and can be retrieved using the offer request ID as usual.
+ * @class
+ * @link https://duffel.com/docs/api/batch-offer-requests
+ */
+export class BatchOfferRequests extends Resource {
+  /**
+   * Endpoint path
+   */
+  path: string
+
+  constructor(client: Client) {
+    super(client)
+    this.path = 'air/batch_offer_requests'
+  }
+
+  /**
+   * Call this endpoint repeatedly to retrieve all the offers as they become available. The total_batches and remaining_batches properties can be used to estimate the remaining amount of work, although you may receive multiple batches at the same time if multiple batches are available.
+   * Once you get a response with remaining_batches of 0 you can stop requesting the endpoint as there are no more offers coming.
+   * @param {string} id - Duffel's unique identifier for the offer request
+   * @link https:/duffel.com/docs/api/offer-requests/get-offer-request-by-id
+   */
+  public get = async (id: string): Promise<DuffelResponse<BatchOfferRequest>> =>
+    this.request({ method: 'GET', path: `${this.path}/${id}` })
+
+  /**
+   * To search for flights, you'll need to create an `offer request`.
+   * An offer request describes the passengers and where and when they want to travel (in the form of a list of `slices`).
+   * It may also include additional filters (e.g. a particular cabin to travel in).
+   * Batch offer requests are a mechanism for retrieving offers as they become available, instead of waiting for the entire offer payload to finish processing.
+   * They function as long-polling resources that you can repeatedly retrieve after creating them, returning whatever offers are available at the time or waiting for more to become available. Batches are expected to be consumed promptly, and as such, batch offer requests expire after one minute.
+   * However, offers remain accessible and can be retrieved using the offer request ID as usual.
+   * @param {Object} [options] - the parameters for making an offer requests (required: slices, passengers; optional: cabin_class)
+   * @link https://duffel.com/docs/api/v2/batch-offer-requests/create-batch-offer-request
+   */
+  public create = async <
+    QueryParams extends CreateBatchOfferRequestQueryParameters,
+  >(
+    options: CreateBatchOfferRequest & QueryParams,
+  ): Promise<DuffelResponse<CreateBatchOfferRequestResponse>> => {
+    const { supplier_timeout, ...data } = options
+
+    return this.request({
+      method: 'POST',
+      path: `${this.path}/`,
+      data,
+      params: {
+        ...(supplier_timeout !== undefined &&
+          supplier_timeout !== null && { supplier_timeout }),
+      },
+    })
+  }
+}

src/booking/BatchOfferRequests/BatchOfferRequestsTypes.ts

@@ -0,0 +1,104 @@
+import { CabinClass, Offer } from '../../types'
+
+import {
+  CreateOfferRequestPassenger,
+  CreateOfferRequestSlice,
+  CreateOfferRequestPrivateFare,
+} from '../OfferRequests/OfferRequestsTypes'
+
+export interface BatchOfferRequest {
+  /**
+   * The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) datetime at which the offer request was created
+   */
+  created_at: string
+
+  /**
+   * Duffel's unique identifier for the offer request
+   */
+  id: string
+
+  /**
+   * Whether the offer request was created in live mode. This field will be set to true if the offer request was created in live mode, or false if it was created in test mode.
+   */
+  live_mode: boolean
+
+  /**
+   * A client key to allow the Duffel Ancillaries component to talk to the Duffel API to retrieve information about an offer and its ancillaries. Learn more about how to use this on https://duffel.com/docs/guides/ancillaries-component.
+   */
+  client_key: string
+
+  /**
+   * The total number of batches of offers.
+   */
+  total_batches: number
+
+  /**
+   * The number of batches of offers that are remaining. This can be used with the total_batches to estimate the amount of work remaining. Once this reaches zero, there are no more batches of offers to process.
+   */
+  remaining_batches: number
+
+  /**
+   * The offers related to this batch offer request.
+   */
+  offers: Omit<Offer, 'available_services'>[]
+}
+
+export type CreateBatchOfferRequestResponse = Omit<BatchOfferRequest, 'offers'>
+
+export interface CreateBatchOfferRequest {
+  /**
+   * The cabin that the passengers want to travel in.
+   */
+  cabin_class?: CabinClass
+
+  /**
+   * 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.
+   */
+  max_connections?: 0 | 1 | 2
+
+  /**
+   * 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.
+   */
+  passengers: CreateOfferRequestPassenger[]
+
+  /**
+   * 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.
+   */
+  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: CreateOfferRequestSlice[]
+}
+
+export interface CreateBatchOfferRequestQueryParameters {
+  /**
+   * The maximum amount of time in milliseconds to wait for each airline search to complete.
+   * This timeout applies to the response time of the call to the airline and includes
+   * some additional overhead added by Duffel. Value should be between `2` seconds and `60` seconds.
+   * Any values outside the range will be ignored and the default supplier_timeout will be used.
+   * If a value is set, the response will only include offers from airline searches that completed
+   * within the given time. If a value is not set, the response will only include offers from
+   * airline searches that completed within the default supplier_timeout value of 20 seconds.
+   * We recommend setting supplier_timeout lower than the timeout on the HTTP request you send to
+   * Duffel API as that will allow us to respond with the offers we received before your request
+   * times out with an empty response.
+   */
+  supplier_timeout?: number
+}

src/booking/BatchOfferRequests/index.ts

@@ -0,0 +1 @@
+export * from './BatchOfferRequests'

src/booking/BatchOfferRequests/mockBatchOfferRequest.ts

@@ -0,0 +1,47 @@
+import { mockOffer } from '../Offers/mockOffer'
+import {
+  CreateBatchOfferRequest,
+  CreateBatchOfferRequestResponse,
+  BatchOfferRequest,
+} from '../../types'
+
+export const mockCreateBatchOfferRequest: CreateBatchOfferRequest = {
+  slices: [
+    {
+      origin: 'LHR',
+      destination: 'JFK',
+      departure_date: '2020-04-24',
+      arrival_time: null,
+      departure_time: null,
+    },
+  ],
+  passengers: [
+    {
+      type: 'adult',
+    },
+    {
+      age: 14,
+    },
+  ],
+  cabin_class: 'economy',
+  max_connections: 1,
+}
+
+export const mockBatchOfferRequest: BatchOfferRequest = {
+  total_batches: 2,
+  remaining_batches: 1,
+  offers: [mockOffer],
+  live_mode: false,
+  id: 'orq_00009hjdomFOCJyxHG7k7k',
+  created_at: '2020-02-12T15:21:01.927Z',
+  client_key: 'example_client_key',
+}
+
+export const mocCreatedBatchOfferRequest: CreateBatchOfferRequestResponse = {
+  total_batches: 2,
+  remaining_batches: 2,
+  live_mode: false,
+  id: 'orq_00009hjdomFOCJyxHG7k7k',
+  created_at: '2020-02-12T15:21:01.927Z',
+  client_key: 'example_client_key',
+}

src/booking/index.ts

@@ -1,5 +1,6 @@
 export * from './AirlineInitiatedChanges'
 export * from './Identity'
+export * from './BatchOfferRequests'
 export * from './OfferRequests'
 export * from './Offers'
 export * from './OrderCancellations'

src/index.ts

@@ -1,5 +1,6 @@
 import { PaymentIntents } from './DuffelPayments'
 import {
+  BatchOfferRequests,
   OfferRequests,
   Offers,
   OrderCancellations,
@@ -29,6 +30,7 @@ export interface DuffelAPIClient {
   aircraft: Aircraft
   airlines: Airlines
   airports: Airports
+  batchOfferRequests: BatchOfferRequests
   offers: Offers
   offerRequests: OfferRequests
   orders: Orders
@@ -48,6 +50,7 @@ export class Duffel {
   public airlines: Airlines
   public airports: Airports
   public links: Sessions
+  public batchOfferRequests: BatchOfferRequests
   public offerRequests: OfferRequests
   public offers: Offers
   public orders: Orders
@@ -77,6 +80,7 @@ export class Duffel {
     this.airports = new Airports(this.client)
     this.airlineInitiatedChanges = new AirlineInitiatedChanges(this.client)
     this.links = new Sessions(this.client)
+    this.batchOfferRequests = new BatchOfferRequests(this.client)
     this.offerRequests = new OfferRequests(this.client)
     this.offers = new Offers(this.client)
     this.orders = new Orders(this.client)

src/types/index.ts

@@ -3,6 +3,7 @@ export * from '../Places/Suggestions/SuggestionsType'
 export * from '../Stays/StaysTypes'
 export * from '../booking/AirlineInitiatedChanges/AirlineInitiatedChangesTypes'
 export * from '../booking/OfferRequests/OfferRequestsTypes'
+export * from '../booking/BatchOfferRequests/BatchOfferRequestsTypes'
 export * from '../booking/Offers/OfferTypes'
 export * from '../booking/OrderCancellations/OrderCancellationsTypes'
 export * from '../booking/OrderChangeOffers/OrderChangeOfferTypes'