@blocklet/payment-react-headless 1.26.0

package/src/checkout/hooks/useCustomerForm.ts

@@ -0,0 +1,156 @@
+import { useState, useMemo, useEffect } from 'react';
+import { useMemoizedFn } from 'ahooks';
+
+import api, { API } from '../../shared/api';
+import { validateForm } from '../../shared/validation';
+import type { FieldConfig, CheckoutFormData } from '../types';
+import { buildFields, createInitialValues, setNestedValue } from '../core/customerForm';
+import type { SessionData } from './useCheckoutSession';
+
+export interface UseCustomerFormReturn {
+  fields: FieldConfig[];
+  values: CheckoutFormData;
+  onChange: (field: string, value: string | boolean | Record<string, string>) => void;
+  errors: Partial<Record<string, string>>;
+  touched: Record<string, boolean>;
+  validate: () => Promise<boolean>;
+  validateField: (field: string) => Promise<void>;
+  /** Re-fetch customer info from backend and update form values (e.g. after login) */
+  refetchCustomer: () => Promise<void>;
+}
+
+export function useCustomerForm(
+  sessionData: SessionData | null,
+  currencyId: string | null,
+  methodId: string | null
+): UseCustomerFormReturn {
+  const session = sessionData?.checkoutSession;
+  const customer = sessionData?.customer;
+
+  const fields = useMemo(() => buildFields(session), [session?.id]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const [values, setValues] = useState<CheckoutFormData>(() => createInitialValues(session, customer));
+  const [errors, setErrors] = useState<Partial<Record<string, string>>>({});
+  const [touched, setTouched] = useState<Record<string, boolean>>({});
+  const [prefetched, setPrefetched] = useState(false);
+
+  // Re-initialize when session loads
+  useEffect(() => {
+    if (session && !prefetched) {
+      setValues(createInitialValues(session, customer));
+    }
+  }, [session?.id]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Sync payment method/currency into values
+  useEffect(() => {
+    if (currencyId || methodId) {
+      setValues((prev) => ({
+        ...prev,
+        ...(currencyId && { payment_currency: currencyId }),
+        ...(methodId && { payment_method: methodId }),
+      }));
+    }
+  }, [currencyId, methodId]);
+
+  // Prefetch customer info
+  useEffect(() => {
+    if (!session || prefetched || session.status === 'complete') return;
+
+    const fetchCustomer = async () => {
+      try {
+        const { data } = await api.get(`${API.CUSTOMER_ME}?fallback=1&skipSummary=1`);
+        if (data) {
+          setPrefetched(true);
+          setValues((prev) => ({
+            ...prev,
+            customer_name: prev.customer_name || data.name || '',
+            customer_email: prev.customer_email || data.email || '',
+            customer_phone: prev.customer_phone || data.phone || '',
+            billing_address: {
+              ...prev.billing_address!,
+              country: prev.billing_address?.country || data.address?.country || '',
+              state: prev.billing_address?.state || data.address?.state || '',
+              city: prev.billing_address?.city || data.address?.city || '',
+              line1: prev.billing_address?.line1 || data.address?.line1 || '',
+              line2: prev.billing_address?.line2 || data.address?.line2 || '',
+              postal_code: prev.billing_address?.postal_code || data.address?.postal_code || '',
+            },
+          }));
+        }
+      } catch {
+        // Ignore - customer info is optional
+      }
+    };
+
+    fetchCustomer();
+  }, [session?.id]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const onChange = useMemoizedFn((field: string, value: string | boolean | Record<string, string>) => {
+    setValues((prev) => setNestedValue(prev, field, value));
+    setTouched((prev) => ({ ...prev, [field]: true }));
+  });
+
+  const getValidateOptions = useMemoizedFn(() => ({
+    phoneEnabled: !!session?.phone_number_collection?.enabled,
+    addressMode: session?.billing_address_collection as 'auto' | 'required' | null,
+    fieldValidation: session?.metadata?.page_info?.field_validation,
+  }));
+
+  const validate = useMemoizedFn(async () => {
+    const result = await validateForm(values, getValidateOptions());
+    setErrors(result.errors);
+    return result.valid;
+  });
+
+  // Single-field blur validation — matches V1's trigger(fieldName)
+  const validateField = useMemoizedFn(async (field: string) => {
+    const result = await validateForm(values, getValidateOptions());
+    setErrors((prev) => {
+      const next = { ...prev };
+      if (result.errors[field]) {
+        next[field] = result.errors[field];
+      } else {
+        delete next[field];
+      }
+      return next;
+    });
+  });
+
+  // Re-fetch customer info (used after login to populate form)
+  const refetchCustomer = useMemoizedFn(async () => {
+    try {
+      const { data } = await api.get(`${API.CUSTOMER_ME}?fallback=1&skipSummary=1`);
+      if (data) {
+        setPrefetched(true);
+        setValues((prev) => ({
+          ...prev,
+          customer_name: data.name || prev.customer_name || '',
+          customer_email: data.email || prev.customer_email || '',
+          customer_phone: data.phone || prev.customer_phone || '',
+          billing_address: {
+            ...prev.billing_address!,
+            country: data.address?.country || prev.billing_address?.country || '',
+            state: data.address?.state || prev.billing_address?.state || '',
+            city: data.address?.city || prev.billing_address?.city || '',
+            line1: data.address?.line1 || prev.billing_address?.line1 || '',
+            line2: data.address?.line2 || prev.billing_address?.line2 || '',
+            postal_code: data.address?.postal_code || prev.billing_address?.postal_code || '',
+          },
+        }));
+      }
+    } catch {
+      // Ignore - customer info is optional
+    }
+  });
+
+  return {
+    fields,
+    values,
+    onChange,
+    errors,
+    touched,
+    validate,
+    validateField,
+    refetchCustomer,
+  };
+}

package/src/checkout/hooks/useCustomerFormFeature.ts

@@ -0,0 +1,7 @@
+import { useCustomerFormContext } from '../context/CustomerFormContext';
+import type { UseCustomerFormReturn } from './useCustomerForm';
+
+// Context-aware version: reads shared customer form state from CheckoutProvider
+export function useCustomerFormFeature(): UseCustomerFormReturn {
+  return useCustomerFormContext();
+}

package/src/checkout/hooks/useExchangeRate.ts

@@ -0,0 +1,28 @@
+import { useExchangeRateContext } from '../context/ExchangeRateContext';
+import { formatExchangeRate, formatExchangeRateDisplay } from '../../shared/format';
+
+export interface UseExchangeRateReturn {
+  value: string | null;
+  display: string | null;
+  provider: string | null;
+  providerDisplay: string | null;
+  fetchedAt: number | null;
+  status: 'loading' | 'available' | 'unavailable';
+  hasDynamicPricing: boolean;
+  refresh: () => Promise<void>;
+}
+
+export function useExchangeRate(): UseExchangeRateReturn {
+  const { rate, provider, providerDisplay, fetchedAt, status, hasDynamicPricing, refresh } = useExchangeRateContext();
+
+  return {
+    value: formatExchangeRate(rate),
+    display: rate ? formatExchangeRateDisplay(rate) : null,
+    provider,
+    providerDisplay,
+    fetchedAt,
+    status,
+    hasDynamicPricing,
+    refresh,
+  };
+}

package/src/checkout/hooks/useLineItems.ts

@@ -0,0 +1,191 @@
+import { useMemo, useState, useEffect, useRef } from 'react';
+import { useMemoizedFn } from 'ahooks';
+import type { TLineItemExpanded, TPrice } from '@blocklet/payment-types';
+
+import { getErrorMessage } from '../../types/checkout-augmented';
+
+import { useSessionContext } from '../context/SessionContext';
+import { usePaymentMethodContext } from '../context/PaymentMethodContext';
+import {
+  adjustQuantity,
+  performUpsell,
+  performDownsell,
+  changeDonationAmount,
+  getCrossSellItem,
+} from '../core/lineItems';
+import { addCrossSellItem, removeCrossSellItem, fetchCrossSellItem } from '../core/crossSell';
+
+export interface UseLineItemsReturn {
+  items: Array<
+    TLineItemExpanded & {
+      adjustable_quantity?: {
+        enabled: boolean;
+        minimum?: number;
+        maximum?: number;
+      };
+    }
+  >;
+  /** true if all items pass inventory check (quantity_available, quantity_limit_per_checkout) */
+  inventoryOk: boolean;
+  updateQuantity: (itemId: string, qty: number) => Promise<void>;
+  upsell: (fromId: string, toId: string) => Promise<void>;
+  downsell: (priceId: string) => Promise<void>;
+  crossSellItem: TPrice | null;
+  crossSellRequired: boolean;
+  addCrossSell: () => Promise<void>;
+  removeCrossSell: () => Promise<void>;
+  isDonation: boolean;
+  setDonationAmount: (priceId: string, amount: string) => Promise<void>;
+}
+
+export function useLineItems(): UseLineItemsReturn {
+  const { items, session, effectiveSessionId, isDonation, refresh } = useSessionContext();
+  const { currency } = usePaymentMethodContext();
+  const currencyId = currency?.id || null;
+
+  // Default quantity from URL params: ?qty=5 or ?qty_price_xxx=10 (matching original product-item.tsx)
+  const defaultQtyApplied = useRef(false);
+  useEffect(() => {
+    if (defaultQtyApplied.current || !effectiveSessionId || !items.length || !currencyId || session?.status === 'complete') return;
+    try {
+      const params = new URLSearchParams(window.location.search);
+      for (const item of items) {
+        const qtyStr = params.get(`qty_${item.price_id}`) || params.get(`qty_${item.price?.id}`) || params.get('qty');
+        if (qtyStr) {
+          const qty = Math.max(1, parseInt(qtyStr, 10));
+          if (Number.isFinite(qty) && qty !== item.quantity) {
+            defaultQtyApplied.current = true;
+            adjustQuantity(effectiveSessionId, item.price_id, qty, currencyId, session, refresh);
+            break; // only apply to the first matching item for ?qty
+          }
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }, [effectiveSessionId, items, currencyId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const updateQuantity = useMemoizedFn(async (itemId: string, qty: number) => {
+    if (session?.status === 'complete') return;
+    try {
+      await adjustQuantity(effectiveSessionId, itemId, qty, currencyId, session, refresh);
+    } catch (err: unknown) {
+      console.error('Failed to update quantity:', getErrorMessage(err));
+    }
+  });
+
+  const upsell = useMemoizedFn(async (fromId: string, toId: string) => {
+    if (session?.status === 'complete') return;
+    await performUpsell(effectiveSessionId, fromId, toId, session, currencyId, refresh);
+  });
+
+  const downsell = useMemoizedFn(async (priceId: string) => {
+    if (session?.status === 'complete') return;
+    await performDownsell(effectiveSessionId, priceId, session, currencyId, refresh);
+  });
+
+  // Cross-sell item detection (must be before addCrossSell so it can reference crossSellItem)
+  const embeddedCrossSellItem = useMemo(() => getCrossSellItem(items), [items]);
+  const [fetchedCrossSellItem, setFetchedCrossSellItem] = useState<TPrice | null>(null);
+
+  // Stable key that only changes on structural item changes (upsell/downsell/add/remove), not quantity
+  const itemPriceIds = useMemo(() => items.map((i) => i.price_id).join(','), [items]);
+
+  // Skip fetch when cross-sell is already added to session line items
+  const hasCrossSellInItems = useMemo(() => items.some((i: any) => i.cross_sell), [items]);
+
+  useEffect(() => {
+    if (!effectiveSessionId || !session) return undefined;
+    if (session.status === 'complete') return undefined;
+    if (embeddedCrossSellItem) {
+      setFetchedCrossSellItem(null); // clear stale fetched item when embedded item exists
+      return undefined;
+    }
+    if (hasCrossSellInItems) {
+      return undefined; // cross-sell already in cart, no need to fetch the offer
+    }
+
+    let cancelled = false;
+    fetchCrossSellItem(effectiveSessionId).then((item) => {
+      if (!cancelled) {
+        setFetchedCrossSellItem(item); // set null explicitly when no cross-sell for current interval
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+    // Re-fetch when item structure changes (e.g. after upsell/downsell changes billing interval)
+  }, [effectiveSessionId, session?.id, embeddedCrossSellItem, itemPriceIds, hasCrossSellInItems]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const crossSellItem = embeddedCrossSellItem || fetchedCrossSellItem;
+  const crossSellRequired = useMemo(() => items.some((item) => item.cross_sell_required), [items]);
+
+  const addCrossSell = useMemoizedFn(async () => {
+    if (session?.status === 'complete') return;
+    if (!crossSellItem) return;
+    try {
+      await addCrossSellItem(effectiveSessionId, crossSellItem.id, session, currencyId, refresh);
+    } catch (err: unknown) {
+      console.error('Failed to add cross-sell:', getErrorMessage(err));
+    }
+  });
+
+  const removeCrossSell = useMemoizedFn(async () => {
+    if (session?.status === 'complete') return;
+    try {
+      await removeCrossSellItem(effectiveSessionId, session, currencyId, refresh);
+    } catch (err: unknown) {
+      console.error('Failed to remove cross-sell:', getErrorMessage(err));
+    }
+  });
+
+  const setDonationAmount = useMemoizedFn(async (priceId: string, amount: string) => {
+    if (session?.status === 'complete') return;
+    if (!isDonation) return;
+    try {
+      await changeDonationAmount(effectiveSessionId, priceId, amount, session, currencyId, refresh);
+    } catch (err: unknown) {
+      console.error('Failed to change amount:', getErrorMessage(err));
+    }
+  });
+
+  const mappedItems = useMemo(
+    () =>
+      items.map((item) => ({
+        ...item,
+        adjustable_quantity: item.adjustable_quantity,
+      })),
+    [items]
+  );
+
+  // Inventory check: matching original formatQuantityInventory logic
+  const inventoryOk = useMemo(
+    () =>
+      items.every((item) => {
+        const { price } = item;
+        if (!price) return true;
+        const q = Number(item.quantity) || 0;
+        const available = price.quantity_available || 0;
+        const sold = price.quantity_sold || 0;
+        const limitPerCheckout = price.quantity_limit_per_checkout || 0;
+        if (available > 0 && sold + q > available) return false;
+        if (limitPerCheckout > 0 && limitPerCheckout < q) return false;
+        return true;
+      }),
+    [items]
+  );
+
+  return {
+    items: mappedItems,
+    inventoryOk,
+    updateQuantity,
+    upsell,
+    downsell,
+    crossSellItem,
+    crossSellRequired,
+    addCrossSell,
+    removeCrossSell,
+    isDonation,
+    setDonationAmount,
+  };
+}

package/src/checkout/hooks/usePaymentMethod.ts

@@ -0,0 +1,165 @@
+import { useState, useMemo, useEffect, useRef } from 'react';
+import { useMemoizedFn } from 'ahooks';
+import type { TPaymentMethodExpanded, TPaymentCurrency } from '@blocklet/payment-types';
+
+import type { CheckoutSessionRuntime } from '../../types/checkout-augmented';
+import { getErrorMessage } from '../../types/checkout-augmented';
+
+import api, { API } from '../../shared/api';
+import {
+  flattenCurrencies,
+  getInitialCurrencyId,
+  getCurrencyStorageKey,
+  findMethodAndCurrency,
+  buildPaymentTypes,
+} from '../core/paymentMethod';
+import type { SessionData } from './useCheckoutSession';
+
+export interface UsePaymentMethodReturn {
+  current: TPaymentMethodExpanded;
+  currency: TPaymentCurrency;
+  available: TPaymentMethodExpanded[];
+  currencies: TPaymentCurrency[];
+  isStripe: boolean;
+  isCrypto: boolean;
+  isCredit: boolean;
+  switching: boolean;
+  setType: (type: 'stripe' | 'crypto') => Promise<void>;
+  types: Array<{
+    type: 'stripe' | 'crypto';
+    label: string;
+    currencies: TPaymentCurrency[];
+    active: boolean;
+  }>;
+  setCurrency: (currencyId: string) => Promise<void>;
+  stripe: {
+    publishableKey: string | null;
+    clientSecret: string | null;
+    status: 'idle' | 'ready' | 'processing' | 'succeeded' | 'failed';
+  } | null;
+}
+
+export function usePaymentMethod(
+  sessionData: SessionData | null,
+  sessionId: string,
+  refreshSession: (force?: boolean) => Promise<void>
+): UsePaymentMethodReturn {
+  const methods = sessionData?.paymentMethods || [];
+  const session = sessionData?.checkoutSession;
+
+  const [currencyId, setCurrencyId] = useState<string | null>(() => getInitialCurrencyId(session, methods));
+  const [switching, setSwitching] = useState(false);
+  const initialSyncedRef = useRef<string | null>(null);
+
+  // Re-initialize when session first loads
+  useEffect(() => {
+    if (session && !currencyId) {
+      setCurrencyId(getInitialCurrencyId(session, methods));
+    }
+  }, [session?.id]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const { method: currentMethod, currency: currentCurrency } = useMemo(
+    () => findMethodAndCurrency(methods, currencyId),
+    [methods, currencyId]
+  );
+
+  const allCurrencies = useMemo(() => flattenCurrencies(methods), [methods]);
+
+  const isStripe = currentMethod?.type === 'stripe';
+  const isCrypto = currentMethod?.type !== 'stripe' && currentMethod?.type !== undefined;
+  const isCredit = currentCurrency?.type === 'credit';
+
+  const types = useMemo(() => buildPaymentTypes(methods, currentMethod), [methods, currentMethod]);
+
+  const setType = useMemoizedFn(async (type: 'stripe' | 'crypto') => {
+    const targetMethod = methods.find((m) => (type === 'stripe' ? m.type === 'stripe' : m.type !== 'stripe'));
+    if (!targetMethod) return;
+
+    const firstCurrency = targetMethod.payment_currencies?.[0];
+    if (firstCurrency) {
+      await switchCurrency(firstCurrency.id);
+    }
+  });
+
+  const switchCurrency = useMemoizedFn(async (newCurrencyId: string) => {
+    if (session?.status === 'complete') return;
+    const { method } = findMethodAndCurrency(methods, newCurrencyId);
+    if (!method || !sessionId) return;
+
+    setSwitching(true);
+    try {
+      await api.put(API.SWITCH_CURRENCY(sessionId), {
+        currency_id: newCurrencyId,
+        payment_method_id: method.id,
+      });
+
+      setCurrencyId(newCurrencyId);
+
+      // Save preference (DID-scoped key matching original payment-react)
+      try {
+        localStorage.setItem(
+          getCurrencyStorageKey((session as CheckoutSessionRuntime | undefined)?.user?.did),
+          newCurrencyId
+        );
+      } catch {
+        // Ignore
+      }
+
+      // Refresh session to get updated data (backend clears quote on currency switch)
+      await refreshSession(true);
+    } catch (err: unknown) {
+      console.error('Failed to switch currency:', getErrorMessage(err));
+      // Fallback: align with backend currency to resolve currencyMismatch
+      // Without this, a failed switch leaves currencyId diverged from session.currency_id,
+      // causing currencyMismatch (and thus `switching`) to stay true permanently
+      if (session?.currency_id) {
+        setCurrencyId(session.currency_id);
+      }
+    } finally {
+      setSwitching(false);
+    }
+  });
+
+  // Sync initial currency with backend if it differs from session.currency_id
+  // This handles the case where frontend picks a different currency (from cache/URL/no-wallet rule)
+  // than the session's default, ensuring backend recalculates amounts for the correct currency
+  useEffect(() => {
+    if (!session?.id || !currencyId || !methods.length) return;
+    // Only sync once per session
+    if (initialSyncedRef.current === session.id) return;
+    initialSyncedRef.current = session.id;
+
+    const sessionCurrencyId = session.currency_id;
+    if (session.status === 'complete') return;
+    if (sessionCurrencyId && sessionCurrencyId !== currencyId) {
+      switchCurrency(currencyId);
+    }
+  }, [session?.id, currencyId, methods.length]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Stripe configuration
+  const stripe = useMemo(() => {
+    if (!currentMethod || currentMethod.type !== 'stripe') return null;
+
+    const stripeSettings = currentMethod.settings?.stripe;
+    return {
+      publishableKey: stripeSettings?.publishable_key || null,
+      clientSecret: (sessionData?.paymentIntent as { client_secret?: string } | undefined)?.client_secret || null,
+      status: 'idle' as const,
+    };
+  }, [currentMethod, sessionData?.paymentIntent]);
+
+  return {
+    current: currentMethod as TPaymentMethodExpanded,
+    currency: currentCurrency as TPaymentCurrency,
+    available: methods,
+    currencies: allCurrencies,
+    isStripe,
+    isCrypto,
+    isCredit,
+    switching,
+    setType,
+    types,
+    setCurrency: switchCurrency,
+    stripe,
+  };
+}

package/src/checkout/hooks/usePaymentMethodFeature.ts

@@ -0,0 +1,8 @@
+import { usePaymentMethodContext } from '../context/PaymentMethodContext';
+import type { UsePaymentMethodReturn } from './usePaymentMethod';
+
+// Context-aware version: reads from PaymentMethodContext
+// Same return type as the param-based usePaymentMethod
+export function usePaymentMethodFeature(): UsePaymentMethodReturn {
+  return usePaymentMethodContext();
+}