@blocklet/payment-react-headless 1.26.0

package/es/checkout/hooks/useCrossSell.js

@@ -0,0 +1,57 @@
+import { useMemo, useState, useEffect } from "react";
+import { useMemoizedFn } from "ahooks";
+import { getErrorMessage } from "../../types/checkout-augmented.js";
+import { useSessionContext } from "../context/SessionContext.js";
+import { usePaymentMethodContext } from "../context/PaymentMethodContext.js";
+import { getCrossSellItem } from "../core/lineItems.js";
+import { addCrossSellItem, removeCrossSellItem, fetchCrossSellItem } from "../core/crossSell.js";
+export function useCrossSell() {
+  const { items, session, effectiveSessionId, refresh } = useSessionContext();
+  const { currency } = usePaymentMethodContext();
+  const currencyId = currency?.id || null;
+  const embeddedItem = useMemo(() => getCrossSellItem(items), [items]);
+  const [fetchedItem, setFetchedItem] = useState(null);
+  const itemPriceIds = useMemo(() => items.map((i) => i.price_id).join(","), [items]);
+  const hasCrossSellInItems = useMemo(() => items.some((i) => i.cross_sell), [items]);
+  useEffect(() => {
+    if (!effectiveSessionId || !session) return void 0;
+    if (session.status === "complete") return void 0;
+    if (embeddedItem) {
+      setFetchedItem(null);
+      return void 0;
+    }
+    if (hasCrossSellInItems) {
+      return void 0;
+    }
+    let cancelled = false;
+    fetchCrossSellItem(effectiveSessionId).then((item2) => {
+      if (!cancelled) {
+        setFetchedItem(item2);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [effectiveSessionId, session?.id, embeddedItem, itemPriceIds, hasCrossSellInItems]);
+  const item = embeddedItem || fetchedItem;
+  const required = useMemo(() => items.some((i) => i.cross_sell_required), [items]);
+  const add = useMemoizedFn(async () => {
+    if (session?.status === "complete") return;
+    const crossSellItemPrice = getCrossSellItem(items);
+    if (!crossSellItemPrice) return;
+    try {
+      await addCrossSellItem(effectiveSessionId, crossSellItemPrice.id, session, currencyId, refresh);
+    } catch (err) {
+      console.error("Failed to add cross-sell:", getErrorMessage(err));
+    }
+  });
+  const remove = useMemoizedFn(async () => {
+    if (session?.status === "complete") return;
+    try {
+      await removeCrossSellItem(effectiveSessionId, session, currencyId, refresh);
+    } catch (err) {
+      console.error("Failed to remove cross-sell:", getErrorMessage(err));
+    }
+  });
+  return { item, required, add, remove };
+}

package/es/checkout/hooks/useCustomerForm.d.ts

@@ -0,0 +1,14 @@
+import type { FieldConfig, CheckoutFormData } from '../types';
+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 declare function useCustomerForm(sessionData: SessionData | null, currencyId: string | null, methodId: string | null): UseCustomerFormReturn;

package/es/checkout/hooks/useCustomerForm.js

@@ -0,0 +1,116 @@
+import { useState, useMemo, useEffect } from "react";
+import { useMemoizedFn } from "ahooks";
+import api, { API } from "../../shared/api.js";
+import { validateForm } from "../../shared/validation.js";
+import { buildFields, createInitialValues, setNestedValue } from "../core/customerForm.js";
+export function useCustomerForm(sessionData, currencyId, methodId) {
+  const session = sessionData?.checkoutSession;
+  const customer = sessionData?.customer;
+  const fields = useMemo(() => buildFields(session), [session?.id]);
+  const [values, setValues] = useState(() => createInitialValues(session, customer));
+  const [errors, setErrors] = useState({});
+  const [touched, setTouched] = useState({});
+  const [prefetched, setPrefetched] = useState(false);
+  useEffect(() => {
+    if (session && !prefetched) {
+      setValues(createInitialValues(session, customer));
+    }
+  }, [session?.id]);
+  useEffect(() => {
+    if (currencyId || methodId) {
+      setValues((prev) => ({
+        ...prev,
+        ...currencyId && { payment_currency: currencyId },
+        ...methodId && { payment_method: methodId }
+      }));
+    }
+  }, [currencyId, methodId]);
+  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 {
+      }
+    };
+    fetchCustomer();
+  }, [session?.id]);
+  const onChange = useMemoizedFn((field, value) => {
+    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,
+    fieldValidation: session?.metadata?.page_info?.field_validation
+  }));
+  const validate = useMemoizedFn(async () => {
+    const result = await validateForm(values, getValidateOptions());
+    setErrors(result.errors);
+    return result.valid;
+  });
+  const validateField = useMemoizedFn(async (field) => {
+    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;
+    });
+  });
+  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 {
+    }
+  });
+  return {
+    fields,
+    values,
+    onChange,
+    errors,
+    touched,
+    validate,
+    validateField,
+    refetchCustomer
+  };
+}

package/es/checkout/hooks/useCustomerFormFeature.d.ts

