@blocklet/payment-react-headless 1.26.0

package/src/checkout/hooks/useUpsell.ts

@@ -0,0 +1,35 @@
+import { useMemoizedFn } from 'ahooks';
+
+import { getErrorMessage } from '../../types/checkout-augmented';
+import { useSessionContext } from '../context/SessionContext';
+import { usePaymentMethodContext } from '../context/PaymentMethodContext';
+import { performUpsell, performDownsell } from '../core/lineItems';
+
+export interface UseUpsellReturn {
+  upsell: (fromId: string, toId: string) => Promise<void>;
+  downsell: (priceId: string) => Promise<void>;
+}
+
+export function useUpsell(): UseUpsellReturn {
+  const { session, effectiveSessionId, refresh } = useSessionContext();
+  const { currency } = usePaymentMethodContext();
+  const currencyId = currency?.id || null;
+
+  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));
+    }
+  });
+
+  return { upsell, downsell };
+}

package/src/checkout/index.ts

@@ -0,0 +1,65 @@
+// Checkout domain exports
+
+// Types
+export type {
+  UseCheckoutReturn,
+  SubmitStatus,
+  SubmitContext,
+  FieldConfig,
+  CheckoutFormData,
+  CheckoutResult,
+} from './types';
+
+// Context & Provider
+export {
+  CheckoutProvider,
+  type CheckoutProviderProps,
+  useSessionContext,
+  usePaymentMethodContext,
+  useExchangeRateContext,
+  useCustomerFormContext,
+  useSubmitContext,
+} from './context';
+
+// Backward-compatible orchestrator
+export { useCheckout } from './hooks/useCheckout';
+
+// Param-based hooks
+export { useCheckoutSession } from './hooks/useCheckoutSession';
+export type { UseCheckoutSessionReturn, SessionData } from './hooks/useCheckoutSession';
+export { usePaymentMethod } from './hooks/usePaymentMethod';
+export type { UsePaymentMethodReturn } from './hooks/usePaymentMethod';
+export { usePricing } from './hooks/usePricing';
+export type { UsePricingReturn } from './hooks/usePricing';
+export { useCustomerForm } from './hooks/useCustomerForm';
+export type { UseCustomerFormReturn } from './hooks/useCustomerForm';
+export { useSubmit } from './hooks/useSubmit';
+export type { UseSubmitReturn } from './hooks/useSubmit';
+
+// NEW: Feature hooks (require <CheckoutProvider>)
+export { useProduct } from './hooks/useProduct';
+export type { UseProductReturn } from './hooks/useProduct';
+export { useLineItems } from './hooks/useLineItems';
+export type { UseLineItemsReturn } from './hooks/useLineItems';
+export { useBillingInterval } from './hooks/useBillingInterval';
+export type { UseBillingIntervalReturn, BillingIntervalData } from './hooks/useBillingInterval';
+export { useUpsell } from './hooks/useUpsell';
+export type { UseUpsellReturn } from './hooks/useUpsell';
+export { useCrossSell } from './hooks/useCrossSell';
+export type { UseCrossSellReturn } from './hooks/useCrossSell';
+export { usePromotion } from './hooks/usePromotion';
+export type { UsePromotionReturn } from './hooks/usePromotion';
+export { useExchangeRate } from './hooks/useExchangeRate';
+export type { UseExchangeRateReturn } from './hooks/useExchangeRate';
+export { useSlippage } from './hooks/useSlippage';
+export type { UseSlippageReturn } from './hooks/useSlippage';
+export { useCheckoutStatus } from './hooks/useCheckoutStatus';
+export type { UseCheckoutStatusReturn } from './hooks/useCheckoutStatus';
+export { usePricingFeature } from './hooks/usePricingFeature';
+export type { UsePricingFeatureReturn } from './hooks/usePricingFeature';
+export { usePaymentMethodFeature } from './hooks/usePaymentMethodFeature';
+export { useCustomerFormFeature } from './hooks/useCustomerFormFeature';
+export { useSubmitFeature } from './hooks/useSubmitFeature';
+
+// Shared utilities
+export { getPriceUnitAmountByCurrency } from '../shared/format';

package/src/checkout/types.ts

