@blocklet/payment-react-headless 1.26.0

package/src/checkout/context/PaymentMethodContext.ts

@@ -0,0 +1,36 @@
+import { createContext, useContext } from 'react';
+import type { TPaymentMethodExpanded, TPaymentCurrency } from '@blocklet/payment-types';
+
+export interface PaymentMethodContextValue {
+  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 const PaymentMethodContext = createContext<PaymentMethodContextValue | null>(null);
+
+export function usePaymentMethodContext(): PaymentMethodContextValue {
+  const ctx = useContext(PaymentMethodContext);
+  if (!ctx) {
+    throw new Error('usePaymentMethodContext must be used within <CheckoutProvider>');
+  }
+  return ctx;
+}

package/src/checkout/context/SessionContext.ts

@@ -0,0 +1,49 @@
+import { createContext, useContext } from 'react';
+import type { TLineItemExpanded, TCheckoutSessionExpanded } from '@blocklet/payment-types';
+import type { SessionData } from '../hooks/useCheckoutSession';
+
+export interface SessionContextValue {
+  sessionData: SessionData | null;
+  sessionId: string;
+  effectiveSessionId: string;
+  isLoading: boolean;
+  error: string | null;
+  errorCode: 'SESSION_EXPIRED' | 'EMPTY_LINE_ITEMS' | null;
+  refresh: (forceRefresh?: boolean) => Promise<void>;
+  items: TLineItemExpanded[];
+  session: TCheckoutSessionExpanded | null | undefined;
+  isDonation: boolean;
+  vendorCount: number;
+  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;
+  subscription: {
+    mode: 'payment' | 'subscription' | 'setup';
+    showStake: boolean;
+    confirmMessage: string;
+  } | null;
+  pageInfo: {
+    formPurposeDescription?: { en: string; zh: string };
+    showProductFeatures: boolean;
+  } | null;
+}
+
+export const SessionContext = createContext<SessionContextValue | null>(null);
+
+export function useSessionContext(): SessionContextValue {
+  const ctx = useContext(SessionContext);
+  if (!ctx) {
+    throw new Error('useSessionContext must be used within <CheckoutProvider>');
+  }
+  return ctx;
+}

package/src/checkout/context/SubmitContext.ts

@@ -0,0 +1,14 @@
+import { createContext, useContext } from 'react';
+import type { UseSubmitReturn } from '../hooks/useSubmit';
+
+export type SubmitContextValue = UseSubmitReturn;
+
+export const SubmitReactContext = createContext<SubmitContextValue | null>(null);
+
+export function useSubmitContext(): SubmitContextValue {
+  const ctx = useContext(SubmitReactContext);
+  if (!ctx) {
+    throw new Error('useSubmitContext must be used within <CheckoutProvider>');
+  }
+  return ctx;
+}

package/src/checkout/context/index.ts

@@ -0,0 +1,6 @@
+export { CheckoutProvider, type CheckoutProviderProps } from './CheckoutProvider';
+export { SessionContext, useSessionContext, type SessionContextValue } from './SessionContext';
+export { PaymentMethodContext, usePaymentMethodContext, type PaymentMethodContextValue } from './PaymentMethodContext';
+export { ExchangeRateContext, useExchangeRateContext, type ExchangeRateContextValue } from './ExchangeRateContext';
+export { CustomerFormContext, useCustomerFormContext, type CustomerFormContextValue } from './CustomerFormContext';
+export { SubmitReactContext, useSubmitContext, type SubmitContextValue } from './SubmitContext';

package/src/checkout/core/billingInterval.ts

@@ -0,0 +1,62 @@
+import type { TLineItemExpanded } from '@blocklet/payment-types';
+import type { UpsellExpanded } from '../../types/checkout-augmented';
+
+export type BillingIntervalType = 'month' | 'year' | 'week' | 'day';
+
+export interface BillingIntervalOption {
+  interval: BillingIntervalType;
+  priceId: string;
+  amount: string;
+  savings: string | null;
+}
+
+export interface BillingIntervalInfo {
+  current: BillingIntervalType | null;
+  available: BillingIntervalOption[];
+  /** The first item used to derive billing info */
+  firstItem: TLineItemExpanded;
+}
+
+export function parseBillingInterval(items: TLineItemExpanded[]): BillingIntervalInfo | null {
+  if (!items.length) return null;
+
+  const firstItem = items[0];
+  const price = firstItem.upsell_price || firstItem.price;
+  const recurring = price?.recurring;
+  if (!recurring) return null;
+
+  const currentInterval = recurring.interval as BillingIntervalType | null;
+
+  const upsell = price?.upsell as UpsellExpanded | undefined;
+  const upsellTo = upsell?.upsells_to;
+  const available: BillingIntervalOption[] = [];
+
+  if (upsellTo?.recurring?.interval && upsellTo.recurring.interval !== currentInterval) {
+    available.push({
+      interval: upsellTo.recurring.interval as BillingIntervalType,
+      priceId: upsell?.upsells_to_id || '',
+      amount: upsellTo.unit_amount || '0',
+      savings: null,
+    });
+  }
+
+  if (firstItem.upsell_price_id && firstItem.price?.recurring) {
+    const origInterval = firstItem.price.recurring.interval;
+    if (origInterval && origInterval !== currentInterval) {
+      available.push({
+        interval: origInterval as BillingIntervalType,
+        priceId: firstItem.price_id,
+        amount: firstItem.price.unit_amount || '0',
+        savings: null,
+      });
+    }
+  }
+
+  if (available.length === 0) return null;
+
+  return {
+    current: currentInterval,
+    available,
+    firstItem,
+  };
+}

package/src/checkout/core/crossSell.ts

@@ -0,0 +1,52 @@
+import type { TCheckoutSessionExpanded, TPrice } from '@blocklet/payment-types';
+
+import api, { API } from '../../shared/api';
+import { recalculatePromotionIfNeeded } from './lineItems';
+
+export async function addCrossSellItem(
+  sessionId: string,
+  crossSellItemId: string,
+  session: TCheckoutSessionExpanded | undefined | null,
+  currencyId: string | null | undefined,
+  refresh: (force?: boolean) => Promise<void>
+): Promise<void> {
+  await api.put(API.CROSS_SELL(sessionId), { to: crossSellItemId });
+  await recalculatePromotionIfNeeded(session, sessionId, currencyId);
+  await refresh(true);
+}
+
+export async function removeCrossSellItem(
+  sessionId: string,
+  session: TCheckoutSessionExpanded | undefined | null,
+  currencyId: string | null | undefined,
+  refresh: (force?: boolean) => Promise<void>
+): Promise<void> {
+  await api.delete(API.CROSS_SELL(sessionId));
+  await recalculatePromotionIfNeeded(session, sessionId, currencyId);
+  await refresh(true);
+}
+
+// Dedup concurrent fetchCrossSellItem calls (multiple useLineItems instances share one in-flight request)
+const pendingFetches = new Map<string, Promise<TPrice | null>>();
+
+export function fetchCrossSellItem(sessionId: string): Promise<TPrice | null> {
+  const existing = pendingFetches.get(sessionId);
+  if (existing) return existing;
+
+  const promise = (async (): Promise<TPrice | null> => {
+    try {
+      const { data } = await api.get(`${API.CROSS_SELL(sessionId)}?skipError=true`);
+      if (data && !data.error) {
+        return data as TPrice;
+      }
+    } catch {
+      // Ignore cross-sell fetch errors
+    }
+    return null;
+  })();
+
+  pendingFetches.set(sessionId, promise);
+  promise.finally(() => pendingFetches.delete(sessionId));
+
+  return promise;
+}

package/src/checkout/core/customerForm.ts

@@ -0,0 +1,122 @@
+import type { TCheckoutSessionExpanded, TCustomer } from '@blocklet/payment-types';
+
+import type { FieldConfig, CheckoutFormData } from '../types';
+
+export function buildFields(session: TCheckoutSessionExpanded | undefined | null): FieldConfig[] {
+  const fields: FieldConfig[] = [];
+
+  fields.push({
+    name: 'customer_name',
+    type: 'text',
+    required: true,
+  });
+
+  fields.push({
+    name: 'customer_email',
+    type: 'email',
+    required: true,
+  });
+
+  if (session?.phone_number_collection?.enabled) {
+    fields.push({
+      name: 'customer_phone',
+      type: 'phone',
+      required: true,
+    });
+  }
+
+  const addressMode = session?.billing_address_collection;
+  if (addressMode === 'required') {
+    // Full address form — all fields required
+    fields.push(
+      {
+        name: 'billing_address.country',
+        type: 'country',
+        required: true,
+        group: 'address',
+      },
+      {
+        name: 'billing_address.line1',
+        type: 'text',
+        required: true,
+        group: 'address',
+      },
+      {
+        name: 'billing_address.line2',
+        type: 'text',
+        required: false,
+        group: 'address',
+      },
+      {
+        name: 'billing_address.city',
+        type: 'text',
+        required: true,
+        group: 'address',
+      },
+      {
+        name: 'billing_address.state',
+        type: 'text',
+        required: true,
+        group: 'address',
+      },
+      {
+        name: 'billing_address.postal_code',
+        type: 'text',
+        required: true,
+        group: 'address',
+      }
+    );
+  } else if (addressMode === 'auto') {
+    // Auto mode — only state and postal_code (country shown as prefix in postal code field)
+    fields.push(
+      {
+        name: 'billing_address.state',
+        type: 'text',
+        required: false,
+        group: 'address',
+      },
+      {
+        name: 'billing_address.postal_code',
+        type: 'text',
+        required: false,
+        group: 'address',
+      }
+    );
+  }
+
+  return fields;
+}
+
+export function createInitialValues(
+  session: TCheckoutSessionExpanded | undefined | null,
+  customer: TCustomer | undefined | null
+): CheckoutFormData {
+  return {
+    customer_name: customer?.name || '',
+    customer_email: (session?.customer_details as { email?: string } | undefined)?.email || customer?.email || '',
+    customer_phone: customer?.phone || '',
+    payment_method: '',
+    payment_currency: session?.currency_id || '',
+    billing_address: {
+      country: customer?.address?.country || '',
+      state: customer?.address?.state || '',
+      city: customer?.address?.city || '',
+      line1: customer?.address?.line1 || '',
+      line2: customer?.address?.line2 || '',
+      postal_code: customer?.address?.postal_code || '',
+    },
+  };
+}
+
+export function setNestedValue<T extends Record<string, unknown>>(obj: T, path: string, value: unknown): T {
+  const parts = path.split('.');
+  if (parts.length === 1) {
+    return { ...obj, [path]: value };
+  }
+
+  const [head, ...rest] = parts;
+  return {
+    ...obj,
+    [head]: setNestedValue((obj[head] || {}) as Record<string, unknown>, rest.join('.'), value),
+  } as T;
+}

package/src/checkout/core/exchangeRate.ts

@@ -0,0 +1,38 @@
+import type { TLineItemExpanded } from '@blocklet/payment-types';
+
+import api, { API } from '../../shared/api';
+
+// Rate polling intervals
+export const BASE_INTERVAL = 30_000;
+export const MAX_INTERVAL = 120_000;
+
+export function checkHasDynamicPricing(items: TLineItemExpanded[]): boolean {
+  return items.some((item) => (item.upsell_price || item.price)?.pricing_type === 'dynamic');
+}
+
+export async function fetchExchangeRate(
+  sessionId: string,
+  currencyId: string | null | undefined
+): Promise<{ rate: string | null; provider: string | null; providerDisplay: string | null; fetchedAt: number | null }> {
+  const { data } = await api.get(API.EXCHANGE_RATE(sessionId), {
+    params: currencyId ? { currency_id: currencyId } : undefined,
+  });
+
+  const rateValue = data.rate || data.exchange_rate;
+  if (rateValue) {
+    // provider_display is preferred (e.g., "token-data (2 sources)")
+    // fallback: provider_name → provider_id → null
+    const providerDisplay = data.provider_display || data.provider_name || data.provider_id || null;
+    return {
+      rate: rateValue,
+      provider: data.provider_name || data.rate_provider_name || null,
+      providerDisplay,
+      fetchedAt: data.fetched_at || data.timestamp_ms || null,
+    };
+  }
+  return { rate: null, provider: null, providerDisplay: null, fetchedAt: null };
+}
+
+export function getBackoffInterval(failCount: number): number {
+  return Math.min(BASE_INTERVAL * 2 ** failCount, MAX_INTERVAL);
+}

package/src/checkout/core/index.ts

@@ -0,0 +1,60 @@
+export { parseProduct, parseSubscription, parsePageInfo } from './session';
+export {
+  flattenCurrencies,
+  hasDidWallet,
+  getInitialCurrencyId,
+  findMethodAndCurrency,
+  buildPaymentTypes,
+} from './paymentMethod';
+export {
+  BASE_INTERVAL,
+  MAX_INTERVAL,
+  checkHasDynamicPricing,
+  fetchExchangeRate,
+  getBackoffInterval,
+} from './exchangeRate';
+export {
+  calculateAmounts,
+  calculateQuoteMeta,
+  calculateTrial,
+  type CalculatedAmounts,
+  type QuoteMeta,
+} from './pricing';
+export {
+  extractPromotionCodeFromSession,
+  applyPromotionCode,
+  removePromotionCode,
+  recalculatePromotion,
+  isPromotionActive,
+  hasAppliedDiscounts,
+} from './promotion';
+export {
+  recalculatePromotionIfNeeded,
+  adjustQuantity,
+  performUpsell,
+  performDownsell,
+  changeDonationAmount,
+  getCrossSellItem,
+} from './lineItems';
+export { addCrossSellItem, removeCrossSellItem, fetchCrossSellItem } from './crossSell';
+export {
+  parseBillingInterval,
+  type BillingIntervalType,
+  type BillingIntervalOption,
+  type BillingIntervalInfo,
+} from './billingInterval';
+export { buildFields, createInitialValues, setNestedValue } from './customerForm';
+export {
+  QUOTE_ERROR_CODES,
+  RELAY_SOCKET_PREFIX,
+  getAppId,
+  getRelayChannel,
+  getRelayProtocol,
+  getSocketHost,
+  buildSubmitPayload,
+  isQuoteError,
+  abortStripePayment,
+  submitCheckout,
+  confirmFastCheckout,
+  updateSlippage,
+} from './submit';

package/src/checkout/core/lineItems.ts

@@ -0,0 +1,106 @@
+import type { TCheckoutSessionExpanded, TLineItemExpanded, TPrice } from '@blocklet/payment-types';
+
+import api, { API } from '../../shared/api';
+import { recalculatePromotion, hasAppliedDiscounts } from './promotion';
+import type { PriceWithCrossSell } from '../../types/checkout-augmented';
+
+export async function recalculatePromotionIfNeeded(
+  session: TCheckoutSessionExpanded | undefined | null,
+  sessionId: string,
+  currencyId: string | null | undefined
+): Promise<void> {
+  if (!hasAppliedDiscounts(session)) return;
+  try {
+    await recalculatePromotion(sessionId, currencyId);
+  } catch {
+    // Ignore recalculation error
+  }
+}
+
+export async function adjustQuantity(
+  sessionId: string,
+  itemId: string,
+  qty: number,
+  currencyId: string | null | undefined,
+  session: TCheckoutSessionExpanded | undefined | null,
+  refresh: (force?: boolean) => Promise<void>
+): Promise<void> {
+  await api.put(API.ADJUST_QUANTITY(sessionId), {
+    itemId,
+    quantity: qty,
+    currency_id: currencyId,
+  });
+  await recalculatePromotionIfNeeded(session, sessionId, currencyId);
+  await refresh(true);
+}
+
+export async function performUpsell(
+  sessionId: string,
+  fromId: string,
+  toId: string,
+  session: TCheckoutSessionExpanded | undefined | null,
+  currencyId: string | null | undefined,
+  refresh: (force?: boolean) => Promise<void>
+): Promise<void> {
+  // Backend rejects upsell with multiple line items — auto-remove cross-sell first
+  // Always try DELETE when multiple items exist (cross_sell flag may not be set)
+  if ((session?.line_items?.length || 0) > 1) {
+    try {
+      await api.delete(API.CROSS_SELL(sessionId));
+    } catch {
+      // No cross-sell to remove — will proceed and let upsell API decide
+    }
+  }
+  await api.put(API.UPSELL(sessionId), { from: fromId, to: toId });
+  await recalculatePromotionIfNeeded(session, sessionId, currencyId);
+  await refresh(true);
+}
+
+export async function performDownsell(
+  sessionId: string,
+  priceId: string,
+  session: TCheckoutSessionExpanded | undefined | null,
+  currencyId: string | null | undefined,
+  refresh: (force?: boolean) => Promise<void>
+): Promise<void> {
+  // Auto-remove cross-sell to keep interval consistency (cross-sell is interval-aware)
+  if ((session?.line_items?.length || 0) > 1) {
+    try {
+      await api.delete(API.CROSS_SELL(sessionId));
+    } catch {
+      // No cross-sell to remove — will proceed and let downsell API decide
+    }
+  }
+  await api.put(API.DOWNSELL(sessionId), { from: priceId });
+  await recalculatePromotionIfNeeded(session, sessionId, currencyId);
+  await refresh(true);
+}
+
+export async function changeDonationAmount(
+  sessionId: string,
+  priceId: string,
+  amount: string,
+  session: TCheckoutSessionExpanded | undefined | null,
+  currencyId: string | null | undefined,
+  refresh: (force?: boolean) => Promise<void>
+): Promise<void> {
+  const { data } = await api.put(API.CHANGE_AMOUNT(sessionId), {
+    priceId,
+    amount,
+  });
+  if (data?.discounts?.length) {
+    await recalculatePromotionIfNeeded(session, sessionId, currencyId);
+  }
+  await refresh(true);
+}
+
+// Extract cross-sell price from items
+export function getCrossSellItem(items: TLineItemExpanded[]): TPrice | null {
+  for (const item of items) {
+    const crossSell = (item.price as PriceWithCrossSell)?.cross_sell;
+    if (crossSell?.cross_sells_to) {
+      return crossSell.cross_sells_to as TPrice;
+    }
+  }
+  return null;
+}

package/src/checkout/core/paymentMethod.ts

@@ -0,0 +1,113 @@
+import type { TPaymentMethodExpanded, TPaymentCurrency, TCheckoutSessionExpanded } from '@blocklet/payment-types';
+
+import type { CheckoutSessionRuntime, CheckoutSessionUser } from '../../types/checkout-augmented';
+
+export type CurrencyWithMethod = TPaymentCurrency & {
+  method?: { id: string; name: string; type: string };
+};
+
+export function flattenCurrencies(methods: TPaymentMethodExpanded[]): CurrencyWithMethod[] {
+  const out: CurrencyWithMethod[] = [];
+  methods.forEach((method) => {
+    const currencies = method.payment_currencies || [];
+    currencies.forEach((currency) => {
+      const enriched: CurrencyWithMethod = {
+        ...currency,
+        method: { id: method.id, name: method.name, type: method.type },
+      };
+      out.push(enriched);
+    });
+  });
+  return out;
+}
+
+export function hasDidWallet(user: CheckoutSessionUser | undefined): boolean {
+  const connected = user?.connectedAccounts || user?.extraConfigs?.connectedAccounts || [];
+  return connected.some((x) => x.provider === 'wallet');
+}
+
+const CURRENCY_PREFERENCE_KEY = 'payment-currency-preference';
+
+export function getCurrencyStorageKey(did?: string): string {
+  return did ? `${CURRENCY_PREFERENCE_KEY}:${did}` : CURRENCY_PREFERENCE_KEY;
+}
+
+export function getInitialCurrencyId(
+  session: TCheckoutSessionExpanded | undefined | null,
+  methods: TPaymentMethodExpanded[]
+): string | null {
+  if (typeof window !== 'undefined') {
+    try {
+      const params = new URLSearchParams(window.location.search);
+      const urlCurrency = params.get('currencyId') || params.get('currency_id');
+      if (urlCurrency) return urlCurrency;
+    } catch {
+      // Ignore
+    }
+
+    const user = (session as CheckoutSessionRuntime | undefined)?.user;
+    if (user && !hasDidWallet(user)) {
+      const stripeMethod = methods.find((m) => m.type === 'stripe');
+      const stripeCurrency = stripeMethod?.payment_currencies?.[0];
+      if (stripeCurrency) return stripeCurrency.id;
+    }
+
+    try {
+      const did = (session as CheckoutSessionRuntime | undefined)?.user?.did;
+      const stored = localStorage.getItem(getCurrencyStorageKey(did));
+      if (stored) return stored;
+    } catch {
+      // Ignore
+    }
+  }
+  return session?.currency_id || null;
+}
+
+export function findMethodAndCurrency(
+  methods: TPaymentMethodExpanded[],
+  currencyId: string | null
+): { method: TPaymentMethodExpanded | null; currency: TPaymentCurrency | null } {
+  if (!currencyId) {
+    const first = methods[0];
+    const firstCurrency = first?.payment_currencies?.[0] || null;
+    return { method: first || null, currency: firstCurrency };
+  }
+
+  for (const method of methods) {
+    for (const currency of method.payment_currencies || []) {
+      if (currency.id === currencyId) {
+        return { method, currency };
+      }
+    }
+  }
+
+  const first = methods[0];
+  return { method: first || null, currency: first?.payment_currencies?.[0] || null };
+}
+
+export function buildPaymentTypes(methods: TPaymentMethodExpanded[], currentMethod: TPaymentMethodExpanded | null) {
+  const typeMap = new Map<string, { currencies: CurrencyWithMethod[]; active: boolean }>();
+
+  methods.forEach((method) => {
+    const type = method.type === 'stripe' ? 'stripe' : 'crypto';
+    if (!typeMap.has(type)) {
+      typeMap.set(type, { currencies: [], active: false });
+    }
+    const entry = typeMap.get(type)!;
+    const enriched: CurrencyWithMethod[] = (method.payment_currencies || []).map((cur) => ({
+      ...cur,
+      method: { id: method.id, name: method.name, type: method.type },
+    }));
+    entry.currencies.push(...enriched);
+    if (method === currentMethod) {
+      entry.active = true;
+    }
+  });
+
+  return Array.from(typeMap.entries()).map(([type, data]) => ({
+    type: type as 'stripe' | 'crypto',
+    label: type === 'stripe' ? 'Card' : 'Crypto',
+    currencies: data.currencies,
+    active: data.active,
+  }));
+}