ti2-tourplan 1.0.121 → 1.0.123

package/README.md

@@ -39,3 +39,69 @@ TL;DR Here's what the license entails:
 7. Any modifications of this code base MUST be distributed with the same license, GPLv3.
 8. This software is provided without warranty.
 9. The software author or license can not be held liable for any damages inflicted by the software.
+
+## Cancel Booking (HostConnect)
+
+This plugin cancels bookings using `CancelServicesRequest` (not `CancelBookingRequest`).
+
+### HostConnect XML Request
+
+```xml
+<Request>
+  <CancelServicesRequest>
+    <AgentID>YOUR_AGENT_ID</AgentID>
+    <Password>YOUR_AGENT_PASSWORD</Password>
+    <BookingId>14226</BookingId>
+    <ReturnBooking>Y</ReturnBooking>
+  </CancelServicesRequest>
+</Request>
+```
+
+Equivalent curl:
+
+```bash
+curl --location 'https://<HOSTCONNECT_ENDPOINT>/api/hostConnectApi' \
+--header 'Content-Type: application/xml; charset=utf-8' \
+--header 'requestId: <uuid>' \
+--header 'Accept: application/xml' \
+--data '<Request>
+  <CancelServicesRequest>
+    <AgentID>YOUR_AGENT_ID</AgentID>
+    <Password>YOUR_AGENT_PASSWORD</Password>
+    <BookingId>14226</BookingId>
+    <ReturnBooking>Y</ReturnBooking>
+  </CancelServicesRequest>
+</Request>'
+```
+
+### HostConnect XML Response (example)
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE Reply SYSTEM "hostConnect_5_05_010.dtd">
+<Reply>
+  <CancelServicesReply>
+    <BookingId>14226</BookingId>
+    <Ref>A2IN111975</Ref>
+    <ServiceStatuses>
+      <ServiceStatus>
+        <ServiceLineId>61738</ServiceLineId>
+        <Date>2026-07-03</Date>
+        <SequenceNumber>10</SequenceNumber>
+        <Status>XX</Status>
+      </ServiceStatus>
+    </ServiceStatuses>
+  </CancelServicesReply>
+</Reply>
+```
+
+### Plugin Return Shape
+
+The plugin returns both:
+
+- `cancelServicesReply`: raw parsed `CancelServicesReply` object
+- `cancellation`: normalized object
+  - `id`: from `BookingId`
+  - `status`: aggregate over all `ServiceStatus.Status` values:
+    - same status on all lines => that status (e.g. `XX`)
+    - mixed line statuses => `MIXED`

package/availability/itinerary-availability-helper.js

@@ -140,6 +140,54 @@ const getDaysInYear = dateString => {
   const year = moment(dateString).year();
   return moment([year]).isLeapYear() ? 366 : 365;
 };
+
+/*
+  Option Availability Integer List (OptAvail)
+  This is a list of integers that represent the availability of the option for
+  each day in the requested date range.
+  The integers are to be interpreted as follows:
+  Greater than 0 means that inventory is available, with the integer specifying
+  the number of units available.
+  For options with a service type of Y , the inventory is in units of rooms.
+  For other service types, the inventory is in units of pax.
+  -1 Not available.
+  -2 Available on free sell.
+  -3 Available on request.
+  Note: A return value of 0 or something less than -3 is impossible.
+*/
+const getAvailabilityOnly = async ({
+  optionId,
+  hostConnectEndpoint,
+  hostConnectAgentID,
+  hostConnectAgentPassword,
+  axios,
+  startDate,
+  requestedEndDate,
+  callTourplan,
+}) => {
+  const isValidRequestedEndDate = moment(requestedEndDate, 'YYYY-MM-DD', true).isValid();
+  const dateTo = isValidRequestedEndDate
+    ? requestedEndDate
+    : moment(startDate).add(1, 'year').subtract(1, 'day').format('YYYY-MM-DD');
+  const model = {
+    OptionInfoRequest: {
+      Opt: optionId,
+      Info: 'AD',
+      AgentID: hostConnectAgentID,
+      Password: hostConnectAgentPassword,
+      DateFrom: startDate,
+      DateTo: dateTo,
+      ACache: 'N',
+    },
+  };
+  const replyObj = await callTourplan({
+    model,
+    endpoint: hostConnectEndpoint,
+    axios,
+    xmlOptions: hostConnectXmlOptions,
+  });
+  return R.pathOr([], ['OptionInfoReply', 'Option', 'OptAvail'], replyObj);
+};
 /*
     Get general option information from Tourplan API.
 
@@ -1327,6 +1375,7 @@ const findNextValidDate = (startDate, dateRanges) => {
 
 module.exports = {
   getAgentCurrencyCode,
+  getAvailabilityOnly,
   getAvailabilityConfig,
   getNoRatesAvailableError,
   getStayResults,

package/availability/itinerary-availability.js

@@ -18,6 +18,7 @@ const {
 } = require('./itinerary-availability-helper');
 
 const {
+  getAvailabilityOnly,
   getAvailabilityConfig,
   getNoRatesAvailableError,
   getStayResults,
@@ -86,6 +87,28 @@ const returnEmptyRatesOrError = (allowSendingServicesWithoutARate, agentCurrency
   };
 };
 
+const getOptAvailValues = optAvail => {
+  if (Array.isArray(optAvail)) {
+    return optAvail
+      .map(value => Number(value))
+      .filter(value => !Number.isNaN(value));
+  }
+
+  if (typeof optAvail === 'string') {
+    return optAvail
+      .trim()
+      .split(/\s+/)
+      .map(value => Number(value))
+      .filter(value => !Number.isNaN(value));
+  }
+
+  return [];
+};
+
+const isOptAvailBookable = optAvailValues => (
+  optAvailValues.some(value => value > 0 || value === -2 || value === -3)
+);
+
 const searchAvailabilityForItinerary = async ({
   axios,
   token: {
@@ -108,6 +131,7 @@ const searchAvailabilityForItinerary = async ({
   payload: {
     optionId,
     startDate,
+    endDate: requestedEndDate,
     /*
     paxConfigs: [{ roomType: 'DB', adults: 2 }, { roomType: 'TW', children: 2 }]
     */
@@ -120,10 +144,38 @@ const searchAvailabilityForItinerary = async ({
     */
     chargeUnitQuantity,
     roomTypeRequired = true,
+    availabilityOnly = false,
   },
   callTourplan,
   cache,
 }) => {
+  const isAvailabilityOnly = availabilityOnly === true;
+
+  if (isAvailabilityOnly) {
+    const availabilityOnlyResponse = await getAvailabilityOnly({
+      optionId,
+      hostConnectEndpoint,
+      hostConnectAgentID,
+      hostConnectAgentPassword,
+      axios,
+      startDate,
+      requestedEndDate,
+      callTourplan,
+    });
+    const optAvailValues = getOptAvailValues(availabilityOnlyResponse);
+    const SCheckPass = isOptAvailBookable(optAvailValues);
+    return {
+      bookable: SCheckPass,
+      type: 'availability',
+      ...(requestedEndDate && SCheckPass ? { endDate: requestedEndDate } : {}),
+      message: SCheckPass
+        ? 'Availability checked successfully'
+        : 'No availability found for the requested range',
+      availability: optAvailValues,
+      rates: [],
+    };
+  }
+
   // Get agent currency code & cache it
   const agentCurrencyCode = await getAgentCurrencyCode({
     hostConnectEndpoint,
@@ -385,7 +437,11 @@ const searchAvailabilityForItinerary = async ({
   if (dateRangesError) {
     if (dateRangesError.message.includes('minimum stay')) {
       // If minimum stay error, return availability with a warning message
-      const { matchingRateSet } = getMatchingRateSet(dateRangeToUse.rateSets, dateRangeToUse.startDate, chargeUnitQuantity);
+      const { matchingRateSet } = getMatchingRateSet(
+        dateRangeToUse.rateSets,
+        dateRangeToUse.startDate,
+        chargeUnitQuantity,
+      );
       minStayRequired = matchingRateSet ? matchingRateSet.minSCU : 0;
       sWarningMsg = MIN_STAY_WARNING_MESSAGE.replace('{minSCU}', minStayRequired);
     } else if (dateRangesError.message.includes('rates are closed')) {

package/availability/itinerary-availability.validation-flags.test.js

@@ -24,6 +24,7 @@ jest.mock('./itinerary-availability-helper', () => ({
     maxPaxPerCharge: null,
   })),
   getNoRatesAvailableError: jest.fn(async () => 'No rates available'),
+  getAvailabilityOnly: jest.fn(async () => '-1 -1 -1'),
   getStayResults: jest.fn(async () => ([{
     RateId: 'R1',
     Currency: 'USD',
@@ -146,4 +147,44 @@ describe('searchAvailabilityForItinerary validation flags', () => {
     expect(result.type).toBe('inventory');
     expect(result.endDate).toBe('2025-04-02');
   });
+
+  it('uses availabilityOnly flow and keeps response shape consistent', async () => {
+    itineraryAvailabilityHelper.getAvailabilityOnly.mockResolvedValueOnce('-1 -2 -1');
+
+    const result = await searchAvailabilityForItinerary({
+      axios: jest.fn(),
+      token: baseToken,
+      payload: { ...basePayload, availabilityOnly: true, endDate: '2025-04-05' },
+      callTourplan: jest.fn(),
+      cache: { getOrExec: async ({ fn, fnParams }) => fn(...fnParams) },
+    });
+
+    expect(itineraryAvailabilityHelper.getAvailabilityOnly).toHaveBeenCalledTimes(1);
+    expect(itineraryAvailabilityHelper.getAgentCurrencyCode).not.toHaveBeenCalled();
+    expect(result).toEqual({
+      bookable: true,
+      type: 'availability',
+      endDate: '2025-04-05',
+      message: 'Availability checked successfully',
+      availability: [-1, -2, -1],
+      rates: [],
+    });
+  });
+
+  it('marks availabilityOnly response as not bookable when all days are unavailable', async () => {
+    itineraryAvailabilityHelper.getAvailabilityOnly.mockResolvedValueOnce('-1 -1 -1');
+
+    const result = await searchAvailabilityForItinerary({
+      axios: jest.fn(),
+      token: baseToken,
+      payload: { ...basePayload, availabilityOnly: true, endDate: '2025-04-05' },
+      callTourplan: jest.fn(),
+      cache: { getOrExec: async ({ fn, fnParams }) => fn(...fnParams) },
+    });
+
+    expect(result.bookable).toBe(false);
+    expect(result.message).toBe('No availability found for the requested range');
+    expect(result.availability).toEqual([-1, -1, -1]);
+    expect(result.rates).toEqual([]);
+  });
 });

package/index.js

@@ -10,6 +10,7 @@ const Normalizer = require('./normalizer');
 
 const { searchAvailabilityForItinerary } = require('./availability/itinerary-availability');
 const { addServiceToItinerary } = require('./itinerary-add-service');
+const { cancelBooking } = require('./itinerary-cancel-booking');
 const { searchProductsForItinerary } = require('./itinerary-products-search');
 const { searchItineraries } = require('./itinerary-search');
 const { hostConnectXmlOptions } = require('./utils');
@@ -679,6 +680,19 @@ class BuyerPlugin {
     });
   }
 
+  async cancelBooking({
+    axios,
+    token,
+    payload,
+  }) {
+    return cancelBooking({
+      axios,
+      token,
+      payload,
+      callTourplan: this.callTourplan.bind(this),
+    });
+  }
+
   async searchItineraries({
     axios,
     typeDefsAndQueries,

package/index.test.js

@@ -132,6 +132,149 @@ describe('search tests', () => {
         }
       });
     });
+    describe('cancelBooking', () => {
+      it('cancels a booking by id', async () => {
+        mockCallTourplan.mockImplementationOnce(async () => ({
+          CancelServicesReply: {
+            BookingId: '316559',
+            Ref: 'A2IN111975',
+            ServiceStatuses: {
+              ServiceStatus: {
+                ServiceLineId: '61738',
+                Date: '2026-07-03',
+                SequenceNumber: '10',
+                Status: 'XX',
+              },
+            },
+          },
+        }));
+        const retVal = await app.cancelBooking({
+          axios,
+          token,
+          payload: {
+            id: '316559',
+            status: 'Cancelled',
+            clicked: 1719571452,
+          },
+        });
+        expect(mockCallTourplan).toHaveBeenNthCalledWith(1, expect.objectContaining({
+          model: {
+            CancelServicesRequest: expect.objectContaining({
+              BookingId: '316559',
+              ReturnBooking: 'Y',
+            }),
+          },
+        }));
+        expect(retVal).toEqual({
+          cancelServicesReply: {
+            BookingId: '316559',
+            Ref: 'A2IN111975',
+            ServiceStatuses: {
+              ServiceStatus: {
+                ServiceLineId: '61738',
+                Date: '2026-07-03',
+                SequenceNumber: '10',
+                Status: 'XX',
+              },
+            },
+          },
+          cancellation: {
+            id: '316559',
+            status: 'XX',
+          },
+        });
+      });
+
+      it('cancels a booking by ref', async () => {
+        mockCallTourplan.mockImplementationOnce(async () => ({
+          CancelServicesReply: {
+            BookingId: '316559',
+            ServiceStatuses: {
+              ServiceStatus: [{
+                ServiceLineId: '61738',
+                Status: 'XX',
+              }],
+            },
+          },
+        }));
+        const retVal = await app.cancelBooking({
+          axios,
+          token,
+          payload: {
+            ref: 'ALFI393706',
+            status: 'Cancelled',
+            clicked: 1719571452,
+          },
+        });
+        expect(mockCallTourplan).toHaveBeenNthCalledWith(1, expect.objectContaining({
+          model: {
+            CancelServicesRequest: expect.objectContaining({
+              Ref: 'ALFI393706',
+              ReturnBooking: 'Y',
+            }),
+          },
+        }));
+        expect(retVal).toEqual({
+          cancelServicesReply: {
+            BookingId: '316559',
+            ServiceStatuses: {
+              ServiceStatus: [{
+                ServiceLineId: '61738',
+                Status: 'XX',
+              }],
+            },
+          },
+          cancellation: {
+            id: '316559',
+            status: 'XX',
+          },
+        });
+      });
+
+      it('returns MIXED status when service statuses differ', async () => {
+        mockCallTourplan.mockImplementationOnce(async () => ({
+          CancelServicesReply: {
+            BookingId: '316559',
+            ServiceStatuses: {
+              ServiceStatus: [{
+                ServiceLineId: '61738',
+                Status: 'XX',
+              }, {
+                ServiceLineId: '61739',
+                Status: 'RQ',
+              }],
+            },
+          },
+        }));
+        const retVal = await app.cancelBooking({
+          axios,
+          token,
+          payload: {
+            bookingId: '316559',
+            status: 'Cancelled',
+            clicked: 1719571452,
+          },
+        });
+        expect(retVal).toEqual({
+          cancelServicesReply: {
+            BookingId: '316559',
+            ServiceStatuses: {
+              ServiceStatus: [{
+                ServiceLineId: '61738',
+                Status: 'XX',
+              }, {
+                ServiceLineId: '61739',
+                Status: 'RQ',
+              }],
+            },
+          },
+          cancellation: {
+            id: '316559',
+            status: 'MIXED',
+          },
+        });
+      });
+    });
     describe('template tests', () => {
       let template;
       it('get the template', async () => {

package/itinerary-cancel-booking.js

@@ -0,0 +1,110 @@
+const assert = require('assert');
+const R = require('ramda');
+const {
+  hostConnectXmlOptions,
+  escapeInvalidXmlChars,
+} = require('./utils');
+
+const getIdentifier = payload => {
+  const bookingId = payload.bookingId || payload.id;
+  if (bookingId) {
+    return {
+      field: 'BookingId',
+      value: String(bookingId),
+    };
+  }
+  const bookingRef = payload.ref || payload.reference;
+  if (bookingRef) {
+    return {
+      field: 'Ref',
+      value: escapeInvalidXmlChars(String(bookingRef)),
+    };
+  }
+  return null;
+};
+
+const extractCancellationReply = replyObj => (
+  R.path(['CancelServicesReply'], replyObj)
+  || {}
+);
+
+const getServiceStatusList = cancellationReply => {
+  let serviceStatuses = R.pathOr([], ['ServiceStatuses', 'ServiceStatus'], cancellationReply);
+  if (!Array.isArray(serviceStatuses)) serviceStatuses = [serviceStatuses];
+  return serviceStatuses
+    .map(serviceStatus => R.path(['Status'], serviceStatus))
+    .filter(Boolean)
+    .map(status => String(status).toUpperCase());
+};
+
+const getAggregateServiceStatus = cancellationReply => {
+  const statuses = getServiceStatusList(cancellationReply);
+  if (!statuses.length) return null;
+  const uniqueStatuses = [...new Set(statuses)];
+  if (uniqueStatuses.length === 1) return uniqueStatuses[0];
+  return 'MIXED';
+};
+
+const normalizeCancellationResponse = (replyObj, payload, identifier) => {
+  const cancellationReply = extractCancellationReply(replyObj);
+  const aggregateServiceStatus = getAggregateServiceStatus(cancellationReply);
+  return {
+    cancelServicesReply: cancellationReply,
+    cancellation: {
+      id: R.path(['BookingId'], cancellationReply) || identifier.value,
+      status: aggregateServiceStatus
+        || R.path(['BookingStatus'], cancellationReply)
+        || R.path(['Status'], cancellationReply)
+        || payload.status
+        || 'Cancelled',
+    },
+  };
+};
+
+/**
+ * Cancels a booking by id or reference
+ * @param {Object} params - The parameters for the cancellation
+ * @param {Object} params.axios - The axios instance
+ * @param {Object} params.token - The token for the cancellation
+ * @param {Object} params.payload - The payload for the cancellation
+ * @param {Object} params.callTourplan - The callTourplan function
+ * @returns {Promise<Object>} The cancellation response
+ */
+const cancelBooking = async ({
+  axios,
+  token: {
+    hostConnectEndpoint,
+    hostConnectAgentID,
+    hostConnectAgentPassword,
+  },
+  payload = {},
+  callTourplan,
+}) => {
+  assert(hostConnectEndpoint, 'Must provide token.hostConnectEndpoint for booking cancellation');
+  assert(hostConnectAgentID, 'Must provide token.hostConnectAgentID for booking cancellation');
+  assert(hostConnectAgentPassword, 'Must provide token.hostConnectAgentPassword for booking cancellation');
+  const identifier = getIdentifier(payload);
+  assert(identifier, 'Must provide booking id or reference for cancellation');
+
+  const baseRequest = {
+    AgentID: hostConnectAgentID,
+    Password: hostConnectAgentPassword,
+    [identifier.field]: identifier.value,
+  };
+  const replyObj = await callTourplan({
+    model: {
+      CancelServicesRequest: {
+        ...baseRequest,
+        ReturnBooking: 'Y',
+      },
+    },
+    endpoint: hostConnectEndpoint,
+    axios,
+    xmlOptions: hostConnectXmlOptions,
+  });
+  return normalizeCancellationResponse(replyObj, payload, identifier);
+};
+
+module.exports = {
+  cancelBooking,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ti2-tourplan",
-  "version": "1.0.121",
+  "version": "1.0.123",
   "description": "Tourplan's TI2 Plugin",
   "main": "index.js",
   "scripts": {