ti2-bokun 1.0.6 → 1.0.8

package/index.js

@@ -4,10 +4,40 @@ const assert = require('assert');
 const moment = require('moment');
 const jwt = require('jsonwebtoken');
 const crypto = require('crypto');
+const {
+  validateContactInfo,
+  getMainContactDetails,
+  normalizeMainContactAnswer,
+  expandRequiredCustomerQuestionIds,
+  extractCountryInputString,
+  COUNTRY_VALIDATION_ERROR,
+  PHONE_VALIDATION_ERROR,
+} = require('./utils/customerInfoFields');
+const {
+  buildCustomFieldsFromQuestions,
+  mapCustomFieldValuesToAnswers,
+  normalizeBookingQuestions,
+  normalizeQuestionAnswerList,
+} = require('./utils/customFields');
+const {
+  TRAVEL_DATE_FORMAT,
+  BOKUN_PASSENGER_FIELD_TO_UI_ID,
+  applyPassengerFieldsToUiFields,
+  validateRequiredContactFields,
+  normalizeCustomFieldValueForBooking,
+  extractRequiredQuestions,
+} = require('./utils/bookingFields');
 const { translateProduct } = require('./resolvers/product');
 const { translateAvailability } = require('./resolvers/availability');
 const { translateBooking } = require('./resolvers/booking');
-const { translatePickupPoint } = require('./resolvers/pickup-point');
+const {
+  fetchCountriesList,
+} = require('./utils/country');
+const {
+  buildRequestUrlAndPath,
+  getHeaders,
+} = require('./utils/bokunRequest');
+const { DEFAULT_EXCLUDED_CUSTOMER_QUESTION_IDS } = require('./utils/customerFieldConstants');
 
 const DIRECTBOOKING_SOURCE = 'DIRECT_REQUEST';
 const CHECKOUT_OPTION_DIRECTBOOKING = 'CUSTOMER_FULL_PAYMENT';
@@ -16,6 +46,19 @@ const PAYMENT_METHOD = 'RESERVE_FOR_EXTERNAL_PAYMENT';
 
 const CONCURRENCY = 3;
 