@@ -0,0 +1,292 @@
+import type {
+  TLineItemExpanded,
+  TPaymentMethodExpanded,
+  TPaymentCurrency,
+  TPrice,
+  TCheckoutSessionExpanded,
+  TPaymentIntent,
+  TCustomer,
+} from '@blocklet/payment-types';
+
+// ── Submit State Machine ──
+
+export type SubmitStatus =
+  | 'idle'
+  | 'submitting'
+  | 'confirming_price'
+  | 'confirming_fast_pay'
+  | 'credit_insufficient'
+  | 'waiting_did'
+  | 'waiting_stripe'
+  | 'completed'
+  | 'failed';
+
+export type SubmitContext =
+  | { type: 'price_change'; changePercent: number }
+  | { type: 'fast_pay'; payType: 'balance' | 'delegation' | 'credit'; amount: string; payer: string }
+  | { type: 'credit_insufficient'; available: string; required: string }
+  | { type: 'stripe'; clientSecret: string; intentType?: 'payment_intent' | 'setup_intent' }
+  | { type: 'did_connect'; action: string; checkpointId: string; extraParams: Record<string, unknown> }
+  | { type: 'error'; message: string; code?: string }
+  | null;
+
+// ── Form ──
+
+export interface FieldConfig {
+  name: string;
+  type: 'text' | 'email' | 'phone' | 'select' | 'country';
+  required: boolean;
+  options?: Array<{ value: string; label: string }>;
+  group?: string;
+}
+
+export type CheckoutFormData = {
+  customer_name: string;
+  customer_email?: string;
+  customer_phone?: string;
+  payment_method: string;
+  payment_currency: string;
+  billing_address?: {
+    country: string;
+    state?: string;
+    city?: string;
+    line1?: string;
+    line2?: string;
+    postal_code: string;
+  };
+};
+
+// ── Checkout Context (result after completion) ──
+
+export type CheckoutResult = {
+  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;
+};
+
+// ── UseCheckoutReturn ──
+
+export interface UseCheckoutReturn {
+  // Loading state
+  isLoading: boolean;
+  error: string | null;
+  /** Structured error code: 'SESSION_EXPIRED' | 'EMPTY_LINE_ITEMS' | null */
+  errorCode: 'SESSION_EXPIRED' | 'EMPTY_LINE_ITEMS' | null;
+  refresh: () => Promise<void>;
+
+  // Vendor count (for post-payment vendor order polling)
+  vendorCount: number;
+
+  // 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;
+
+  // Line items
+  lineItems: {
+    items: Array<
+      TLineItemExpanded & {
+        adjustable_quantity?: {
+          enabled: boolean;
+          minimum?: number;
+          maximum?: number;
+        };
+      }
+    >;
+    updateQuantity: (itemId: string, qty: number) => Promise<void>;
+    upsell: (fromId: string, toId: string) => Promise<void>;
+    downsell: (priceId: string) => Promise<void>;
+    billingInterval: {
+      current: 'month' | 'year' | 'week' | 'day' | null;
+      available: Array<{
+        interval: 'month' | 'year' | 'week' | 'day';
+        priceId: string;
+        amount: string;
+        savings: string | null;
+      }>;
+      switch: (interval: 'month' | 'year' | 'week' | 'day') => Promise<void>;
+    } | null;
+    crossSellItem: TPrice | null;
+    crossSellRequired: boolean;
+    addCrossSell: () => Promise<void>;
+    removeCrossSell: () => Promise<void>;
+  };
+
+  // Payment method
+  paymentMethod: {
+    current: TPaymentMethodExpanded;
+    currency: TPaymentCurrency;
+    available: TPaymentMethodExpanded[];
+    currencies: TPaymentCurrency[];
+    isStripe: boolean;
+    isCrypto: boolean;
+    isCredit: boolean;
+    setType: (type: 'stripe' | 'crypto') => Promise<void>;
+    types: Array<{
+      type: 'stripe' | 'crypto';
+      label: string;
+      currencies: TPaymentCurrency[];
+      active: boolean;
+    }>;
+    setCurrency: (currencyId: string) => Promise<void>;
+  };
+
+  // Stripe config
+  stripe: {
+    publishableKey: string | null;
+    clientSecret: string | null;
+    status: 'idle' | 'ready' | 'processing' | 'succeeded' | 'failed';
+  } | null;
+
+  // Pricing
+  pricing: {
+    subtotal: 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;
+    };
+  };
+
+  // Form
+  form: {
+    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>;
+  };
+
+  // Submit
+  submit: {
+    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: {
+      payment_status: string;
+      session_status: string;
+      vendors: Array<{
+        success: boolean;
+        status: 'delivered' | 'pending' | 'failed';
+        progress: number;
+        message: string;
+        appUrl?: string;
+        title?: string;
+        name?: string;
+        vendorType: string;
+      }>;
+      error: string | null;
+      isAllCompleted: boolean;
+      hasFailed: boolean;
+    } | null;
+  };
+
+  // Subscription config
+  subscription: {
+    mode: 'payment' | 'subscription' | 'setup';
+    showStake: boolean;
+    confirmMessage: string;
+  } | null;
+
+  // Page config
+  pageInfo: {
+    formPurposeDescription?: { en: string; zh: string };
+    showProductFeatures: boolean;
+  } | null;
+
+  // Convenience
+  canSubmit: boolean;
+  isCompleted: boolean;
+  isDonation: boolean;
+  setDonationAmount: (priceId: string, amount: string) => Promise<void>;
+
+  // Customer info (from API, available when logged in)
+  customer: {
+    name: string;
+    email: string;
+    phone: string;
+    address: {
+      country: string;
+      state: string;
+      city: string;
+      line1: string;
+      line2: string;
+      postal_code: string;
+    };
+  } | null;
+
+  // Raw session (for advanced UI access)
+  livemode: boolean;
+  session: TCheckoutSessionExpanded | null;
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+// Root re-export: checkout domain
+export {
+  // Types
+  type UseCheckoutReturn,
+  type SubmitStatus,
+  type SubmitContext,
+  type FieldConfig,
+  type CheckoutFormData,
+  type CheckoutResult,
+  type UseCheckoutSessionReturn,
+  type SessionData,
+  type UsePaymentMethodReturn,
+  type UsePricingReturn,
+  type UseCustomerFormReturn,
+  type UseSubmitReturn,
+  type UseProductReturn,
+  type UseLineItemsReturn,
+  type UseBillingIntervalReturn,
+  type BillingIntervalData,
+  type UseUpsellReturn,
+  type UseCrossSellReturn,
+  type UsePromotionReturn,
+  type UseExchangeRateReturn,
+  type UseSlippageReturn,
+  type UseCheckoutStatusReturn,
+  type UsePricingFeatureReturn,
+  type CheckoutProviderProps,
+
+  // Context & Provider
+  CheckoutProvider,
+  useSessionContext,
+  usePaymentMethodContext,
+  useExchangeRateContext,
+  useCustomerFormContext,
+  useSubmitContext,
+
+  // Backward-compatible orchestrator
+  useCheckout,
+
+  // Param-based hooks
+  useCheckoutSession,
+  usePaymentMethod,
+  usePricing,
+  useCustomerForm,
+  useSubmit,
+
+  // Feature hooks (require <CheckoutProvider>)
+  useProduct,
+  useLineItems,
+  useBillingInterval,
+  useUpsell,
+  useCrossSell,
+  usePromotion,
+  useExchangeRate,
+  useSlippage,
+  useCheckoutStatus,
+  usePricingFeature,
+  usePaymentMethodFeature,
+  useCustomerFormFeature,
+  useSubmitFeature,
+
+  // Shared utilities
+  getPriceUnitAmountByCurrency,
+} from './checkout';

