ti2 1.0.80 → 1.0.82

package/.cursorignore

@@ -0,0 +1 @@
+# Add directories or file patterns to ignore during indexing (e.g. foo/ or *.csv)

package/README.md

@@ -33,29 +33,36 @@ Plugins are the connectores to other systems and/or features you intent to use;
 
 ### Plugin Library
 
-| Methods | [Ventrata](https://github.com/TourConnect/ti2-ventrata) | [TravelGateX](https://github.com/TourConnect/ti2-travelgate) | [Didgigo](https://github.com/TourConnect/ti2-didgigo) | [TourConnect](https://github.com/TourConnect/ti2-tourconnect)
-| ---- | -------- | ---------- | ---- | ---- |
+| Methods | FareHarbor | PeekPro| Zaui | Xola |[Ventrata](https://github.com/TourConnect/ti2-ventrata) | [TravelGateX](https://github.com/TourConnect/ti2-travelgate) | [Didgigo](https://github.com/TourConnect/ti2-didgigo) | [TourConnect](https://github.com/TourConnect/ti2-tourconnect) | TourPlan |
+| ---- | -------- | ---------- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
 |**Base**|
-|validateToken|||✓|✓|
-|copyMedia||||✓|
+|validateToken|✓|✓|✓|✓|✓|✓|✓|✓|✓|
+|tokenTemplate|✓|✓|✓|✓|✓|✓|✓|✓|✓|
 |**Content**|
-|getProfile|||✓|✓|
-|updateProfile||||✓|
-|getLocations|||✓|✓|
-|getLocation|||✓|✓|
-|createLocation|||✓|✓|
-|updateLocation|||✓|✓|
-|getProducts|||✓|✓|
-|getProduct|||✓|✓|
-|createProduct|||✓|✓|
-|updateProduct|||✓|✓|
+|copyMedia||||||||✓|
+|getProfile|||||||✓|✓|
+|updateProfile||||||||✓|
+|getLocations|||||||✓|✓|
+|getLocation|||||||✓|✓|
+|createLocation|||||||✓|✓|
+|updateLocation|||||||✓|✓|
+|getProducts|||||||✓|✓|
+|getProduct|||||||✓|✓|
+|createProduct|||||||✓|✓|
+|updateProduct|||||||✓|✓|
 |**Bookings**|
-|searchProducts|✓|✓|
-|searchBooking|✓|✓|
-|searchAvailability|✓|✓|
-|searchQuote|✓|✓|
-|createBooking|✓|✓|
-|cancelBooking|✓|✓|
+|searchProducts|✓|✓|✓|✓|✓|✓|
+|searchBooking|✓|✓|✓|✓|✓|✓|
+|searchAvailability|✓|✓|✓|✓|✓|✓|
+|searchQuote|✓|✓|✓|✓|✓|✓|
+|createBooking|✓|✓|✓|✓|✓|✓|
+|cancelBooking|✓|✓|✓|✓|✓|✓|
+|searchProductsForItinerary|||||||||✓|
+|searchAvailabilityForItinerary|||||||||✓|
+|addServiceToItinerary|||||||||✓|
+|getCreateItineraryFields|||||||||✓|
+|searchItineraries|||||||||✓|
+|queryAllotment|||||||||✓|
 
 ## Contributing
 

package/controllers/app.js

@@ -466,7 +466,7 @@ const getAppToken = async (req, res, next) => {
     },
   });
   if (!userAppKey) {
-    return next({ status: 404, message: 'User integratio is not found' });
+    return next({ status: 404, message: `User integratio is not found for ${integrationId}:${userId}:${hint}` });
   }
   return res.json({ token: await userAppKey.token });
 };

package/controllers/bookings.js

