ti2 1.0.115 → 1.0.118

package/controllers/bookings.js

@@ -1,4 +1,5 @@
 const assert = require('assert');
+const crypto = require('crypto');
 const hash = require('object-hash');
 const R = require('ramda');
 const { UserAppKey } = require('../models/index');
@@ -28,6 +29,94 @@ const typeDefsAndQueries = {
   itineraryBookingQuery,
 };
 
+const getPositiveIntegerEnv = (name, defaultValue) => {
+  const value = Number(process.env[name]);
+  const integerValue = Math.floor(value);
+  return Number.isFinite(value) && integerValue > 0 ? integerValue : defaultValue;
+};
+
+const getProductSearchLockTtlSeconds = () => getPositiveIntegerEnv('PRODUCT_SEARCH_LOCK_TTL_SECONDS', 120);
+const productSearchLockWaitMs = getPositiveIntegerEnv('PRODUCT_SEARCH_LOCK_WAIT_MS', 25 * 1000);
+const productSearchLockPollMs = getPositiveIntegerEnv('PRODUCT_SEARCH_LOCK_POLL_MS', 250);
+const emptyProductSearchCacheTtlSeconds = 60;
+const productSearchCacheTtlSeconds = 30 * 24 * 60 * 60;
+const productSearchOperationId = 'bookingsProductSearch';
+const productSearchCacheDecisionEvent = 'bookingsProductSearch:cache:decision';
+const legacyProductSearchCacheEvents = {
+  cache_saved: 'bookingsProductSearch:cache:save',
+  partial_refresh_skipped: 'bookingsProductSearch:cache:partialRefreshSkipped',
+  empty_refresh_skipped: 'bookingsProductSearch:cache:emptyRefreshSkipped',
+  empty_cache_saved: 'bookingsProductSearch:cache:emptyRefresh',
+};
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+const productSearchCacheKey = ({ userId, hint }) => hash({ userId, hint, operationId: productSearchOperationId });
+
+const productCount = value => R.pathOr([], ['products'], value).length;
+
+const hasProductCache = cacheContent => Boolean(cacheContent && cacheContent.products);
+
+const safeHash = value => (value === undefined || value === null ? undefined : hash(String(value)));
+
+const emitProductSearchCacheDecision = ({ app, cacheKey, userId, hint, requestId, searchInput, optionId, forceRefresh, startedAt }, action, extra = {}) => {
+  if (!app.events || !app.events.emit) return;
+  const payload = {
+    action,
+    operationId: productSearchOperationId,
+    requestId,
+    pluginName: app.name,
+    userIdHash: safeHash(userId),
+    hintHash: safeHash(hint),
+    cacheKeyHash: safeHash(cacheKey),
+    forceRefresh: Boolean(forceRefresh),
+    hasSearchInput: Boolean((searchInput || '').trim()),
+    hasOptionId: Boolean(optionId && optionId.length),
+    elapsedMs: Date.now() - startedAt,
+    ...extra,
+  };
+  app.events.emit(productSearchCacheDecisionEvent, payload);
+  if (legacyProductSearchCacheEvents[action]) {
+    app.events.emit(legacyProductSearchCacheEvents[action], payload);
+  }
+};
+
+const createLockRenewal = ({ app, key, value, ttl, onDecision }) => {
+  if (!app.cache.expireIfValue || ttl <= 0) return { stop: async () => {} };
+
+  const renewEveryMs = Math.max(250, Math.floor(ttl * 500));
+  let stopped = false;
+  let inFlightRenewal = Promise.resolve();
+  const renew = async () => {
+    if (stopped) return;
+    const renewed = await app.cache.expireIfValue({ key, value, ttl });
+    if (!renewed) {
+      stopped = true;
+      onDecision('lock_renew_lost', { reason: 'ownerTokenMismatch' });
+    }
+  };
+  const interval = setInterval(() => {
+    inFlightRenewal = renew().catch(err => {
+      stopped = true;
+      onDecision('lock_renew_failed', { reason: err.message });
+    });
+  }, renewEveryMs);
+  if (interval.unref) interval.unref();
+
+  return {
+    stop: async () => {
+      stopped = true;
+      clearInterval(interval);
+      await inFlightRenewal;
+    },
+  };
+};
+
+const createProductSearchUnavailableError = () => {
+  const err = new Error('Product search cache refresh did not produce cached results');
+  err.status = 503;
+  return err;
+};
+
 const getAppAndToken = async ({ plugins, appKey, userId, hint }) => {
   const app = plugins.find(({ name }) => name === appKey);
   assert(app, 'could not find the app ' + appKey);
@@ -77,6 +166,7 @@ const bookingsCancel = plugins => async (req, res, next) => {
   } = req;
   try {
     const { app, token } = await getAppAndToken({ plugins, appKey, userId, hint });
+    assert(app.cancelBooking, `cancelBooking is not available for ${appKey}`);
     const results = await app.cancelBooking({
       axios,
       token,
@@ -86,6 +176,46 @@ const bookingsCancel = plugins => async (req, res, next) => {
       hint,
       requestId: req.requestId,
     });
+    app.events.emit('bookingsCancelBooking', {
+      userId,
+      hint,
+      operationId: 'cancelBooking',
+      requestId: req.requestId,
+      pluginName: app.name,
+      payload: results,
+    });
+    return res.json(results);
+  } catch (err) {
+    return next(err);
+  }
+};
+
+const confirmBooking = plugins => async (req, res, next) => {
+  const {
+    axios,
+    params: { appKey, userId, hint },
+    body,
+  } = req;
+  try {
+    const { app, token } = await getAppAndToken({ plugins, appKey, userId, hint });
+    assert(app.confirmBooking, `confirmBooking is not available for ${appKey}`);
+    const results = await app.confirmBooking({
+      axios,
+      token,
+      payload: body,
+      typeDefsAndQueries,
+      userId,
+      hint,
+      requestId: req.requestId,
+    });
+    app.events.emit('bookingsConfirmBooking', {
+      userId,
+      hint,
+      operationId: 'confirmBooking',
+      requestId: req.requestId,
+      pluginName: app.name,
+      payload: results,
+    });
     return res.json(results);
   } catch (err) {
     return next(err);
@@ -123,6 +253,22 @@ const $searchProductList = (products, searchInput = '', optionId = '') => {
   return filteredProducts;
 };
 
+// Plugins may flag incomplete catalog responses with `catalogPartial` or `partial`;
+// both must suppress cache writes so a partial result does not replace a complete cache.
+const hasCacheableProductResults = pluginResults => Boolean(
+  pluginResults
+  && pluginResults.products
+  && pluginResults.products.length > 0
+  && !pluginResults.catalogPartial
+  && !pluginResults.partial
+);
+
+const hasNonEmptyProductCache = cacheContent => Boolean(
+  cacheContent
+  && cacheContent.products
+  && cacheContent.products.length > 0
+);
+
 const $bookingsProductSearch = plugins => async ({
   axios,
   appKey,
@@ -149,7 +295,19 @@ const $bookingsProductSearch = plugins => async ({
   assert(app.searchProducts || app.searchProductsForItinerary, `searchProducts or searchProductsForItinerary is not available for ${appKey}`);
   const func = (app.searchProducts || app.searchProductsForItinerary).bind(app);
 
-  const cacheKey = hash({ userId, hint, operationId: 'bookingsProductSearch' });
+  const cacheKey = productSearchCacheKey({ userId, hint });
+  const telemetryContext = {
+    app,
+    cacheKey,
+    userId,
+    hint,
+    requestId,
+    searchInput,
+    optionId,
+    forceRefresh,
+    startedAt: Date.now(),
+  };
+  const emitDecision = (action, extra = {}) => emitProductSearchCacheDecision(telemetryContext, action, extra);
   const pluginExecutionLockKey = `${cacheKey}:lock`; // Lock for direct plugin execution
   const jobQueueLockKey = `${cacheKey}:jobLock`;   // Lock for preventing multiple job queues
 
@@ -160,12 +318,75 @@ const $bookingsProductSearch = plugins => async ({
   const isStaleByTTR = lastUpdated && (Date.now() - lastUpdated > ttr * 1000);
   const doNotCallPluginForProducts = token.doNotCallPluginForProducts || R.path(['cacheSettings', 'bookingsProductSearch', 'doNotCall'], app);
   const hasPluginExecutionLock = await app.cache.get({ key: pluginExecutionLockKey });
+  emitDecision(hasProductCache(initialActualCacheContent) ? 'cache_hit' : 'cache_miss', {
+    cacheProductCount: productCount(initialActualCacheContent),
+    cacheAgeMs: lastUpdated ? Date.now() - lastUpdated : undefined,
+    ttrMs: ttr * 1000,
+    reason: hasPluginExecutionLock ? 'lockActive' : undefined,
+  });
+  assert(app.cache.saveIfNotExists, 'cache adapter must expose saveIfNotExists');
+
+  const getCachedProductSearchResults = async () => {
+    const cacheContent = await app.cache.get({ key: cacheKey });
+    if (hasProductCache(cacheContent)) return cacheContent;
+    return null;
+  };
+
+  const waitForProductSearchCache = async () => {
+    const timeoutAt = Date.now() + productSearchLockWaitMs;
+    while (Date.now() < timeoutAt) {
+      const cacheContent = await getCachedProductSearchResults();
+      if (cacheContent) return cacheContent;
+
+      const lockStillActive = await app.cache.get({ key: pluginExecutionLockKey });
+      if (!lockStillActive) return null;
+
+      await sleep(productSearchLockPollMs);
+    }
+
+    return getCachedProductSearchResults();
+  };
+
+  const acquirePluginExecutionLock = async lockOwnerToken => app.cache.saveIfNotExists({
+    key: pluginExecutionLockKey,
+    value: lockOwnerToken,
+    ttl: getProductSearchLockTtlSeconds(),
+  });
 
   // Helper function to call the plugin, save cache, and return results
-  const fetchFromPluginAndCache = async () => {
-    await app.cache.save({ key: pluginExecutionLockKey, value: true, ttl: 120 });
+  const fetchFromPluginAndCache = async (reason = 'cache_miss') => {
+    const lockOwnerToken = crypto.randomBytes(16).toString('hex');
+    const lockStartedAt = Date.now();
+    const lockAcquired = await acquirePluginExecutionLock(lockOwnerToken);
+    if (!lockAcquired) {
+      emitDecision('lock_wait', { reason, lockWaitMs: 0 });
+      const cacheContent = await waitForProductSearchCache();
+      const lockWaitMs = Date.now() - lockStartedAt;
+      if (cacheContent) {
+        emitDecision('cache_hit', {
+          reason: 'waitedForLeader',
+          lockWaitMs,
+          cacheProductCount: productCount(cacheContent),
+        });
+        return cacheContent;
+      }
+      emitDecision('lock_timeout', { reason, lockWaitMs });
+      throw createProductSearchUnavailableError();
+    }
+
+    const lockTtlSeconds = getProductSearchLockTtlSeconds();
+    emitDecision('lock_acquired', { reason, lockTtlSeconds });
+    const lockRenewal = createLockRenewal({
+      app,
+      key: pluginExecutionLockKey,
+      value: lockOwnerToken,
+      ttl: lockTtlSeconds,
+      onDecision: emitDecision,
+    });
+
     let pluginResults;
     try {
+      const pluginStartedAt = Date.now();
       pluginResults = await func({
         axios,
         token,
@@ -175,46 +396,72 @@ const $bookingsProductSearch = plugins => async ({
         userId,
         hint,
       });
+      const pluginElapsedMs = Date.now() - pluginStartedAt;
 
-      // This function is responsible for caching if it fetched good results.
+      // This function is responsible for caching if it fetched usable results.
       // This applies to forceRefresh, initial load, or direct calls that result in a fetch.
       // The $updateProductSearchCache function handles caching for background jobs queued due to stale data.
-      if (pluginResults && pluginResults.products && pluginResults.products.length > 0) {
-        const monthInSeconds = 30 * 24 * 60 * 60;
-        await app.cache.save({ key: `${cacheKey}:lastUpdated`, value: Date.now(), ttl: monthInSeconds });
-        await app.cache.save({ key: cacheKey, value: pluginResults, ttl: monthInSeconds });
-        app.events.emit('bookingsProductSearch:cache:save', {
-          cacheKey, userId, hint, operationId: 'bookingsProductSearch', requestId, pluginName: app.name,
+      if (hasCacheableProductResults(pluginResults)) {
+        await app.cache.save({ key: `${cacheKey}:lastUpdated`, value: Date.now(), ttl: productSearchCacheTtlSeconds });
+        await app.cache.save({ key: cacheKey, value: pluginResults, ttl: productSearchCacheTtlSeconds });
+        emitDecision('cache_saved', {
+          reason,
+          pluginElapsedMs,
+          cacheProductCount: productCount(pluginResults),
+        });
+      } else if (pluginResults && (pluginResults.catalogPartial || pluginResults.partial)) {
+        emitDecision('partial_refresh_skipped', {
+          reason: 'directPartialResultNotCached',
+          pluginElapsedMs,
+          cachePreserved: false,
+          returnedProductCount: productCount(pluginResults),
+        });
+      } else if (pluginResults && pluginResults.products && pluginResults.products.length === 0) {
+        // Short-lived empty cache gives concurrent waiters the same answer as the lock holder.
+        await app.cache.save({ key: cacheKey, value: pluginResults, ttl: emptyProductSearchCacheTtlSeconds });
+        emitDecision('empty_cache_saved', {
+          reason,
+          pluginElapsedMs,
+          cacheProductCount: 0,
         });
       }
-      // If pluginResults are empty, cache is NOT updated here by fetchFromPluginAndCache.
-      // This maintains existing behavior for forceRefresh/initial load paths.
-      // $updateProductSearchCache has its own logic for handling empty results from background refresh.
     } finally {
-      await app.cache.drop({ key: pluginExecutionLockKey });
+      await lockRenewal.stop();
+      if (app.cache.dropIfValue) {
+        await app.cache.dropIfValue({ key: pluginExecutionLockKey, value: lockOwnerToken });
+      } else {
+        await app.cache.drop({ key: pluginExecutionLockKey });
+      }
     }
     return pluginResults || { products: [] }; // Ensure products array exists
   };
 
   // 1. `doNotCallPluginForProducts` is true, and not `forceRefresh`: Serve from cache or empty.
   if (doNotCallPluginForProducts && !forceRefresh) {
-    if (initialActualCacheContent && initialActualCacheContent.products) {
+    if (hasProductCache(initialActualCacheContent)) {
       const searchResults = $searchProductList(initialActualCacheContent.products, searchInput, optionId);
+      emitDecision('cache_hit', {
+        reason: 'doNotCallPluginForProducts',
+        cacheProductCount: initialActualCacheContent.products.length,
+        returnedProductCount: searchResults.length,
+      });
       return { ...initialActualCacheContent, products: searchResults, ...(token.configuration || {}) };
     }
+    emitDecision('cache_miss', { reason: 'doNotCallPluginForProducts' });
     return { products: [], ...(token.configuration || {}) };
   }
 
   // 2. `forceRefresh` is true (and not case 1): Fetch from plugin.
   //    fetchFromPluginAndCache will handle caching the new results.
   if (forceRefresh) {
-    const funcResults = await fetchFromPluginAndCache();
+    emitDecision('force_refresh');
+    const funcResults = await fetchFromPluginAndCache('force_refresh');
     const searchResults = $searchProductList(funcResults.products, searchInput, optionId);
     return { ...funcResults, products: searchResults, ...(token.configuration || {}) };
   }
 
   // 3. Cache exists (initialActualCacheContent) and not forceRefresh:
-  if (initialActualCacheContent && initialActualCacheContent.products) {
+  if (hasProductCache(initialActualCacheContent)) {
     const cacheIsEmpty = !initialActualCacheContent.products.length;
     const trimmedSearch = (searchInput || '').trim();
     const searchFilterIsEmpty = (!trimmedSearch || trimmedSearch === '*') && !(optionId && optionId.length);
@@ -222,8 +469,15 @@ const $bookingsProductSearch = plugins => async ({
     // If cache is empty and no search filter, skip to case 4 to fetch fresh data
     const shouldSkipEmptyCache = cacheIsEmpty && searchFilterIsEmpty;
     if (!shouldSkipEmptyCache) {
-      const returnCachedResults = () => {
+      const returnCachedResults = (action = 'cache_hit', extra = {}) => {
         const searchResults = $searchProductList(initialActualCacheContent.products, searchInput, optionId);
+        emitDecision(action, {
+          cacheProductCount: initialActualCacheContent.products.length,
+          returnedProductCount: searchResults.length,
+          cacheAgeMs: lastUpdated ? Date.now() - lastUpdated : undefined,
+          ttrMs: ttr * 1000,
+          ...extra,
+        });
         return { ...initialActualCacheContent, products: searchResults, ...(token.configuration || {}) };
       };
 
@@ -231,18 +485,20 @@ const $bookingsProductSearch = plugins => async ({
 
       // Cache is fresh or plugin execution in progress: serve from cache
       if (!isEffectivelyStale || hasPluginExecutionLock) {
-        return returnCachedResults();
+        return returnCachedResults('cache_hit', { reason: hasPluginExecutionLock ? 'lockActive' : 'freshCache' });
       }
 
-      // Cache is stale - check if background job already queued
-      const hasJobQueueLock = await app.cache.get({ key: jobQueueLockKey });
-      if (hasJobQueueLock) {
-        return returnCachedResults();
+      // Cache is stale - queue at most one background refresh job and serve stale data.
+      const jobQueueLockAcquired = await app.cache.saveIfNotExists({
+        key: jobQueueLockKey,
+        value: true,
+        ttl: 60,
+      });
+      if (!jobQueueLockAcquired) {
+        return returnCachedResults('stale_served', { reason: 'backgroundRefreshDeduped' });
       }
 
-      // Queue background refresh job and serve stale data
-      await app.cache.save({ key: jobQueueLockKey, value: true, ttl: 60 });
-      await addJob({
+      const jobId = await addJob({
         type: 'plugin',
         pluginName: appKey,
         method: app.searchProducts ? 'searchProducts' : 'searchProductsForItinerary',
@@ -255,13 +511,16 @@ const $bookingsProductSearch = plugins => async ({
         },
       }, { removeOnComplete: true });
 
-      return returnCachedResults();
+      return returnCachedResults('stale_served', {
+        reason: 'backgroundRefreshQueued',
+        jobId,
+      });
     }
   }
 
   // 4. No cache content (and not caught by previous conditions like forceRefresh or doNotCallPluginForProducts):
   //    Fetch from plugin. fetchFromPluginAndCache will handle caching.
-  const funcResults = await fetchFromPluginAndCache();
+  const funcResults = await fetchFromPluginAndCache('cache_miss');
   const searchResults = $searchProductList(funcResults.products, searchInput, optionId);
   return {
     ...funcResults,
@@ -550,28 +809,72 @@ const $updateProductSearchCache = plugins => async ({
     return; // Or throw error
   }
 
-  const cacheKey = hash({ userId, hint, operationId: 'bookingsProductSearch' });
-  const monthInSeconds = 30 * 24 * 60 * 60;
+  const cacheKey = productSearchCacheKey({ userId, hint });
+  const markRefreshAttempted = () => app.cache.save({
+    key: `${cacheKey}:lastUpdated`,
+    value: Date.now(),
+    ttl: productSearchCacheTtlSeconds,
+  });
+  const emitCacheEvent = (action, extra = {}) => emitProductSearchCacheDecision({
+    app,
+    cacheKey,
+    userId,
+    hint,
+    requestId,
+    searchInput: '',
+    optionId: '',
+    forceRefresh: false,
+    startedAt: Date.now(),
+  }, action, extra);
+
+  if (hasCacheableProductResults(pluginResult)) {
+    await markRefreshAttempted();
+    await app.cache.save({ key: cacheKey, value: pluginResult, ttl: productSearchCacheTtlSeconds });
+    emitCacheEvent('cache_saved', { cacheProductCount: productCount(pluginResult) });
+  } else {
+    const isPartialRefresh = pluginResult && (pluginResult.catalogPartial || pluginResult.partial);
+    const existingCacheContent = await app.cache.get({ key: cacheKey });
+    if (hasNonEmptyProductCache(existingCacheContent)) {
+      await markRefreshAttempted();
+      const eventExtra = {
+        reason: isPartialRefresh ? 'partialResultPreservedExistingCache' : 'emptyResultPreservedExistingCache',
+        cachePreserved: true,
+        existingProductCount: existingCacheContent.products.length,
+      };
+      if (isPartialRefresh) eventExtra.returnedProductCount = productCount(pluginResult);
+      emitCacheEvent(
+        isPartialRefresh ? 'partial_refresh_skipped' : 'empty_refresh_skipped',
+        eventExtra,
+      );
+      return;
+    }
+
+    if (isPartialRefresh) {
+      await markRefreshAttempted();
+      emitCacheEvent('partial_refresh_skipped', {
+        reason: 'partialResultNotCached',
+        cachePreserved: false,
+        returnedProductCount: productCount(pluginResult),
+      });
+      return;
+    }
 
-  // Always update lastUpdated to prevent immediate re-trigger of background jobs
-  // even if the plugin returned empty results.
-  await app.cache.save({ key: `${cacheKey}:lastUpdated`, value: Date.now(), ttl: monthInSeconds });
+    // Best-effort race guard: avoid overwriting a non-empty cache written after the first read.
+    const latestCacheContent = await app.cache.get({ key: cacheKey });
+    if (hasNonEmptyProductCache(latestCacheContent)) {
+      await markRefreshAttempted();
+      emitCacheEvent('empty_refresh_skipped', {
+        reason: 'emptyResultPreservedConcurrentCache',
+        cachePreserved: true,
+        existingProductCount: latestCacheContent.products.length,
+      });
+      return;
+    }
 
-  if (pluginResult && pluginResult.products && pluginResult.products.length > 0) {
-    await app.cache.save({ key: cacheKey, value: pluginResult, ttl: monthInSeconds });
-    app.events.emit('bookingsProductSearch:cache:save', {
-      cacheKey, userId, hint, operationId: 'bookingsProductSearch', requestId, pluginName: app.name,
-    });
-    console.log(`[$updateProductSearchCache][requestId: ${requestId}] Saved products to cache for ${appKey}, user ${userId}, hint ${hint}.`);
-  } else {
-    // If plugin returned no products, update the cache to reflect this.
-    // This prevents serving stale data indefinitely if the source truly has no products anymore.
-    await app.cache.save({ key: cacheKey, value: { products: [] }, ttl: monthInSeconds });
-    app.events.emit('bookingsProductSearch:cache:emptyRefresh', {
-      cacheKey, userId, hint, operationId: 'bookingsProductSearch', requestId, pluginName: app.name,
-      pluginResult, // Log what the plugin returned
-    });
-    console.log(`[$updateProductSearchCache][requestId: ${requestId}] Plugin returned empty/no products. Cached empty for ${appKey}, user ${userId}, hint ${hint}.`);
+    // Empty complete refreshes are authoritative only when there is no existing non-empty cache.
+    await markRefreshAttempted();
+    await app.cache.save({ key: cacheKey, value: { products: [] }, ttl: productSearchCacheTtlSeconds });
+    emitCacheEvent('empty_cache_saved', { cacheProductCount: 0 });
   }
 };
 
@@ -580,6 +883,7 @@ const controllerFactory = plugins => {
   const controllerFunctions = {
     bookingsSearch: bookingsSearch(plugins),
     bookingsCancel: bookingsCancel(plugins),
+    confirmBooking: confirmBooking(plugins),
     $bookingsProductSearch: $bookingsProductSearch(plugins),
     bookingsProductSearch: bookingsProductSearch(plugins),
     getProductPackages: getProductPackages(plugins),

package/index.js

@@ -90,6 +90,9 @@ module.exports = async ({
         get: args => cache.get({ ...args, pluginName }),
         getOrExec: args => cache.getOrExec({ ...args, pluginName }),
         save: args => cache.save({ ...args, pluginName }),
+        saveIfNotExists: args => cache.saveIfNotExists({ ...args, pluginName }),
+        expireIfValue: args => cache.expireIfValue({ ...args, pluginName }),
+        dropIfValue: args => cache.dropIfValue({ ...args, pluginName }),
         scan: args => cache.scan({ ...args, pluginName }),
       },
       axios: pluginAxios,

package/package.json

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

package/test/plugin.js

@@ -75,6 +75,21 @@ class Plugin {
     });
     this.searchQuote = jestPlugin.fn(() => ({ quote: [{ id: chance.guid() }] }));
     this.createBooking = jestPlugin.fn(() => {});
+    this.cancelBooking = jestPlugin.fn(() => ({
+      cancelServicesReply: {},
+      cancellation: {
+        id: chance.guid(),
+        status: 'Cancelled',
+      },
+    }));
+    this.confirmBooking = jestPlugin.fn(() => ({
+      confirmBookingReply: {},
+      booking: {
+        id: chance.guid(),
+        status: 'OK',
+        serviceLines: [],
+      },
+    }));
     this.getAffiliateAgents = jestPlugin.fn(() => ({ agents: [] }));
     this.searchItineraries = jestPlugin.fn(() => ({ bookings: [] }));
     this.searchProductsForItinerary = jestPlugin.fn(() => ({ products: [] }));
@@ -535,6 +550,32 @@ class Plugin {
    */
   createBooking() {}
 
+  /**
+   * Cancel a booking
+   * @async
+   * @param {Object} args - Cancel booking arguments.
+   * @param {Object} args.token - A token definition, it's content varies between integrations.
+   * @param {Object} args.payload - Booking identifier payload.
+   * @returns {object} retVal - the return object.
+   */
+  cancelBooking() {}
+
+  /**
+   * Confirm a quote as a booking
+   * @async
+   * @param {Object} args - Confirm booking arguments.
+   * @param {Object} args.token - A token definition, it's content varies between integrations.
+   * @param {Object} args.payload - Booking identifier payload.
+   * @param {string} [args.payload.bookingId] - Booking id to confirm.
+   * @param {string} [args.payload.id] - Booking id to confirm.
+   * @param {string} [args.payload.ref] - Booking reference to confirm.
+   * @param {string} [args.payload.reference] - Booking reference to confirm.
+   * @returns {object} retVal - the return object.
+   * @returns {Object} retVal.confirmBookingReply - Raw integration reply.
+   * @returns {Booking} retVal.booking - A normalized Booking object.
+   */
+  confirmBooking() {}
+
   /**
    * @typedef {Object} Passenger
    * @property {string} firstName - Passenger first name

package/tutorials/plugin-development.md

@@ -39,6 +39,8 @@ 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}
+* [cancelBooking]{@link Plugin#cancelBooking}
+* [confirmBooking]{@link Plugin#confirmBooking}
 * [searchProductsForItinerary]{@link Plugin#searchProductsForItinerary}
 * [searchAvailabilityForItinerary]{@link Plugin#searchAvailabilityForItinerary}
 * [addServiceToItinerary]{@link Plugin#addServiceToItinerary}

package/.windsurfrules

@@ -1,9 +0,0 @@
-This is a Node.js project using Sequelize for database operations and Express.js for the web server.
-The API is defined in api.yml using OpenAPI 3.0.2
-The database is defined in models/index.js
-The models are defined in models/
-to run tests you have to run them on the ti2 named docker container, and consider this codebase is part of node_modules/ti2 path for example : 
-`` $ docker exec ti2 bash -c "cd /ti2 && npx jest lib/__tests__/callback.js --forceExit"``
-When writing / editing tests, make use of test/utils.js and review their implementation to understand how to mock the environment.
-Do not make any changes until you 95% confident of the changes you want to make, ask follow up questions until you have that confidence.
-when sending jobs to the background worker using the queue, asssume a worker is always runing to execute it but is on a different instance thread, so to review / wait for jobs we have to use the wokrer/queue.js listJobs fn to check for it