@tagadapay/headless-sdk 1.8.0-rc.0 → 1.8.0

package/dist/core/types.js

@@ -0,0 +1,5 @@
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,25 @@
+import type { CatalogProduct } from '../../core/types.js';
+export interface UseCatalogReturn {
+    products: CatalogProduct[];
+    isLoading: boolean;
+    error: Error | null;
+    /** Fetch all products for the store. */
+    loadProducts: (opts?: {
+        productIds?: string[];
+        variantIds?: string[];
+    }) => Promise<CatalogProduct[]>;
+    /** Fetch a single product by ID. */
+    loadProduct: (productId: string) => Promise<CatalogProduct | null>;
+}
+/**
+ * React hook for browsing the store's product catalog.
+ *
+ * @example
+ * ```tsx
+ * const { products, isLoading, loadProducts } = useCatalog();
+ *
+ * useEffect(() => { loadProducts(); }, []);
+ * ```
+ */
+export declare function useCatalog(): UseCatalogReturn;
+//# sourceMappingURL=useCatalog.d.ts.map

package/dist/react/hooks/useCatalog.js

@@ -0,0 +1,58 @@
+import { useState, useCallback } from 'react';
+import { useHeadlessClient } from '../provider.js';
+/**
+ * React hook for browsing the store's product catalog.
+ *
+ * @example
+ * ```tsx
+ * const { products, isLoading, loadProducts } = useCatalog();
+ *
+ * useEffect(() => { loadProducts(); }, []);
+ * ```
+ */
+export function useCatalog() {
+    const client = useHeadlessClient();
+    const [products, setProducts] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const loadProducts = useCallback(async (opts) => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            const items = await client.catalog.getProducts(opts);
+            setProducts(items);
+            return items;
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            throw e;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client]);
+    const loadProduct = useCallback(async (productId) => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            return await client.catalog.getProduct(productId);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            throw e;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client]);
+    return {
+        products,
+        isLoading,
+        error,
+        loadProducts,
+        loadProduct,
+    };
+}
+//# sourceMappingURL=useCatalog.js.map

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

@@ -0,0 +1,58 @@
+import type { CheckoutSession, LineItem, ShippingRate, Address, CheckoutCustomer } from '../../core/types.js';
+export interface UseCheckoutReturn {
+    session: CheckoutSession | null;
+    isLoading: boolean;
+    error: Error | null;
+    /** Reload the session from the server. */
+    refresh: () => Promise<void>;
+    /** Create a new checkout session (auto-loads it after creation). */
+    createSession: (opts: {
+        items: LineItem[];
+        currency?: string;
+        returnUrl?: string;
+        customerEmail?: string;
+    }) => Promise<void>;
+    /** Replace cart items. */
+    updateCart: (items: LineItem[]) => Promise<void>;
+    /** Update customer info on the session. */
+    updateCustomer: (customer: Partial<CheckoutCustomer>) => Promise<void>;
+    /** Update address on the session. */
+    updateAddress: (addresses: {
+        shippingAddress?: Address;
+        billingAddress?: Address;
+    }) => Promise<void>;
+    /**
+     * Update customer info AND address in a single call. Prefer this over
+     * calling `updateCustomer` then `updateAddress` separately — the
+     * underlying server action is destructive on partial saves
+     * (`customers.firstName = shippingAddress.firstName ?? null`), so
+     * sending the address without the customer name will silently wipe
+     * `customer.firstName` / `customer.lastName` from the session.
+     */
+    updateCustomerAndAddress: (data: {
+        customer: Partial<CheckoutCustomer>;
+        shippingAddress?: Address;
+        billingAddress?: Address;
+    }) => Promise<void>;
+    /** Apply a promo code. */
+    applyPromo: (code: string) => Promise<void>;
+    /** Remove the applied promo code. */
+    removePromo: (promotionId?: string) => Promise<void>;
+    /** Fetch shipping rates. */
+    getShippingRates: () => Promise<ShippingRate[]>;
+    /** Select a shipping rate. */
+    selectShippingRate: (rateId: string) => Promise<void>;
+}
+/**
+ * React hook for checkout session management.
+ *
+ * @param checkoutToken - The checkout token from the URL (e.g. `?checkoutToken=xxx`).
+ * @param sessionToken - Optional JWT session token (from URL param `token`).
+ *
+ * @example
+ * ```tsx
+ * const { session, isLoading, applyPromo, createSession } = useCheckout(checkoutToken, sessionToken);
+ * ```
+ */
+export declare function useCheckout(checkoutToken: string | null | undefined, sessionToken?: string): UseCheckoutReturn;
+//# sourceMappingURL=useCheckout.d.ts.map

