@coras-io/embed 0.1.0

package/dist/views/payment-page/payment-page.utils.js

@@ -0,0 +1,906 @@
+import { msg } from "@lit/localize";
+import { apiGet, withErrorHandling } from "../../core/api/queries.js";
+/**
+ * Capitalizes the first letter of a string and replaces underscores with spaces
+ */
+export const capitalizeFirstLetter = (str) => {
+    if (!str)
+        return "";
+    return str.charAt(0).toUpperCase() + str.slice(1).replace(/_/g, " ");
+};
+/**
+ * Gets the default phone code selection based on locale.
+ * Extracts the country code from the locale (e.g., "en-IE" -> "IE")
+ * and finds the matching country. Falls back to first country if no match.
+ */
+export const getDefaultPhoneCode = (countries, locale) => {
+    if (!countries || countries.length === 0) {
+        return null;
+    }
+    // Extract country code from locale (e.g., "en-IE" -> "IE", "de-DE" -> "DE")
+    const localeCountryCode = locale?.split("-")[1]?.toUpperCase();
+    // Try to find the country matching the locale
+    let defaultCountry = localeCountryCode
+        ? countries.find((country) => country.code === localeCountryCode)
+        : undefined;
+    // Fall back to first available country if locale country not found
+    if (!defaultCountry) {
+        defaultCountry = countries[0];
+    }
+    if (defaultCountry) {
+        return {
+            name: defaultCountry.name || "",
+            code: defaultCountry.code || "",
+            phoneCode: String(defaultCountry.phone_code || ""),
+        };
+    }
+    return null;
+};
+/**
+ * Gets the value of a field from the form values.
+ * Values are automatically trimmed to remove leading/trailing whitespace,
+ * which prevents validation errors from the API when fields are autocompleted.
+ */
+export const getFieldValue = (fieldName, formValues) => {
+    let value;
+    // For reservation fields, get the value from the nested structure if available
+    if (fieldName && fieldName.startsWith("reservation_")) {
+        const parts = fieldName.split("_");
+        const reservationId = parts[1];
+        // Check if this is a reservation-level field or a ticket-level field
+        if (parts[2] === "ticket") {
+            // This is a ticket-level field
+            const ticketId = parts[3];
+            const field = parts.slice(4).join("_");
+            // Check if reservationId, ticketId, and field are defined
+            if (reservationId && ticketId && field) {
+                // Try to get the value from the nested structure
+                if (formValues.reservations &&
+                    formValues.reservations[reservationId] &&
+                    formValues.reservations[reservationId][ticketId] &&
+                    formValues.reservations[reservationId][ticketId][field] !== undefined) {
+                    value = formValues.reservations[reservationId][ticketId][field];
+                    return value.trim();
+                }
+            }
+        }
+        else {
+            // This is a reservation-level field
+            const field = parts.slice(2).join("_");
+            // Check if reservationId and field are defined
+            if (reservationId && field) {
+                // Try to get the value from the nested structure
+                if (formValues.reservations &&
+                    formValues.reservations[reservationId] &&
+                    formValues.reservations[reservationId].requirements &&
+                    formValues.reservations[reservationId].requirements[field] !==
+                        undefined) {
+                    value = formValues.reservations[reservationId].requirements[field];
+                    return value.trim();
+                }
+            }
+        }
+    }
+    // Fall back to the flat structure
+    value = formValues[fieldName] || "";
+    return value.trim();
+};
+/**
+ * Handles form value changes and updates the form values object
+ */
+export const handleFormValueChange = (fieldName, value, formValues) => {
+    // Create a deep copy of the current formValues
+    const newFormValues = { ...formValues };
+    // Check if this is a reservation field
+    if (fieldName && fieldName.startsWith("reservation_")) {
+        // Parse the field name to extract reservation ID, ticket ID (if present), and field name
+        const parts = fieldName.split("_");
+        const reservationId = parts[1];
+        // Check if this is a reservation-level field or a ticket-level field
+        if (parts[2] === "ticket") {
+            // This is a ticket-level field
+            const ticketId = parts[3];
+            const field = parts.slice(4).join("_"); // In case the field name contains underscores
+            // Check if reservationId and ticketId are defined
+            if (reservationId && ticketId && field) {
+                // Initialize the reservations object if it doesn't exist
+                if (!newFormValues.reservations) {
+                    newFormValues.reservations = {};
+                }
+                // Initialize the nested objects if they don't exist
+                if (!newFormValues.reservations[reservationId]) {
+                    newFormValues.reservations[reservationId] = {};
+                }
+                if (!newFormValues.reservations[reservationId][ticketId]) {
+                    newFormValues.reservations[reservationId][ticketId] = {};
+                }
+                // Set the value in the nested structure
+                newFormValues.reservations[reservationId][ticketId][field] = value;
+            }
+        }
+        else {
+            // This is a reservation-level field
+            const field = parts.slice(2).join("_"); // In case the field name contains underscores
+            // Check if reservationId and field are defined
+            if (reservationId && field) {
+                // Initialize the reservations object if it doesn't exist
+                if (!newFormValues.reservations) {
+                    newFormValues.reservations = {};
+                }
+                // Initialize the nested objects if they don't exist
+                if (!newFormValues.reservations[reservationId]) {
+                    newFormValues.reservations[reservationId] = {};
+                }
+                if (!newFormValues.reservations[reservationId].requirements) {
+                    newFormValues.reservations[reservationId].requirements = {};
+                }
+                // Set the value in the nested structure
+                newFormValues.reservations[reservationId].requirements[field] = value;
+            }
+        }
+        // Also keep the flat structure for backward compatibility
+        newFormValues[fieldName] = value;
+    }
+    else {
+        // For regular fields, use the flat structure
+        newFormValues[fieldName] = value;
+    }
+    return newFormValues;
+};
+/**
+ * Checks if the form has a name field requirement
+ */
+export const hasNameField = (data) => {
+    if (!data?.general?.requirements)
+        return false;
+    return data.general.requirements.some((req) => req.field === "first_name" || req.field === "second_name");
+};
+/**
+ * Checks if the form has a first name field requirement
+ */
+export const hasFirstNameField = (data) => {
+    if (!data?.general?.requirements)
+        return false;
+    return data.general.requirements.some((req) => req.field === "first_name");
+};
+/**
+ * Checks if the form has a second name field requirement
+ */
+export const hasSecondNameField = (data) => {
+    if (!data?.general?.requirements)
+        return false;
+    return data.general.requirements.some((req) => req.field === "second_name");
+};
+/**
+ * Checks if the form has a phone field requirement
+ */
+export const hasPhoneField = (data) => {
+    if (!data?.general?.requirements)
+        return false;
+    return data.general.requirements.some((req) => req.field === "phone_number");
+};
+/**
+ * Checks if the form has an email field requirement
+ */
+export const hasEmailField = (data) => {
+    if (!data?.general?.requirements)
+        return false;
+    return data.general.requirements.some((req) => req.field === "email");
+};
+/**
+ * Validates a single field and returns the error message if invalid
+ */
+export const validateField = (fieldName, value, formErrors, FIELDS, required, context) => {
+    const newErrors = { ...formErrors };
+    // For custom fields from ticket or reservation requirements
+    if (fieldName && fieldName.startsWith("reservation_")) {
+        // Apply required validator to all requirement fields
+        const error = required({ value });
+        newErrors[fieldName] = error || "";
+        return { isValid: !error, errors: newErrors };
+    }
+    const fieldConfig = FIELDS[fieldName];
+    if (!fieldConfig || !fieldConfig.validators) {
+        newErrors[fieldName] = "";
+        return { isValid: true, errors: newErrors };
+    }
+    const error = fieldConfig.validators({ value, context });
+    newErrors[fieldName] = error || "";
+    return { isValid: !error, errors: newErrors };
+};
+/**
+ * Validates the entire form and returns whether it's valid and updated errors
+ * @param shouldValidateBillingAddress - Optional override to control billing address validation.
+ *   When true, validates billing address fields if required by API.
+ *   When false, skips billing address validation regardless of API requirements.
+ *   When undefined, uses the API requirements to determine if validation is needed.
+ */
+export const validateForm = (formValues, formErrors, FIELDS, required, checkData, shouldValidateBillingAddress, contextProvider) => {
+    let isValid = true;
+    let newErrors = { ...formErrors };
+    const validateFieldFn = (fieldName) => {
+        // Get the value using the utility function
+        const value = getFieldValue(fieldName, formValues);
+        const context = contextProvider?.(fieldName);
+        // Validate the field
+        const result = validateField(fieldName, value, newErrors, FIELDS, required, context);
+        newErrors = result.errors;
+        if (!result.isValid) {
+            isValid = false;
+        }
+    };
+    // Validate only fields that are displayed based on requirements
+    if (hasFirstNameField(checkData)) {
+        validateFieldFn("first_name");
+    }
+    if (hasSecondNameField(checkData)) {
+        validateFieldFn("second_name");
+    }
+    if (hasPhoneField(checkData)) {
+        validateFieldFn("phone");
+    }
+    if (hasEmailField(checkData)) {
+        validateFieldFn("email");
+    }
+    // Validate billing address fields only when they are displayed.
+    // Defaults to true for backward compatibility, but callers should always pass the parameter.
+    const validateBillingAddress = shouldValidateBillingAddress ?? true;
+    if (validateBillingAddress) {
+        validateFieldFn("addressLine1");
+        validateFieldFn("city");
+        validateFieldFn("postcode");
+        validateFieldFn("country");
+        // addressLine2 is optional, so we don't validate it
+    }
+    // Validate custom fields from ticket requirements
+    if (checkData?.reservations) {
+        for (const reservation of checkData.reservations) {
+            // PP-004: Validate reservation-level requirements (e.g., pickup_point)
+            if (reservation.requirements) {
+                for (const requirement of reservation.requirements) {
+                    const fieldName = `reservation_${reservation.id}_${requirement.field}`;
+                    validateFieldFn(fieldName);
+                }
+            }
+            // Validate ticket-level requirements
+            if (reservation.tickets) {
+                for (const ticket of reservation.tickets) {
+                    if (ticket.requirements) {
+                        for (const requirement of ticket.requirements) {
+                            const fieldName = `reservation_${reservation.id}_ticket_${ticket.id}_${requirement.field}`;
+                            validateFieldFn(fieldName);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return { isValid, errors: newErrors };
+};
+export { filterCountries } from "../../components/phone-field/phone-field.utils.js";
+/**
+ * Finds the country name matching a geolocation code.
+ */
+export const getDefaultCountry = (countries, code) => {
+    if (!code || countries.length === 0)
+        return "";
+    const upperCode = code.toUpperCase();
+    const match = countries.find((c) => c.code?.toUpperCase() === upperCode);
+    return match?.name || "";
+};
+/**
+ * Calculates the shortest expiration time from reservations
+ */
+export function getShortestExpirationSeconds(reservations) {
+    if (!reservations || reservations.length === 0)
+        return 0;
+    let min = Number.MAX_SAFE_INTEGER;
+    for (const reservation of reservations) {
+        const exp = reservation.expires_in;
+        if (exp > 0 && exp < min) {
+            min = exp;
+        }
+    }
+    return min === Number.MAX_SAFE_INTEGER ? 0 : min;
+}
+/**
+ * Calculates the total ticket quantity from reservations
+ */
+export function getTotalQuantity(reservations) {
+    if (!reservations || reservations.length === 0)
+        return 0;
+    let total = 0;
+    for (const reservation of reservations) {
+        total += reservation.number_of_tickets || 0;
+    }
+    return total;
+}
+/**
+ * Calculates total price from reservation data
+ */
+export function getTotalPrice(data) {
+    if (!data)
+        return 0;
+    if (typeof data.total_price === "number") {
+        return data.total_price;
+    }
+    if (data.reservations && data.reservations.length > 0) {
+        let price = 0;
+        for (const reservation of data.reservations) {
+            price += reservation.total_price || 0;
+        }
+        return price;
+    }
+    return 0;
+}
+/**
+ * Prepares customer data from form values
+ */
+export function prepareCustomerData(formValues, selectedPhoneCode, findCountryCode, hasBillingAddressFields) {
+    const firstName = getFieldValue("first_name", formValues);
+    const secondName = getFieldValue("second_name", formValues);
+    const name = getFieldValue("name", formValues);
+    const email = getFieldValue("email", formValues);
+    const phone = getFieldValue("phone", formValues);
+    const phoneCode = selectedPhoneCode?.phoneCode || "";
+    const countryName = getFieldValue("country", formValues);
+    const countryCode = findCountryCode(countryName);
+    const customerData = {
+        name: name || `${firstName} ${secondName}`.trim(),
+        email,
+        phone: phone ? `${phoneCode}${phone}` : undefined,
+        address: {
+            line1: getFieldValue("addressLine1", formValues),
+            line2: getFieldValue("addressLine2", formValues),
+            city: getFieldValue("city", formValues),
+            postal_code: getFieldValue("postcode", formValues),
+            country: countryCode,
+        },
+    };
+    return {
+        ...customerData,
+        address: hasBillingAddressFields ? customerData.address : undefined,
+    };
+}
+/**
+ * Prepares reservation data with requirements
+ */
+export function prepareReservationData(reservations, getFieldValue) {
+    const reservationIds = [];
+    const reservationData = {};
+    reservations.forEach((reservation) => {
+        if (reservation.reservation_id) {
+            reservationIds.push(reservation.reservation_id);
+            // Handle pickup point if available
+            if (reservation.pickup_point) {
+                const requirements = {};
+                // Add pickup point data to requirements
+                Object.entries(reservation.pickup_point).forEach(([key, value]) => {
+                    if (value) {
+                        requirements[key] = value;
+                    }
+                });
+                if (Object.keys(requirements).length > 0) {
+                    reservationData[reservation.reservation_id] = { requirements };
+                }
+            }
+            // Handle attendee information
+            if (reservation.tickets?.length) {
+                const tickets = [];
+                reservation.tickets.forEach((ticket) => {
+                    const ticketId = ticket.ticket_id;
+                    const attendeeRequired = ticket.attendee_required || ticket.attendee_filled;
+                    if (ticketId && attendeeRequired) {
+                        const ticketRequirements = {};
+                        // Get attendee information from form values
+                        const fieldNamePrefix = `reservation_${reservation.reservation_id}_ticket_${ticketId}_`;
+                        // Common attendee fields
+                        const attendeeFields = [
+                            "first_name",
+                            "second_name",
+                            "email",
+                            "phone_number",
+                        ];
+                        attendeeFields.forEach((field) => {
+                            const fieldName = `${fieldNamePrefix}${field}`;
+                            const value = getFieldValue(fieldName);
+                            if (value) {
+                                ticketRequirements[field] = value;
+                            }
+                        });
+                        if (Object.keys(ticketRequirements).length > 0) {
+                            tickets.push({
+                                id: ticketId,
+                                requirements: ticketRequirements,
+                            });
+                        }
+                    }
+                });
+                if (tickets.length > 0) {
+                    if (!reservationData[reservation.reservation_id]) {
+                        reservationData[reservation.reservation_id] = {};
+                    }
+                    reservationData[reservation.reservation_id].tickets = tickets;
+                }
+            }
+        }
+    });
+    return { reservations: reservationIds, reservationData };
+}
+/**
+ * Prepares attendee data for the attendees field in the PUT request to /reservations
+ */
+export function prepareAttendeesData(reservations, reservationsCheck, getFieldValue, selectedPhoneCode) {
+    const attendees = [];
+    let hasRequirements = false;
+    // Check if reservations are returned from the API check
+    if (reservationsCheck?.reservations &&
+        reservationsCheck.reservations.length > 0) {
+        hasRequirements = true;
+    }
+    reservations.forEach((reservation) => {
+        if (reservation.tickets?.length) {
+            reservation.tickets.forEach((ticket) => {
+                const ticketId = ticket.ticket_id;
+                const attendeeRequired = ticket.attendee_required || ticket.attendee_filled;
+                if (ticketId && attendeeRequired) {
+                    hasRequirements = true;
+                    const fieldNamePrefix = `reservation_${reservation.reservation_id}_ticket_${ticketId}_`;
+                    const firstName = getFieldValue(`${fieldNamePrefix}first_name`);
+                    const secondName = getFieldValue(`${fieldNamePrefix}second_name`);
+                    const email = getFieldValue(`${fieldNamePrefix}email`);
+                    const idNumber = getFieldValue(`${fieldNamePrefix}id_number`);
+                    const gender = getFieldValue(`${fieldNamePrefix}gender`);
+                    const city = getFieldValue(`${fieldNamePrefix}city`);
+                    const province = getFieldValue(`${fieldNamePrefix}province`);
+                    const dateOfBirth = getFieldValue(`${fieldNamePrefix}date_of_birth`);
+                    // Handle phone number with country code
+                    const phoneNumberRaw = getFieldValue(`${fieldNamePrefix}phone_number`);
+                    const countryCode = getFieldValue(`${fieldNamePrefix}country_code`) ||
+                        selectedPhoneCode?.code;
+                    // Get dial code (e.g. "353") and prepend to local number
+                    const phoneCode = getFieldValue(`${fieldNamePrefix}phone_code`) ||
+                        selectedPhoneCode?.phoneCode ||
+                        "";
+                    const fullPhone = phoneCode && phoneNumberRaw
+                        ? `${phoneCode}${phoneNumberRaw}`
+                        : phoneNumberRaw;
+                    const phoneNumber = formatPhoneWithPlus(fullPhone);
+                    const attendee = {
+                        ticket_id: ticketId,
+                        first_name: firstName || null,
+                        second_name: secondName || null,
+                        email: email || null,
+                        phone_number: phoneNumber || null,
+                        id_number: idNumber || null,
+                        gender: gender || null,
+                        city: city || null,
+                        province: province || null,
+                        country_code: countryCode || null,
+                        date_of_birth: dateOfBirth || null,
+                    };
+                    attendees.push(attendee);
+                }
+            });
+        }
+    });
+    return { attendees, hasRequirements };
+}
+/**
+ * Type guard for API errors
+ */
+export const isApiError = (err) => {
+    return (typeof err === "object" &&
+        err !== null &&
+        "errors" in err &&
+        typeof err.errors === "object");
+};
+/**
+ * Extracts a user-safe error message from an unknown error.
+ * Returns the fallback message for non-Error objects or errors whose
+ * message looks like an internal/SDK string (stack traces, object dumps).
+ * Callers should provide a domain-specific fallback.
+ */
+export function sanitizeErrorMessage(error, fallback) {
+    if (!(error instanceof Error))
+        return fallback;
+    const message = error.message;
+    // Reject messages that look like internal/SDK details:
+    // - Stack traces or file paths
+    // - Very long messages (likely JSON dumps or debug info)
+    // - Messages containing common internal patterns
+    if (!message ||
+        message.length > 200 ||
+        /\bat\b.*\(/.test(message) ||
+        /\/[a-z_-]+\.(js|ts|mjs)/i.test(message) ||
+        /^\{/.test(message) ||
+        /^\[object /i.test(message)) {
+        return fallback;
+    }
+    return message;
+}
+/**
+ * Handles API errors by mapping them to form fields
+ */
+export function mapApiErrorsToForm(error, currentFormErrors, attendees, reservations) {
+    if (isApiError(error) && error.errors) {
+        const formErrors = { ...currentFormErrors };
+        // Map API errors to form fields
+        Object.entries(error.errors).forEach(([field, message]) => {
+            // Handle attendees validation errors
+            if (field === "attendees" && typeof message === "object") {
+                // Process each attendee error
+                Object.entries(message).forEach(([attendeeIndex, attendeeErrors]) => {
+                    const index = parseInt(attendeeIndex, 10);
+                    if (!isNaN(index) && index >= 0 && index < attendees.length) {
+                        const attendee = attendees[index];
+                        // Process each field error for this attendee
+                        Object.entries(attendeeErrors).forEach(([fieldName, fieldErrors]) => {
+                            // Get the first error message (usually there's only one)
+                            const errorMessage = Array.isArray(fieldErrors) && fieldErrors.length > 0
+                                ? fieldErrors[0]
+                                : String(fieldErrors);
+                            // Only assign if we have a valid error message
+                            if (errorMessage) {
+                                // Construct the form field name using the ticket_id from the attendee
+                                if (attendee && attendee.ticket_id) {
+                                    // Find the reservation_id for this ticket
+                                    for (const reservation of reservations) {
+                                        if (reservation.tickets?.some((ticket) => ticket.ticket_id === attendee.ticket_id)) {
+                                            const formFieldName = `reservation_${reservation.reservation_id}_ticket_${attendee.ticket_id}_${fieldName}`;
+                                            formErrors[formFieldName] = errorMessage;
+                                            break;
+                                        }
+                                    }
+                                }
+                            }
+                        });
+                    }
+                });
+            }
+            // Handle nested fields like customer.email
+            else if (field.includes(".")) {
+                const [category, specificField] = field.split(".");
+                if (category === "customer" && specificField) {
+                    formErrors[specificField] = message;
+                }
+                else if (category === "reservation_data") {
+                    // Handle reservation-specific errors
+                    const parts = field.split(".");
+                    if (parts.length >= 3) {
+                        const reservationId = parts[1];
+                        const reservationField = parts[2];
+                        if (reservationId && reservationField) {
+                            formErrors[`reservation_${reservationId}_${reservationField}`] =
+                                message;
+                        }
+                    }
+                }
+            }
+            else {
+                // Handle array messages properly
+                const errorMessage = Array.isArray(message) && message.length > 0 && message[0]
+                    ? String(message[0])
+                    : String(message || "");
+                // Map API field names to form field names
+                let formFieldName = field;
+                if (field === "phone_number") {
+                    formFieldName = "phone";
+                }
+                formErrors[formFieldName] = errorMessage;
+            }
+        });
+        return { formErrors };
+    }
+    else {
+        // Generic error
+        return {
+            formErrors: currentFormErrors,
+            cardError: msg("An error occurred. Please try again."),
+        };
+    }
+}
+/**
+ * Checks transaction status with exponential backoff.
+ * Pass an AbortSignal to cancel polling early (e.g., on component disconnect).
+ */
+export async function pollTransactionStatus(userId, maxAttempts, initialInterval, maxInterval, client, distributorID, locale, onReferenceId, signal) {
+    let attempts = 0;
+    let currentInterval = initialInterval;
+    const checkStatus = async () => {
+        try {
+            const { data, error } = await withErrorHandling(apiGet({
+                client,
+                distributorID,
+                locale,
+                endpoint: "/{api_version}/users/{customer_id}/transactions",
+                path: { customer_id: userId },
+            }));
+            if (error) {
+                console.error("Failed to check transaction status");
+                return { status: null, tokensToIssue: null };
+            }
+            if (data && data.length > 0) {
+                const transaction = data[0];
+                if (!transaction)
+                    return { status: null, tokensToIssue: null };
+                if (transaction.reference_id && onReferenceId) {
+                    onReferenceId(transaction.reference_id);
+                }
+                const loyaltyEarn = transaction.loyalty?.earn;
+                const tokensToIssue = loyaltyEarn
+                    ? String(Object.values(loyaltyEarn)[0] ?? "")
+                    : null;
+                return { status: transaction.status || null, tokensToIssue };
+            }
+            return { status: null, tokensToIssue: null };
+        }
+        catch (err) {
+            console.error("Error polling transaction status:", err);
+            return { status: null, tokensToIssue: null };
+        }
+    };
+    return new Promise((resolve) => {
+        const poll = async () => {
+            if (signal?.aborted) {
+                resolve({ status: null, tokensToIssue: null });
+                return;
+            }
+            attempts++;
+            const result = await checkStatus();
+            if (isFinalStatus(result.status)) {
+                resolve(result);
+                return;
+            }
+            if (attempts >= maxAttempts) {
+                resolve(result);
+                return;
+            }
+            const nextInterval = Math.min(currentInterval * 2, maxInterval);
+            currentInterval = nextInterval;
+            setTimeout(poll, currentInterval);
+        };
+        poll();
+    });
+}
+/**
+ * Validates an email address
+ */
+export const isValidEmail = (email) => {
+    const re = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return re.test(email);
+};
+/**
+ * Validates a wallet email address
+ */
+export const validateWalletEmail = (email) => {
+    if (!email) {
+        return msg("Email is required");
+    }
+    if (!isValidEmail(email)) {
+        return msg("Please enter a valid email address");
+    }
+    return "";
+};
+/**
+ * ISO-3166-1 alpha-2 pattern (two uppercase letters).
+ */
+const ISO_ALPHA2_REGEX = /^[A-Z]{2}$/;
+/**
+ * Deterministic fallback country code when no mapping is found.
+ * Stripe PaymentRequest requires a valid ISO code.
+ */
+const DEFAULT_COUNTRY_CODE = "US";
+/**
+ * Finds a country code for a country name.
+ * PP-007: Returns a strict ISO alpha-2 code — never a raw country name.
+ * Falls back to DEFAULT_COUNTRY_CODE when no match is found.
+ */
+export const findCountryCode = (countryName, countries = []) => {
+    if (!countryName)
+        return "";
+    // If already an ISO alpha-2 code, return normalized uppercase
+    if (ISO_ALPHA2_REGEX.test(countryName.toUpperCase())) {
+        return countryName.toUpperCase();
+    }
+    const country = countries.find((c) => c.name.toLowerCase() === countryName.toLowerCase());
+    if (country?.code)
+        return country.code;
+    // PP-007: Deterministic fallback instead of returning raw name
+    console.warn(`Country "${countryName}" could not be mapped to ISO code, falling back to ${DEFAULT_COUNTRY_CODE}`);
+    return DEFAULT_COUNTRY_CODE;
+};
+/**
+ * Checks if the component should show specific fields
+ */
+export function getFieldVisibility(data) {
+    return {
+        hasNameField: hasNameField(data),
+        hasFirstNameField: hasFirstNameField(data),
+        hasSecondNameField: hasSecondNameField(data),
+        hasPhoneField: hasPhoneField(data),
+        hasEmailField: hasEmailField(data),
+    };
+}
+/**
+ * Gets field configuration from FIELDS or returns a default
+ */
+export function getFieldConfig(fieldName, FIELDS_CONFIG, customField, customType) {
+    const labelKey = (customField || fieldName);
+    const config = FIELDS_CONFIG[labelKey];
+    if (config) {
+        return {
+            label: config.label(),
+            placeholder: config.placeholder ? config.placeholder() : "",
+            helpText: config.helpText?.() ?? "",
+            type: config.type,
+            autocomplete: config.autocomplete,
+        };
+    }
+    if (customField) {
+        return {
+            label: capitalizeFirstLetter(customField),
+            placeholder: "",
+            helpText: "",
+            type: customType || "text",
+            autocomplete: "off",
+        };
+    }
+    return null;
+}
+// Stripe error mapping extracted for reuse and testing
+export function mapStripeErrorToField(error) {
+    const err = error || {};
+    const code = err["code"] || "";
+    const param = err["param"] || "";
+    const p = param.toLowerCase();
+    if (p.includes("cvc") || p.includes("cvv"))
+        return "cvc";
+    if (p.includes("exp") ||
+        p.includes("expiry") ||
+        p.includes("exp_month") ||
+        p.includes("exp_year"))
+        return "expiry";
+    if (p.includes("number") ||
+        p.includes("card[number]") ||
+        p.includes("card_number"))
+        return "number";
+    const c = code.toLowerCase();
+    if (c.includes("cvc"))
+        return "cvc";
+    if (c.includes("expiry") || c.includes("exp_"))
+        return "expiry";
+    if (c.includes("number"))
+        return "number";
+    if (c.includes("card_declined") || c.includes("card_error"))
+        return "number";
+    return null;
+}
+export function isFinalStatus(status) {
+    if (!status)
+        return false;
+    const FINAL_STATUSES = [
+        "PAID",
+        "FAILED",
+        "REFUNDED",
+        "PARTIAL_REFUNDED",
+        "CANCELLED",
+        "PARTIALLY_CANCELLED",
+    ];
+    return FINAL_STATUSES.includes(status);
+}
+export function extractPaymentIntentId(clientSecret) {
+    const parts = clientSecret.split("_secret_");
+    return parts[0] || "";
+}
+/**
+ * Formats phone number with a plus prefix if needed.
+ * IMPROVED: Validates a phone format before adding a prefix to prevent invalid numbers.
+ *
+ * @param phone - Phone number to format
+ * @returns Formatted phone number with + prefix, or undefined if invalid
+ */
+export function formatPhoneWithPlus(phone) {
+    if (!phone)
+        return undefined;
+    // Remove whitespace and common separators
+    const cleaned = phone.replace(/[\s\-().]/g, "");
+    // Phone already has + prefix
+    if (cleaned.startsWith("+")) {
+        // Validate it's not just "+" with no digits
+        const digitsOnly = cleaned.slice(1);
+        if (!digitsOnly || !/^\d+$/.test(digitsOnly)) {
+            console.error("Invalid phone number format");
+            return undefined;
+        }
+        return cleaned;
+    }
+    // Validate contains only digits before adding a prefix
+    if (!/^\d+$/.test(cleaned)) {
+        console.error("Phone number contains invalid characters");
+        return undefined;
+    }
+    // Add + prefix
+    return `+${cleaned}`;
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Pending crypto transfer recovery — validation & integrity
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Ethereum transaction hash format: 0x followed by exactly 64 hex characters.
+ */
+const TX_HASH_REGEX = /^0x[0-9a-fA-F]{64}$/;
+/**
+ * Validates an Ethereum transaction hash (0x + 64 hex chars = 66 total).
+ */
+export function isValidTransactionHash(hash) {
+    return TX_HASH_REGEX.test(hash);
+}
+/**
+ * Validates a transfer amount is a parseable positive finite number.
+ */
+export function isValidTransferAmount(amount) {
+    const n = parseFloat(amount);
+    return !isNaN(n) && isFinite(n) && n > 0;
+}
+/**
+ * Runtime type guard for PendingTransferPayload.
+ * Validates structure, field types, tx hash format, and amount format.
+ * Allows missing/empty `checksum` for backward compatibility with entries
+ * written before the checksum was added.
+ */
+export function isValidPendingTransferPayload(data) {
+    if (data === null || typeof data !== "object")
+        return false;
+    const obj = data;
+    if (typeof obj.transactionHash !== "string")
+        return false;
+    if (typeof obj.amount !== "string")
+        return false;
+    if (typeof obj.timestamp !== "number")
+        return false;
+    if (!isValidTransactionHash(obj.transactionHash))
+        return false;
+    if (!isValidTransferAmount(obj.amount))
+        return false;
+    if (!isFinite(obj.timestamp) || obj.timestamp <= 0)
+        return false;
+    // checksum is optional (legacy entries may not have it)
+    if (obj.checksum !== undefined && typeof obj.checksum !== "string") {
+        return false;
+    }
+    return true;
+}
+/**
+ * Computes a SHA-256 hex checksum over the transfer payload fields.
+ * Returns empty string if crypto.subtle is unavailable (e.g., non-HTTPS context).
+ */
+export async function computeTransferChecksum(transactionHash, amount, timestamp) {
+    try {
+        const message = `${transactionHash}:${amount}:${timestamp}`;
+        const encoded = new TextEncoder().encode(message);
+        const buffer = await crypto.subtle.digest("SHA-256", encoded);
+        const hashArray = Array.from(new Uint8Array(buffer));
+        return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+    }
+    catch {
+        // crypto.subtle unavailable (e.g., non-HTTPS, older browser) — skip checksum
+        return "";
+    }
+}
+/**
+ * Verifies the integrity checksum of a pending transfer payload.
+ * PP-006: Hardened — legacy entries without checksums are no longer trusted
+ * when crypto.subtle is available. Returns true only if checksums match
+ * or crypto.subtle is completely unavailable (cannot verify at all).
+ */
+export async function verifyTransferChecksum(payload) {
+    const computed = await computeTransferChecksum(payload.transactionHash, payload.amount, payload.timestamp);
+    // If crypto.subtle is unavailable, we cannot verify at all — accept cautiously
+    if (!computed)
+        return true;
+    // PP-006: Reject entries without a checksum when we can verify
+    if (!payload.checksum)
+        return false;
+    return computed === payload.checksum;
+}