ti2 1.0.116 → 1.0.119

package/README.md

@@ -56,6 +56,7 @@ Plugins are the connectores to other systems and/or features you intent to use;
 |searchAvailability|✓|✓|✓|✓|✓|✓|
 |searchQuote|✓|✓|✓|✓|✓|✓|
 |createBooking|✓|✓|✓|✓|✓|✓|
+|confirmBooking|✓|✓|✓|✓|✓|✓|
 |cancelBooking|✓|✓|✓|✓|✓|✓|
 |searchProductsForItinerary|||||||||✓|
 |searchAvailabilityForItinerary|||||||||✓|

package/__tests__/cache.js

@@ -39,6 +39,46 @@ describe('cache', () => {
     });
   });
 
+  describe('owner-token helpers', () => {
+    it('should only renew and drop a key when the expected value still owns it', async () => {
+      const key = 'owner-lock:test';
+      testKeys.push(key);
+
+      await cache.save({ pluginName: testPluginName, key, value: 'owner-a', ttl: 1 });
+
+      const renewedByWrongOwner = await cache.expireIfValue({
+        pluginName: testPluginName,
+        key,
+        value: 'owner-b',
+        ttl: 60,
+      });
+      const renewedByOwner = await cache.expireIfValue({
+        pluginName: testPluginName,
+        key,
+        value: 'owner-a',
+        ttl: 60,
+      });
+      const droppedByWrongOwner = await cache.dropIfValue({
+        pluginName: testPluginName,
+        key,
+        value: 'owner-b',
+      });
+
+      expect(renewedByWrongOwner).toBe(false);
+      expect(renewedByOwner).toBe(true);
+      expect(droppedByWrongOwner).toBe(false);
+      expect(await cache.get({ pluginName: testPluginName, key })).toBe('owner-a');
+
+      const droppedByOwner = await cache.dropIfValue({
+        pluginName: testPluginName,
+        key,
+        value: 'owner-a',
+      });
+      expect(droppedByOwner).toBe(true);
+      expect(await cache.get({ pluginName: testPluginName, key })).toBeFalsy();
+    });
+  });
+
   describe('scan', () => {
     it('should return keys matching the pattern without plugin prefix', async () => {
       // Save some test keys

package/api.yml

@@ -358,6 +358,39 @@ components:
           type: object
           allOf:     # Combines the BasicErrorModel and the inline model
             - $ref: '#/components/schemas/bookingDetail'
+    bookingDetailsForConfirm:
+      type: object
+      additionalProperties: true
+      description: Booking identifier; provide bookingId, id, ref, or reference
+      properties:
+        bookingId:
+          type: string
+        id:
+          type: string
+        ref:
+          type: string
+        reference:
+          type: string
+    confirmBookingReturn:
+      type: object
+      additionalProperties: true
+      properties:
+        confirmBookingReply:
+          type: object
+        booking:
+          type: object
+          properties:
+            ref:
+              type: string
+            id:
+              type: string
+            status:
+              type: string
+            serviceLines:
+              type: array
+              items:
+                type: object
+                additionalProperties: true
     packageSearchQuery:
       type: object
       additionalProperties: true
@@ -1815,6 +1848,85 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/cancellationReturn'
+  /bookings/{appKey}/{userId}/confirm:
+    post:
+      security:
+        - bearerAuth: ['admin', 'user']
+      tags:
+        - bookings
+      summary: Confirms a quote as a booking
+      operationId: confirmBooking
+      parameters:
+        - name: appKey
+          in: path
+          description: app to confirm the booking for, defaults to first token
+          required: true
+          example: 'travelgate-hotelx'
+          schema:
+            type: string
+        - name: userId
+          in: path
+          description: the user/company that the appKey belongs to
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: Booking identifier to confirm
+        required:  true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/bookingDetailsForConfirm'
+      responses:
+        '200':
+          description: Booking confirmation details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/confirmBookingReturn'
+  /bookings/{appKey}/{userId}/{hint}/confirm:
+    post:
+      security:
+        - bearerAuth: ['admin', 'user']
+      tags:
+        - bookings
+      summary: Confirms a quote as a booking for a specific hint
+      operationId: confirmBooking
+      parameters:
+        - name: appKey
+          in: path
+          description: app to confirm the booking for
+          required: true
+          example: 'travelgate'
+          schema:
+            type: string
+        - name: userId
+          in: path
+          description: the user/company that the appKey belongs to
+          required: true
+          schema:
+            type: string
+        - name: hint
+          in: path
+          description: a specific token hint to be used
+          required: true
+          example: 'travelgate-australia'
+          schema:
+            type: string
+      requestBody:
+        description: Booking identifier to confirm
+        required:  true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/bookingDetailsForConfirm'
+      responses:
+        '200':
+          description: Booking confirmation details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/confirmBookingReturn'
   /packages/{appKey}/{userId}/search:
     post:
       security:

package/cache.js

@@ -48,6 +48,39 @@ const saveIfNotExists = async ({
   return result === 'OK';
 };
 
+const expireIfValue = async ({
+  pluginName,
+  key: keyParam,
+  value,
+  ttl = defaultTTL,
+}) => {
+  const key = buildKey({ pluginName, key: keyParam });
+  const expectedValue = JSON.stringify(value);
+  const result = await cache.eval(`
+    if redis.call('get', KEYS[1]) == ARGV[1] then
+      return redis.call('expire', KEYS[1], ARGV[2])
+    end
+    return 0
+  `, 1, key, expectedValue, ttl);
+  return result === 1;
+};
+
+const dropIfValue = async ({
+  pluginName,
+  key: keyParam,
+  value,
+}) => {
+  const key = buildKey({ pluginName, key: keyParam });
+  const expectedValue = JSON.stringify(value);
+  const result = await cache.eval(`
+    if redis.call('get', KEYS[1]) == ARGV[1] then
+      return redis.call('del', KEYS[1])
+    end
+    return 0
+  `, 1, key, expectedValue);
+  return result === 1;
+};
+
 const get = async ({
   pluginName,
   key: keyParam,
@@ -125,6 +158,8 @@ module.exports = {
   cache,
   save,
   saveIfNotExists,
+  expireIfValue,
+  dropIfValue,
   getOrExec,
   drop,
   get,

package/controllers/__tests__/bookings-searchProducts.js

@@ -9,7 +9,7 @@ const cache = require('../../cache');
 // Mock the worker/queue module
 jest.mock('../../worker/queue', () => ({
   ...jest.requireActual('../../worker/queue'), // Import and retain default behavior
-  addJob: jest.fn().mockResolvedValue({ id: 'mockJobId' }), // Mock addJob
+  addJob: jest.fn().mockResolvedValue('mockJobId'), // Mock addJob
   // Provide mock for jobStatus as it might be called by other parts of the code or tests
   jobStatus: jest.fn().mockResolvedValue({ status: 'completed', progress: 100, returnValue: null }),
 }));
@@ -160,6 +160,64 @@ describe('user: bookings controller - searchProducts', () => {
         expect(products[0].options.length).toBe(1);
         expect(products[0].options[0].optionName).toBe('Transfer from Sydney Harbor Bridge to Hilton Hotel');
       });
+      it('should filter cached full catalog by optionId without another plugin call', async () => {
+        const { products } = await doApiPost({
+          url: `/products/${testAppName}/${testUserId}/${testHint}/search`,
+          token: userToken,
+          payload: { optionId: '2345' },
+        });
+        expect(travelgatePlugin.searchProducts).not.toHaveBeenCalled();
+        expect(products).toHaveLength(1);
+        expect(products[0].options).toHaveLength(1);
+        expect(products[0].options[0].optionId).toBe('2345');
+      });
+      it('should emit sanitized cache-decision telemetry without raw ids, hints, payloads, or plugin results', async () => {
+        const emitSpy = jest.spyOn(travelgatePlugin.events, 'emit');
+        await doApiPost({
+          url: `/products/${testAppName}/${testUserId}/${testHint}/search`,
+          token: userToken,
+          payload: { searchInput: 'Transfer from Sydney Harbor to Hilton Hotel' },
+        });
+        const decisionPayloads = emitSpy.mock.calls
+          .filter(call => call[0] === 'bookingsProductSearch:cache:decision')
+          .map(call => call[1]);
+        expect(decisionPayloads.length).toBeGreaterThan(0);
+        decisionPayloads.forEach(payload => {
+          expect(payload.userId).toBeUndefined();
+          expect(payload.hint).toBeUndefined();
+          expect(payload.cacheKey).toBeUndefined();
+          expect(payload.pluginResult).toBeUndefined();
+          expect(payload.searchInput).toBeUndefined();
+          expect(payload.optionId).toBeUndefined();
+          expect(payload.userIdHash).toBeTruthy();
+          expect(payload.hintHash).toBeTruthy();
+          expect(payload.cacheKeyHash).toBeTruthy();
+          expect(JSON.stringify(payload)).not.toContain(testUserId);
+          expect(JSON.stringify(payload)).not.toContain(testHint);
+          expect(JSON.stringify(payload)).not.toContain('Transfer from Sydney Harbor');
+        });
+        emitSpy.mockRestore();
+      });
+
+      it('includes raw scope only on legacy cache-save events', async () => {
+        const emitSpy = jest.spyOn(travelgatePlugin.events, 'emit');
+        await doApiPost({
+          url: `/products/${testAppName}/${testUserId}/${testHint}/search`,
+          token: userToken,
+          payload: { forceRefresh: true },
+        });
+        const cacheSavePayload = emitSpy.mock.calls
+          .filter(call => call[0] === 'bookingsProductSearch:cache:save')
+          .map(call => call[1])
+          .find(payload => payload.action === 'cache_saved');
+
+        expect(cacheSavePayload).toBeTruthy();
+        expect(cacheSavePayload.userId).toBe(testUserId);
+        expect(cacheSavePayload.hint).toBe(testHint);
+        expect(cacheSavePayload.userIdHash).toBeTruthy();
+        expect(cacheSavePayload.hintHash).toBeTruthy();
+        emitSpy.mockRestore();
+      });
     });
     describe('doNotCallPluginForProducts flag', () => {
       const doNotCallHint = 'hint_for_doNotCallPluginForProducts';
@@ -260,6 +318,7 @@ describe('user: bookings controller - searchProducts', () => {
         it('call outside of TTR should serve stale data and queue background refresh with correct parameters', async () => {
           travelgatePlugin.searchProducts.mockClear(); // Clear before action
           addJob.mockClear(); // Clear addJob mock before this action that should trigger it
+          const emitSpy = jest.spyOn(travelgatePlugin.events, 'emit');
 
           const { products } = await doApiPost({
             url: `/products/${testAppName}/${testUserId}/${ttrTestHint}/search`, // appName is 'travelgate'
@@ -293,6 +352,15 @@ describe('user: bookings controller - searchProducts', () => {
           expect(jobData.postProcess.args.userId).toBe(testUserId);
           expect(jobData.postProcess.args.hint).toBe(ttrTestHint);
           expect(jobParams).toEqual({ removeOnComplete: true });
+          expect(emitSpy).toHaveBeenCalledWith(
+            'bookingsProductSearch:cache:decision',
+            expect.objectContaining({
+              action: 'stale_served',
+              reason: 'backgroundRefreshQueued',
+              jobId: 'mockJobId',
+            }),
+          );
+          emitSpy.mockRestore();
         });
       });
       // The 'lock mechanism (job queuing on stale cache)' describe block has been moved to the top level.
@@ -430,13 +498,22 @@ describe('user: bookings controller - searchProducts', () => {
       expect(cached.products).toEqual(initialProductsInCache);
       expect(lastUpdated).toBeGreaterThan(1);
       expect(emitSpy).toHaveBeenCalledWith(
-        'bookingsProductSearch:cache:emptyRefreshSkipped',
+        'bookingsProductSearch:cache:decision',
         expect.objectContaining({
+          action: 'empty_refresh_skipped',
           reason: 'emptyResultPreservedExistingCache',
           cachePreserved: true,
           existingProductCount: initialProductsInCache.length,
         }),
       );
+      expect(emitSpy).toHaveBeenCalledWith(
+        'bookingsProductSearch:cache:emptyRefreshSkipped',
+        expect.objectContaining({
+          action: 'empty_refresh_skipped',
+          reason: 'emptyResultPreservedExistingCache',
+          cachePreserved: true,
+        }),
+      );
       emitSpy.mockRestore();
     });
 
@@ -528,12 +605,21 @@ describe('user: bookings controller - searchProducts', () => {
       expect(cached.products).toEqual(initialProductsInCache);
       expect(lastUpdated).toBeGreaterThan(1);
       expect(emitSpy).toHaveBeenCalledWith(
-        'bookingsProductSearch:cache:partialRefreshSkipped',
+        'bookingsProductSearch:cache:decision',
         expect.objectContaining({
+          action: 'partial_refresh_skipped',
           reason: 'partialResultPreservedExistingCache',
           cachePreserved: true,
           existingProductCount: initialProductsInCache.length,
-          pluginResult,
+          returnedProductCount: pluginResult.products.length,
+        }),
+      );
+      expect(emitSpy).toHaveBeenCalledWith(
+        'bookingsProductSearch:cache:partialRefreshSkipped',
+        expect.objectContaining({
+          action: 'partial_refresh_skipped',
+          reason: 'partialResultPreservedExistingCache',
+          cachePreserved: true,
         }),
       );
       emitSpy.mockRestore();
@@ -575,13 +661,22 @@ describe('user: bookings controller - searchProducts', () => {
         value: { products: [] },
       }));
       expect(fakePlugin.events.emit).toHaveBeenCalledWith(
-        'bookingsProductSearch:cache:emptyRefreshSkipped',
+        'bookingsProductSearch:cache:decision',
         expect.objectContaining({
+          action: 'empty_refresh_skipped',
           reason: 'emptyResultPreservedConcurrentCache',
           cachePreserved: true,
           existingProductCount: 1,
         }),
       );
+      expect(fakePlugin.events.emit).toHaveBeenCalledWith(
+        'bookingsProductSearch:cache:emptyRefreshSkipped',
+        expect.objectContaining({
+          action: 'empty_refresh_skipped',
+          reason: 'emptyResultPreservedConcurrentCache',
+          cachePreserved: true,
+        }),
+      );
     });
   });
 });
@@ -777,6 +872,98 @@ describe('Bookings Product Search Lock Mechanism (Job Queuing on Stale Cache)',
     expect(addJob).not.toHaveBeenCalled();
   });
 
+  it('concurrent forceRefresh requests should wait for one plugin fetch', async () => {
+    await clearProductSearchCache();
+
+    const refreshedProducts = [{
+      productId: 'force-product',
+      productName: 'Force Product',
+      options: [{
+        optionId: 'force-option',
+        optionName: 'Force Option',
+      }],
+    }];
+    lockTestPlugin.searchProducts.mockReset();
+    const releasePluginFetches = [];
+    const pluginFetchStarted = new Promise(resolve => {
+      lockTestPlugin.searchProducts.mockImplementation(() => {
+        resolve();
+        return new Promise(pluginResolve => {
+          releasePluginFetches.push(() => pluginResolve({ products: refreshedProducts }));
+        });
+      });
+    });
+    const makeForceRequest = () => doApiPost({
+      url: `/products/${testAppName}/${testUserId}/${ttrTestHint}/search`,
+      token: userToken,
+      payload: { forceRefresh: true },
+    });
+
+    const requestPromises = [makeForceRequest(), makeForceRequest(), makeForceRequest()];
+    await pluginFetchStarted;
+    await new Promise(resolve => setTimeout(resolve, 50));
+
+    releasePluginFetches.forEach(releasePluginFetch => releasePluginFetch());
+    const results = await Promise.all(requestPromises);
+
+    results.forEach(result => {
+      expect(result.products).toEqual(refreshedProducts);
+    });
+    expect(lockTestPlugin.searchProducts).toHaveBeenCalledTimes(1);
+    expect(addJob).not.toHaveBeenCalled();
+  });
+
+  it('renews the plugin execution lock while a cold product fetch exceeds the initial TTL', async () => {
+    await clearProductSearchCache();
+    const originalLockTtl = process.env.PRODUCT_SEARCH_LOCK_TTL_SECONDS;
+    process.env.PRODUCT_SEARCH_LOCK_TTL_SECONDS = '1';
+
+    const slowProducts = [{
+      productId: 'slow-product',
+      productName: 'Slow Product',
+      options: [{
+        optionId: 'slow-option',
+        optionName: 'Slow Option',
+      }],
+    }];
+    lockTestPlugin.searchProducts.mockReset();
+    const expireIfValueSpy = jest.spyOn(lockTestPlugin.cache, 'expireIfValue');
+    const releasePluginFetches = [];
+    const pluginFetchStarted = new Promise(resolve => {
+      lockTestPlugin.searchProducts.mockImplementation(() => {
+        resolve();
+        return new Promise(pluginResolve => {
+          releasePluginFetches.push(() => pluginResolve({ products: slowProducts }));
+        });
+      });
+    });
+
+    try {
+      const firstRequest = makeProductSearchRequest();
+      await pluginFetchStarted;
+      await new Promise(resolve => setTimeout(resolve, 1500));
+      const secondRequest = makeProductSearchRequest();
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      releasePluginFetches.forEach(releasePluginFetch => releasePluginFetch());
+      const results = await Promise.all([firstRequest, secondRequest]);
+
+      results.forEach(result => {
+        expect(result.products).toEqual(slowProducts);
+      });
+      expect(lockTestPlugin.searchProducts).toHaveBeenCalledTimes(1);
+      expect(addJob).not.toHaveBeenCalled();
+      expect(expireIfValueSpy).toHaveBeenCalled();
+    } finally {
+      expireIfValueSpy.mockRestore();
+      if (originalLockTtl === undefined) {
+        delete process.env.PRODUCT_SEARCH_LOCK_TTL_SECONDS;
+      } else {
+        process.env.PRODUCT_SEARCH_LOCK_TTL_SECONDS = originalLockTtl;
+      }
+    }
+  });
+
   it('multiple concurrent requests with no cache should share an empty plugin result', async () => {
     await clearProductSearchCache();
 

package/controllers/__tests__/bookings.js

@@ -170,6 +170,59 @@ describe('user: bookings controller', () => {
     expect(plugins[0].createBooking.mock.calls[0][0].payload).toEqual(payload);
     expect(plugins[0].createBooking.mock.calls[0][0].token).toEqual(token);
   });
+  it('should be able to confirm a booking (with hint)', async () => {
+    const payload = {
+      bookingId: '14226',
+    };
+    await doApiPost({
+      url: `/bookings/${appKey}/${userId}/testingToken/confirm`,
+      token: userToken,
+      payload,
+    });
+    expect(plugins[0].confirmBooking).toHaveBeenCalled();
+    expect(plugins[0].confirmBooking.mock.calls[0][0].payload).toEqual(payload);
+    expect(plugins[0].confirmBooking.mock.calls[0][0].token).toEqual(token);
+  });
+  it('should be able to confirm a booking (no hint)', async () => {
+    const payload = {
+      bookingId: '14226',
+    };
+    await doApiPost({
+      url: `/bookings/${appKey}/${userId}/confirm`,
+      token: userToken,
+      payload,
+    });
+    expect(plugins[0].confirmBooking).toHaveBeenCalled();
+    expect(plugins[0].confirmBooking.mock.calls[0][0].payload).toEqual(payload);
+    expect(plugins[0].confirmBooking.mock.calls[0][0].token).toEqual(token);
+  });
+  it('should emit cancelBooking operation metadata when cancelling', async () => {
+    const payload = {
+      bookingId: chance.guid(),
+    };
+    const emitSpy = jest.spyOn(plugins[0].events, 'emit');
+    try {
+      await doApiPost({
+        url: `/bookings/${appKey}/${userId}/testingToken/cancel`,
+        token: userToken,
+        payload,
+      });
+      expect(plugins[0].cancelBooking).toHaveBeenCalled();
+      expect(plugins[0].cancelBooking.mock.calls[0][0].payload).toEqual(payload);
+      expect(plugins[0].cancelBooking.mock.calls[0][0].token).toEqual(token);
+      expect(emitSpy).toHaveBeenCalledWith(
+        'bookingsCancelBooking',
+        expect.objectContaining({
+          userId,
+          hint: 'testingToken',
+          operationId: 'cancelBooking',
+          pluginName: appKey,
+        }),
+      );
+    } finally {
+      emitSpy.mockRestore();
+    }
+  });
   it('should forward inline credentials directly to create booking', async () => {
     const payload = {
       id: chance.guid(),

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');
@@ -34,12 +35,86 @@ const getPositiveIntegerEnv = (name, defaultValue) => {
   return Number.isFinite(value) && integerValue > 0 ? integerValue : defaultValue;
 };
 
-const productSearchLockTtlSeconds = getPositiveIntegerEnv('PRODUCT_SEARCH_LOCK_TTL_SECONDS', 120);
+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,
+      userId,
+      hint,
+    });
+  }
+};
+
+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;
@@ -95,6 +170,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,
@@ -104,6 +180,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);
@@ -183,7 +299,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
 
@@ -194,11 +322,17 @@ 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 (cacheContent && cacheContent.products) return cacheContent;
+    if (hasProductCache(cacheContent)) return cacheContent;
     return null;
   };
 
@@ -217,23 +351,46 @@ const $bookingsProductSearch = plugins => async ({
     return getCachedProductSearchResults();
   };
 
-  const acquirePluginExecutionLock = async () => app.cache.saveIfNotExists({
+  const acquirePluginExecutionLock = async lockOwnerToken => app.cache.saveIfNotExists({
     key: pluginExecutionLockKey,
-    value: true,
-    ttl: productSearchLockTtlSeconds,
+    value: lockOwnerToken,
+    ttl: getProductSearchLockTtlSeconds(),
   });
 
   // Helper function to call the plugin, save cache, and return results
-  const fetchFromPluginAndCache = async () => {
-    const lockAcquired = await acquirePluginExecutionLock();
+  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();
-      if (cacheContent) return cacheContent;
+      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,
@@ -243,51 +400,72 @@ const $bookingsProductSearch = plugins => async ({
         userId,
         hint,
       });
+      const pluginElapsedMs = Date.now() - pluginStartedAt;
 
       // 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 (hasCacheableProductResults(pluginResults)) {
-        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,
+        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)) {
-        app.events.emit('bookingsProductSearch:cache:partialRefreshSkipped', {
-          cacheKey, userId, hint, operationId: 'bookingsProductSearch', requestId, pluginName: app.name,
-          reason: 'directPartialResultNotCached', pluginResult: pluginResults,
+        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,
+        });
       }
     } 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);
@@ -295,8 +473,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 || {}) };
       };
 
@@ -304,7 +489,7 @@ 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 - queue at most one background refresh job and serve stale data.
@@ -314,10 +499,10 @@ const $bookingsProductSearch = plugins => async ({
         ttl: 60,
       });
       if (!jobQueueLockAcquired) {
-        return returnCachedResults();
+        return returnCachedResults('stale_served', { reason: 'backgroundRefreshDeduped' });
       }
 
-      await addJob({
+      const jobId = await addJob({
         type: 'plugin',
         pluginName: appKey,
         method: app.searchProducts ? 'searchProducts' : 'searchProductsForItinerary',
@@ -330,13 +515,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,
@@ -625,22 +813,28 @@ 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: monthInSeconds,
-  });
-  const emitCacheEvent = (eventName, extra = {}) => app.events.emit(eventName, {
-    cacheKey, userId, hint, operationId: 'bookingsProductSearch', requestId, pluginName: app.name,
-    ...extra,
+    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: monthInSeconds });
-    emitCacheEvent('bookingsProductSearch:cache:save');
+    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 });
@@ -651,9 +845,9 @@ const $updateProductSearchCache = plugins => async ({
         cachePreserved: true,
         existingProductCount: existingCacheContent.products.length,
       };
-      if (isPartialRefresh) eventExtra.pluginResult = pluginResult;
+      if (isPartialRefresh) eventExtra.returnedProductCount = productCount(pluginResult);
       emitCacheEvent(
-        isPartialRefresh ? 'bookingsProductSearch:cache:partialRefreshSkipped' : 'bookingsProductSearch:cache:emptyRefreshSkipped',
+        isPartialRefresh ? 'partial_refresh_skipped' : 'empty_refresh_skipped',
         eventExtra,
       );
       return;
@@ -661,10 +855,10 @@ const $updateProductSearchCache = plugins => async ({
 
     if (isPartialRefresh) {
       await markRefreshAttempted();
-      emitCacheEvent('bookingsProductSearch:cache:partialRefreshSkipped', {
+      emitCacheEvent('partial_refresh_skipped', {
         reason: 'partialResultNotCached',
         cachePreserved: false,
-        pluginResult,
+        returnedProductCount: productCount(pluginResult),
       });
       return;
     }
@@ -673,7 +867,7 @@ const $updateProductSearchCache = plugins => async ({
     const latestCacheContent = await app.cache.get({ key: cacheKey });
     if (hasNonEmptyProductCache(latestCacheContent)) {
       await markRefreshAttempted();
-      emitCacheEvent('bookingsProductSearch:cache:emptyRefreshSkipped', {
+      emitCacheEvent('empty_refresh_skipped', {
         reason: 'emptyResultPreservedConcurrentCache',
         cachePreserved: true,
         existingProductCount: latestCacheContent.products.length,
@@ -683,8 +877,8 @@ const $updateProductSearchCache = plugins => async ({
 
     // 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: monthInSeconds });
-    emitCacheEvent('bookingsProductSearch:cache:emptyRefresh');
+    await app.cache.save({ key: cacheKey, value: { products: [] }, ttl: productSearchCacheTtlSeconds });
+    emitCacheEvent('empty_cache_saved', { cacheProductCount: 0 });
   }
 };
 
@@ -693,6 +887,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

@@ -91,6 +91,8 @@ module.exports = async ({
         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.116",
+  "version": "1.0.119",
   "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}