@blocklet/payment-react-headless 1.26.0

package/src/checkout/hooks/useSubmit.ts

@@ -0,0 +1,684 @@
+import { useState, useRef, useEffect } from 'react';
+import { useMemoizedFn } from 'ahooks';
+import { WsClient } from '@arcblock/ws';
+
+import type { TLineItemExpanded } from '@blocklet/payment-types';
+
+import api, { API } from '../../shared/api';
+import { waitForCheckoutComplete, generateIdempotencyKey } from '../../shared/polling';
+import type { CheckoutSessionRuntime } from '../../types/checkout-augmented';
+import { getErrorMessage, getAxiosErrorDetails } from '../../types/checkout-augmented';
+import type { SessionData } from './useCheckoutSession';
+import type { SubmitStatus, SubmitContext, CheckoutResult, CheckoutFormData } from '../types';
+import {
+  RELAY_SOCKET_PREFIX,
+  getAppId,
+  getRelayChannel,
+  getRelayProtocol,
+  getSocketHost,
+  getSessionFingerprint,
+  buildSubmitPayload,
+  isQuoteError,
+  abortStripePayment,
+  submitCheckout,
+  confirmFastCheckout,
+} from '../core/submit';
+
+export interface VendorStatus {
+  success: boolean;
+  status: 'delivered' | 'pending' | 'failed';
+  progress: number;
+  message: string;
+  appUrl?: string;
+  title?: string;
+  name?: string;
+  vendorType: string;
+}
+
+export interface VendorOrderStatus {
+  payment_status: string;
+  session_status: string;
+  vendors: VendorStatus[];
+  error: string | null;
+  isAllCompleted: boolean;
+  hasFailed: boolean;
+}
+
+export interface UseSubmitReturn {
+  status: SubmitStatus;
+  context: SubmitContext;
+  execute: () => Promise<void>;
+  confirm: () => Promise<void>;
+  cancel: () => void;
+  result: CheckoutResult | null;
+  retry: () => Promise<void>;
+  reset: () => void;
+  stripeConfirm: () => Promise<void>;
+  stripeCancel: () => Promise<void>;
+  vendorStatus: VendorOrderStatus | null;
+  /** Whether the checkout config is locked (user clicked "Connect and Pay", pending login/submit) */
+  locked: boolean;
+  /** Lock the checkout config — prevents quantity/currency/method changes */
+  lock: () => void;
+}
+
+export function useSubmit(
+  sessionData: SessionData | null,
+  sessionId: string,
+  currencyId: string | null,
+  isStripe: boolean,
+  isCredit: boolean,
+  isDonation: boolean,
+  formValues: CheckoutFormData,
+  validateForm: () => Promise<boolean>,
+  refreshSession: (force?: boolean) => Promise<void>,
+  updateSessionData?: (data: SessionData) => void
+): UseSubmitReturn {
+  const session = sessionData?.checkoutSession;
+
+  const [status, setStatus] = useState<SubmitStatus>('idle');
+  const [context, setContext] = useState<SubmitContext>(null);
+  const [result, setResult] = useState<CheckoutResult | null>(null);
+  const [locked, setLocked] = useState(false);
+
+  const lock = useMemoizedFn(() => setLocked(true));
+  const unlock = useMemoizedFn(() => setLocked(false));
+
+  const mountedRef = useRef(true);
+  const pollingAbortRef = useRef(false);
+  const socketRef = useRef<WsClient | null>(null);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const subscriptionRef = useRef<{
+    channel: string;
+    on: (event: string, fn: (...args: any[]) => void) => void;
+    off?: (event: string, fn: (...args: any[]) => void) => void;
+  } | null>(null);
+  const lastPayloadRef = useRef<Record<string, unknown> | null>(null);
+  const [vendorStatus, setVendorStatus] = useState<VendorOrderStatus | null>(null);
+  const vendorTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const quoteRetryCountRef = useRef(0);
+  const MAX_QUOTE_RETRIES = 2;
+
+  // Stable idempotency key: reuse same Quote on retry (intent: "retry with same Quote")
+  // Only regenerate when payment context truly changes (currency, line items)
+  const idempotencyKeyRef = useRef<string>('');
+  const sessionFingerprintRef = useRef<string>('');
+
+  // Auto-detect already-completed session on load/refresh (e.g. page refresh after payment)
+  const completedDetectedRef = useRef(false);
+  useEffect(() => {
+    if (completedDetectedRef.current) return;
+    if (!session || !sessionData) return;
+
+    const isSessionComplete =
+      (session as any).status === 'complete' &&
+      ['paid', 'no_payment_required'].includes((session as any).payment_status);
+
+    if (isSessionComplete && status === 'idle') {
+      completedDetectedRef.current = true;
+      setResult(sessionData as CheckoutResult);
+      setStatus('completed');
+    }
+  }, [session, sessionData]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // WebSocket: connect and listen for checkout.session.completed
+  useEffect(() => {
+    mountedRef.current = true;
+
+    if (!sessionId || !getAppId()) return undefined;
+
+    const socket = new WsClient(`${getRelayProtocol()}//${getSocketHost()}${RELAY_SOCKET_PREFIX}`, {
+      longpollerTimeout: 5000,
+      heartbeatIntervalMs: 30 * 1000,
+    });
+    socket.connect();
+    socketRef.current = socket;
+
+    const sub = socket.subscribe(getRelayChannel('events'));
+    sub.channel = 'events';
+    subscriptionRef.current = sub;
+
+    return () => {
+      mountedRef.current = false;
+      pollingAbortRef.current = true;
+
+      if (subscriptionRef.current) {
+        socket.unsubscribe(getRelayChannel(subscriptionRef.current.channel));
+        subscriptionRef.current = null;
+      }
+      socket.disconnect();
+      socketRef.current = null;
+    };
+  }, [sessionId]);
+
+  // Listen for checkout completion via WebSocket
+  const handleWsComplete = useMemoizedFn(async ({ response }: { response: { id?: string } }) => {
+    if (response.id === sessionId && status !== 'completed') {
+      pollingAbortRef.current = true;
+      await handleCompletion();
+    }
+  });
+
+  useEffect(() => {
+    const sub = subscriptionRef.current;
+    if (sub) {
+      sub.on('checkout.session.completed', handleWsComplete);
+    }
+    return () => {
+      if (sub) {
+        try {
+          sub.off?.('checkout.session.completed', handleWsComplete);
+        } catch {
+          // Ignore
+        }
+      }
+    };
+  }, [subscriptionRef.current, status]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Common completion handler
+  const handleCompletion = useMemoizedFn(async () => {
+    try {
+      const completionResult = await waitForCheckoutComplete(sessionId);
+      if (!mountedRef.current) return;
+      setResult(completionResult);
+      // Update session context so downstream consumers (e.g. SuccessView) have fresh data
+      updateSessionData?.(completionResult as SessionData);
+      setStatus('completed');
+      setContext(null);
+    } catch (err: unknown) {
+      if (!mountedRef.current) return;
+      setStatus('failed');
+      setContext({ type: 'error', message: getErrorMessage(err) || 'Payment verification failed' });
+    }
+  });
+
+  // Vendor order polling after completion
+  useEffect(() => {
+    if (status !== 'completed' || !sessionId) return undefined;
+
+    const hasVendors = (session?.line_items as TLineItemExpanded[] | undefined)?.some(
+      (item) => !!item?.price?.product?.vendor_config?.length
+    );
+    if (!hasVendors) return undefined;
+
+    const startTime = Date.now();
+
+    const fetchVendorStatus = async () => {
+      try {
+        const { data } = await api.get(API.VENDOR_ORDER_STATUS(sessionId));
+        if (!mountedRef.current) return;
+
+        const needCheckError = Date.now() - startTime > 6000;
+        const allCompleted = data?.vendors?.every((v: VendorStatus) => v.progress >= 100);
+        const hasFailed = data?.vendors?.some(
+          (v: VendorStatus & { error?: string; error_message?: string }) =>
+            v.status === 'failed' || (needCheckError && !!v.error && !!v.error_message)
+        );
+
+        setVendorStatus({
+          ...data,
+          isAllCompleted: !hasFailed && allCompleted,
+          hasFailed,
+        });
+
+        if (hasFailed || allCompleted) return;
+
+        vendorTimerRef.current = setTimeout(fetchVendorStatus, 5000);
+      } catch {
+        // Ignore polling errors
+      }
+    };
+
+    fetchVendorStatus();
+
+    return () => {
+      if (vendorTimerRef.current) clearTimeout(vendorTimerRef.current);
+    };
+  }, [status, sessionId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Auto-refresh session for quote errors, with auto-retry for stale-lock errors (like V1)
+  const handleQuoteError = useMemoizedFn(async (errorCode: string, errorData?: Record<string, unknown>) => {
+    try {
+      await refreshSession(true);
+      if (!mountedRef.current) return;
+    } catch {
+      // Ignore refresh error
+    }
+
+    // QUOTE_UPDATED means the price actually changed — user should review
+    if (errorCode === 'QUOTE_UPDATED' && errorData?.checkoutSession) {
+      quoteRetryCountRef.current = 0;
+      setStatus('failed');
+      setContext({ type: 'error', message: 'Price updated, please resubmit', code: errorCode });
+      return;
+    }
+
+    // Stale-lock errors: auto-retry silently (up to MAX_QUOTE_RETRIES)
+    const canAutoRetry = ['QUOTE_LOCK_EXPIRED', 'QUOTE_EXPIRED_OR_USED', 'QUOTE_NOT_FOUND', 'QUOTE_REQUIRED'].includes(
+      errorCode
+    );
+    if (canAutoRetry && quoteRetryCountRef.current < MAX_QUOTE_RETRIES) {
+      quoteRetryCountRef.current += 1;
+      setStatus('idle');
+      setContext(null);
+      await execute(true);
+      return;
+    }
+
+    // Exhausted retries or unknown quote error
+    quoteRetryCountRef.current = 0;
+    setStatus('failed');
+    setContext({
+      type: 'error',
+      message: 'Price updated, please resubmit',
+      code: errorCode,
+    });
+  });
+
+  // Route based on submit response
+  const routeSubmitResponse = useMemoizedFn(async (data: Record<string, unknown>) => {
+    // Stripe payment — check BEFORE noPaymentRequired to match V1 behavior
+    // V1 routes by payment method type first, regardless of noPaymentRequired flag
+    if (isStripe) {
+      const stripeCtx = data.stripeContext as
+        | { status?: string; client_secret?: string; intent_type?: string }
+        | undefined;
+      if (stripeCtx?.status === 'succeeded') {
+        await handleCompletion();
+        return;
+      }
+
+      const piCtx = data.paymentIntent as { client_secret?: string } | undefined;
+      const clientSecret = stripeCtx?.client_secret || piCtx?.client_secret;
+      if (clientSecret) {
+        const intentType = (stripeCtx?.intent_type || 'payment_intent') as 'payment_intent' | 'setup_intent';
+        setStatus('waiting_stripe');
+        setContext({ type: 'stripe', clientSecret, intentType });
+        return;
+      }
+
+      // Stripe with no client_secret (e.g., free trial with no setup_intent needed)
+      if (data.noPaymentRequired) {
+        try {
+          const confirmResult = await confirmFastCheckout(sessionId);
+          const confirmSession = confirmResult.checkoutSession as Record<string, unknown> | undefined;
+          if (confirmResult.fastPaid || confirmSession?.status === 'complete') {
+            await handleCompletion();
+            return;
+          }
+        } catch {
+          // fall through
+        }
+      }
+
+      await handleCompletion();
+      return;
+    }
+
+    // No payment required (free trial, etc.) — crypto/DID path
+    if (data.noPaymentRequired) {
+      try {
+        const confirmResult = await confirmFastCheckout(sessionId);
+        const confirmSession = confirmResult.checkoutSession as Record<string, unknown> | undefined;
+        if (confirmResult.fastPaid || confirmSession?.status === 'complete') {
+          await handleCompletion();
+        } else {
+          setStatus('waiting_did');
+          setContext({
+            type: 'did_connect',
+            action: session?.mode || 'payment',
+            checkpointId: sessionId,
+            extraParams: {
+              checkoutSessionId: sessionId,
+              sessionUserDid: (session as CheckoutSessionRuntime | undefined)?.user?.did,
+            },
+          });
+        }
+      } catch {
+        if (!mountedRef.current) return;
+        setStatus('waiting_did');
+        setContext({
+          type: 'did_connect',
+          action: session?.mode || 'payment',
+          checkpointId: sessionId,
+          extraParams: {
+            checkoutSessionId: sessionId,
+            sessionUserDid: (session as CheckoutSessionRuntime | undefined)?.user?.did,
+          },
+        });
+      }
+      return;
+    }
+
+    // Fast pay routing — match V1: credit first, then balance/delegation
+    const fastPayInfo = data.fastPayInfo as
+      | { type?: string; amount?: string; payer?: string; token?: { balance?: string } }
+      | undefined;
+    const balance = data.balance as { sufficient?: boolean } | undefined;
+    const delegation = data.delegation as { sufficient?: boolean } | undefined;
+
+    // Credit payment — only when currency type is 'credit' (matches V1: paymentCurrency?.type === 'credit')
+    if (isCredit) {
+      if (data.creditSufficient === true && fastPayInfo) {
+        setStatus('confirming_fast_pay');
+        setContext({
+          type: 'fast_pay',
+          payType: 'credit',
+          amount: fastPayInfo.amount || '0',
+          payer: fastPayInfo.payer || '',
+        });
+        return;
+      }
+      // Credit currency but insufficient — show dialog
+      setStatus('credit_insufficient');
+      setContext({
+        type: 'credit_insufficient',
+        available: '0',
+        required: '0',
+      });
+      return;
+    }
+
+    // Balance/delegation fast pay (non-credit, non-donation)
+    if ((balance?.sufficient || delegation?.sufficient) && !isDonation && fastPayInfo) {
+      setStatus('confirming_fast_pay');
+      setContext({
+        type: 'fast_pay',
+        payType: (fastPayInfo.type as 'balance' | 'delegation') || 'balance',
+        amount: fastPayInfo.amount || '',
+        payer: fastPayInfo.payer || '',
+      });
+      return;
+    }
+
+    // Need DID connect (crypto payment)
+    setStatus('waiting_did');
+    setContext({
+      type: 'did_connect',
+      action: session?.mode || 'payment',
+      checkpointId: sessionId,
+      extraParams: {
+        checkoutSessionId: sessionId,
+        sessionUserDid: (session as CheckoutSessionRuntime | undefined)?.user?.did,
+      },
+    });
+  });
+
+  // Handle submit error
+  const handleSubmitError = useMemoizedFn(async (err: unknown) => {
+    const { code: errorCode, data: errorData, message: errMessage } = getAxiosErrorDetails(err);
+
+    // Quote-related errors
+    if (errorCode && isQuoteError(errorCode)) {
+      await handleQuoteError(errorCode, errorData);
+      return;
+    }
+
+    // RATE_BELOW_SLIPPAGE_LIMIT: fallback — stable idempotency key should prevent this,
+    // but handle gracefully if it occurs (e.g., after session refresh with new context)
+    if (errorCode === 'RATE_BELOW_SLIPPAGE_LIMIT') {
+      try {
+        await refreshSession(true);
+      } catch {
+        // Ignore
+      }
+      if (!mountedRef.current) return;
+      // Invalidate stale key so next submit creates a fresh quote
+      idempotencyKeyRef.current = '';
+      sessionFingerprintRef.current = '';
+      setStatus('failed');
+      setContext({
+        type: 'error',
+        message: (errorData?.error as string) || 'Exchange rate below acceptable limit, please retry',
+        code: errorCode,
+      });
+      return;
+    }
+
+    // RATE_UNAVAILABLE
+    if (errorCode === 'RATE_UNAVAILABLE') {
+      try {
+        await refreshSession(true);
+      } catch {
+        // Ignore
+      }
+      if (!mountedRef.current) return;
+      setStatus('failed');
+      setContext({
+        type: 'error',
+        message: (errorData?.rateError as string) || 'Exchange rate unavailable',
+        code: errorCode,
+      });
+      return;
+    }
+
+    // PRICE_CHANGED — match V1: show confirmation dialog with change_percent (snake_case from backend)
+    if (errorCode === 'PRICE_CHANGED') {
+      setStatus('confirming_price');
+      setContext({
+        type: 'price_change',
+        changePercent: (errorData?.change_percent as number) || 0,
+      });
+      return;
+    }
+
+    // PRICE_UNAVAILABLE / PRICE_UNSTABLE
+    if (errorCode === 'PRICE_UNAVAILABLE' || errorCode === 'PRICE_UNSTABLE') {
+      try {
+        await refreshSession(true);
+      } catch {
+        // Ignore
+      }
+      if (!mountedRef.current) return;
+      setStatus('failed');
+      setContext({
+        type: 'error',
+        message: (errorData?.error as string) || 'Price unavailable, please retry',
+        code: errorCode,
+      });
+      return;
+    }
+
+    // UNIFIED_APP_REQUIRED / CUSTOMER_LIMITED
+    if (errorCode === 'UNIFIED_APP_REQUIRED' || errorCode === 'CUSTOMER_LIMITED') {
+      setStatus('failed');
+      setContext({
+        type: 'error',
+        message: (errorData?.error as string) || errMessage || 'Cannot complete payment',
+        code: errorCode,
+      });
+      return;
+    }
+
+    // Generic error
+    const message = (errorData?.error as string) || errMessage || 'Payment failed';
+    setStatus('failed');
+    setContext({ type: 'error', message, code: errorCode });
+  });
+
+  // Main execute
+  const execute = useMemoizedFn(async (force = false) => {
+    if (!force && status !== 'idle') return;
+
+    // Reset quote retry counter on fresh user-initiated submit
+    if (!force) quoteRetryCountRef.current = 0;
+
+    if (!(await validateForm())) return;
+
+    // Vendor account validation
+    const user = (session as CheckoutSessionRuntime | undefined)?.user;
+    if (!user?.sourceAppPid) {
+      const hasVendorConfig = (session?.line_items as TLineItemExpanded[] | undefined)?.some(
+        (item) => !!item?.price?.product?.vendor_config?.length
+      );
+      if (hasVendorConfig) {
+        setStatus('failed');
+        setContext({ type: 'error', message: 'Vendor account required', code: 'VENDOR_ACCOUNT_REQUIRED' });
+        return;
+      }
+    }
+
+    setStatus('submitting');
+    setContext(null);
+    setResult(null);
+    pollingAbortRef.current = false;
+
+    // Stable idempotency key: only regenerate when payment context changes
+    // Same context retry → reuse Quote (intent: "Failed Payments don't invalidate Quote")
+    const fingerprint = getSessionFingerprint(session, currencyId);
+    if (fingerprint !== sessionFingerprintRef.current || !idempotencyKeyRef.current) {
+      sessionFingerprintRef.current = fingerprint;
+      idempotencyKeyRef.current = generateIdempotencyKey(sessionId, currencyId || '');
+    }
+
+    const payload = buildSubmitPayload(sessionId, currencyId, formValues, session, false, idempotencyKeyRef.current);
+    lastPayloadRef.current = payload;
+
+    try {
+      const data = await submitCheckout(sessionId, isDonation, payload);
+      if (!mountedRef.current) return;
+      await routeSubmitResponse(data);
+    } catch (err: unknown) {
+      if (!mountedRef.current) return;
+      await handleSubmitError(err);
+    }
+  });
+
+  // Confirm: handles both fast_pay and price_change
+  const confirm = useMemoizedFn(async () => {
+    if (status === 'confirming_fast_pay') {
+      setStatus('submitting');
+      try {
+        const data = await confirmFastCheckout(sessionId);
+
+        if (!mountedRef.current) return;
+
+        if (data.fastPaid) {
+          await handleCompletion();
+        } else {
+          setStatus('waiting_did');
+          setContext({
+            type: 'did_connect',
+            action: session?.mode || 'payment',
+            checkpointId: sessionId,
+            extraParams: {
+              checkoutSessionId: sessionId,
+              sessionUserDid: (session as CheckoutSessionRuntime | undefined)?.user?.did,
+            },
+          });
+        }
+      } catch (err: unknown) {
+        if (!mountedRef.current) return;
+
+        const { code: errorCode, data: errorData, message: errMsg } = getAxiosErrorDetails(err);
+
+        if (errorCode && isQuoteError(errorCode)) {
+          await handleQuoteError(errorCode, errorData);
+          return;
+        }
+
+        if (errorCode === 'RATE_UNAVAILABLE') {
+          try {
+            await refreshSession(true);
+          } catch {
+            /* Ignore */
+          }
+          if (!mountedRef.current) return;
+          setStatus('failed');
+          setContext({
+            type: 'error',
+            message: (errorData?.rateError as string) || 'Exchange rate unavailable',
+            code: errorCode,
+          });
+          return;
+        }
+
+        setStatus('failed');
+        setContext({
+          type: 'error',
+          message: (errorData?.error as string) || errMsg || 'Fast pay confirmation failed',
+          code: errorCode,
+        });
+      }
+      return;
+    }
+
+    if (status === 'confirming_price') {
+      setStatus('submitting');
+      setContext(null);
+      pollingAbortRef.current = false;
+
+      // Price confirmed resubmit: reuse same idempotency key (same Quote context)
+      const payload = buildSubmitPayload(sessionId, currencyId, formValues, session, true, idempotencyKeyRef.current);
+      lastPayloadRef.current = payload;
+
+      try {
+        const data = await submitCheckout(sessionId, isDonation, payload);
+        if (!mountedRef.current) return;
+        await routeSubmitResponse(data);
+      } catch (err: unknown) {
+        if (!mountedRef.current) return;
+        await handleSubmitError(err);
+      }
+    }
+  });
+
+  // Cancel
+  const cancel = useMemoizedFn(() => {
+    if (status === 'confirming_price' || status === 'confirming_fast_pay' || status === 'credit_insufficient') {
+      setStatus('idle');
+      setContext(null);
+      unlock();
+    }
+  });
+
+  // Retry
+  const retry = useMemoizedFn(async () => {
+    if (status !== 'failed') return;
+    setStatus('idle');
+    setContext(null);
+    setResult(null);
+    await execute(true);
+  });
+
+  // Reset
+  const reset = useMemoizedFn(() => {
+    pollingAbortRef.current = true;
+    setStatus('idle');
+    setContext(null);
+    setResult(null);
+    unlock();
+  });
+
+  // Stripe confirm
+  const stripeConfirm = useMemoizedFn(async () => {
+    if (status !== 'waiting_stripe') return;
+    setStatus('submitting');
+    setContext(null);
+    await handleCompletion();
+  });
+
+  // Stripe cancel
+  const stripeCancel = useMemoizedFn(async () => {
+    if (status !== 'waiting_stripe') return;
+    await abortStripePayment(sessionId);
+    setStatus('idle');
+    setContext(null);
+  });
+
+  return {
+    status,
+    context,
+    execute,
+    confirm,
+    cancel,
+    result,
+    retry,
+    reset,
+    stripeConfirm,
+    stripeCancel,
+    vendorStatus,
+    locked,
+    lock,
+  };
+}

package/src/checkout/hooks/useSubmitFeature.ts

@@ -0,0 +1,7 @@
+import { useSubmitContext } from '../context/SubmitContext';
+import type { UseSubmitReturn } from './useSubmit';
+
+// Context-aware version: reads shared submit state from CheckoutProvider
+export function useSubmitFeature(): UseSubmitReturn {
+  return useSubmitContext();
+}