@@ -0,0 +1,2 @@
+import type { UseCustomerFormReturn } from './useCustomerForm';
+export declare function useCustomerFormFeature(): UseCustomerFormReturn;

package/es/checkout/hooks/useCustomerFormFeature.js

@@ -0,0 +1,4 @@
+import { useCustomerFormContext } from "../context/CustomerFormContext.js";
+export function useCustomerFormFeature() {
+  return useCustomerFormContext();
+}

package/es/checkout/hooks/useExchangeRate.d.ts

@@ -0,0 +1,11 @@
+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 declare function useExchangeRate(): UseExchangeRateReturn;

package/es/checkout/hooks/useExchangeRate.js

@@ -0,0 +1,15 @@
+import { useExchangeRateContext } from "../context/ExchangeRateContext.js";
+import { formatExchangeRate, formatExchangeRateDisplay } from "../../shared/format.js";
+export function useExchangeRate() {
+  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/es/checkout/hooks/useLineItems.d.ts

@@ -0,0 +1,22 @@
+import type { TLineItemExpanded, TPrice } from '@blocklet/payment-types';
+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 declare function useLineItems(): UseLineItemsReturn;

package/es/checkout/hooks/useLineItems.js

@@ -0,0 +1,139 @@
+import { useMemo, useState, useEffect, useRef } from "react";
+import { useMemoizedFn } from "ahooks";
+import { getErrorMessage } from "../../types/checkout-augmented.js";
+import { useSessionContext } from "../context/SessionContext.js";
+import { usePaymentMethodContext } from "../context/PaymentMethodContext.js";
+import {
+  adjustQuantity,
+  performUpsell,
+  performDownsell,
+  changeDonationAmount,
+  getCrossSellItem
+} from "../core/lineItems.js";
+import { addCrossSellItem, removeCrossSellItem, fetchCrossSellItem } from "../core/crossSell.js";
+export function useLineItems() {
+  const { items, session, effectiveSessionId, isDonation, refresh } = useSessionContext();
+  const { currency } = usePaymentMethodContext();
+  const currencyId = currency?.id || null;
+  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;
+          }
+        }
+      }
+    } catch {
+    }
+  }, [effectiveSessionId, items, currencyId]);
+  const updateQuantity = useMemoizedFn(async (itemId, qty) => {
+    if (session?.status === "complete") return;
+    try {
+      await adjustQuantity(effectiveSessionId, itemId, qty, currencyId, session, refresh);
+    } catch (err) {
+      console.error("Failed to update quantity:", getErrorMessage(err));
+    }
+  });
+  const upsell = useMemoizedFn(async (fromId, toId) => {
+    if (session?.status === "complete") return;
+    await performUpsell(effectiveSessionId, fromId, toId, session, currencyId, refresh);
+  });
+  const downsell = useMemoizedFn(async (priceId) => {
+    if (session?.status === "complete") return;
+    await performDownsell(effectiveSessionId, priceId, session, currencyId, refresh);
+  });
+  const embeddedCrossSellItem = useMemo(() => getCrossSellItem(items), [items]);
+  const [fetchedCrossSellItem, setFetchedCrossSellItem] = useState(null);
+  const itemPriceIds = useMemo(() => items.map((i) => i.price_id).join(","), [items]);
+  const hasCrossSellInItems = useMemo(() => items.some((i) => i.cross_sell), [items]);
+  useEffect(() => {
+    if (!effectiveSessionId || !session) return void 0;
+    if (session.status === "complete") return void 0;
+    if (embeddedCrossSellItem) {
+      setFetchedCrossSellItem(null);
+      return void 0;
+    }
+    if (hasCrossSellInItems) {
+      return void 0;
+    }
+    let cancelled = false;
+    fetchCrossSellItem(effectiveSessionId).then((item) => {
+      if (!cancelled) {
+        setFetchedCrossSellItem(item);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [effectiveSessionId, session?.id, embeddedCrossSellItem, itemPriceIds, hasCrossSellInItems]);
+  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) {
+      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) {
+      console.error("Failed to remove cross-sell:", getErrorMessage(err));
+    }
+  });
+  const setDonationAmount = useMemoizedFn(async (priceId, amount) => {
+    if (session?.status === "complete") return;
+    if (!isDonation) return;
+    try {
+      await changeDonationAmount(effectiveSessionId, priceId, amount, session, currencyId, refresh);
+    } catch (err) {
+      console.error("Failed to change amount:", getErrorMessage(err));
+    }
+  });
+  const mappedItems = useMemo(
+    () => items.map((item) => ({
+      ...item,
+      adjustable_quantity: item.adjustable_quantity
+    })),
+    [items]
+  );
+  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/es/checkout/hooks/usePaymentMethod.d.ts

@@ -0,0 +1,26 @@
+import type { TPaymentMethodExpanded, TPaymentCurrency } from '@blocklet/payment-types';
+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 declare function usePaymentMethod(sessionData: SessionData | null, sessionId: string, refreshSession: (force?: boolean) => Promise<void>): UsePaymentMethodReturn;

package/es/checkout/hooks/usePaymentMethod.js

@@ -0,0 +1,101 @@
+import { useState, useMemo, useEffect, useRef } from "react";
+import { useMemoizedFn } from "ahooks";
+import { getErrorMessage } from "../../types/checkout-augmented.js";
+import api, { API } from "../../shared/api.js";
+import {
+  flattenCurrencies,
+  getInitialCurrencyId,
+  getCurrencyStorageKey,
+  findMethodAndCurrency,
+  buildPaymentTypes
+} from "../core/paymentMethod.js";
+export function usePaymentMethod(sessionData, sessionId, refreshSession) {
+  const methods = sessionData?.paymentMethods || [];
+  const session = sessionData?.checkoutSession;
+  const [currencyId, setCurrencyId] = useState(() => getInitialCurrencyId(session, methods));
+  const [switching, setSwitching] = useState(false);
+  const initialSyncedRef = useRef(null);
+  useEffect(() => {
+    if (session && !currencyId) {
+      setCurrencyId(getInitialCurrencyId(session, methods));
+    }
+  }, [session?.id]);
+  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 !== void 0;
+  const isCredit = currentCurrency?.type === "credit";
+  const types = useMemo(() => buildPaymentTypes(methods, currentMethod), [methods, currentMethod]);
+  const setType = useMemoizedFn(async (type) => {
+    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) => {
+    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);
+      try {
+        localStorage.setItem(
+          getCurrencyStorageKey(session?.user?.did),
+          newCurrencyId
+        );
+      } catch {
+      }
+      await refreshSession(true);
+    } catch (err) {
+      console.error("Failed to switch currency:", getErrorMessage(err));
+      if (session?.currency_id) {
+        setCurrencyId(session.currency_id);
+      }
+    } finally {
+      setSwitching(false);
+    }
+  });
+  useEffect(() => {
+    if (!session?.id || !currencyId || !methods.length) return;
+    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]);
+  const stripe = useMemo(() => {
+    if (!currentMethod || currentMethod.type !== "stripe") return null;
+    const stripeSettings = currentMethod.settings?.stripe;
+    return {
+      publishableKey: stripeSettings?.publishable_key || null,
+      clientSecret: sessionData?.paymentIntent?.client_secret || null,
+      status: "idle"
+    };
+  }, [currentMethod, sessionData?.paymentIntent]);
+  return {
+    current: currentMethod,
+    currency: currentCurrency,
+    available: methods,
+    currencies: allCurrencies,
+    isStripe,
+    isCrypto,
+    isCredit,
+    switching,
+    setType,
+    types,
+    setCurrency: switchCurrency,
+    stripe
+  };
+}

package/es/checkout/hooks/usePaymentMethodFeature.d.ts

@@ -0,0 +1,2 @@
+import type { UsePaymentMethodReturn } from './usePaymentMethod';
+export declare function usePaymentMethodFeature(): UsePaymentMethodReturn;

package/es/checkout/hooks/usePaymentMethodFeature.js

@@ -0,0 +1,4 @@
+import { usePaymentMethodContext } from "../context/PaymentMethodContext.js";
+export function usePaymentMethodFeature() {
+  return usePaymentMethodContext();
+}

package/es/checkout/hooks/usePricing.d.ts

@@ -0,0 +1,57 @@
+import type { TPaymentCurrency } from '@blocklet/payment-types';
+import type { SessionData } from './useCheckoutSession';
+export interface UsePricingReturn {
+    subtotal: string;
+    paymentAmount: string;
+    discount: string | null;
+    tax: {
+        amount: string;
+        rate: number;
+        inclusive: boolean;
+    } | null;
+    staking: string | null;
+    total: string;
+    usdEquivalent: string | null;
+    hasDynamicPricing: boolean;
+    rate: {
+        value: string | null;
+        display: string | null;
+        provider: string | null;
+        providerDisplay: string | null;
+        fetchedAt: number | null;
+        status: 'loading' | 'available' | 'unavailable';
+        refresh: () => Promise<void>;
+    };
+    quote: {
+        locked: boolean;
+        lockedAt: number | null;
+        expiresAt: number | null;
+        expired: boolean;
+        baseCurrency: string | null;
+    };
+    slippage: {
+        percent: number;
+        set: (config: {
+            mode: string;
+            percent: number;
+        }) => Promise<void>;
+    };
+    promotion: {
+        applied: boolean;
+        code: string | null;
+        active: boolean;
+        inactiveReason: string | null;
+        apply: (code: string) => Promise<{
+            success: boolean;
+            error?: string;
+        }>;
+        remove: () => Promise<void>;
+    };
+    trial: {
+        active: boolean;
+        days: number;
+        afterTrialPrice: string | null;
+        afterTrialInterval: string | null;
+    };
+}
+export declare function usePricing(sessionData: SessionData | null, sessionId: string, currency: TPaymentCurrency | null, isStripe: boolean, refreshSession: (force?: boolean) => Promise<void>, paymentMethodType?: string | null): UsePricingReturn;