package/dist/react/hooks/useCheckout.js

@@ -0,0 +1,177 @@
+import { useState, useEffect, useCallback } from 'react';
+import { useHeadlessClient } from '../provider.js';
+/**
+ * React hook for checkout session management.
+ *
+ * @param checkoutToken - The checkout token from the URL (e.g. `?checkoutToken=xxx`).
+ * @param sessionToken - Optional JWT session token (from URL param `token`).
+ *
+ * @example
+ * ```tsx
+ * const { session, isLoading, applyPromo, createSession } = useCheckout(checkoutToken, sessionToken);
+ * ```
+ */
+export function useCheckout(checkoutToken, sessionToken) {
+    const client = useHeadlessClient();
+    const [session, setSession] = useState(null);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const loadSession = useCallback(async () => {
+        if (!checkoutToken)
+            return;
+        setIsLoading(true);
+        setError(null);
+        try {
+            const s = await client.checkout.loadSession(checkoutToken, sessionToken);
+            setSession(s);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, checkoutToken, sessionToken]);
+    useEffect(() => {
+        loadSession();
+    }, [loadSession]);
+    const createSession = useCallback(async (opts) => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            const result = await client.checkout.createSession(opts);
+            const newUrl = new URL(window.location.href);
+            newUrl.searchParams.set('checkoutToken', result.checkoutToken);
+            newUrl.searchParams.set('token', result.sessionToken);
+            window.history.replaceState({}, '', newUrl.toString());
+            const s = await client.checkout.loadSession(result.checkoutToken, result.sessionToken);
+            setSession(s);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client]);
+    const updateCart = useCallback(async (items) => {
+        if (!session)
+            return;
+        // `updateCart` returns mutation stats (counts), not a CheckoutSession.
+        // We previously assigned that result into `setSession`, which silently
+        // replaced the session with `{ success, updated, created, total }`.
+        // Mirror the same pattern as `updateAddress`: mutate, then reload.
+        setIsLoading(true);
+        try {
+            await client.checkout.updateCart(session.id, items);
+            await loadSession();
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, session, loadSession]);
+    const updateCustomer = useCallback(async (customer) => {
+        if (!session)
+            return;
+        await client.checkout.updateCustomer(session.id, customer);
+    }, [client, session]);
+    const updateAddress = useCallback(async (addresses) => {
+        if (!session)
+            return;
+        setIsLoading(true);
+        try {
+            await client.checkout.updateAddress(session.id, addresses);
+            await loadSession();
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, session, loadSession]);
+    const updateCustomerAndAddress = useCallback(async (data) => {
+        if (!session)
+            return;
+        setIsLoading(true);
+        try {
+            await client.checkout.updateCustomerAndAddress(session.id, data);
+            await loadSession();
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, session, loadSession]);
+    const applyPromo = useCallback(async (code) => {
+        if (!session)
+            return;
+        setIsLoading(true);
+        try {
+            await client.checkout.applyPromoCode(session.id, code);
+            await loadSession();
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, session, loadSession]);
+    const removePromo = useCallback(async (promotionId) => {
+        if (!session)
+            return;
+        setIsLoading(true);
+        try {
+            await client.checkout.removePromoCode(session.id, promotionId);
+            await loadSession();
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, session, loadSession]);
+    const getShippingRates = useCallback(async () => {
+        if (!session)
+            return [];
+        return client.checkout.getShippingRates(session.id);
+    }, [client, session]);
+    const selectShippingRate = useCallback(async (rateId) => {
+        if (!session)
+            return;
+        setIsLoading(true);
+        try {
+            await client.checkout.selectShippingRate(session.id, rateId);
+            await loadSession();
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client, session, loadSession]);
+    return {
+        session,
+        isLoading,
+        error,
+        refresh: loadSession,
+        createSession,
+        updateCart,
+        updateCustomer,
+        updateAddress,
+        updateCustomerAndAddress,
+        applyPromo,
+        removePromo,
+        getShippingRates,
+        selectShippingRate,
+    };
+}
+//# sourceMappingURL=useCheckout.js.map

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

@@ -0,0 +1,28 @@
+import type { Customer, Order, Subscription } from '../../core/types.js';
+export interface UseCustomerReturn {
+    customer: Customer | null;
+    orders: Order[];
+    subscriptions: Subscription[];
+    isLoading: boolean;
+    error: Error | null;
+    /** Load customer profile by ID. */
+    loadCustomer: (customerId: string) => Promise<void>;
+    /** Load customer orders. */
+    loadOrders: (customerId: string) => Promise<void>;
+    /** Load customer subscriptions. */
+    loadSubscriptions: (customerId: string) => Promise<void>;
+    /** Update customer profile. */
+    updateProfile: (customerId: string, data: Partial<Pick<Customer, 'email' | 'firstName' | 'lastName' | 'phone'>>) => Promise<void>;
+}
+/**
+ * React hook for customer data -- profile, orders, subscriptions.
+ *
+ * @param customerId - Auto-loads the customer profile when provided.
+ *
+ * @example
+ * ```tsx
+ * const { customer, orders, loadOrders } = useCustomer(session?.customer?.id);
+ * ```
+ */
+export declare function useCustomer(customerId?: string | null): UseCustomerReturn;
+//# sourceMappingURL=useCustomer.d.ts.map

package/dist/react/hooks/useCustomer.js

@@ -0,0 +1,77 @@
+import { useState, useEffect, useCallback } from 'react';
+import { useHeadlessClient } from '../provider.js';
+/**
+ * React hook for customer data -- profile, orders, subscriptions.
+ *
+ * @param customerId - Auto-loads the customer profile when provided.
+ *
+ * @example
+ * ```tsx
+ * const { customer, orders, loadOrders } = useCustomer(session?.customer?.id);
+ * ```
+ */
+export function useCustomer(customerId) {
+    const client = useHeadlessClient();
+    const [customer, setCustomer] = useState(null);
+    const [orders, setOrders] = useState([]);
+    const [subscriptions, setSubscriptions] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const loadCustomer = useCallback(async (id) => {
+        setIsLoading(true);
+        setError(null);
+        try {
+            const c = await client.customer.getProfile(id);
+            setCustomer(c);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [client]);
+    const loadOrders = useCallback(async (id) => {
+        try {
+            const res = await client.customer.getOrders(id);
+            setOrders(res.orders);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }, [client]);
+    const loadSubscriptions = useCallback(async (id) => {
+        try {
+            const subs = await client.customer.getSubscriptions(id);
+            setSubscriptions(subs);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }, [client]);
+    const updateProfile = useCallback(async (id, data) => {
+        try {
+            const updated = await client.customer.updateProfile(id, data);
+            setCustomer(updated);
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }, [client]);
+    useEffect(() => {
+        if (customerId)
+            loadCustomer(customerId);
+    }, [customerId, loadCustomer]);
+    return {
+        customer,
+        orders,
+        subscriptions,
+        isLoading,
+        error,
+        loadCustomer,
+        loadOrders,
+        loadSubscriptions,
+        updateProfile,
+    };
+}
+//# sourceMappingURL=useCustomer.js.map

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

@@ -0,0 +1,26 @@
+/**
+ * React hook for Google Places Autocomplete — handles script injection,
+ * debounced prediction search, place detail fetching, and address extraction.
+ */
+import { type GooglePrediction, type GooglePlaceDetails, type ExtractedAddress, type FormattedAddress } from '../../core/helpers/autocomplete.js';
+export type { GooglePrediction, GooglePlaceDetails, ExtractedAddress, FormattedAddress };
+export interface UseGoogleAutocompleteOptions {
+    apiKey: string;
+    language?: string;
+    region?: string;
+    version?: string;
+    /** Defer script loading until searchPlaces() is first called. Default: false. */
+    defer?: boolean;
+}
+export interface UseGoogleAutocompleteReturn {
+    predictions: GooglePrediction[];
+    isLoading: boolean;
+    isScriptLoaded: boolean;
+    searchPlaces: (input: string, countryRestriction?: string) => void;
+    getPlaceDetails: (placeId: string) => Promise<GooglePlaceDetails | null>;
+    extractAddressComponents: (place: GooglePlaceDetails) => ExtractedAddress;
+    extractFormattedAddress: (place: GooglePlaceDetails) => FormattedAddress;
+    clearPredictions: () => void;
+}
+export declare function useGoogleAutocomplete(options: UseGoogleAutocompleteOptions): UseGoogleAutocompleteReturn;
+//# sourceMappingURL=useGoogleAutocomplete.d.ts.map

package/dist/react/hooks/useGoogleAutocomplete.js

@@ -0,0 +1,70 @@
+/**
+ * React hook for Google Places Autocomplete — handles script injection,
+ * debounced prediction search, place detail fetching, and address extraction.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { GoogleAutocompleteCore, loadGoogleMapsScript, } from '../../core/helpers/autocomplete.js';
+export function useGoogleAutocomplete(options) {
+    const { apiKey, language, region, version, defer = false } = options;
+    const [predictions, setPredictions] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [isScriptLoaded, setIsScriptLoaded] = useState(false);
+    const debounceRef = useRef(null);
+    const pendingRef = useRef(null);
+    const inject = useCallback(() => {
+        loadGoogleMapsScript(apiKey, { language, region, version }).then(() => setIsScriptLoaded(true));
+    }, [apiKey, language, region, version]);
+    // Eager load unless defer
+    useEffect(() => {
+        if (!apiKey || defer)
+            return;
+        inject();
+    }, [apiKey, defer, inject]);
+    // Replay pending search after deferred load
+    useEffect(() => {
+        if (isScriptLoaded && pendingRef.current) {
+            const { input, country } = pendingRef.current;
+            pendingRef.current = null;
+            doSearch(input, country);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [isScriptLoaded]);
+    const doSearch = useCallback((input, countryRestriction) => {
+        if (!isScriptLoaded) {
+            if (defer) {
+                pendingRef.current = { input, country: countryRestriction };
+                inject();
+            }
+            return;
+        }
+        if (input.length < 3) {
+            setPredictions([]);
+            return;
+        }
+        if (debounceRef.current)
+            clearTimeout(debounceRef.current);
+        debounceRef.current = setTimeout(async () => {
+            setIsLoading(true);
+            const results = await GoogleAutocompleteCore.searchPlaces(input, {
+                componentRestrictions: countryRestriction ? { country: countryRestriction.toLowerCase() } : undefined,
+            });
+            setPredictions(results);
+            setIsLoading(false);
+        }, 300);
+    }, [isScriptLoaded, defer, inject]);
+    const getPlaceDetails = useCallback((placeId) => GoogleAutocompleteCore.getPlaceDetails(placeId), []);
+    const extractAddressComponents = useCallback((place) => GoogleAutocompleteCore.extractAddressComponents(place), []);
+    const extractFormattedAddress = useCallback((place) => GoogleAutocompleteCore.extractFormattedAddress(place), []);
+    const clearPredictions = useCallback(() => setPredictions([]), []);
+    return {
+        predictions,
+        isLoading,
+        isScriptLoaded,
+        searchPlaces: doSearch,
+        getPlaceDetails,
+        extractAddressComponents,
+        extractFormattedAddress,
+        clearPredictions,
+    };
+}
+//# sourceMappingURL=useGoogleAutocomplete.js.map

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

@@ -0,0 +1,23 @@
+/**
+ * React hooks for ISO country/region data — CDN-backed,
+ * with Google Places → ISO region mapping.
+ */
+import { type ISOCountry, type ISORegion, type SupportedLanguage } from '../../core/helpers/countries.js';
+export type { ISOCountry, ISORegion, SupportedLanguage };
+export interface UseISODataReturn {
+    countries: Record<string, ISOCountry>;
+    getRegions: (countryCode: string) => ISORegion[];
+    findRegion: (countryCode: string, regionCode: string) => ISORegion | null;
+    mapGoogleToISO: (googleState: string, googleStateLong: string, countryCode: string) => ISORegion | null;
+    isLoaded: boolean;
+}
+export declare function useISOData(language?: SupportedLanguage): UseISODataReturn;
+export declare function useCountryOptions(language?: SupportedLanguage): Array<{
+    value: string;
+    label: string;
+}>;
+export declare function useRegionOptions(countryCode: string, language?: SupportedLanguage): Array<{
+    value: string;
+    label: string;
+}>;
+//# sourceMappingURL=useISOData.d.ts.map

package/dist/react/hooks/useISOData.js

@@ -0,0 +1,63 @@
+/**
+ * React hooks for ISO country/region data — CDN-backed,
+ * with Google Places → ISO region mapping.
+ */
+import { useEffect, useMemo, useState } from 'react';
+import { ISODataCore, } from '../../core/helpers/countries.js';
+import { ensureGeoDataLoaded, isLanguageLoaded } from '../../core/helpers/iso3166.js';
+export function useISOData(language = 'en') {
+    const [isLoaded, setIsLoaded] = useState(isLanguageLoaded(language));
+    useEffect(() => {
+        let cancelled = false;
+        ensureGeoDataLoaded(language)
+            .then(() => { if (!cancelled)
+            setIsLoaded(true); })
+            .catch((err) => console.error('[headless-sdk] Failed to load geodata:', err));
+        return () => { cancelled = true; };
+    }, [language]);
+    return useMemo(() => {
+        if (!isLoaded) {
+            return {
+                countries: {},
+                getRegions: () => [],
+                findRegion: () => null,
+                mapGoogleToISO: () => null,
+                isLoaded: false,
+            };
+        }
+        return {
+            countries: ISODataCore.getCountries(language),
+            getRegions: (cc) => ISODataCore.getRegions(cc, language),
+            findRegion: (cc, rc) => ISODataCore.findRegion(cc, rc, language),
+            mapGoogleToISO: (gs, gsl, cc) => ISODataCore.mapGoogleToISO(gs, gsl, cc, language),
+            isLoaded: true,
+        };
+    }, [language, isLoaded]);
+}
+// ---------------------------------------------------------------------------
+// useCountryOptions — countries as select options
+// ---------------------------------------------------------------------------
+export function useCountryOptions(language = 'en') {
+    const { countries, isLoaded } = useISOData(language);
+    return useMemo(() => {
+        if (!isLoaded)
+            return [];
+        return Object.values(countries)
+            .map((c) => ({ value: c.iso, label: c.name }))
+            .sort((a, b) => a.label.localeCompare(b.label));
+    }, [countries, isLoaded]);
+}
+// ---------------------------------------------------------------------------
+// useRegionOptions — regions/states for a country as select options
+// ---------------------------------------------------------------------------
+export function useRegionOptions(countryCode, language = 'en') {
+    const { getRegions, isLoaded } = useISOData(language);
+    return useMemo(() => {
+        if (!isLoaded || !countryCode)
+            return [];
+        return getRegions(countryCode)
+            .map((r) => ({ value: r.iso, label: r.name }))
+            .sort((a, b) => a.label.localeCompare(b.label));
+    }, [countryCode, getRegions, isLoaded]);
+}
+//# sourceMappingURL=useISOData.js.map