@tagadapay/plugin-sdk 1.0.30 → 2.0.1

package/dist/data/iso3166.d.ts

@@ -0,0 +1,30 @@
+export interface Country {
+    code: string;
+    name: string;
+    iso3?: string;
+    numeric?: number;
+    uniqueKey?: string;
+}
+export interface State {
+    code: string;
+    name: string;
+    countryCode: string;
+    uniqueKey?: string;
+}
+export declare const getCountries: () => Country[];
+export declare const getAllStates: () => State[];
+export declare const getStatesForCountry: (countryCode: string) => State[];
+export declare const findCountryByName: (countryName: string) => Country | null;
+export declare const findRegionByCode: (regionCode: string) => State | null;
+export declare const isValidCountryCode: (countryCode: string) => boolean;
+export declare const isValidStateCode: (countryCode: string, stateCode: string) => boolean;
+export declare const getCountryWithRegions: (countryCode: string) => {
+    country: {
+        code: any;
+        name: any;
+        iso3: any;
+        numeric: any;
+        uniqueKey: string;
+    };
+    regions: State[];
+} | null;

package/dist/data/iso3166.js

@@ -0,0 +1,102 @@
+// Import the ISO3166 library API functions
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore - iso3166-2-db doesn't have TypeScript definitions
+import { getDataSet, reduce } from 'iso3166-2-db';
+// Get the full dataset with default English language
+const worldDatabase = reduce(getDataSet(), 'en');
+// Transform the ISO3166 data into our expected format
+export const getCountries = () => {
+    const countries = [];
+    Object.keys(worldDatabase).forEach((countryCode) => {
+        const countryData = worldDatabase[countryCode];
+        countries.push({
+            code: countryData.iso, // iso3166-1 alpha-2 code
+            name: countryData.name,
+            iso3: countryData.iso3, // iso3166-1 alpha-3 code
+            numeric: countryData.numeric,
+            uniqueKey: `country-${countryData.iso}`,
+        });
+    });
+    // Sort countries alphabetically by name
+    return countries.sort((a, b) => a.name.localeCompare(b.name));
+};
+// Get all states/regions for all countries
+export const getAllStates = () => {
+    const states = [];
+    Object.keys(worldDatabase).forEach((countryCode) => {
+        const countryData = worldDatabase[countryCode];
+        if (countryData.regions && Array.isArray(countryData.regions)) {
+            countryData.regions.forEach((region, index) => {
+                states.push({
+                    code: region.iso, // iso3166-2 code (the part after the dash)
+                    name: region.name,
+                    countryCode: countryData.iso,
+                    uniqueKey: `state-${countryData.iso}-${region.iso}-${index}`,
+                });
+            });
+        }
+    });
+    // Sort states alphabetically by name
+    return states.sort((a, b) => a.name.localeCompare(b.name));
+};
+// Get states for a specific country
+export const getStatesForCountry = (countryCode) => {
+    const countryData = worldDatabase[countryCode];
+    if (!countryData?.regions || !Array.isArray(countryData.regions)) {
+        return [];
+    }
+    return countryData.regions
+        .map((region, index) => ({
+        code: region.iso,
+        name: region.name,
+        countryCode: countryData.iso,
+        uniqueKey: `state-${countryData.iso}-${region.iso}-${index}`,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+};
+// Find country by name (fuzzy search)
+export const findCountryByName = (countryName) => {
+    const countries = getCountries();
+    const normalizedSearchName = countryName.toLowerCase().trim();
+    // Exact match first
+    const exactMatch = countries.find((country) => country.name.toLowerCase() === normalizedSearchName);
+    if (exactMatch)
+        return exactMatch;
+    // Partial match
+    const partialMatch = countries.find((country) => country.name.toLowerCase().includes(normalizedSearchName) ||
+        normalizedSearchName.includes(country.name.toLowerCase()));
+    return partialMatch ?? null;
+};
+// Find region by ISO code (e.g., "US-CA" for California)
+export const findRegionByCode = (regionCode) => {
+    const [countryCode, stateCode] = regionCode.split('-');
+    if (!countryCode || !stateCode)
+        return null;
+    const states = getStatesForCountry(countryCode);
+    return states.find((state) => state.code === stateCode) ?? null;
+};
+// Validate if a country code exists
+export const isValidCountryCode = (countryCode) => {
+    return Object.prototype.hasOwnProperty.call(worldDatabase, countryCode);
+};
+// Validate if a state code exists for a given country
+export const isValidStateCode = (countryCode, stateCode) => {
+    const states = getStatesForCountry(countryCode);
+    return states.some((state) => state.code === stateCode);
+};
+// Get country info including regions
+export const getCountryWithRegions = (countryCode) => {
+    const countryData = worldDatabase[countryCode];
+    if (!countryData)
+        return null;
+    return {
+        country: {
+            code: countryData.iso,
+            name: countryData.name,
+            iso3: countryData.iso3,
+            numeric: countryData.numeric,
+            uniqueKey: `country-${countryData.iso}`,
+        },
+        regions: getStatesForCountry(countryCode),
+    };
+};

package/dist/react/hooks/useAddress.js

@@ -277,25 +277,25 @@ export function useAddress(options = {}) {
     // Custom styles for Google Places dropdown
     useEffect(() => {
         if (enableGooglePlaces && !document.getElementById('google-places-custom-styles')) {
-            const autocompleteStyles = `
-        .pac-container {
-          border-radius: 8px;
-          box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
-          border: 1px solid #e2e8f0;
-          margin-top: 4px;
-          font-family: inherit;
-          z-index: 9999;
-        }
-        .pac-item {
-          padding: 10px 12px;
-          font-size: 14px;
-          cursor: pointer;
-          border-top: 1px solid #f3f4f6;
-        }
-        .pac-item:first-child { border-top: none; }
-        .pac-item:hover { background-color: #f8fafc; }
-        .pac-item-selected, .pac-item-selected:hover { background-color: #eef2ff; }
-        .pac-matched { font-weight: 600; }
+            const autocompleteStyles = `
+        .pac-container {
+          border-radius: 8px;
+          box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+          border: 1px solid #e2e8f0;
+          margin-top: 4px;
+          font-family: inherit;
+          z-index: 9999;
+        }
+        .pac-item {
+          padding: 10px 12px;
+          font-size: 14px;
+          cursor: pointer;
+          border-top: 1px solid #f3f4f6;
+        }
+        .pac-item:first-child { border-top: none; }
+        .pac-item:hover { background-color: #f8fafc; }
+        .pac-item-selected, .pac-item-selected:hover { background-color: #eef2ff; }
+        .pac-matched { font-weight: 600; }
       `;
             const styleElement = document.createElement('style');
             styleElement.id = 'google-places-custom-styles';

package/dist/react/hooks/useAddressV2.d.ts

@@ -0,0 +1,53 @@
+import { type Country as ISO3166Country, type State as ISO3166State } from '../../data/iso3166';
+export type Country = ISO3166Country;
+export type State = ISO3166State;
+export interface AddressField {
+    value: string;
+    isValid: boolean;
+    error?: string;
+    touched?: boolean;
+}
+export interface AddressData {
+    firstName: string;
+    lastName: string;
+    email: string;
+    phone: string;
+    country: string;
+    address1: string;
+    address2: string;
+    city: string;
+    state: string;
+    postal: string;
+}
+export interface UseAddressV2Config {
+    autoValidate?: boolean;
+    enableGooglePlaces?: boolean;
+    googlePlacesApiKey?: string;
+    countryRestrictions?: string[];
+    onFieldsChange?: (data: AddressData) => void;
+    debounceConfig?: {
+        autoSaveDelay?: number;
+        enabled?: boolean;
+    };
+    initialValues?: Partial<AddressData>;
+}
+export interface UseAddressV2Return {
+    fields: Record<keyof AddressData, AddressField>;
+    setValue: (field: keyof AddressData, value: string) => void;
+    setValues: (values: Partial<AddressData>) => void;
+    getValue: (field: keyof AddressData) => string;
+    getValues: () => AddressData;
+    validateField: (field: keyof AddressData) => boolean;
+    validateAll: () => boolean;
+    isValid: boolean;
+    reset: () => void;
+    countries: Country[];
+    states: State[];
+    getStatesForCountry: (countryCode: string) => State[];
+    addressRef: React.RefObject<HTMLInputElement | null>;
+    addressInputValue: string;
+    setAddressInputValue: (value: string) => void;
+    handleFieldChange: (field: keyof AddressData) => (value: string) => void;
+    handleFieldBlur: (field: keyof AddressData) => () => void;
+}
+export declare const useAddressV2: (config?: UseAddressV2Config) => UseAddressV2Return;

package/dist/react/hooks/useAddressV2.js

@@ -0,0 +1,379 @@
+import { useState, useMemo, useCallback, useRef, useEffect } from 'react';
+import { usePlacesWidget } from 'react-google-autocomplete';
+// Import the standardized ISO3166 data
+import { getCountries, getAllStates, getStatesForCountry, isValidCountryCode, isValidStateCode, } from '../../data/iso3166';
+// Default field structure
+const createDefaultField = (value = '') => ({
+    value,
+    isValid: true,
+    error: undefined,
+    touched: false,
+});
+// Default form data
+const createDefaultFormData = (initialValues = {}) => ({
+    firstName: createDefaultField(initialValues.firstName),
+    lastName: createDefaultField(initialValues.lastName),
+    email: createDefaultField(initialValues.email),
+    phone: createDefaultField(initialValues.phone),
+    country: createDefaultField(initialValues.country),
+    address1: createDefaultField(initialValues.address1),
+    address2: createDefaultField(initialValues.address2),
+    city: createDefaultField(initialValues.city),
+    state: createDefaultField(initialValues.state),
+    postal: createDefaultField(initialValues.postal),
+});
+// Validation functions
+const isValidEmail = (email) => {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+};
+const isValidPhone = (phone) => {
+    const phoneRegex = /^[+]?[\d\s\-()]+$/;
+    return phone.length >= 10 && phoneRegex.test(phone);
+};
+const isValidPostal = (postal, country) => {
+    if (!postal)
+        return false;
+    const patterns = {
+        US: /^\d{5}(-\d{4})?$/,
+        CA: /^[A-Za-z]\d[A-Za-z] \d[A-Za-z]\d$/,
+        GB: /^[A-Z]{1,2}\d[A-Z\d]? \d[A-Z]{2}$/,
+        DE: /^\d{5}$/,
+        FR: /^\d{5}$/,
+    };
+    const pattern = patterns[country];
+    return pattern ? pattern.test(postal) : postal.length >= 3;
+};
+export const useAddressV2 = (config = {}) => {
+    const { autoValidate = false, enableGooglePlaces = false, googlePlacesApiKey, countryRestrictions = [], onFieldsChange, debounceConfig = { autoSaveDelay: 1000, enabled: true }, initialValues = {}, } = config;
+    // State management
+    const [fields, setFields] = useState(() => createDefaultFormData(initialValues));
+    // Google Places integration
+    const [addressInputValue, setAddressInputValue] = useState(initialValues.address1 || '');
+    const addressRef = useRef(null);
+    // Debounce timeout ref
+    const debounceTimeoutRef = useRef(null);
+    // Memoized countries with restrictions applied (using ISO3166 data)
+    const countries = useMemo(() => {
+        const allCountries = getCountries(); // Already includes uniqueKey and is deduplicated
+        return countryRestrictions.length > 0
+            ? allCountries.filter((country) => countryRestrictions.includes(country.code))
+            : allCountries;
+    }, [countryRestrictions]);
+    // Memoized states for all countries (using ISO3166 data)
+    const allStates = useMemo(() => {
+        return getAllStates(); // Already includes uniqueKey and is deduplicated
+    }, []);
+    // Get states for current selected country
+    const states = useMemo(() => {
+        const selectedCountry = fields.country.value;
+        if (!selectedCountry)
+            return [];
+        return allStates.filter((state) => state.countryCode === selectedCountry);
+    }, [allStates, fields.country.value]);
+    // Get states for any country (utility function) - use ISO3166 function
+    const getStatesForCountryFn = useCallback((countryCode) => {
+        return getStatesForCountry(countryCode); // Use the ISO3166 function directly
+    }, []);
+    // Validation function for a single field
+    const validateField = useCallback((field) => {
+        const value = fields[field].value;
+        switch (field) {
+            case 'email':
+                return value ? isValidEmail(value) : true;
+            case 'phone':
+                return value ? isValidPhone(value) : true;
+            case 'postal':
+                return value ? isValidPostal(value, fields.country.value) : true;
+            case 'firstName':
+            case 'lastName':
+            case 'address1':
+            case 'city':
+                return value.trim().length > 0;
+            case 'country': {
+                return isValidCountryCode(value);
+            }
+            case 'state': {
+                if (!fields.country.value)
+                    return true;
+                return isValidStateCode(fields.country.value, value);
+            }
+            default:
+                return true;
+        }
+    }, [fields]);
+    // Validate all fields
+    const validateAll = useCallback(() => {
+        const fieldsToValidate = [
+            'firstName',
+            'lastName',
+            'email',
+            'phone',
+            'country',
+            'address1',
+            'city',
+            'state',
+            'postal',
+        ];
+        return fieldsToValidate.every((field) => validateField(field));
+    }, [validateField]);
+    // Check if form is currently valid
+    const isValid = useMemo(() => validateAll(), [validateAll]);
+    // Get validation error message
+    const getFieldError = useCallback((field, value) => {
+        if (!value &&
+            ['firstName', 'lastName', 'email', 'phone', 'country', 'address1', 'city'].includes(field)) {
+            return `${field.charAt(0).toUpperCase() + field.slice(1)} is required`;
+        }
+        switch (field) {
+            case 'email':
+                return value && !isValidEmail(value) ? 'Please enter a valid email address' : undefined;
+            case 'phone':
+                return value && !isValidPhone(value) ? 'Please enter a valid phone number' : undefined;
+            case 'postal':
+                return value && !isValidPostal(value, fields.country.value)
+                    ? 'Please enter a valid postal code'
+                    : undefined;
+            case 'country':
+                return value && !isValidCountryCode(value) ? 'Please select a valid country' : undefined;
+            case 'state': {
+                if (!fields.country.value)
+                    return undefined;
+                const countryStates = getStatesForCountry(fields.country.value);
+                if (countryStates.length > 0 && !isValidStateCode(fields.country.value, value)) {
+                    return 'Please select a valid state/province';
+                }
+                return undefined;
+            }
+            default:
+                return undefined;
+        }
+    }, [fields.country.value]);
+    // Refs for stable references to avoid recreating callbacks
+    const onFieldsChangeRef = useRef(onFieldsChange);
+    const debounceConfigRef = useRef(debounceConfig);
+    // Update refs when values change
+    useEffect(() => {
+        onFieldsChangeRef.current = onFieldsChange;
+    }, [onFieldsChange]);
+    useEffect(() => {
+        debounceConfigRef.current = debounceConfig;
+    }, [debounceConfig]);
+    // Store fields ref for stable access
+    const fieldsRef = useRef(fields);
+    useEffect(() => {
+        fieldsRef.current = fields;
+    }, [fields]);
+    // Debounced onFieldsChange callback (stable reference - NO DEPENDENCIES!)
+    const triggerFieldsChange = useCallback(() => {
+        const currentConfig = debounceConfigRef.current;
+        const currentCallback = onFieldsChangeRef.current;
+        if (!currentConfig.enabled || !currentCallback)
+            return;
+        if (debounceTimeoutRef.current) {
+            clearTimeout(debounceTimeoutRef.current);
+        }
+        debounceTimeoutRef.current = setTimeout(() => {
+            // Get current field values at execution time, not creation time
+            const currentFields = fieldsRef.current;
+            const currentValues = {
+                firstName: currentFields.firstName.value,
+                lastName: currentFields.lastName.value,
+                email: currentFields.email.value,
+                phone: currentFields.phone.value,
+                country: currentFields.country.value,
+                address1: currentFields.address1.value,
+                address2: currentFields.address2.value,
+                city: currentFields.city.value,
+                state: currentFields.state.value,
+                postal: currentFields.postal.value,
+            };
+            currentCallback(currentValues);
+        }, currentConfig.autoSaveDelay);
+    }, []); // NO DEPENDENCIES - truly stable!
+    // Set single field value with validation
+    const setValue = useCallback((field, value, triggerSave = false) => {
+        setFields((prev) => {
+            const error = autoValidate ? getFieldError(field, value) : undefined;
+            const newFields = {
+                ...prev,
+                [field]: {
+                    value,
+                    isValid: !error,
+                    error,
+                    touched: true,
+                },
+            };
+            // Reset state when country changes
+            if (field === 'country') {
+                newFields.state = createDefaultField('');
+            }
+            return newFields;
+        });
+        // Handle address input value for Google Places
+        if (field === 'address1') {
+            setAddressInputValue(value);
+        }
+        // Only trigger auto-save when explicitly requested (on blur, not on every keystroke)
+        if (triggerSave) {
+            triggerFieldsChange();
+        }
+    }, [autoValidate, getFieldError, triggerFieldsChange]);
+    // Set multiple field values
+    const setValues = useCallback((values) => {
+        setFields((prev) => {
+            const newFields = { ...prev };
+            Object.entries(values).forEach(([key, value]) => {
+                const field = key;
+                const error = autoValidate ? getFieldError(field, value || '') : undefined;
+                newFields[field] = {
+                    value: value || '',
+                    isValid: !error,
+                    error,
+                    touched: true,
+                };
+            });
+            // Reset state if country changed
+            if (values.country !== undefined) {
+                newFields.state = createDefaultField(values.state || '');
+            }
+            return newFields;
+        });
+        // Update address input value if address1 was changed
+        if (values.address1 !== undefined) {
+            setAddressInputValue(values.address1);
+        }
+        // Trigger debounced callback
+        triggerFieldsChange();
+    }, [autoValidate, getFieldError, triggerFieldsChange]);
+    // Get single field value
+    const getValue = useCallback((field) => {
+        return fields[field].value;
+    }, [fields]);
+    // Get all field values
+    const getValues = useCallback(() => {
+        return {
+            firstName: fields.firstName.value,
+            lastName: fields.lastName.value,
+            email: fields.email.value,
+            phone: fields.phone.value,
+            country: fields.country.value,
+            address1: fields.address1.value,
+            address2: fields.address2.value,
+            city: fields.city.value,
+            state: fields.state.value,
+            postal: fields.postal.value,
+        };
+    }, [fields]);
+    // Reset form
+    const reset = useCallback(() => {
+        setFields(createDefaultFormData());
+        setAddressInputValue('');
+    }, []);
+    // Optimized field change handler factory
+    const handleFieldChange = useCallback((field) => {
+        return (value) => setValue(field, value);
+    }, [setValue]);
+    // Optimized field blur handler factory
+    const handleFieldBlur = useCallback((field) => {
+        return () => {
+            if (!autoValidate) {
+                setFields((prev) => {
+                    const value = prev[field].value;
+                    const error = getFieldError(field, value);
+                    return {
+                        ...prev,
+                        [field]: {
+                            ...prev[field],
+                            isValid: !error,
+                            error,
+                            touched: true,
+                        },
+                    };
+                });
+            }
+        };
+    }, [autoValidate, getFieldError]);
+    // Google Places autocomplete setup - we'll return the ref for manual connection
+    const placesConfig = useMemo(() => ({
+        apiKey: googlePlacesApiKey,
+        onPlaceSelected: (place) => {
+            if (!place.geometry || !enableGooglePlaces)
+                return;
+            const addressComponents = place.address_components || [];
+            const newValues = {};
+            addressComponents.forEach((component) => {
+                const types = component.types;
+                if (types.includes('street_number')) {
+                    newValues.address1 = `${component.long_name} ${newValues.address1 || ''}`.trim();
+                }
+                else if (types.includes('route')) {
+                    newValues.address1 = `${newValues.address1 || ''} ${component.long_name}`.trim();
+                }
+                else if (types.includes('locality')) {
+                    newValues.city = component.long_name;
+                }
+                else if (types.includes('administrative_area_level_1')) {
+                    newValues.state = component.short_name;
+                }
+                else if (types.includes('country')) {
+                    newValues.country = component.short_name;
+                }
+                else if (types.includes('postal_code')) {
+                    newValues.postal = component.long_name;
+                }
+            });
+            // Only update if country is in restrictions (if any)
+            if (newValues.country && countryRestrictions.length > 0) {
+                if (!countryRestrictions.includes(newValues.country)) {
+                    console.warn(`Google Places returned country ${newValues.country} which is not in restrictions`);
+                    return;
+                }
+            }
+            setValues(newValues);
+        },
+        options: {
+            types: ['address'],
+            ...(countryRestrictions.length > 0 && {
+                componentRestrictions: { country: countryRestrictions },
+            }),
+        },
+    }), [googlePlacesApiKey, enableGooglePlaces, countryRestrictions, setValues]);
+    // Use the Google Places hook - always call the hook to avoid conditional hook calls
+    const googlePlacesHook = usePlacesWidget(enableGooglePlaces
+        ? placesConfig
+        : {
+            apiKey: '',
+            onPlaceSelected: () => {
+                // No-op when Google Places is disabled
+            },
+            options: {},
+        });
+    // Cleanup debounce timeout on unmount
+    useEffect(() => {
+        return () => {
+            if (debounceTimeoutRef.current) {
+                clearTimeout(debounceTimeoutRef.current);
+            }
+        };
+    }, []);
+    return {
+        fields,
+        setValue,
+        setValues,
+        getValue,
+        getValues,
+        validateField,
+        validateAll,
+        isValid,
+        reset,
+        countries,
+        states,
+        getStatesForCountry: getStatesForCountryFn,
+        addressRef: enableGooglePlaces ? (googlePlacesHook.ref ?? addressRef) : addressRef,
+        addressInputValue,
+        setAddressInputValue,
+        handleFieldChange,
+        handleFieldBlur,
+    };
+};

package/dist/react/hooks/useGoogleAutocomplete.d.ts

@@ -0,0 +1,69 @@
+declare global {
+    interface Window {
+        google?: {
+            maps?: {
+                places?: {
+                    AutocompleteService: new () => any;
+                    PlacesService: new (map: any) => any;
+                    PlacesServiceStatus: {
+                        OK: string;
+                        ZERO_RESULTS: string;
+                    };
+                };
+                Map: new (element: HTMLElement) => any;
+            };
+        };
+    }
+}
+export interface GooglePrediction {
+    place_id: string;
+    description: string;
+    structured_formatting?: {
+        main_text: string;
+        secondary_text: string;
+    };
+}
+export interface GoogleAddressComponent {
+    long_name: string;
+    short_name: string;
+    types: string[];
+}
+export interface GooglePlaceDetails {
+    address_components: GoogleAddressComponent[];
+    formatted_address: string;
+}
+export interface ExtractedAddress {
+    streetNumber: string;
+    route: string;
+    locality: string;
+    administrativeAreaLevel1: string;
+    administrativeAreaLevel1Long: string;
+    country: string;
+    postalCode: string;
+}
+export interface UseGoogleAutocompleteOptions {
+    apiKey: string;
+    libraries?: string[];
+    version?: string;
+    language?: string;
+    region?: string;
+}
+export interface UseGoogleAutocompleteResult {
+    predictions: GooglePrediction[];
+    isLoading: boolean;
+    isScriptLoaded: boolean;
+    searchPlaces: (input: string, countryRestriction?: string) => void;
+    getPlaceDetails: (placeId: string) => Promise<GooglePlaceDetails | null>;
+    extractAddressComponents: (place: GooglePlaceDetails) => ExtractedAddress;
+    clearPredictions: () => void;
+}
+/**
+ * React hook for Google Places Autocomplete with automatic script injection
+ * Automatically loads the Google Maps JavaScript API with Places library
+ */
+export declare function useGoogleAutocomplete(options: UseGoogleAutocompleteOptions): UseGoogleAutocompleteResult;
+/**
+ * Hook to check if Google Maps API is loaded
+ * @deprecated Use useGoogleAutocomplete with isScriptLoaded instead
+ */
+export declare function useGoogleMapsLoaded(): boolean;