ti2 1.0.116 → 1.0.118

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,44 @@ 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();
+      });
     });
     describe('doNotCallPluginForProducts flag', () => {
       const doNotCallHint = 'hint_for_doNotCallPluginForProducts';
@@ -260,6 +298,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 +332,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 +478,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 +585,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 +641,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 +852,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,82 @@ 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);
+  }
+};
+
+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 +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,
@@ -104,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);
@@ -183,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
 
@@ -194,11 +318,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 +347,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 +396,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 +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 || {}) };
       };
 
@@ -304,7 +485,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 +495,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 +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,
@@ -625,22 +809,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 +841,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 +851,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 +863,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 +873,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 +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

@@ -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.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

package/CLAUDE.md

@@ -1,166 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Ti2 (Tourism Information Interchange) is an open-source integration framework for the tourism industry. It provides standardized functions for bookings, content, and rates management through a plugin-based architecture.
-
-## Critical Development Rules
-
-1. **Docker Container Execution**: ALL commands must be run inside the `ti2` Docker container
-   - The codebase is located at `/ti2` path inside the container
-   - This project is part of `node_modules/ti2` in the container environment
-   - **NEVER run npm, node, or npx commands on the host machine**
-   - Always use: `docker exec ti2 bash -c "cd /ti2 && <command>"`
-   - Example for npm install: `docker exec ti2 bash -c "cd /ti2 && npm install <package>"`
-
-2. **Testing Rules**:
-   - Tests MUST be run inside the Docker container
-   - Example: `docker exec ti2 bash -c "cd /ti2 && npx jest lib/__tests__/callback.js --forceExit"`
-   - Use `test/utils.js` for mocking the environment
-   - Review test utility implementations before writing/editing tests
-
-3. **Background Jobs**:
-   - Jobs sent to the queue run on a separate worker thread/instance
-   - Use `worker/queue.js` `listJobs` function to check job status
-   - Workers are always assumed to be running
-
-4. **Code Confidence**: Do not make changes until 95% confident. Ask follow-up questions if uncertain.
-
-## Public Repo Privacy
-
-- `ti2` is open source. Before opening or updating public PRs, review summaries, inline comments, release notes, or commit messages, scrub internal TourConnect service names and private implementation details.
-- Do not mention internal services such as `pyfilematch`, `filematch`, `tcoutlook`, private frontend names, private trace URLs, private customer identifiers, or internal deployment architecture in public GitHub text.
-- Use generic wording such as `upstream caller`, `internal catalog caller`, `private frontend`, `caller-side timeout`, or `internal workflow` when context is needed.
-- After editing public GitHub text, search the PR body, issue comments, review comments, and review summaries for internal service names before handoff.
-
-## Common Development Commands
-
-```bash
-# Run tests (inside Docker container)
-docker exec ti2 bash -c "cd /ti2 && npm test"
-docker exec ti2 bash -c "cd /ti2 && npx jest [test-file] --forceExit"
-
-# Run specific test file
-docker exec ti2 bash -c "cd /ti2 && npx jest controllers/__tests__/bookings.js --forceExit"
-
-# Database migrations
-docker exec ti2 bash -c "cd /ti2 && npm run sequelize db:migrate"
-
-# Generate documentation
-docker exec ti2 bash -c "cd /ti2 && npm run doc"
-```
-
-## Architecture
-
-### Core Components
-
-1. **Main Entry Point** (`index.js`):
-   - Initializes Express server on port 10010 (default)
-   - Sets up Swagger documentation at `/api-docs`
-   - Handles plugin instantiation and middleware
-   - Implements caching mechanism
-   - Manages background job processing via `worker/queue.js`
-
-2. **API Definition** (`api.yml`):
-   - OpenAPI 3.0.0 specification
-   - Defines all endpoints and schemas
-   - JWT Bearer authentication
-
-3. **Plugin System**:
-   - Two types: Integration Plugins (connect systems) and App Plugins (value-added tools)
-   - Plugins are instantiated with cache, axios, events, and configuration
-   - Plugin schemas are merged with main API schema
-   - Each plugin gets its own routes under `/apps/{pluginName}`
-
-4. **Controllers** (`controllers/`):
-   - `app.js`: Core application controller
-   - `bookings.js`: Booking operations (searchProducts, createBooking, etc.)
-   - `admin.js`: Administrative functions
-   - `user.js`: User management
-   - `ping.js`: Health check endpoints
-   - `allotment.js`: Allotment management
-
-5. **Database Models** (`models/`):
-   - Sequelize ORM with MySQL
-   - Key models: Integration, User, UserAppKey, CronJobs, ApiCronJobs
-   - Migrations in `migrations/` directory
-
-6. **Worker System** (`worker/`):
-   - Bull queue for background job processing
-   - Redis-backed job queue
-   - Supports plugin jobs, API jobs, and callback jobs
-   - Multi-worker support with throng
-
-7. **Authentication** (`auth/authHandler.js`):
-   - JWT-based authentication
-   - Bearer token scheme
-
-### Key Features
-
-- **Caching**: Redis-based caching with configurable TTL
-- **Event System**: EventEmitter2 for plugin communication
-- **Background Jobs**: Async job processing with Bull/Redis
-- **Cron Jobs**: Scheduled task execution
-- **Multi-tenancy**: Support for multiple integrations/plugins
-
-### Plugin Development
-
-Plugins must implement standard methods:
-- `validateToken`: Token validation
-- `tokenTemplate`: Token configuration template
-- Booking methods: `searchProducts`, `searchAvailability`, `createBooking`, `cancelBooking`
-- Content methods: `getProducts`, `getProduct`, `createProduct`, `updateProduct`
-
-### Testing Strategy
-
-- Jest testing framework
-- Test fixtures in `__fixtures__/`
-- Mock plugins in `__mocks__/`
-- Use `test/utils.js` for creating test environments
-- Tests organized by controller in `controllers/__tests__/`
-
-## Database
-
-- Sequelize ORM with MySQL/MariaDB
-- Connection managed through `models/db.js`
-- Migrations handled via sequelize-cli
-- Models auto-loaded from `models/` directory
-
-## Environment Variables
-
-Key variables:
-- `PORT`: Server port (default: 10010)
-- `REDIS_URL`: Redis connection (default: redis://redis:6379)
-- `jwtSecret`: JWT signing secret
-- `adminKey`: Admin authentication key
-- `WEB_CONCURRENCY`: Number of workers
-- `MAX_JOBS_PER_WORKER`: Job concurrency per worker
-- `SSL_INSECURE_ALLOWED_DOMAINS`: Pipe-separated list of domains where SSL certificate verification is skipped (e.g., `localhost|staging.example.com|192.168.1.100`)
-
-Plugin-specific variables follow pattern: `ti2_{pluginName}_{setting}`
-
-### SSL Configuration
-
-The `SSL_INSECURE_ALLOWED_DOMAINS` environment variable allows you to specify domains where SSL certificate verification should be skipped. This is useful for:
-- Development environments with self-signed certificates
-- Testing against staging servers with invalid certificates
-- Local development with HTTPS
-
-Example usage:
-```bash
-# Skip SSL verification for specific domains
-export SSL_INSECURE_ALLOWED_DOMAINS="localhost|staging.api.com|192.168.1.100"
-
-# Multiple domains separated by pipe
-export SSL_INSECURE_ALLOWED_DOMAINS="dev.example.com|test.example.com"
-```
-
-**Important Implementation Notes**:
-- SSL configuration is ONLY applied to plugin axios instances (for external API calls) and worker axios instances
-- Internal communication (callbacks, per-request axios) do NOT use SSL configuration  
-- SSL configuration uses a per-request interceptor approach for better isolation
-- The configuration checks domains dynamically on each request
-
-**Warning**: Only use this in development/testing environments. Never skip SSL verification in production for security reasons.