@@ -6,6 +6,8 @@ const { typeDefs: availTypeDefs, query: availQuery } = require('./graphql-schema
 const { typeDefs: bookingTypeDefs, query: bookingQuery } = require('./graphql-schemas/booking');
 const { typeDefs: rateTypeDefs, query: rateQuery } = require('./graphql-schemas/rate');
 const { typeDefs: pickupTypeDefs, query: pickupQuery } = require('./graphql-schemas/pickup-point');
+const { typeDefs: itineraryProductTypeDefs, query: itineraryProductQuery } = require('./graphql-schemas/itinerary-product');
+const { typeDefs: itineraryBookingTypeDefs, query: itineraryBookingQuery } = require('./graphql-schemas/itinerary-booking');
 
 const typeDefsAndQueries = {
   productTypeDefs,
@@ -18,6 +20,10 @@ const typeDefsAndQueries = {
   rateQuery,
   pickupTypeDefs,
   pickupQuery,
+  itineraryProductTypeDefs,
+  itineraryProductQuery,
+  itineraryBookingTypeDefs,
+  itineraryBookingQuery,
 };
 
 const bookingsSearch = plugins => async (req, res, next) => {
@@ -37,8 +43,8 @@ const bookingsSearch = plugins => async (req, res, next) => {
     });
     assert(userAppKeys, 'could not find the app key');
     const token = await userAppKeys.token;
-    assert(app.searchHotelBooking || app.searchBooking, `searchHotelBooking or searchBooking is not available for ${appKey}`);
-    const search = (app.searchHotelBooking || app.searchBooking).bind(app);
+    assert(app.searchItineraries || app.searchHotelBooking || app.searchBooking, `searchItineraries or searchHotelBooking or searchBooking is not available for ${appKey}`);
+    const search = (app.searchHotelBooking || app.searchBooking || app.searchItineraries).bind(app);
     const results = await search({
       axios,
       token,
@@ -102,7 +108,8 @@ const $bookingsProductSearch = plugins => async ({
   }));
   assert(userAppKeys, 'could not find the app key');
   const token = await userAppKeys.token;
-  const results = await app.searchProducts({
+  const func = (app.searchProducts || app.searchProductsForItinerary).bind(app);
+  const results = await func({
     axios,
     token,
     payload,
@@ -182,7 +189,8 @@ const bookingsAvailabilitySearch = plugins => async (req, res, next) => {
     }));
     assert(userAppKeys, 'could not find the app key');
     const token = await userAppKeys.token;
-    const results = await app.searchAvailability({
+    const func = (app.searchAvailability || app.searchAvailabilityForItinerary).bind(app);
+    const results = await func({
       axios,
       token,
       payload,
@@ -292,8 +300,8 @@ const createBooking = plugins => async (req, res, next) => {
     }));
     assert(userAppKeys, 'could not find the app key');
     const token = await userAppKeys.token;
-    assert(payload.id, 'the quote id is required');
-    const results = await app.createBooking({
+    const func = (app.createBooking || app.addServiceToItinerary).bind(app);
+    const results = await func({
       axios,
       token,
       payload,
@@ -418,8 +426,9 @@ const getCreateBookingFields = plugins => async (req, res, next) => {
     }));
     assert(userAppKeys, 'could not find the app key');
     const token = await userAppKeys.token;
-    assert(app.getCreateBookingFields, `getCreateBookingFields is not available for ${appKey}`);
-    const results = await app.getCreateBookingFields({
+    assert(app.getCreateBookingFields || app.getCreateItineraryFields, `getCreateBookingFields or getCreateItineraryFields is not available for ${appKey}`);
+    const func = (app.getCreateItineraryFields || app.getCreateBookingFields).bind(app);
+    const results = await func({
       axios,
       token,
       payload,

package/controllers/graphql-schemas/itinerary-booking.js

@@ -0,0 +1,94 @@
+const typeDefs = `
+  type Passenger {
+    firstName: String!
+    lastName: String!
+    passengerType: String!
+    age: Int
+    dob: String
+    personId: String
+  }
+
+  type PaxConfig {
+    roomType: String
+    adults: Int
+    children: Int
+    infants: Int
+    passengers: [Passenger]
+  }
+
+  type ServiceLine {
+    serviceLineId: ID!
+    optionId: String!
+    optionName: String
+    linePrice: String
+    quantity: Int
+    startDate: String!
+    supplierName: String
+    supplierId: String
+    paxList: [Passenger]
+    paxConfigs: [PaxConfig]
+  }
+
+  type Query {
+    bookingId: ID!
+    name: String!
+    bookingStatus: String!
+    ref: String!
+    agentRef: String
+    totalPrice: String!
+    travelDate: String!
+    enteredDate: String!
+    canEdit: Boolean!
+    serviceLines: [ServiceLine]!
+  }
+`;
+
+const query = `{
+  name
+  bookingId
+  bookingStatus
+  ref
+  agentRef
+  totalPrice
+  travelDate
+  enteredDate
+  canEdit
+  serviceLines {
+    serviceLineId
+    linePrice
+    quantity
+    optionId
+    optionName
+    supplierId
+    supplierName
+    supplierId
+    startDate
+    paxConfigs {
+      roomType
+      adults
+      children
+      infants
+      passengers {
+        firstName
+        lastName
+        passengerType
+        age
+        dob
+        personId
+      }
+    }
+    paxList {
+      firstName
+      lastName
+      passengerType
+      age
+      dob
+      personId
+    }
+  }
+}`;
+
+module.exports = {
+  typeDefs,
+  query,
+};

package/controllers/graphql-schemas/itinerary-product.js

@@ -0,0 +1,135 @@
+const typeDefs = `
+
+  type Extra {
+    id: ID!
+    name: String!
+    chargeBasis: String
+    isCompulsory: Boolean
+    isPricePerPerson: Boolean
+  }
+
+  type UnitRestriction {
+    allowed: Boolean
+    minAge: Int
+    maxAge: Int
+    maxPax: Int
+    maxAdults: Int
+  }
+
+  type OptionRestrictions {
+    roomTypeRequired: Boolean
+    Adult: UnitRestriction
+    Child: UnitRestriction
+    Infant: UnitRestriction
+    Single: UnitRestriction
+    Double: UnitRestriction
+    Twin: UnitRestriction
+    Triple: UnitRestriction
+    Quad: UnitRestriction
+  }
+
+  type ProductUnit {
+    unitId: ID!
+    unitName: String!
+    restrictions: UnitRestriction
+  }
+
+  type ProductOption {
+    optionId: ID!
+    optionName: String!
+    lastUpdateTimestamp: Int
+    serviceType: String
+    extras: [Extra]
+    units: [ProductUnit]
+    restrictions: OptionRestrictions
+  }
+
+  type Query {
+    productId: ID!
+    productName: String!
+    address: String
+    description: String
+    serviceTypes: [String]
+    options: [ProductOption]
+  }
+`;
+
+const query = `{
+  productId
+  productName
+  description
+  serviceTypes
+  address
+  options {
+    optionId
+    optionName
+    lastUpdateTimestamp
+    serviceType
+    extras {
+      id
+      name
+      chargeBasis
+      isCompulsory
+      isPricePerPerson
+    }
+    units {
+      unitId
+      unitName
+      restrictions {
+        allowed
+        minAge
+        maxAge
+        maxPax
+        maxAdults
+      }
+    }
+    restrictions {
+      roomTypeRequired
+      Adult {
+        allowed
+        minAge
+        maxAge
+      }
+      Child {
+        allowed
+        minAge
+        maxAge
+      }
+      Infant {
+        allowed
+        minAge
+        maxAge
+      }
+      Single {
+        allowed
+        maxPax
+        maxAdults
+      }
+      Double {
+        allowed
+        maxPax
+        maxAdults
+      }
+      Twin {
+        allowed
+        maxPax
+        maxAdults
+      }
+      Triple {
+        allowed
+        maxPax
+        maxAdults
+      }
+      Quad {
+        allowed
+        maxPax
+        maxAdults
+      }
+    }
+  }
+}`;
+
+module.exports = {
+  typeDefs,
+  query,
+};

package/index.js

@@ -270,7 +270,8 @@ module.exports = async ({
         ];
         const body = req.customBody;
         if (cachingOperations.indexOf(body.operationId) > -1) {
-          const cacheKey = hash(R.omit(['requestId', 'date'], body));
+          const cacheBody = R.omit(['requestId', 'date'], body);
+          const cacheKey = hash(cacheBody);
           req.cacheKey = cacheKey;
           const foundCache = await cache.get({
             pluginName: body.params.appKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ti2",
-  "version": "1.0.80",
+  "version": "1.0.82",
   "description": "Tourist Industry Exchange (TI2)",
   "main": "index.js",
   "scripts": {

package/test/plugin.js

@@ -54,7 +54,36 @@ class Plugin {
     });
     this.searchQuote = jestPlugin.fn(() => ({ quote: [{ id: chance.guid() }] }));
     this.createBooking = jestPlugin.fn(() => {});
-    this.queryAllotment = jestPlugin.fn(async (args) => {
+    this.searchItineraries = jestPlugin.fn(() => ({ bookings: [] }));
+    this.searchProductsForItinerary = jestPlugin.fn(() => ({ products: [] }));
+    this.searchAvailabilityForItinerary = jestPlugin.fn(({
+      token,
+      payload: {
+        optionId,
+        startDate,
+        paxConfigs,
+      },
+    }) => {
+      expect(token).toBeTruthy();
+      expect(optionId).toBeTruthy();
+      expect(startDate).toBeTruthy();
+      expect(paxConfigs).toBeTruthy();
+      return { bookable: true, rates: [{ rateId: 'Default' }] };
+    });
+    this.getCreateItineraryFields = jestPlugin.fn(() => ({
+      customFields: [],
+    }));
+    this.addServiceToItinerary = jestPlugin.fn(() => ({
+      message: '',
+      booking: {
+        id: chance.guid(),
+        reference: chance.guid(),
+        linePrice: chance.guid(),
+        lineId: chance.guid(),
+      },
+    }));
+
+    this.queryAllotment = jestPlugin.fn(async args => {
       const {
         axios,
         payload,
@@ -65,7 +94,7 @@ class Plugin {
       if (payload.keyPath === 'errorGeneral') {
         await axios.get('http://www.example.com');
       }
-      return { allotments: [] }
+      return { allotments: [] };
     });
     this.tokenTemplate = jestPlugin.fn(() => ({
       apiKey: {
@@ -443,7 +472,7 @@ class Plugin {
    * @returns {object} retVal - the return object
    * @returns {Availability[]} retVal.availability - Array of availability objects
    */
-  availabilityCalndar() {
+  availabilityCalendar() {
     // return (args);
   }
 
@@ -479,6 +508,219 @@ class Plugin {
    */
   createBooking() {}
 
+  /**
+   * @typedef {Object} Passenger
+   * @property {string} firstName - Passenger first name
+   * @property {string} lastName - Passenger last name
+   * @property {PassengerType} passengerType - Passenger type
+   * @property {number} [age] - Passenger age
+   * @property {string} [dob] - Date of birth (YYYY-MM-DD)
+   * @property {string} [personId] - Unique identifier for the passenger
+   */
+
+  /**
+   * @typedef {('Single'|'Double'|'Twin'|'Triple'|'Quad'|'Other')} RoomType
+   */
+
+  /**
+   * @typedef {('Adult'|'Child'|'Infant')} PassengerType
+   */
+
+  /**
+   * @typedef {Object} PaxConfig - At least one of adults, children or infants must be provided
+   * @property {RoomType} [roomType] - Room type
+   * @property {number} [adults] - Number of adults
+   * @property {number} [children] - Number of children
+   * @property {number} [infants] - Number of infants
+   * @property {Array<Passenger>} [passengers] - List of passengers for this pax config
+   */
+
+  /**
+   * @typedef {Object} PUDOInfo
+   * @property {string} [time] - Travel time
+   * @property {string} [location] - Location details
+   * @property {string} [flightDetails] - Flight information
+   */
+
+
+  // ItineraryProduct Related Types
+  /**
+   * @typedef {Object} ItineraryProductUnit
+   * @property {RoomType|PassengerType} unitId - Unit identifier for Accommodation products, allowed values: 'Single', 'Double', 'Twin', 'Triple', 'Quad'; for Activity products, allowed values: 'Adult', 'Child', 'Infant'
+   * @property {string} unitName - Unit name, can be the same as unitId
+   * @property {ItineraryUnitRestriction} restrictions - Unit restrictions
+   */
+
+  /**
+   * @typedef {Object} ItineraryUnitRestriction
+   * @property {boolean} allowed - Whether the unit is available
+   * @property {number} [minAge] - Minimum age requirement
+   * @property {number} [maxAge] - Maximum age requirement
+   */
+
+  /**
+   * @typedef {Object} ItineraryProductOption
+   * @property {string} optionId - Option identifier, this identifier should be unique in a sense that it should be able to represent the option and the product. For example, if in your system the option identifier are 1, 2, 3, say the productId is '123', the optionId you provided to us should be something like '123-1' or '123-2' etc.
+   * @property {string} optionName - Option name
+   * @property {number} [lastUpdateTimestamp] - Last update time
+   * @property {string} serviceType - Type of service, one of 'Accommodation', 'Activity', 'Transfer'
+   * @property {Array<Extra>} extras - Extras allowed for this product option
+   * @property {Array<ItineraryProductUnit>} units - Available units
+   * @property {Object} restrictions - Aggregated restrictions of each unit for this product option
+   * @property {boolean} [restrictions.roomTypeRequired] - Whether room type is required, if it's required, our IA tool will check if the roomType in the paxConfigs matches the roomType allowed in the option
+   * @property {ItineraryUnitRestriction} [restrictions.Adult] - restrictions for adult
+   * @property {ItineraryUnitRestriction} [restrictions.Child] - restrictions for child
+   * @property {ItineraryUnitRestriction} [restrictions.Infant] - restrictions for infant
+   * @property {ItineraryUnitRestriction} [restrictions.Single] - restrictions for Single room type
+   * @property {ItineraryUnitRestriction} [restrictions.Double] - restrictions for Double room type
+   * @property {ItineraryUnitRestriction} [restrictions.Twin] - restrictions for Twin room type
+   * @property {ItineraryUnitRestriction} [restrictions.Triple] - restrictions for Triple room type
+   * @property {ItineraryUnitRestriction} [restrictions.Quad] - restrictions for Quad room type
+   */
+
+  /**
+   * @typedef {Object} ItineraryProduct - An itinerary product contains two levels: product, option. For accommodation products, the product is the hotel, the option is the room name (Deluxe Room, Ocean View Room, etc). For activity products, the product is the Tour Company, the option is the activity type (e.g. Full Day, Half Day, etc). Specific data examples will be provided in the tutorial page.
+   * @property {string} productId - ItineraryProduct identifier
+   * @property {string} productName - ItineraryProduct name
+   * @property {Array<string>} [serviceTypes] - Types of services offered: ['Accommodation', 'Activity', 'Transfer']
+   * @property {Array<ItineraryProductOption>} options - Available options
+   */
+
+  // Booking Related Types
+  /**
+   * @typedef {Object} CustomFieldValue
+   * @property {string} id - Custom Field identifier
+   * @property {string} value - Field value
+   */
+
+  /**
+   * @typedef {Object} Extra
+   * @property {string} id - Extra identifier
+   * @property {string} name - Extra name
+   */
+
+  /**
+   * @typedef {Object} ItineraryServiceLine
+   * @property {string} serviceLineId - Service line identifier
+   * @property {string} optionId - Option identifier
+   * @property {string} optionName - Option name
+   * @property {string} [supplierName] - Supplier name
+   * @property {string} [supplierId] - Supplier id
+   * @property {string} [linePrice] - Line price
+   * @property {string} [quantity] - Quantity
+   * @property {string} startDate - Start date (YYYY-MM-DD)
+   * @property {Array<PaxConfig>} paxConfigs - List of pax configs for this service line
+   * @property {Array<Passenger>} paxList - List of passengers for this service line
+   */
+
+  /**
+   * @typedef {Object} ItineraryBooking
+   * @property {string} bookingId - Unique booking identifier
+   * @property {string} name - Booking name
+   * @property {string} bookingStatus - Booking status
+   * @property {string} ref - Booking reference
+   * @property {string} agentRef - external booking reference
+   * @property {string} totalPrice - Total price of the booking
+   * @property {string} travelDate - Start Date of travel (YYYY-MM-DD)
+   * @property {string} enteredDate - Date of booking (YYYY-MM-DD)
+   * @property {boolean} canEdit - Whether the booking can be edited
+   * @property {ItineraryServiceLine[]} serviceLines - Booked service lines
+  */
+
+  /**
+   * @typedef {('yes-no'|'short'|'long'|'count'|'extended-option')} CustomFieldTypes
+  /**
+   * @typedef {Object} CreateItineraryCustomField
+   * @property {string} id - Custom Field identifier
+   * @property {string} label - Custom Field label
+   * @property {CustomFieldTypes} type - Custom Field type
+   * @property {boolean} [isPerService] - Whether the custom field is per service, or per entire booking/quote
+   * @property {Array<Object>} [options] - Options if the type is extended-option
+   * @property {Object} options.value - Option value
+   * @property {Object} options.label - Option label
+   */
+
+  /**
+   * Search for bookable products
+   * @async
+   * @param {Object} args
+   * @param {Object} args.token - Authentication token
+   * @param {object} args.payload - Search criteria
+   * @param {string} [args.payload.productId] - Optional specific product to search for
+   * @param {string} [args.payload.optionId] - Optional specific product option to search for
+   * @param {string} [args.payload.searchInput] - Optional text search across all fields
+   * @param {boolean} [args.payload.forceRefresh] - Optional flag to bypass cache
+   * @returns {object} retVal - the return object.
+   * @returns {Array<ItineraryProduct>} retVal.products - An array of products spec objects.
+   */
+  searchProductsForItinerary() {}
+
+  /**
+   * @typedef {Object} SearchAvailabilityForItineraryResponse
+   * @property {boolean} bookable - Whether the product is bookable
+   * @property {Array} [rates] - If there are multiple rates, they will be returned in this array
+   * @property {string} rates[].rateId - It's ok if you don't use such a thing as rateId in your internal system, but you can use it to package important information so we can make a booking. For example, you can do jwt.encode({ foo: 'bar' }, secret) and send it to us here, and later when we make a booking, we send the rateId to you so you can decode it and get the foo: 'bar' information.
+   * @property {string} [rates[].externalRateText] - Combined rate description
+   */
+  /**
+   * Search for product availability
+   * @async
+   * @param {Object} args
+   * @param {Object} args.token - Authentication token
+   * @param {object} args.payload - Search criteria
+   * @param {string} args.payload.optionId - ItineraryProduct option ID
+   * @param {string} args.payload.startDate - YYYY-MM-DD format
+   * @param {Array<PaxConfig>} args.payload.paxConfigs - Required for room-based products
+   * @param {number} [args.payload.chargeUnitQuantity=1] - Number of units to book
+   * @returns {SearchAvailabilityForItineraryResponse}
+   */
+  searchAvailabilityForItinerary() {}
+
+  /**
+   * @typedef {Object} AddServiceToItineraryResponse
+   * @property {string} message - Error message
+   * @property {object} booking - Booking object
+   * @property {string} booking.id - Booking identifier from your system
+   * @property {string} booking.reference - Reference number from your system
+   * @property {string} booking.linePrice - Price of the booking line
+   * @property {string} booking.lineId - Line identifier from your system
+  */
+  /**
+   * Create an itinerary
+   * @async
+   * @param {Object} args
+   * @param {Object} args.token - Authentication token
+   * @param {object} args.payload - Booking/Quote details
+   * @param {string} args.payload.QB - 'Q' for quote, 'B' for booking
+   * @param {string} args.payload.quoteName - Name of the booking/quote
+   * @param {string} [args.payload.quoteId] - identifier of the booking/quote, if one is provided, we are expecting the service line to be inserted to an existing booking/quote
+   * @param {string} [args.payload.lineId] - identifier of the service line in the booking/quote, if one is provided, we are expecting an existing service line to be updated
+   * @param {string} [args.payload.rateId] - Rate identifier, we are sending 'Default' if no rates are provided by the check availability call
+   * @param {string} args.payload.optionId - Option identifier of the service line
+   * @param {string} args.payload.startDate - Start date always in (YYYY-MM-DD) format
+   * @param {string} [args.payload.reference] - Reference number from external system
+   * @param {Array<PaxConfig>} args.payload.paxConfigs - Passenger configurations
+   * @param {Array<Object>} [args.payload.extras] - Additional extras
+   * @param {Extra} args.payload.extras.selectedExtra - Selected extra
+   * @param {number} args.payload.extras.quantity - quantity
+   * @param {PUDOInfo} [args.payload.puInfo] - Pickup information
+   * @param {PUDOInfo} [args.payload.doInfo] - Dropoff information
+   * @param {string} [args.payload.notes] - Additional notes
+   * @param {Array<CustomFieldValue>} [args.payload.customFieldValues] - Custom field values
+   * @returns {AddServiceToItineraryResponse}
+   */
+  addServiceToItinerary() {}
+
+  /**
+   * Some additional fields available for the addServiceToItinerary call
+   * @async
+   * @param {Object} args
+   * @param {Object} args.token - Authentication token
+   * @returns {object} retVal - the return object.
+   * @returns {Array<CreateItineraryCustomField>} retVal.customFields - An array of custom fields spec objects.
+   */
+  getCreateItineraryFields() {}
+
   /**
    * Allotment Object
   /**
@@ -496,6 +738,23 @@ class Plugin {
    * @property {string[]} keyPaths - An array of key paths generated by combining supplier code and product codes.
    */
 
+  /**
+   * Search for itineraries
+   * @async
+   * @param {Object} args
+   * @param {Object} args.token - Authentication token
+   * @param {object} args.payload - Search criteria
+   * @param {string} args.payload.purchaseDateStart - Start date for purchase search (YYYY-MM-DD)
+   * @param {string} args.payload.purchaseDateEnd - End date for purchase search (YYYY-MM-DD)
+   * @param {string} args.payload.travelDateStart - Start date for travel search (YYYY-MM-DD)
+   * @param {string} args.payload.travelDateEnd - End date for travel search (YYYY-MM-DD)
+   * @param {string} args.payload.name - Search by customer name
+   * @param {string} args.payload.bookingId - Search by booking ID
+   * @returns {object} retVal - the return object.
+   * @returns {Array<ItineraryBooking>} retVal.bookings - An array of itinerary bookings matching search criteria.
+   */
+  searchItineraries() {}
+
   /**
    * Query Allotment
    * @async

package/tutorials/index.json

@@ -4,5 +4,8 @@
     },
     "plugin-development": {
         "title": "Plugin Development"
+    },
+    "itinerary-assist-plugin-dev": {
+        "title": "Itinerary Assist Plugin Tutorial"
     }
 }

package/tutorials/itinerary-assist-plugin-dev.md

@@ -0,0 +1,403 @@
+
+### Important notes:
+   - Required methods:
+      - [searchProductsForItinerary]{@link Plugin#searchProductsForItinerary}
+      - [searchAvailabilityForItinerary]{@link Plugin#searchAvailabilityForItinerary}
+      - [addServiceToItinerary]{@link Plugin#addServiceToItinerary}
+      - [searchItineraries]{@link Plugin#searchItineraries}
+   - Optional methods:
+      - [getCreateItineraryFields]{@link Plugin#getCreateItineraryFields}
+   
+   - If a key in the payload is said to be optional, it may be undefined or null, please handle them accordingly
+   - expected return structure should be exactly as described in the documentation, it's ok to include extra fields in the response, but please note that our IA tool will only handle the fields that are described in the documentation
+   ---
+
+### Existing Itinerary Assist Plugin
+[Tourplan](https://github.com/tourconnect/ti2-tourplan)
+Feel free to use it as a reference for how tests are written and how it handles the authentication and data mapping.
+
+
+### FAQ
+
+1. For searchProductsForItinerary, it says "when we send empty payload, the expected response is the entire list of ACTIVE products". How do I handle pagination if my system has thousands of products? Is there a limit?
+
+We have to get access to the entire list of products, so we can create a vector database for AI to match the extracted text with a service. We recommend using a cache to store the products on your end and refresh it periodically.
+
+2. My booking system uses different terms for passenger types (e.g., "CHD" instead of "Child"). Should I handle this mapping in the plugin, or will Ti2 provide a mapping configuration?
+
+You should handle this mapping in the plugin, as it's specific to your system.
+
+3.  How should I handle currency conversion? My system supports multiple currencies, but I don't see currency fields in the response formats.
+
+It's not required to include currency fields in the response, as the Itinerary Assist tool currently doesn't handle pricing related operations.
+
+4. For real-time availability checks in searchAvailabilityForItinerary, what's the expected response time limit? My booking system might need to query multiple suppliers.
+
+The availbility check is always just for one service. And we expect the response time to be less than 30 seconds.
+
+5. Will Ti2 provide a validation suite to verify my plugin's responses match the expected format?
+
+No, we currently rely on you to validate the response format, but we are working on a validation suite that will be available in the future.
+
+6. The plugin.js file shows Jest tests, but are there specific test scenarios I need to cover?
+
+No, we don't have a specific test scenarios, but we recommend you to cover the following:
+- Authentication
+- Response format for all operations
+
+
+## Examples
+
+### [searchProductsForItinerary]{@link Plugin#searchProductsForItinerary}
+
+**We need the entire list of ACTIVE products so that we can create vector database for AI to match the extracted text with a service**
+
+
+#### Example Payload
+**Note: when we send empty payload, the expected response is the entire list of ACTIVE products**
+```typescript
+  {}
+```
+
+#### Example Response
+**Note: We provided graphql types and queries for Itinerary Product, in hope for a easier way to map your data to our format. However, if you are not familiar with graphql, you don't have to use them, just make sure the response is in the correct format**
+```typescript
+{
+  "products": [
+    // Example of an Accommodation product
+    {
+      "productId": "1",
+      "productName": "DoubleTree by Hilton Angel Kings Cross",
+      "serviceTypes": [
+        "Accommodation"
+      ],
+      "options": [
+        {
+          "extras": [],
+          "lastUpdateTimestamp": 1586595549,
+          "optionId": "106784",
+          "optionName": "Bed and English Breakfast-Executive Room",
+          "restrictions": {
+            "Adult": {
+              "allowed": true,
+              "maxAge": "999",
+              "minAge": "16"
+            },
+            "Child": {
+              "allowed": true,
+              "maxAge": "15",
+              "minAge": "2"
+            },
+            "Double": {
+              "allowed": true,
+              "maxAdults": "2",
+              "maxPax": "2"
+            },
+            "Infant": {
+              "allowed": true,
+              "maxAge": "1",
+              "minAge": "0"
+            },
+            "Quad": {
+              "allowed": false
+            },
+            "Single": {
+              "allowed": true,
+              "maxAdults": "1",
+              "maxPax": "1"
+            },
+            "Triple": {
+              "allowed": false
+            },
+            "Twin": {
+              "allowed": false
+            },
+            "roomTypeRequired": true
+          },
+          "serviceType": "Accommodation",
+          "units": [
+            {
+              "restrictions": {
+                "allowed": true,
+                "paxCount": "1"
+              },
+              "unitId": "Single",
+              "unitName": "Single"
+            },
+            {
+              "restrictions": {
+                "allowed": false
+              },
+              "unitId": "Twin",
+              "unitName": "Twin"
+            },
+            {
+              "restrictions": {
+                "allowed": true,
+                "paxCount": "2"
+              },
+              "unitId": "Double",
+              "unitName": "Double"
+            },
+            {
+              "restrictions": {
+                "allowed": false
+              },
+              "unitId": "Quad",
+              "unitName": "Quad"
+            }
+          ]
+        }
+      ]
+    },
+    // Example of a Transfers product
+    {
+      "productId": "6489",
+      "productName": "Davids of London Ltd",
+      "serviceTypes": [
+        "Transfers"
+      ],
+      "options": [
+        {
+          "extras": [],
+          "lastUpdateTimestamp": 1700750093,
+          "optionId": "LONTRDAVIDSHDWBVC",
+          "optionName": "Half-Day Warner Bros Studios (6-Hours)-FIT- V- Class (1-5 Pax)",
+          "restrictions": {
+            "Adult": {
+              "allowed": true,
+              "maxAge": "999",
+              "minAge": "16"
+            },
+            "Child": {
+              "allowed": true,
+              "maxAge": "15",
+              "minAge": "5"
+            },
+            "Double": {
+              "allowed": false
+            },
+            "Infant": {
+              "allowed": true,
+              "maxAge": "4",
+              "minAge": "0"
+            },
+            "Quad": {
+              "allowed": false
+            },
+            "Single": {
+              "allowed": false
+            },
+            "Triple": {
+              "allowed": false
+            },
+            "Twin": {
+              "allowed": false
+            },
+            "roomTypeRequired": false
+          },
+          "serviceType": "Transfers",
+          "units": [
+            {
+              "restrictions": {
+                "maxAge": "999",
+                "minAge": "16"
+              },
+              "unitId": "Adults",
+              "unitName": "Adults"
+            },
+            {
+              "restrictions": {
+                "maxAge": "15",
+                "minAge": "5"
+              },
+              "unitId": "Children",
+              "unitName": "Children"
+            },
+            {
+              "restrictions": {
+                "maxAge": "4",
+                "minAge": "0"
+              },
+              "unitId": "Infants",
+              "unitName": "Infants"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+
+### [searchAvailabilityForItinerary]{@link Plugin#searchAvailabilityForItinerary}
+
+#### Example Payload
+
+```typescript
+{
+  optionId: 'LONTRDAVIDSHDWBVC',
+  startDate: '2025-04-01',
+  chargeUnitQuantity: 1,
+  paxConfigs: [{ roomType: 'DB', adults: 2 }],
+}
+```
+#### ExampleResponse
+
+```typescript
+{
+  bookable: true,
+  rates: [{
+    rateId: '123',
+    externalRateText: 'Example rate description'
+  }]
+}
+```
+
+
+
+### [addServiceToItinerary]{@link Plugin#addServiceToItinerary}
+
+#### Example Payload
+```javascript
+{
+  quoteName: String,
+  rateId: String,           // Optional
+  quoteId: String,          // Optional
+  optionId: String,
+  startDate: String,        // YYYY-MM-DD
+  reference: String,        // Optional
+  paxConfigs: [{
+    roomType: String,       // Optional
+    passengers: [{          // Optional
+      firstName: String,
+      lastName: String,
+      passengerType: String,  // 'Adult' | 'Child' | 'Infant'
+      age: Number,            // Optional
+      dob: String,            // Optional, YYYY-MM-DD
+      personId: String        // Optional
+    }]
+  }],
+  extras: [{                // Optional
+    selectedExtra: {
+      id: String
+    },
+    quantity: Number
+  }],
+  puInfo: {                 // Optional, pickup information
+    time: String,           // Optional
+    location: String,       // Optional
+    flightDetails: String   // Optional
+  },
+  doInfo: {                 // Optional, dropoff information
+    time: String,           // Optional
+    location: String,       // Optional
+    flightDetails: String   // Optional
+  },
+  notes: String,            // Optional
+  QB: 'Q',                  // Q for Quote, B for Booking
+  customFieldValues: [{     // Optional
+    id: String,
+    value: String
+  }]
+}
+```
+
+#### Example Response
+
+```typescript
+{
+  message: 'Booking created successfully',
+  booking: {
+    id: '123',
+    reference: 'ref-123',
+    linePrice: '100',
+    lineId: 'lineId-123',
+  }
+}
+```
+
+### [searchItineraries]{@link Plugin#searchItineraries}
+
+
+#### Example Payload
+
+**Note: The payload must include either:**
+- purchaseDateStart AND purchaseDateEnd, OR
+- travelDateStart AND travelDateEnd, OR
+- name, OR
+- bookingId
+
+```javascript
+
+{
+  purchaseDateStart: String,  // Optional, YYYY-MM-DD
+  purchaseDateEnd: String,    // Optional, YYYY-MM-DD
+  travelDateStart: String,    // Optional, YYYY-MM-DD
+  travelDateEnd: String,      // Optional, YYYY-MM-DD
+  name: String,              // Optional
+  bookingId: String          // Optional
+}
+```
+
+
+#### Example Response
+**Note: We provided graphql types and queries for Itinerary Booking, in hope for a easier way to map your data to our format. However, if you are not familiar with graphql, you don't have to use them, just make sure the response is in the correct format**
+```javascript
+{
+  "bookings": [{
+      "agentRef": "2356674/1",
+      "bookingId": "316559",
+      "bookingStatus": "Quotation",
+      "enteredDate": "2024-09-12",
+      "ref": "ALFI393706",
+      "serviceLines": [{
+          "optionId": "LONHOSANLONBFBDLX",
+          "optionName": "Bed and Full Buffet Breakfast",
+          "paxConfigs": [{
+              "adults": 1,
+              "children": 0,
+              "infants": 0,
+              "passengers": [{
+                  "age": null,
+                  "dob": null,
+                  "firstName": "Sean",
+                  "lastName": "Conta",
+                  "passengerType": "Adult",
+                  "personId": "628199",
+                },
+              ],
+              "roomType": "DB",
+            },
+          ],
+          "paxList": [{
+              "age": null,
+              "dob": null,
+              "firstName": "Sean",
+              "lastName": "Conta",
+              "passengerType": "Adult",
+              "personId": "628199",
+            },
+          ],
+          "serviceLineId": "745684",
+          "startDate": "2025-08-13",
+        },
+      ],
+      "totalPrice": "187795",
+      "travelDate": "2025-08-13",
+    },
+  ],
+}
+```
+
+#### Example
+```javascript
+await searchItineraries({
+  payload: {
+    purchaseDateStart: '2024-01-01',
+    purchaseDateEnd: '2024-12-31',
+    name: 'John Doe'
+  }
+})
+```

package/tutorials/plugin-development.md

@@ -2,6 +2,21 @@
 
 Plugins can extend the functionality of Ti2 and/or provide access to other platforms; you should use one of the following methods to provide a stadandarized way to access other systems; if you want to implement new functionality that is not encompassed on the available methods you are more than welcome to add new methods and contribute to the Ti2 codebase.
 
+
+## Steps to develop a plugin
+  1. Contact us to get access to the ti2-<your plugin name> repository.
+      - We will create a skeleton repository for you and add you as a contributor.
+  2. Clone the repository and start developing your plugin.
+  3. Follow respective tutorials to develop your plugin.
+      - [A Plugin for Itinerary Assist AI]{@tutorial itinerary-assist-plugin-dev}
+  4. Make sure to add tests for your plugin. For more information, refer to the [Testing Suite](#testing-suite) section.
+  5. Contact us to deploy your plugin to our hosted staging instance.
+      - Please let us know any environment variables that are required for your plugin to work. For more information, refer to the [Environment variables](#environment-variables) section.
+      - We will provide you with tokens and endpoints to test your plugin.
+  6. Test your plugin against our staging instance.
+  7. Contact us once you have tested your plugin and it's working as expected.
+      - We will deploy your plugin to our production instance.
+
 ## Available Methods
 
 We are using a set of standardized methods to maintain compatibility; the following methods are available, more can be supported but should be a added to the TI2 spec first to maximize it's compatibility.
@@ -24,10 +39,15 @@ We are using a set of standardized methods to maintain compatibility; the follow
 * [searchAvailability]{@link Plugin#searchAvailability}
 * [searchQuote]{@link Plugin#searchQuote}
 * [createBooking]{@link Plugin#createBooking}
-
+* [searchProductsForItinerary]{@link Plugin#searchProductsForItinerary}
+* [searchAvailabilityForItinerary]{@link Plugin#searchAvailabilityForItinerary}
+* [addServiceToItinerary]{@link Plugin#addServiceToItinerary}
+* [getCreateItineraryFields]{@link Plugin#getCreateItineraryFields}
+* [searchItineraries]{@link Plugin#searchItineraries}
+* [queryAllotment]{@link Plugin#queryAllotment}
 ---
 
-## Environment variables
+## <a id="environment-variables"></a> Environment variables
 
 Plugin environment keys are passed down from the hosting ti2 instance when they are generated, this is the preferred way to access environment keys from the plugins, such values are not design to hold client / user's API keys or specific data, they are to be stored in the database via the AppKey collection.
 
@@ -40,6 +60,8 @@ ti2_tourconnect_apiUrl=http://backend:8080
 
 ## Codebase setup
 
+**##Skip this section if you are using the skeleton repository.##**
+
 You can review some of the plugins previously developed and use them as a guide, plugin methods are encourage to include tests and to return results with the same format; however, the returned values can include additional information, currently Ti2 is expected to run on node version 12.22.8; we suggest you use the same for your codebase.
 
 
@@ -51,6 +73,8 @@ $ node init .
 
 ## Entry file / constructor
 
+**##Skip this section if you are using the skeleton repository.##**
+
 The plugin is expected to have an index.js file that exports a Plugin Class like so:
 
 ```javascript
@@ -79,6 +103,8 @@ The plugin named ti2-ventrata would receive acceptLanguage variable and it's val
 
 ## Method calling
 
+**##Skip this section if you are using the skeleton repository.##**
+
 On the previous example code we are declaring a validateToken method; we are normally expected to receive two parameters one is token and the second one payload.
 
 ```javascript
@@ -104,7 +130,7 @@ module.exports = Plugin;
 
 The token parameter should store all the settings for the current configured end user; on these example we are defaulting this settings to the ones configured to the pluging when it was instanced; so if the user settings do not include an apiUrl it will fall back to the environment variable on the running server.
 
-## Testing Suite
+## <a id="testing-suite"></a> Testing Suite
 
 The plugin should contain a test file, for the following example assumes we will be using jest as the testing platform.
 
@@ -163,6 +189,8 @@ After setting up a [Ti2 instance]{@tutorial setup-your-instance} you can add you
 
 ## Extending the base API
 
+**##Typically not needed##**
+
 Ti2 uses the [Swagger API specification](https://swagger.io/specification/) standard to define it's own methods, you can review the basic methods [here](https://ti2-staging.tourconnect.com/api-docs/); these methods can be extended using the same format; this allows any plugin to extend the base API endpoints that are linked to any plugin method (part of the basic methods or new ones).
 
 All the extender methods would be availble under the /\[plugin name] namespace, i.e.: /ti2-greatPlugin/ping.
@@ -212,6 +240,8 @@ paths:
 
 ## Database Migrations (plugin's own database tables)
 
+**##Typically not needed##**
+
 Ti2 uses [Sequelize v6.13](https://sequelize.org/v6) which is the database ORM we ecourage you to use, you can add your own tables via migrations that should be placed under a migrations folder on the root of the plugin folder.
 
 Migrations should be run after the fact, from the root of ti2 instance like so: