@blocklet/payment-react-headless 1.26.0

package/src/checkout/hooks/useCheckout.ts

@@ -0,0 +1,267 @@
+import { useMemo, useEffect, useRef, useState } from 'react';
+import { useMemoizedFn } from 'ahooks';
+import type { TLineItemExpanded, TPrice } from '@blocklet/payment-types';
+
+import { getErrorMessage } from '../../types/checkout-augmented';
+
+import type { UseCheckoutReturn } from '../types';
+import { useCheckoutSession } from './useCheckoutSession';
+import { usePaymentMethod } from './usePaymentMethod';
+import { usePricing } from './usePricing';
+import { useCustomerForm } from './useCustomerForm';
+import { useSubmit } from './useSubmit';
+import {
+  recalculatePromotionIfNeeded,
+  adjustQuantity,
+  performUpsell,
+  performDownsell,
+  changeDonationAmount,
+  getCrossSellItem,
+} from '../core/lineItems';
+import { addCrossSellItem, removeCrossSellItem, fetchCrossSellItem } from '../core/crossSell';
+import { parseBillingInterval } from '../core/billingInterval';
+
+export function useCheckout(sessionId: string): UseCheckoutReturn {
+  // 1. Session
+  const {
+    isLoading,
+    error,
+    errorCode,
+    refresh,
+    sessionData,
+    resolvedSessionId,
+    vendorCount,
+    product,
+    subscription,
+    pageInfo,
+  } = useCheckoutSession(sessionId);
+
+  const session = sessionData?.checkoutSession;
+  // Use resolved ID (cs_xxx) for all API calls - handles plink_ → cs_ resolution
+  const effectiveSessionId = resolvedSessionId || sessionId;
+
+  // 2. Payment method
+  const paymentMethodHook = usePaymentMethod(sessionData, effectiveSessionId, refresh);
+
+  // 3. Pricing
+  const pricingHook = usePricing(
+    sessionData,
+    effectiveSessionId,
+    paymentMethodHook.currency,
+    paymentMethodHook.isStripe,
+    refresh,
+    paymentMethodHook.current?.type || null
+  );
+
+  // 4. Customer form
+  const formHook = useCustomerForm(
+    sessionData,
+    paymentMethodHook.currency?.id || null,
+    paymentMethodHook.current?.id || null
+  );
+
+  // 5. Determine isDonation
+  const isDonation = session?.submit_type === 'donate';
+
+  // 6. Submit
+  const submitHook = useSubmit(
+    sessionData,
+    effectiveSessionId,
+    paymentMethodHook.currency?.id || null,
+    paymentMethodHook.isStripe,
+    paymentMethodHook.isCredit,
+    isDonation,
+    formHook.values,
+    formHook.validate,
+    refresh
+  );
+
+  // 7. Line items operations
+  const items = (session?.line_items || []) as TLineItemExpanded[];
+  const currencyId = paymentMethodHook.currency?.id || null;
+
+  // Recalculate promotion when currency changes or on initial load
+  const prevCurrencyRef = useRef<string | null>(null);
+  useEffect(() => {
+    const currId = paymentMethodHook.currency?.id || null;
+    if (!currId || !session) return;
+    if (prevCurrencyRef.current === null || currId !== prevCurrencyRef.current) {
+      prevCurrencyRef.current = currId;
+      recalculatePromotionIfNeeded(session, effectiveSessionId, currId).then(() => refresh(true));
+    }
+  }, [paymentMethodHook.currency?.id, session?.id]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const updateQuantity = useMemoizedFn(async (itemId: string, qty: number) => {
+    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) => {
+    try {
+      await performUpsell(effectiveSessionId, fromId, toId, session, currencyId, refresh);
+    } catch (err: unknown) {
+      console.error('Failed to upsell:', getErrorMessage(err));
+    }
+  });
+
+  const downsell = useMemoizedFn(async (priceId: string) => {
+    try {
+      await performDownsell(effectiveSessionId, priceId, session, currencyId, refresh);
+    } catch (err: unknown) {
+      console.error('Failed to downsell:', getErrorMessage(err));
+    }
+  });
+
+  // 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);
+
+  useEffect(() => {
+    if (!effectiveSessionId || !session) return undefined;
+    if (embeddedCrossSellItem) return undefined;
+
+    let cancelled = false;
+    fetchCrossSellItem(effectiveSessionId).then((item) => {
+      if (!cancelled && item) {
+        setFetchedCrossSellItem(item);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [effectiveSessionId, session?.id, embeddedCrossSellItem]); // 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 (!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 () => {
+    try {
+      await removeCrossSellItem(effectiveSessionId, session, currencyId, refresh);
+    } catch (err: unknown) {
+      console.error('Failed to remove cross-sell:', getErrorMessage(err));
+    }
+  });
+
+  // Billing interval
+  const billingInterval = useMemo(() => {
+    const parsed = parseBillingInterval(items);
+    if (!parsed) return null;
+
+    return {
+      current: parsed.current,
+      available: parsed.available,
+      switch: async (interval: 'month' | 'year' | 'week' | 'day') => {
+        const target = parsed.available.find((a) => a.interval === interval);
+        if (!target) return;
+
+        if (!parsed.firstItem.upsell_price_id && target.priceId) {
+          await upsell(parsed.firstItem.price_id, target.priceId);
+        } else if (parsed.firstItem.upsell_price_id) {
+          await downsell(parsed.firstItem.upsell_price_id);
+        }
+      },
+    };
+  }, [items, effectiveSessionId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Donation: custom amount change
+  const setDonationAmount = useMemoizedFn(async (priceId: string, amount: string) => {
+    if (!isDonation) return;
+    try {
+      await changeDonationAmount(effectiveSessionId, priceId, amount, session, currencyId, refresh);
+    } catch (err: unknown) {
+      console.error('Failed to change amount:', getErrorMessage(err));
+    }
+  });
+
+  // Convenience flags
+  const canSubmit = submitHook.status === 'idle' && !isLoading && !error && session?.status === 'open';
+
+  const isCompleted = submitHook.status === 'completed';
+
+  return {
+    isLoading,
+    error,
+    errorCode,
+    refresh: async () => {
+      await refresh();
+    },
+
+    product,
+    vendorCount,
+
+    lineItems: {
+      items: items.map((item) => ({
+        ...item,
+        adjustable_quantity: item.adjustable_quantity,
+      })),
+      updateQuantity,
+      upsell,
+      downsell,
+      billingInterval,
+      crossSellItem,
+      crossSellRequired,
+      addCrossSell,
+      removeCrossSell,
+    },
+
+    paymentMethod: {
+      current: paymentMethodHook.current,
+      currency: paymentMethodHook.currency,
+      available: paymentMethodHook.available,
+      currencies: paymentMethodHook.currencies,
+      isStripe: paymentMethodHook.isStripe,
+      isCrypto: paymentMethodHook.isCrypto,
+      isCredit: paymentMethodHook.isCredit,
+      setType: paymentMethodHook.setType,
+      types: paymentMethodHook.types,
+      setCurrency: paymentMethodHook.setCurrency,
+    },
+
+    stripe: paymentMethodHook.stripe,
+
+    pricing: pricingHook,
+
+    form: formHook,
+
+    submit: submitHook,
+
+    subscription,
+    pageInfo,
+
+    canSubmit,
+    isCompleted,
+    isDonation,
+    setDonationAmount,
+
+    customer: sessionData?.customer
+      ? {
+          name: sessionData.customer.name || '',
+          email: sessionData.customer.email || '',
+          phone: sessionData.customer.phone || '',
+          address: {
+            country: sessionData.customer.address?.country || '',
+            state: sessionData.customer.address?.state || '',
+            city: sessionData.customer.address?.city || '',
+            line1: sessionData.customer.address?.line1 || '',
+            line2: sessionData.customer.address?.line2 || '',
+            postal_code: sessionData.customer.address?.postal_code || '',
+          },
+        }
+      : null,
+
+    livemode: !!session?.livemode,
+    session: session || null,
+  };
+}

package/src/checkout/hooks/useCheckoutSession.ts

@@ -0,0 +1,217 @@
+import { useState, useCallback, useRef, useEffect } from 'react';
+import { useMemoizedFn } from 'ahooks';
+import type {
+  TCheckoutSessionExpanded,
+  TLineItemExpanded,
+  TPaymentMethodExpanded,
+  TPaymentIntent,
+  TCustomer,
+} from '@blocklet/payment-types';
+
+import api, { API } from '../../shared/api';
+import { getAxiosErrorDetails } from '../../types/checkout-augmented';
+import { parseProduct, parseSubscription, parsePageInfo } from '../core/session';
+
+export interface SessionData {
+  checkoutSession: TCheckoutSessionExpanded;
+  paymentMethods: TPaymentMethodExpanded[];
+  paymentIntent?: TPaymentIntent;
+  customer?: TCustomer;
+  quotes?: Record<
+    string,
+    {
+      quote_id: string;
+      expires_at: number;
+      quoted_amount: string;
+      exchange_rate?: string;
+      rate_provider_name?: string;
+      rate_provider_id?: string;
+    }
+  >;
+  rateUnavailable?: boolean;
+  rateError?: string;
+}
+
+export interface UseCheckoutSessionReturn {
+  // Loading
+  isLoading: boolean;
+  error: string | null;
+  /** Error code for structured error handling: 'SESSION_EXPIRED' | 'EMPTY_LINE_ITEMS' | null */
+  errorCode: 'SESSION_EXPIRED' | 'EMPTY_LINE_ITEMS' | null;
+  refresh: (forceRefresh?: boolean) => Promise<void>;
+  /** Directly update session data (e.g. after completion polling returns fresh data) */
+  setSessionData: (data: SessionData) => void;
+
+  // Raw session data (internal, for sub-hooks)
+  sessionData: SessionData | null;
+
+  // Resolved session ID (cs_xxx, resolved from plink_ if needed)
+  resolvedSessionId: string;
+
+  // Vendor info for completion polling
+  vendorCount: number;
+
+  // Parsed product
+  product: {
+    name: string;
+    description: string;
+    images: string[];
+    features: Array<{ name: string; icon?: string }>;
+    billing: {
+      mode: 'payment' | 'subscription';
+      interval: 'month' | 'year' | 'week' | 'day' | null;
+      intervalCount: number;
+      displayInterval: string;
+    };
+    metadata: Record<string, string>;
+  } | null;
+
+  // Parsed subscription config
+  subscription: {
+    mode: 'payment' | 'subscription' | 'setup';
+    showStake: boolean;
+    confirmMessage: string;
+  } | null;
+
+  // Parsed page info
+  pageInfo: {
+    formPurposeDescription?: { en: string; zh: string };
+    showProductFeatures: boolean;
+  } | null;
+}
+
+export function useCheckoutSession(sessionId: string): UseCheckoutSessionReturn {
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [sessionData, setSessionData] = useState<SessionData | null>(null);
+  const abortRef = useRef<AbortController | null>(null);
+  const mountedRef = useRef(true);
+  // For plink_ → cs_ resolution
+  const resolvedIdRef = useRef<string | null>(null);
+
+  const isPaymentLink = sessionId?.startsWith('plink_');
+
+  // Resolve plink_ to cs_ via POST /start/:id
+  const resolveSessionId = useMemoizedFn(async (): Promise<string> => {
+    if (!isPaymentLink) return sessionId;
+    if (resolvedIdRef.current) return resolvedIdRef.current;
+
+    const { data } = await api.post(API.START_PAYMENT_LINK(sessionId));
+    const resolved = data?.checkoutSession?.id;
+    if (!resolved) throw new Error('Failed to start payment link session');
+    resolvedIdRef.current = resolved;
+    return resolved;
+  });
+
+  const fetchSession = useMemoizedFn(async (forceRefresh = false) => {
+    // Cancel previous request
+    if (abortRef.current) {
+      abortRef.current.abort();
+    }
+    abortRef.current = new AbortController();
+
+    if (!sessionId) {
+      setIsLoading(false);
+      setError('Session ID is required');
+      return;
+    }
+
+    try {
+      // Only show loading skeleton on initial load, not on refreshes
+      if (!forceRefresh) {
+        setIsLoading(true);
+      }
+      setError(null);
+
+      // Resolve plink_ to real session id
+      const realId = await resolveSessionId();
+
+      const url = forceRefresh ? `${API.RETRIEVE_SESSION(realId)}?forceRefresh=1` : API.RETRIEVE_SESSION(realId);
+
+      const { data } = await api.get(url, {
+        signal: abortRef.current.signal,
+      });
+
+      if (!mountedRef.current) return;
+
+      // Validate session (matching original payment-react checks)
+      const cs = data?.checkoutSession;
+      if (cs) {
+        // Session expired check — skip for already-completed sessions
+        if (cs.status !== 'complete' && cs.expires_at && cs.expires_at <= Math.round(Date.now() / 1000)) {
+          setError('SESSION_EXPIRED');
+          setIsLoading(false);
+          return;
+        }
+        // Empty line_items check
+        if (!cs.line_items?.length) {
+          setError('EMPTY_LINE_ITEMS');
+          setIsLoading(false);
+          return;
+        }
+      }
+
+      setSessionData(data);
+      setIsLoading(false);
+    } catch (err: unknown) {
+      if (!mountedRef.current) return;
+      const { isCancelled, message } = getAxiosErrorDetails(err);
+      if (isCancelled) return;
+
+      setError(message || 'Failed to load checkout session');
+      setIsLoading(false);
+    }
+  });
+
+  const refresh = useCallback(
+    async (forceRefresh = false) => {
+      await fetchSession(forceRefresh);
+    },
+    [fetchSession]
+  );
+
+  // Initial load
+  useEffect(() => {
+    mountedRef.current = true;
+    fetchSession();
+    return () => {
+      mountedRef.current = false;
+      if (abortRef.current) {
+        abortRef.current.abort();
+      }
+    };
+  }, [sessionId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const session = sessionData?.checkoutSession;
+
+  // Expose the resolved session ID (cs_xxx) for downstream hooks
+  const resolvedSessionId = resolvedIdRef.current || (isPaymentLink ? '' : sessionId);
+
+  // Determine error code for structured handling
+  let errorCode: 'SESSION_EXPIRED' | 'EMPTY_LINE_ITEMS' | null = null;
+  if (error === 'SESSION_EXPIRED') {
+    errorCode = 'SESSION_EXPIRED';
+  } else if (error === 'EMPTY_LINE_ITEMS') {
+    errorCode = 'EMPTY_LINE_ITEMS';
+  }
+
+  // Count vendor configs for post-payment polling
+  const vendorCount =
+    (session?.line_items as TLineItemExpanded[] | undefined)?.reduce((count: number, item) => {
+      return count + (item?.price?.product?.vendor_config?.length || 0);
+    }, 0) || 0;
+
+  return {
+    isLoading,
+    error,
+    errorCode,
+    refresh,
+    setSessionData,
+    sessionData,
+    resolvedSessionId,
+    vendorCount,
+    product: session ? parseProduct(session) : null,
+    subscription: session ? parseSubscription(session) : null,
+    pageInfo: session ? parsePageInfo(session) : null,
+  };
+}

package/src/checkout/hooks/useCheckoutStatus.ts

@@ -0,0 +1,31 @@
+import { useSessionContext } from '../context/SessionContext';
+
+export interface UseCheckoutStatusReturn {
+  isLoading: boolean;
+  error: string | null;
+  errorCode: 'SESSION_EXPIRED' | 'EMPTY_LINE_ITEMS' | null;
+  canSubmit: boolean;
+  isCompleted: boolean;
+  isDonation: boolean;
+  livemode: boolean;
+}
+
+export function useCheckoutStatus(): UseCheckoutStatusReturn {
+  const { isLoading, error, errorCode, session, isDonation } = useSessionContext();
+
+  // Note: canSubmit requires submit status which lives outside context
+  // For full canSubmit, use in combination with useSubmit
+  const canSubmit = !isLoading && !error && session?.status === 'open';
+  const isCompleted = session?.status === 'complete';
+  const livemode = !!session?.livemode;
+
+  return {
+    isLoading,
+    error,
+    errorCode,
+    canSubmit,
+    isCompleted,
+    isDonation,
+    livemode,
+  };
+}

package/src/checkout/hooks/useCrossSell.ts

@@ -0,0 +1,80 @@
+import { useMemo, useState, useEffect } from 'react';
+import { useMemoizedFn } from 'ahooks';
+import type { TPrice } from '@blocklet/payment-types';
+
+import { getErrorMessage } from '../../types/checkout-augmented';
+
+import { useSessionContext } from '../context/SessionContext';
+import { usePaymentMethodContext } from '../context/PaymentMethodContext';
+import { getCrossSellItem } from '../core/lineItems';
+import { addCrossSellItem, removeCrossSellItem, fetchCrossSellItem } from '../core/crossSell';
+
+export interface UseCrossSellReturn {
+  item: TPrice | null;
+  required: boolean;
+  add: () => Promise<void>;
+  remove: () => Promise<void>;
+}
+
+export function useCrossSell(): UseCrossSellReturn {
+  const { items, session, effectiveSessionId, refresh } = useSessionContext();
+  const { currency } = usePaymentMethodContext();
+  const currencyId = currency?.id || null;
+
+  const embeddedItem = useMemo(() => getCrossSellItem(items), [items]);
+  const [fetchedItem, setFetchedItem] = 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 (embeddedItem) {
+      setFetchedItem(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) {
+        setFetchedItem(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, embeddedItem, itemPriceIds, hasCrossSellInItems]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  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: unknown) {
+      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: unknown) {
+      console.error('Failed to remove cross-sell:', getErrorMessage(err));
+    }
+  });
+
+  return { item, required, add, remove };
+}