+const COUNTRY_FIELD_IDS = new Set(['country', 'nationality']);
+
+const normalizePassengerDetailValue = ({ questionId, value }) => {
+  if (value == null) return value;
+  const normalizedQuestionId = String(questionId || '').toLowerCase();
+  const isCountryLike = normalizedQuestionId === 'country' || normalizedQuestionId === 'nationality';
+  if (!isCountryLike || typeof value !== 'object' || Array.isArray(value)) return value;
+
+  if (value.label != null && String(value.label).trim() !== '') return String(value.label).trim();
+  if (value.value != null && String(value.value).trim() !== '') return String(value.value).trim();
+  return value;
+};
+
 const emptyContact = () => ({
   fullName: null,
   firstName: null,
@@ -23,23 +66,11 @@ const emptyContact = () => ({
   emailAddress: null,
   phoneNumber: null,
   locales: [],
-  postalCode: null,
+  postcode: null,
   country: null,
   notes: null,
 });
 
-/** Bokun requires a non-empty, plausible email on booking; surface clear errors to the UI. */
-const validateBookingEmail = raw => {
-  const trimmed = raw == null ? '' : String(raw).trim();
-  if (trimmed === '') {
-    return { ok: false, error: 'Email is required. Please enter a valid email address.' };
-  }
-  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(trimmed)) {
-    return { ok: false, error: 'Please enter a valid email address.' };
-  }
-  return { ok: true, email: trimmed };
-};
-
 /**
  * Build UI-format unitItems from Bokun booking response.
  * Matches pricingCategories.id / pricePerCategoryUnit.id to show pricingCategories.title as unitName.
@@ -491,6 +522,33 @@ const toRetailMinor = (price, currencyPrecision = 2) => {
   return Math.round(p * (10 ** (Number.isNaN(prec) ? 2 : prec)));
 };
 
+const extractBokunErrorMessage = err => {
+  const responseData = err && err.response && err.response.data;
+  if (!responseData) return err && err.message;
+  if (typeof responseData === 'string') return responseData;
+  if (responseData.errorMessage) return responseData.errorMessage;
+  if (responseData.message) return responseData.message;
+  if (responseData.error) {
+    if (typeof responseData.error === 'string') return responseData.error;
+    if (responseData.error.message) return responseData.error.message;
+  }
+  if (Array.isArray(responseData.errors) && responseData.errors.length > 0) {
+    return responseData.errors
+      .map(entry => {
+        if (!entry) return null;
+        if (typeof entry === 'string') return entry;
+        return entry.message || null;
+      })
+      .filter(Boolean)
+      .join(', ');
+  }
+  if (responseData.details) {
+    if (typeof responseData.details === 'string') return responseData.details;
+    return JSON.stringify(responseData.details);
+  }
+  return err && err.message;
+};
+
 /**
  * Shape a single availability slot to the UI-expected format.
  * unitId is always string across product, availability, and booking.
@@ -677,6 +735,7 @@ const buildAvailabilityRoot = ({
   currency,
   fallbackDate,
   pricingCategoryLookup,
+  pickupPoints = [],
 }) => {
   const availabilityDate = parseAvailabilityDate(availability);
   const fallbackLocalDate = typeof fallbackDate === 'string'
@@ -758,8 +817,9 @@ const buildAvailabilityRoot = ({
     currency: fallbackCurrency,
     offer: availability.offer || availability.offers || null,
     offers: availability.offers,
-    pickupAvailable: availability.pickupAvailable || availability.pickupAllotment || false,
+    pickupAvailable: pickupPoints.length > 0 || availability.pickupAvailable || availability.pickupAllotment || false,
     pickupRequired: availability.pickupRequired || false,
+    pickupPoints,
     pricingFrom: resolvedPricing,
     unitPricingFrom: unitPricing,
     ratePricing: availability.ratePricing,
@@ -822,74 +882,32 @@ const deriveStableJwtKey = ({ accessKey, secretKey }) => {
 };
 
 /**
- * Build full request URL and the path to use for signature (path the server sees).
- * If baseUrl is https://api.bokun.io/rest-v2, pathForSigning must be /rest-v2/activity.json/... so the signature matches.
+ * Map a Bokun `startPoints[]` entry (from the product payload) to the
+ * canonical pickup-point shape used by the availability slot and the
+ * pickup-point GraphQL resolver.
+ *
+ *  startPoint field               → pickup point field
+ *  id (number)                    → id (string)
+ *  title                          → name
+ *  type                           → pickupType
+ *  address.addressLine1 + city    → address (human-readable string)
+ *  address.geoPoint.latitude/lng  → latitude / longitude
+ *  pickupTicketDescription        → description
  */
-const buildRequestUrlAndPath = (baseUrl, path) => {
-  const pathPart = path.startsWith('/') ? path : `/${path}`;
-  const url = `${baseUrl.replace(/\/$/, '')}${pathPart}`;
-  let pathForSigning = pathPart;
-  try {
-    const u = new URL(url);
-    pathForSigning = u.pathname + u.search;
-  } catch (_) {
-    // fallback: use pathPart if URL parse fails
-  }
-  return { url, pathForSigning };
-};
-
-/**
- * Bókun signature per https://bokun.dev/booking-api-rest/vU6sCfxwYdJWd1QAcLt12i/configuring-the-platform-for-api-usage-and-authentication/sFiGRpo4detkmrZPcWtQPj
- * String to sign = date + accessKey + HTTP method (uppercase) + path (including query string, no scheme/host).
- * Then HMAC-SHA1 with secret key, then Base64.
- */
-const generateBokunSignature = ({
-  secretKey,
-  accessKey,
-  date,
-  method,
-  path,
-}) => {
-  const stringToSign = `${date}${accessKey}${method.toUpperCase()}${path}`;
-  const signature = crypto
-    .createHmac('sha1', secretKey)
-    .update(stringToSign)
-    .digest('base64');
-  return signature;
-};
-
-const getHeaders = ({
-  accessKey,
-  secretKey,
-  method,
-  path,
-}) => {
-  if (typeof secretKey !== 'string' || !secretKey) {
-    throw new Error(
-      'Bokun API secretKey is required. Configure accessKey and secretKey in the integration token '
-      + 'or set ti2_bokun_accessKey and ti2_bokun_secretKey.',
-    );
-  }
-  if (typeof accessKey !== 'string' || !accessKey) {
-    throw new Error(
-      'Bokun API accessKey is required. Configure accessKey and secretKey in the integration token '
-      + 'or set ti2_bokun_accessKey and ti2_bokun_secretKey.',
-    );
-  }
-  const date = moment.utc().format('YYYY-MM-DD HH:mm:ss');
-  const signature = generateBokunSignature({
-    secretKey,
-    accessKey,
-    date,
-    method,
-    path,
-  });
-
+const mapStartPointToPickupPoint = point => {
+  if (!point) return null;
+  const addr = point.address || {};
+  const geoPoint = addr.geoPoint || {};
+  const addressParts = [addr.addressLine1, addr.city, addr.state, addr.countryCode].filter(Boolean);
   return {
-    'X-Bokun-Date': date,
-    'X-Bokun-AccessKey': accessKey,
-    'X-Bokun-Signature': signature,
-    'Content-Type': 'application/json;charset=UTF-8',
+    id: point.id != null ? String(point.id) : null,
+    name: point.title || null,
+    description: point.pickupTicketDescription || null,
+    address: addressParts.length > 0 ? addressParts.join(', ') : null,
+    latitude: geoPoint.latitude ?? null,
+    longitude: geoPoint.longitude ?? null,
+    pickupType: point.type || null,
+    directions: null,
   };
 };
 
@@ -931,9 +949,16 @@ const fetchAvailabilityForProduct = async ({
       url: productUrl,
       headers: productHeaders,
     });
-    pricingCategoryLookup = buildPricingCategoryLookup(R.pathOr({}, ['data'], productResponse));
+    const productData = R.pathOr({}, ['data'], productResponse);
+    pricingCategoryLookup = buildPricingCategoryLookup(productData);
+    const showPickupPlaces = Boolean(productData.displaySettings?.showPickupPlaces);
+    const pickupPoints = showPickupPlaces
+      ? (Array.isArray(productData.startPoints) ? productData.startPoints : [])
+        .map(mapStartPointToPickupPoint)
+        .filter(Boolean)
+      : [];
 
-    // Get availability details
+    // Fetch availability
     const queryString = queryParts.join('&');
     const path = `/activity.json/${productId}/availabilities?${queryString}`;
     const { url, pathForSigning } = buildRequestUrlAndPath(baseUrl, path);
@@ -943,11 +968,7 @@ const fetchAvailabilityForProduct = async ({
       method: 'GET',
       path: pathForSigning,
     });
-    const availabilityResponse = await axios({
-      method: 'get',
-      url,
-      headers,
-    });
+    const availabilityResponse = await axios({ method: 'get', url, headers });
     const availabilities = R.pathOr([], ['data'], availabilityResponse);
     const translated = await Promise.map(availabilities, async availability => {
       const rateMatch = findRateMatch({
@@ -984,6 +1005,7 @@ const fetchAvailabilityForProduct = async ({
         currency: rateCurrency || currency,
         fallbackDate: startDate,
         pricingCategoryLookup,
+        pickupPoints,
       });
 
       const translatedAvailability = await translateAvailability({
@@ -1032,6 +1054,204 @@ const fetchAvailabilityForProduct = async ({
   }
 };
 
+// Apply the live (or fallback) Bokun country list as the option set on the
+// `country` / `nationality` UI fields. NOTE: this is an authoritative override
+// — any pre-existing `options` / `type` on those fields (e.g. carried over
+// from a Bokun bookingQuestion) are intentionally replaced so the dropdown
+// always renders Bokun's canonical country list.
+const decorateCountryFields = (fieldList, options) => {
+  if (!Array.isArray(fieldList)) return fieldList;
+  if (!Array.isArray(options) || options.length === 0) return fieldList;
+  return fieldList.map(field => {
+    const normalizedFieldId = String(field?.id || '').toLowerCase();
+    if (!field || !COUNTRY_FIELD_IDS.has(normalizedFieldId)) return field;
+    return {
+      ...field,
+      type: 'extended-option',
+      selectMultiple: false,
+      options,
+    };
+  });
+};
+
+const getContactValidationErrors = contactInfo => (
+  Array.isArray(contactInfo?.errors) && contactInfo.errors.length > 0
+    ? contactInfo.errors
+    : [contactInfo?.error || 'Contact information is required.']
+);
+
+const shouldRetryContactValidationWithDynamicCountries = (contactInfo, holder) => {
+  if (!contactInfo || contactInfo.ok) return false;
+  const hasCountryInput = Boolean(
+    holder
+    && (
+      extractCountryInputString(holder.country) !== ''
+      || extractCountryInputString(holder.nationality) !== ''
+    ),
+  );
+  if (!hasCountryInput) return false;
+
+  const errors = getContactValidationErrors(contactInfo);
+  return errors.some(e => e === COUNTRY_VALIDATION_ERROR)
+    && errors.every(e => e === COUNTRY_VALIDATION_ERROR || e === PHONE_VALIDATION_ERROR);
+};
+
+const normalizePassengerFields = passengerFields => (
+  (Array.isArray(passengerFields) ? passengerFields : [])
+    .map(entry => {
+      if (!entry || typeof entry !== 'object') return null;
+      const fieldCode = typeof entry.field === 'string' ? entry.field.trim() : '';
+      if (!fieldCode) return null;
+      const normalizedFieldCode = fieldCode.toUpperCase().replace(/[^A-Z0-9]/g, '');
+      return {
+        field: BOKUN_PASSENGER_FIELD_TO_UI_ID[normalizedFieldCode] || fieldCode.toLowerCase(),
+        required: Boolean(entry.required),
+      };
+    })
+    .filter(Boolean)
+);
+
+async function fetchMandatoryBookingQuestionsForProduct(plugin, {
+  axios,
+  token,
+  productId,
+}) {
+  try {
+    if (!productId) return { leadPassengerContactInfo: [], passengerContactInfo: [], bookingQuestions: [] };
+
+    const { endpoint, testMode } = token || {};
+    const { accessKey, secretKey } = plugin.getCredentials(token);
+    const baseUrl = testMode ? 'https://api.bokuntest.com' : (endpoint || plugin.endpoint || 'https://api.bokun.io');
+
+    const productPath = `/activity.json/${encodeURIComponent(productId)}`;
+    const { url: productUrl, pathForSigning: productPathForSigning } = buildRequestUrlAndPath(
+      baseUrl,
+      productPath,
+    );
+    const productHeaders = getHeaders({
+      accessKey,
+      secretKey,
+      method: 'GET',
+      path: productPathForSigning,
+    });
+
+    const productResponse = await axios({
+      method: 'get',
+      url: productUrl,
+      headers: productHeaders,
+    });
+
+    const productData = R.pathOr({}, ['data'], productResponse);
+    const leadPassengerContactInfo = normalizePassengerFields(
+      R.pathOr([], ['mainContactFields'], productData),
+    );
+    const passengerContactInfo = normalizePassengerFields(
+      R.pathOr([], ['passengerFields'], productData),
+    );
+    const bookingQuestions = normalizeBookingQuestions(
+      R.pathOr([], ['bookingQuestions'], productData),
+    );
+
+    return { leadPassengerContactInfo, passengerContactInfo, bookingQuestions };
+  } catch (err) {
+    // Best-effort enrichment only; keep static fields if remote question
+    // lookup fails. Use console.error so operators still see auth/perm
+    // failures, and include the HTTP status when available.
+    const status = err.response?.status;
+    console.error(
+      `Could not fetch mandatory booking questions for product ${String(productId)} (status ${status || 'n/a'}):`,
+      err.response?.data || err.message,
+    );
+    return { leadPassengerContactInfo: [], passengerContactInfo: [], bookingQuestions: [] };
+  }
+}
+
+async function toTranslatedBooking({
+  bookingPayload,
+  bookingTypeDefs,
+  bookingQuery,
+  baseUrl,
+  tenant,
+}) {
+  let booking = R.path(['data', 'booking'], bookingPayload)
+    || R.path(['data'], bookingPayload)
+    || bookingPayload?.booking
+    || bookingPayload;
+  const redirectUrl = R.path(['data', 'redirectRequest', 'url'], bookingPayload);
+  if (typeof redirectUrl === 'string' && /^https?:\/\//i.test(redirectUrl.trim()) && !booking.publicUrl) {
+    booking = { ...booking, publicUrl: redirectUrl.trim() };
+  }
+  const bookingUnitItems = buildUnitItemsForBooking(booking, {});
+  const rootValue = { ...booking, unitItems: bookingUnitItems };
+  const translatedBooking = await translateBooking({
+    rootValue,
+    typeDefs: bookingTypeDefs,
+    query: bookingQuery,
+    apiEndpoint: baseUrl,
+    tenant,
+  });
+  if (Array.isArray(bookingUnitItems) && bookingUnitItems.length > 0) {
+    translatedBooking.unitItems = bookingUnitItems;
+  }
+  return { booking: translatedBooking };
+}
+
+function getActivityInfo({
+  availabilityKey,
+  jwtKey,
+  unitItems,
+  currency,
+  product,
+}) {
+  let availabilityMetadata = {};
+
+  if (availabilityKey) {
+    try {
+      availabilityMetadata = jwt.verify(availabilityKey, jwtKey);
+    } catch (err) {
+      console.error('Error decoding availability key:', err.message);
+      throw new Error('Invalid availabilityKey');
+    }
+  }
+
+  const keyUnitItems = Array.isArray(availabilityMetadata.unitItems) ? availabilityMetadata.unitItems : [];
+  const providedUnitItems = Array.isArray(unitItems) ? unitItems : [];
+  const finalUnitItems = keyUnitItems.length > 0 ? keyUnitItems : providedUnitItems;
+
+  const bookingCurrency = currency
+    || availabilityMetadata.currency
+    || 'USD';
+
+  const rateIdFromKey = availabilityMetadata.rateId;
+  const parsedRateId = rateIdFromKey && !Number.isNaN(Number(rateIdFromKey))
+    ? Number(rateIdFromKey)
+    : null;
+
+  const startTimeIdRaw = availabilityMetadata.startTimeId || availabilityMetadata.availabilityId || null;
+  const parsedStartTimeId = startTimeIdRaw && !Number.isNaN(Number(startTimeIdRaw))
+    ? Number(startTimeIdRaw)
+    : startTimeIdRaw;
+
+  const activityIdFromKey = availabilityMetadata.productId;
+  const bookingDate = availabilityMetadata.localDateTimeStart
+    ? moment(availabilityMetadata.localDateTimeStart).format(TRAVEL_DATE_FORMAT)
+    : null;
+
+  const activityIdRaw = activityIdFromKey || (product && (product.productId || product.id));
+  const parsedActivityId = activityIdRaw != null && !Number.isNaN(Number(activityIdRaw))
+    ? Number(activityIdRaw)
+    : activityIdRaw;
+
+  return {
+    finalUnitItems,
+    bookingCurrency,
+    parsedRateId,
+    parsedStartTimeId,
+    bookingDate,
+    parsedActivityId,
+  };
+}
+
 class Plugin {
   constructor(params) {
     Object.entries(params).forEach(([attr, value]) => {
@@ -1042,6 +1262,13 @@ class Plugin {
     this.accessKey = this.accessKey || process.env.ti2_bokun_accessKey;
     this.secretKey = this.secretKey || process.env.ti2_bokun_secretKey;
 
+    // Per-instance cache for the Bokun country list keyed by baseUrl.
+    // Populated lazily by getCreateBookingFields and reused across calls
+    // for the configured TTL (defaults to 7 days). Each cache entry is
+    // either { options, expiresAt } once resolved, or { promise, expiresAt: 0 }
+    // while a fetch is in flight (de-duplicates concurrent callers).
+    this.countriesCacheByBaseUrl = new Map();
+
     this.getCredentials = (token = {}) => {
       const accessKey = token.accessKey || this.accessKey || process.env.ti2_bokun_accessKey;
       const secretKey = token.secretKey || this.secretKey || process.env.ti2_bokun_secretKey;
@@ -1275,72 +1502,66 @@ class Plugin {
     return this.searchAvailability({ axios, token, payload, typeDefsAndQueries });
   }
 
-  async searchPickupPoints({
-    axios,
-    token,
-    payload: { productId },
-    typeDefsAndQueries: { pickupTypeDefs, pickupQuery },
-  }) {
-    const { endpoint, testMode } = token || {};
-    const { accessKey, secretKey } = this.getCredentials(token);
-    const baseUrl = testMode ? 'https://api.bokuntest.com' : (endpoint || this.endpoint || 'https://api.bokun.io');
-    const path = `/activity.json/${productId}/pickup-places`;
-    const { url, pathForSigning } = buildRequestUrlAndPath(baseUrl, path);
-    const headers = getHeaders({
-      accessKey,
-      secretKey,
-      method: 'GET',
-      path: pathForSigning,
-    });
-
-    try {
-      const response = await axios({
-        method: 'get',
-        url,
-        headers,
-      });
-
-      const pickupPoints = R.pathOr([], ['data'], response);
-
-      const translatedPoints = await Promise.map(pickupPoints, async point => (
-        translatePickupPoint({
-          rootValue: point,
-          typeDefs: pickupTypeDefs,
-          query: pickupQuery,
-        })
-      ), { concurrency: CONCURRENCY });
+  async getCreateBookingFields({ axios, token, payload = {}, query = {} } = {}) {
+    const requestData = Object.keys(query).length > 0 ? query : payload;
+    const { productId } = requestData;
+
+    // Fetch the per-product booking questions and the global country list in
+    // parallel. The country list is cached for COUNTRIES_CACHE_TTL_MS so
+    // subsequent calls reuse the result and only the question fetch hits the
+    // network. We only allow a country fetch when we'd already be calling
+    // Bokun for questions — otherwise we return the static list and avoid
+    // adding HTTP traffic to caller-supplied flows.
+    const [productQuestionPayload, countryOptions] = await Promise.all([
+      fetchMandatoryBookingQuestionsForProduct(this, { axios, token, productId }),
+      fetchCountriesList(this, {
+        axios,
+        token,
+        useNetwork: true,
+      }),
+    ]);
+    const { leadPassengerContactInfo, passengerContactInfo, bookingQuestions } = productQuestionPayload;
+    const expandedLeadPassengerContactInfo = expandRequiredCustomerQuestionIds(leadPassengerContactInfo);
+    const expandedPassengerContactInfo = expandRequiredCustomerQuestionIds(passengerContactInfo);
+    const fieldsWithPassengerFlags = applyPassengerFieldsToUiFields(
+      expandedLeadPassengerContactInfo,
+      expandedPassengerContactInfo,
+    );
+    const fields = decorateCountryFields(fieldsWithPassengerFlags, countryOptions);
+    const customFields = buildCustomFieldsFromQuestions([
+      bookingQuestions,
+    ]);
 
-      return ({ pickupPoints: translatedPoints });
-    } catch (err) {
-      console.error('Error fetching pickup points:', err.response?.data || err.message);
-      throw err;
-    }
-  }
+    const excludedCustomerFieldIds = new Set(
+      (Array.isArray(DEFAULT_EXCLUDED_CUSTOMER_QUESTION_IDS) ? DEFAULT_EXCLUDED_CUSTOMER_QUESTION_IDS : [])
+        .map(id => String(id || '').trim())
+        .filter(Boolean),
+    );
 
-  // eslint-disable-next-line class-methods-use-this
-  async getCreateBookingFields() {
-    const fields = [
-      { id: 'firstName', title: 'First name', type: 'short', required: true },
-      { id: 'lastName', title: 'Last name', type: 'short', required: true },
-      { id: 'emailAddress', title: 'Email', type: 'short', required: true },
-      { id: 'phoneNumber', title: 'Phone', type: 'short', required: false },
-      { id: 'country', title: 'Country', type: 'short', required: false },
-      { id: 'postalCode', title: 'Postal code', type: 'short', required: false },
-    ];
-
-    // Optional per-product custom booking questions can be added later.
-    const customFields = [];
-    return { fields, customFields };
-  }
+    const additionalCustomerFields = fields
+      .filter(field => field && field.visiblePerBooking)
+      .filter(field => !excludedCustomerFieldIds.has(String(field.id || '').trim()))
+      .map(field => ({ ...field, required: Boolean(field.requiredPerBooking), isCustomerField: true }));
 
-  async getCreateItineraryFields(args = {}) {
-    return this.getCreateBookingFields(args);
+    return { fields, customFields, additionalCustomerFields };
   }
 
   /**
    * Create a booking using Bokun checkout endpoints.
-   * - Uses /checkout.json/submit with directBooking
-   * - Then /checkout.json/confirm-reserved/{code} to confirm reservation
+   * - POST /checkout.json/submit with directBooking
+   * - POST /checkout.json/confirm-reserved/{code}
+   *
+   * @param {Object} args
+   * @param {Object} args.axios - axios instance for the outbound calls
+   * @param {Object} args.token - vendor token (provides credentials/endpoint)
+   * @param {Object} args.payload - booking payload from the UI
+   * @param {Object} args.typeDefsAndQueries - GraphQL typeDefs/query used to translate the response
+   * @returns {Promise<{ booking: Object|null, error?: string }>} On success
+   *   `{ booking }`. On checkout failures, missing confirmation code, or
+   *   options preflight validation failure, `{ booking: null, error }`.
+   * @throws {Error} When `holder` contact validation fails (invalid/missing
+   *   email, etc.) or when `availabilityKey` cannot be decoded — same contract
+   *   as earlier versions that threw on invalid contact email.
    */
   async createBooking({
     axios,
@@ -1355,53 +1576,80 @@ class Plugin {
       integrationIsDirectBooking = false,
       product,
       unitItems,
+      participants = [],
       currency,
+      mainContactDetails: providedMainContactDetails = [],
+      activityAnswers = [],
+      customFieldValues = [],
+      dateFormat: customFieldDateFormat,
+      sendNotificationToMainContact = true,
     } = payload;
-
     const { endpoint, testMode } = token || {};
     const { accessKey, secretKey } = this.getCredentials(token);
     const jwtKey = this.getJwtKey(token);
     assert(jwtKey, 'JWT secret should be set for availability keys');
 
     const baseUrl = testMode ? 'https://api.bokuntest.com' : (endpoint || this.endpoint || 'https://api.bokun.io');
-    let availabilityMetadata = {};
-
-    if (availabilityKey) {
-      try {
-        availabilityMetadata = jwt.verify(availabilityKey, jwtKey);
-      } catch (err) {
-        console.error('Error decoding availability key:', err.message);
-        throw new Error('Invalid availabilityKey');
-      }
-    }
-
-    const keyUnitItems = Array.isArray(availabilityMetadata.unitItems) ? availabilityMetadata.unitItems : [];
-    const providedUnitItems = Array.isArray(unitItems) ? unitItems : [];
-    const finalUnitItems = keyUnitItems.length > 0 ? keyUnitItems : providedUnitItems;
-
-    const bookingCurrency = currency
-      || availabilityMetadata.currency
-      || 'USD';
-
-    const rateIdFromKey = availabilityMetadata.rateId;
-    const parsedRateId = rateIdFromKey && !Number.isNaN(Number(rateIdFromKey))
-      ? Number(rateIdFromKey)
-      : null;
-
-    const startTimeIdRaw = availabilityMetadata.startTimeId || availabilityMetadata.availabilityId || null;
-    const parsedStartTimeId = startTimeIdRaw && !Number.isNaN(Number(startTimeIdRaw))
-      ? Number(startTimeIdRaw)
-      : startTimeIdRaw;
-
-    const activityIdFromKey = availabilityMetadata.productId;
-    const bookingDate = availabilityMetadata.localDateTimeStart
-      ? moment(availabilityMetadata.localDateTimeStart).format('YYYY-MM-DD')
-      : null;
+    const {
+      finalUnitItems,
+      bookingCurrency,
+      parsedRateId,
+      parsedStartTimeId,
+      bookingDate,
+      parsedActivityId,
+    } = getActivityInfo({
+      availabilityKey,
+      jwtKey,
+      unitItems,
+      currency,
+      product,
+    });
 
-    const activityIdRaw = activityIdFromKey || (product && (product.productId || product.id));
-    const parsedActivityId = activityIdRaw != null && !Number.isNaN(Number(activityIdRaw))
-      ? Number(activityIdRaw)
-      : activityIdRaw;
+    // Validate basic contact details first (no network). If the only failure
+    // is country resolution (or phone format dependent on country), retry once
+    // with the live country list so newly-added Bokun countries are accepted.
+    let contactInfo = validateContactInfo(holder);
+    if (shouldRetryContactValidationWithDynamicCountries(contactInfo, holder)) {
+      const countryOptions = await fetchCountriesList(this, { axios, token });
+      contactInfo = validateContactInfo(holder, { countryOptions });
+    }
+    if (!contactInfo.ok) {
+      const contactErrors = getContactValidationErrors(contactInfo);
+      const contactErrorMessage = contactErrors.join(', ');
+      console.error('Error creating booking: ', contactErrorMessage);
+      throw new Error(contactErrorMessage);
+    }
+    const defaultMainContactDetails = getMainContactDetails(contactInfo.contact);
+    const providedMainContactDetailsNormalized = normalizeQuestionAnswerList(providedMainContactDetails);
+    const mergedMainContactDetailsByQuestionId = {};
+    defaultMainContactDetails.forEach(answer => {
+      const normalizedAnswer = normalizeMainContactAnswer(answer);
+      if (!normalizedAnswer?.questionId) return;
+      mergedMainContactDetailsByQuestionId[normalizedAnswer.questionId] = normalizedAnswer;
+    });
+    providedMainContactDetailsNormalized.forEach(answer => {
+      const normalizedAnswer = normalizeMainContactAnswer(answer);
+      if (!normalizedAnswer?.questionId) return;
+      mergedMainContactDetailsByQuestionId[normalizedAnswer.questionId] = normalizedAnswer;
+    });
+    const normalizedActivityAnswers = normalizeQuestionAnswerList(activityAnswers);
+    const {
+      bookingAnswers,
+      passengerAnswersByIndex,
+      customerAnswers,
+    } = mapCustomFieldValuesToAnswers(customFieldValues, {
+      normalizeFieldValue: ({ field, value }) => normalizeCustomFieldValueForBooking({
+        field,
+        value,
+        inputDateFormat: customFieldDateFormat,
+      }),
+    });
+    customerAnswers.forEach(answer => {
+      const normalizedAnswer = normalizeMainContactAnswer(answer);
+      if (!normalizedAnswer?.questionId) return;
+      mergedMainContactDetailsByQuestionId[normalizedAnswer.questionId] = normalizedAnswer;
+    });
+    const mainContactDetails = Object.values(mergedMainContactDetailsByQuestionId);
 
     const source = DIRECTBOOKING_SOURCE;
     const checkoutOption = integrationIsDirectBooking
@@ -1409,71 +1657,88 @@ class Plugin {
       : CHECKOUT_OPTION_AGENT_RESERVATION;
     const paymentMethod = PAYMENT_METHOD;
 
-    const toTranslatedBooking = async bookingPayload => {
-      let booking = R.path(['data', 'booking'], bookingPayload)
-        || R.path(['data'], bookingPayload)
-        || bookingPayload?.booking
-        || bookingPayload;
-      const redirectUrl = R.path(['data', 'redirectRequest', 'url'], bookingPayload);
-      if (typeof redirectUrl === 'string' && /^https?:\/\//i.test(redirectUrl.trim()) && !booking.publicUrl) {
-        booking = { ...booking, publicUrl: redirectUrl.trim() };
-      }
-      const bookingUnitItems = buildUnitItemsForBooking(booking, {});
-      const rootValue = { ...booking, unitItems: bookingUnitItems };
-      const translatedBooking = await translateBooking({
-        rootValue,
-        typeDefs: bookingTypeDefs,
-        query: bookingQuery,
-        apiEndpoint: baseUrl,
-        tenant: token.tenant,
-      });
-      if (Array.isArray(bookingUnitItems) && bookingUnitItems.length > 0) {
-        translatedBooking.unitItems = bookingUnitItems;
-      }
-      return { booking: translatedBooking };
-    };
-
     // Booking flow via checkout:
     // 1) POST /checkout.json/submit with directBooking
     // 2) POST /checkout.json/confirm-reserved/{code}
 
-    const passengersArray = (Array.isArray(finalUnitItems) ? finalUnitItems : []).map(item => ({
-      pricingCategoryId: item.unitId != null ? Number(item.unitId) : undefined,
-      ...(item.quantity ? { quantity: item.quantity } : {}),
-    })).filter(item => item.pricingCategoryId != null);
+    // Expand unit items so every passenger gets its own entry (quantity: 1).
+    // A unit item with quantity N becomes N individual entries so that
+    // participants[i].fields maps cleanly onto the i-th passenger.
+    const expandedUnitItems = [];
+    (Array.isArray(finalUnitItems) ? finalUnitItems : []).forEach(item => {
+      const qty = Number(item.quantity) || 1;
+      let q = 0;
+      while (q < qty) {
+        expandedUnitItems.push({ ...item, quantity: 1 });
+        q += 1;
+      }
+    });
 
+    const passengersArray = expandedUnitItems.map((item, passengerIndex) => {
+      // Answers from the JWT availability key (booking-question answers per passenger)
+      const itemAnswers = normalizeQuestionAnswerList(item.answers)
+        .map(a => ({ ...a, passengerIndex }));
+
+      // Per-passenger answers from participants[i].fields (UI form).
+      // Each entry: { field: { id, type, isPerUnitItem, ... }, value }
+      const participant = Array.isArray(participants) ? participants[passengerIndex] : undefined;
+      // customFieldValues → per-passenger booking-question answers (sent as answers with passengerIndex)
+      const participantCustomFieldValues = participant?.customFieldValues || [];
+      // fields → per-passenger contact info (handled separately, explained below)
+      const participantContactFields = participant?.fields || [];
+
+      console.log('SACHIN participantCustomFieldValues: ', JSON.stringify(participantCustomFieldValues, null, 2));
+      console.log('SACHIN participantContactFields: ', JSON.stringify(participantContactFields, null, 2));
+      const participantAnswers = participantCustomFieldValues
+        .map(entry => {
+          const questionId = entry?.field?.id || entry?.field?.questionId;
+          if (!questionId) return null;
+          const raw = entry.value;
+          const values = (Array.isArray(raw) ? raw : [raw])
+            .filter(v => v != null && v !== '');
+          if (values.length === 0) return null;
+          return { questionId: String(questionId), values, passengerIndex };
+        })
+        .filter(Boolean);
+
+      console.log('SACHIN participantAnswers: ', JSON.stringify(participantAnswers, null, 2));
+      const passengerDetails = participantContactFields
+        .map(entry => {
+          const questionId = entry?.field?.id || entry?.field?.questionId;
+          if (!questionId) return null;
+          const raw = entry.value;
+          const values = (Array.isArray(raw) ? raw : [raw])
+            .map(v => normalizePassengerDetailValue({ questionId, value: v }))
+            .filter(v => v != null && v !== '');
+          if (values.length === 0) return null;
+          return { questionId: String(questionId), values, passengerIndex };
+        })
+        .filter(Boolean);
+
+      console.log('SACHIN passengerDetails: ', JSON.stringify(passengerDetails, null, 2));
+      // Indexed customFieldValues (field|N suffix) also scoped to this passenger
+      const indexedAnswers = (passengerAnswersByIndex[passengerIndex] || [])
+        .map(a => ({ ...a, passengerIndex }));
+
+      const allAnswers = [...itemAnswers, ...participantAnswers, ...indexedAnswers];
+
+      return {
+        pricingCategoryId: item.unitId != null ? Number(item.unitId) : undefined,
+        quantity: 1,
+        ...(allAnswers.length > 0 ? { answers: allAnswers } : {}),
+        ...(passengerDetails.length > 0 ? { passengerDetails } : {}),
+      };
+    }).filter(item => item.pricingCategoryId != null);
     const activityBookingRequest = {
       activityId: parsedActivityId,
       ...(parsedRateId != null ? { rateId: parsedRateId } : {}),
       ...(bookingDate ? { date: bookingDate } : {}),
       ...(parsedStartTimeId ? { startTimeId: parsedStartTimeId } : {}),
+      ...((normalizedActivityAnswers.length > 0 || bookingAnswers.length > 0)
+        ? { answers: [...normalizedActivityAnswers, ...bookingAnswers] }
+        : {}),
       passengers: passengersArray,
     };
-
-    const firstNameValue = holder?.firstName || (holder?.name ? holder.name.split(' ')[0] : '') || '';
-    const rawLastName = holder?.surname || (holder?.name ? holder.name.split(' ').slice(1).join(' ') : '') || '';
-    const lastNameValue = rawLastName || firstNameValue || 'Guest';
-    const activityEmailCheck = validateBookingEmail(holder?.email || holder?.emailAddress);
-    if (!activityEmailCheck.ok) {
-      throw new Error(activityEmailCheck.error);
-    }
-    const emailValue = activityEmailCheck.email;
-
-    const mainContactDetails = [
-      {
-        questionId: 'firstName',
-        values: [firstNameValue],
-      },
-      {
-        questionId: 'lastName',
-        values: [lastNameValue],
-      },
-      {
-        questionId: 'email',
-        values: [emailValue],
-      },
-    ];
-
     const directBooking = {
       mainContactDetails,
       activityBookings: [activityBookingRequest],
@@ -1485,11 +1750,53 @@ class Plugin {
       paymentMethod,
       source,
       directBooking,
-      sendNotificationToMainContact: true,
+      sendNotificationToMainContact,
       showPricesInNotification: true,
       currency: bookingCurrency,
     };
 
+    try {
+      const optionsPath = `/checkout.json/options/booking-request?currency=${
+        encodeURIComponent(bookingCurrency)
+      }&lang=EN`;
+      const {
+        url: optionsUrl,
+        pathForSigning: optionsPathForSigning,
+      } = buildRequestUrlAndPath(baseUrl, optionsPath);
+      const optionsHeaders = getHeaders({
+        accessKey,
+        secretKey,
+        method: 'POST',
+        path: optionsPathForSigning,
+      });
+      const optionsResponse = await axios({
+        method: 'post',
+        url: optionsUrl,
+        headers: optionsHeaders,
+        data: directBooking,
+      });
+      const optionsData = R.pathOr({}, ['data'], optionsResponse);
+      const requiredQuestions = extractRequiredQuestions(optionsData);
+
+      const requiredFieldError = validateRequiredContactFields({
+        requiredQuestions,
+        mainContactDetails: directBooking.mainContactDetails,
+        sendNotificationToMainContact,
+      });
+      if (requiredFieldError) {
+        console.error('Error creating booking via checkout:', requiredFieldError);
+        return { booking: null, error: requiredFieldError };
+      }
+    } catch (optionsErr) {
+      // Best-effort: don't block booking creation if Bokun's options endpoint
+      // is unavailable. Surface as a warning so it doesn't trip error alarms.
+      console.warn(
+        'Could not fetch required booking questions (status %s): %j',
+        optionsErr.response?.status || 'n/a',
+        optionsErr.response?.data || optionsErr.message,
+      );
+    }
+
     const submitPath = '/checkout.json/submit?lang=EN';
     const { url: submitUrl, pathForSigning: submitPathForSigning } = buildRequestUrlAndPath(baseUrl, submitPath);
     const submitHeaders = getHeaders({
@@ -1538,7 +1845,7 @@ class Plugin {
       const bookingConfirmationBody = {
         externalBookingReference: externalBookingReference || null,
         showPricesInNotification: true,
-        sendNotificationToMainContact: true,
+        sendNotificationToMainContact,
         amount: amountForConfirmation,
         currency: bookingCurrency,
       };
@@ -1550,56 +1857,24 @@ class Plugin {
         data: bookingConfirmationBody,
       });
 
-      return await toTranslatedBooking(confirmResponse);
+      return await toTranslatedBooking({
+        bookingPayload: confirmResponse,
+        bookingTypeDefs,
+        bookingQuery,
+        baseUrl,
+        tenant: token.tenant,
+      });
     } catch (err) {
       const details = err.response?.data || err.message;
+      const errorMessage = extractBokunErrorMessage(err);
       console.error('Error creating booking via checkout:', details);
-      return { booking: null, error: typeof details === 'string' ? details : JSON.stringify(details) };
+      return {
+        booking: null,
+        error: errorMessage || (typeof details === 'string' ? details : JSON.stringify(details)),
+      };
     }
   }
 
-  // /**
-  //  * Get checkout options for a booking request.
-  //  * Wraps POST /checkout.json/options/booking-request
-  //  * Schema: body is BookingRequest, response is Checkout.
-  //  */
-  // async checkoutOptionsForBookingRequest({
-  //   axios,
-  //   token,
-  //   payload = {},
-  // }) {
-  //   const { endpoint, testMode } = token || {};
-  //   const { accessKey, secretKey } = this.getCredentials(token);
-  //   const baseUrl = testMode ? 'https://api.bokuntest.com' : (endpoint || this.endpoint || 'https://api.bokun.io');
-
-  //   const { bookingRequest } = payload;
-  //   assert(bookingRequest, 'bookingRequest is required for checkoutOptionsForBookingRequest');
-
-  //   const path = '/checkout.json/options/booking-request';
-  //   const { url, pathForSigning } = buildRequestUrlAndPath(baseUrl, path);
-  //   const headers = getHeaders({
-  //     accessKey,
-  //     secretKey,
-  //     method: 'POST',
-  //     path: pathForSigning,
-  //   });
-
-  //   try {
-  //     const response = await axios({
-  //       method: 'post',
-  //       url,
-  //       headers,
-  //       data: bookingRequest,
-  //     });
-  //     const checkout = R.pathOr({}, ['data'], response);
-  //     return { checkout };
-  //   } catch (err) {
-  //     const details = err.response?.data || err.message;
-  //     console.error('Error fetching checkout options for booking request:', details);
-  //     return { checkout: null, error: typeof details === 'string' ? details : JSON.stringify(details) };
-  //   }
-  // }
-
   async cancelBooking({
     axios,
     token,