package/src/shared/api.ts

@@ -0,0 +1,118 @@
+import { createAxios } from '@blocklet/js-sdk';
+import type { InternalAxiosRequestConfig } from 'axios';
+import isNull from 'lodash/isNull';
+
+declare global {
+  interface Window {
+    blocklet?: {
+      prefix?: string;
+      componentId?: string;
+      componentMountPoints?: Array<{ did: string; mountPoint: string }>;
+      appName?: string;
+      languages?: string[];
+    };
+    __PAYMENT_KIT_AUTH_TOKEN?: string;
+    __PAYMENT_KIT_BASE_URL?: string;
+  }
+}
+
+const PAYMENT_KIT_DID = 'z2qaCNvKMv5GjouKdcDWexv6WqtHbpNPQDnAk';
+
+export function getPrefix(): string {
+  const prefix = window.blocklet?.prefix || '/';
+  const baseUrl = window.location?.origin;
+
+  if (window.__PAYMENT_KIT_BASE_URL) {
+    try {
+      const tmp = new URL(window.__PAYMENT_KIT_BASE_URL);
+      if (tmp.origin !== window.location.origin) {
+        return window.__PAYMENT_KIT_BASE_URL;
+      }
+    } catch {
+      // Invalid baseUrl, fallback
+    }
+  }
+
+  const componentId = (window.blocklet?.componentId || '').split('/').pop();
+  if (componentId === PAYMENT_KIT_DID) {
+    return `${baseUrl}${prefix}`;
+  }
+
+  const component = (window.blocklet?.componentMountPoints || []).find((x) => x?.did === PAYMENT_KIT_DID);
+  if (component) {
+    return `${baseUrl}${component.mountPoint}`;
+  }
+
+  return `${baseUrl}${prefix}`;
+}
+
+export function getLocale(languages?: string[]): string {
+  if (typeof window === 'undefined') return 'en';
+  try {
+    // Try to get locale from localStorage (common pattern in ArcBlock apps)
+    const stored = localStorage.getItem('locale');
+    if (stored) return stored;
+  } catch {
+    // localStorage not available
+  }
+  if (languages && languages.length > 0) return languages[0];
+  return navigator.language?.split('-')[0] || 'en';
+}
+
+function createApi() {
+  const api = createAxios();
+
+  api.interceptors.request.use(
+    (config: InternalAxiosRequestConfig) => {
+      const prefix = getPrefix();
+      config.baseURL = prefix || '';
+
+      const locale = getLocale(window.blocklet?.languages);
+      const query = new URLSearchParams(config.url?.split('?').pop());
+
+      config.params = { ...(config.params || {}), locale };
+
+      const authToken = window.__PAYMENT_KIT_AUTH_TOKEN;
+      if (authToken && typeof config.params.authToken === 'undefined' && !query.has('authToken')) {
+        config.params.authToken = authToken;
+      }
+
+      if (typeof config.params.livemode === 'undefined' && query.has('livemode') === false) {
+        const livemode = localStorage.getItem('livemode');
+        config.params.livemode = isNull(livemode) ? true : JSON.parse(livemode);
+      }
+
+      return config;
+    },
+    (err: unknown) => Promise.reject(err)
+  );
+
+  return api;
+}
+
+const api = createApi();
+
+export default api;
+
+// API endpoint constants
+export const API = {
+  START_PAYMENT_LINK: (id: string) => `/api/checkout-sessions/start/${id}`,
+  RETRIEVE_SESSION: (id: string) => `/api/checkout-sessions/retrieve/${id}`,
+  SWITCH_CURRENCY: (id: string) => `/api/checkout-sessions/${id}/switch-currency`,
+  SUBMIT: (id: string) => `/api/checkout-sessions/${id}/submit`,
+  DONATE_SUBMIT: (id: string) => `/api/checkout-sessions/${id}/donate-submit`,
+  FAST_CHECKOUT_CONFIRM: (id: string) => `/api/checkout-sessions/${id}/fast-checkout-confirm`,
+  EXCHANGE_RATE: (id: string) => `/api/checkout-sessions/${id}/exchange-rate`,
+  ADJUST_QUANTITY: (id: string) => `/api/checkout-sessions/${id}/adjust-quantity`,
+  UPSELL: (id: string) => `/api/checkout-sessions/${id}/upsell`,
+  DOWNSELL: (id: string) => `/api/checkout-sessions/${id}/downsell`,
+  CROSS_SELL: (id: string) => `/api/checkout-sessions/${id}/cross-sell`,
+  CHANGE_AMOUNT: (id: string) => `/api/checkout-sessions/${id}/amount`,
+  SLIPPAGE: (id: string) => `/api/checkout-sessions/${id}/slippage`,
+  ABORT_STRIPE: (id: string) => `/api/checkout-sessions/${id}/abort-stripe`,
+  RECALCULATE_PROMOTION_SESSION: (id: string) => `/api/checkout-sessions/${id}/recalculate-promotion`,
+  APPLY_PROMOTION: (id: string) => `/api/checkout-sessions/${id}/apply-promotion`,
+  REMOVE_PROMOTION: (id: string) => `/api/checkout-sessions/${id}/remove-promotion`,
+  CUSTOMER_ME: '/api/customers/me',
+  VENDOR_ORDER_STATUS: (id: string) => `/api/vendors/order/${id}/status`,
+} as const;