@blocklet/payment-react 1.24.3 → 1.25.0

package/src/hooks/dynamic-pricing.ts

@@ -0,0 +1,617 @@
+/**
+ * useDynamicPricing Hook
+ *
+ * Extracts and centralizes all dynamic pricing related calculations
+ * for the checkout summary component.
+ *
+ * Final Freeze Architecture: Quotes are created at Submit time only.
+ * This hook handles preview-time display calculations.
+ */
+
+import { useMemo } from 'react';
+import type { TCheckoutSession, TLineItemExpanded, TPaymentCurrency, TPaymentIntent } from '@blocklet/payment-types';
+import { BN, fromTokenToUnit, fromUnitToToken } from '@ocap/util';
+import {
+  formatDateTime,
+  formatDynamicPrice,
+  formatExchangeRate,
+  formatUsdAmount,
+  getUsdAmountFromTokenUnits,
+} from '../libs/util';
+
+export interface LiveRateInfo {
+  rate?: string;
+  provider_id?: string;
+  provider_name?: string;
+  provider_display?: string; // Human-readable: "CoinGecko" or "CoinGecko (2 sources)"
+  base_currency?: string;
+  timestamp_ms?: number;
+  fetched_at?: number; // When we fetched the data (updates every 30s)
+}
+
+export interface LiveQuoteSnapshot {
+  id: string;
+  quoted_amount: string;
+  exchange_rate: string;
+  expires_at: number;
+  rate_timestamp_ms?: number | null;
+  renewed?: boolean;
+}
+
+export interface DiscountInfo {
+  promotion_code?: string;
+  coupon?: string;
+  discount_amount?: string;
+  coupon_details?: {
+    percent_off?: number;
+    amount_off?: string;
+    currency_id?: string;
+    currency_options?: Record<string, { amount_off?: string }>;
+  };
+}
+
+export interface DynamicPricingOptions {
+  items: TLineItemExpanded[];
+  currency: TPaymentCurrency;
+  liveRate?: LiveRateInfo;
+  liveQuoteSnapshot?: LiveQuoteSnapshot;
+  checkoutSession?: TCheckoutSession;
+  paymentIntent?: TPaymentIntent | null;
+  locale?: string;
+  isStripePayment?: boolean;
+  isSubscription?: boolean;
+  slippageConfig?: {
+    mode?: 'percent' | 'rate';
+    percent?: number | null;
+    min_acceptable_rate?: string;
+    base_currency?: string;
+  };
+  trialInDays?: number;
+  trialEnd?: number;
+  discounts?: DiscountInfo[];
+}
+
+export interface RateInfo {
+  exchangeRate: string | null;
+  baseCurrency: string;
+  providerName: string | null;
+  providerId: string | null;
+  timestampMs: number | null;
+  fetchedAt: number | null; // When we fetched (for display)
+}
+
+export interface QuoteMeta {
+  exchangeRate: string | null;
+  baseCurrency: string;
+  expiresAt: number | null;
+  providerName: string | null;
+  providerId: string | null;
+  rateTimestampMs: number | null;
+  slippagePercent: number | null;
+}
+
+/**
+ * Extract quote metadata from line items
+ */
+function extractQuoteMeta(items: TLineItemExpanded[]): QuoteMeta | null {
+  if (!items?.length) {
+    return null;
+  }
+
+  let exchangeRate: string | null = null;
+  let baseCurrency: string | null = null;
+  let expiresAt: number | null = null;
+  let providerName: string | null = null;
+  let providerId: string | null = null;
+  let rateTimestampMs: number | null = null;
+  let slippagePercent: number | null = null;
+
+  items.forEach((item) => {
+    const price = item.upsell_price || item.price;
+    const rate = (item as any)?.exchange_rate;
+    if (!exchangeRate && rate) {
+      exchangeRate = rate;
+    }
+    const base = (price as any)?.base_currency;
+    if (!baseCurrency && base) {
+      baseCurrency = base;
+    }
+    const expires = (item as any)?.expires_at;
+    if (expires) {
+      expiresAt = expiresAt === null ? expires : Math.min(expiresAt, expires);
+    }
+    const itemProviderName = (item as any)?.rate_provider_name;
+    if (!providerName && itemProviderName) {
+      providerName = itemProviderName;
+    }
+    const itemProviderId = (item as any)?.rate_provider_id;
+    if (!providerId && itemProviderId) {
+      providerId = itemProviderId;
+    }
+    const itemRateTimestamp = (item as any)?.rate_timestamp_ms;
+    if (!rateTimestampMs && Number.isFinite(Number(itemRateTimestamp))) {
+      rateTimestampMs = Number(itemRateTimestamp);
+    }
+    const itemSlippage = (item as any)?.slippage_percent;
+    if (slippagePercent === null && Number.isFinite(Number(itemSlippage))) {
+      slippagePercent = Number(itemSlippage);
+    }
+  });
+
+  return {
+    exchangeRate,
+    baseCurrency: baseCurrency || 'USD',
+    expiresAt,
+    providerName,
+    providerId,
+    rateTimestampMs,
+    slippagePercent,
+  };
+}
+
+/**
+ * Calculate token amount from USD base amount and exchange rate
+ * @param items - Line items to calculate
+ * @param rate - Exchange rate
+ * @param currencyDecimal - Currency decimal places
+ * @param trialing - Whether currently in trial period (skips recurring items if true)
+ */
+function calculateTokenAmount(
+  items: TLineItemExpanded[],
+  rate: string,
+  currencyDecimal: number,
+  trialing: boolean = false
+): string | null {
+  // Get USD base amount from items
+  const usdTotal = items.reduce((acc, item) => {
+    const price = item.upsell_price || item.price;
+    // Skip recurring items when in trial period (they don't need payment during trial)
+    if (trialing && price?.type === 'recurring') {
+      return acc;
+    }
+    // Skip metered items (pay-as-you-go, no upfront payment)
+    if (price?.type === 'recurring' && price?.recurring?.usage_type === 'metered') {
+      return acc;
+    }
+    const baseAmount = (price as any)?.base_amount;
+    if (baseAmount) {
+      const quantity = item.quantity || 1;
+      return acc + Number(baseAmount) * quantity;
+    }
+    return acc;
+  }, 0);
+
+  if (usdTotal <= 0) {
+    return null;
+  }
+
+  const rateNum = Number(rate);
+  if (rateNum <= 0) {
+    return null;
+  }
+
+  // Calculate token amount: usdTotal / exchangeRate
+  const tokenAmount = usdTotal / rateNum;
+  const tokenAmountUnit = fromTokenToUnit(tokenAmount.toFixed(currencyDecimal || 8), currencyDecimal || 8);
+  return tokenAmountUnit.toString();
+}
+
+/**
+ * Extract quote lock timestamp from various sources
+ */
+function extractQuoteLockedAt(
+  paymentIntent?: TPaymentIntent | null,
+  checkoutSession?: TCheckoutSession
+): number | null {
+  if (paymentIntent?.quote_locked_at) {
+    const lockedAtMs = new Date(paymentIntent.quote_locked_at).getTime();
+    if (Number.isFinite(lockedAtMs)) {
+      return Math.floor(lockedAtMs / 1000);
+    }
+  }
+  const metaLockedAt = checkoutSession?.metadata?.quote_locked_at;
+  if (typeof metaLockedAt === 'number') {
+    return metaLockedAt;
+  }
+  if (typeof metaLockedAt === 'string') {
+    const parsed = Number(metaLockedAt);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+  return null;
+}
+
+/**
+ * Custom hook for dynamic pricing calculations
+ */
+export function useDynamicPricing(options: DynamicPricingOptions) {
+  const {
+    items,
+    currency,
+    liveRate,
+    liveQuoteSnapshot,
+    checkoutSession,
+    paymentIntent,
+    locale = 'en',
+    isStripePayment = false,
+    isSubscription = checkoutSession?.mode === 'subscription' || checkoutSession?.mode === 'setup',
+    slippageConfig,
+    trialInDays = 0,
+    trialEnd = 0,
+    discounts,
+  } = options;
+
+  // Check if currently in trial period
+  const currentTime = Math.floor(Date.now() / 1000);
+  const trialing = trialInDays > 0 || trialEnd > currentTime;
+
+  // Check if any items have dynamic pricing
+  const hasDynamicPricing = useMemo(
+    () => items.some((item) => ((item.upsell_price || item.price) as any)?.pricing_type === 'dynamic'),
+    [items]
+  );
+
+  // Extract quote metadata from line items
+  const quoteMeta = useMemo(() => (hasDynamicPricing ? extractQuoteMeta(items) : null), [items, hasDynamicPricing]);
+
+  // Combine live rate with quote metadata
+  const rateInfo = useMemo<RateInfo>(
+    () => ({
+      exchangeRate: isStripePayment ? null : liveRate?.rate || quoteMeta?.exchangeRate || null,
+      baseCurrency: liveRate?.base_currency || quoteMeta?.baseCurrency || 'USD',
+      providerName: isStripePayment ? null : liveRate?.provider_name || quoteMeta?.providerName || null,
+      providerId: isStripePayment ? null : liveRate?.provider_id || quoteMeta?.providerId || null,
+      timestampMs: isStripePayment ? null : liveRate?.timestamp_ms || quoteMeta?.rateTimestampMs || null,
+      fetchedAt: isStripePayment ? null : liveRate?.fetched_at || null, // When we fetched the data
+    }),
+    [liveRate, quoteMeta, isStripePayment]
+  );
+
+  // Calculate token amount from live rate (Final Freeze: no quote during preview)
+  // When trialing, skip recurring items as they don't need payment during trial
+  const calculatedTokenAmount = useMemo(() => {
+    if (isStripePayment || !hasDynamicPricing || !liveRate?.rate) {
+      return null;
+    }
+    return calculateTokenAmount(items, liveRate.rate, currency.decimal, trialing);
+  }, [hasDynamicPricing, liveRate?.rate, items, currency.decimal, isStripePayment, trialing]);
+
+  // Calculate discount amount dynamically when rate changes
+  // For percent_off: subtotal * percent_off / 100
+  // For amount_off: min(amount_off, subtotal) - because discount can't exceed subtotal
+  const calculatedDiscountAmount = useMemo(() => {
+    if (!discounts?.length) {
+      return null;
+    }
+
+    const couponDetails = discounts[0]?.coupon_details;
+    if (!couponDetails) {
+      return null;
+    }
+
+    // Stripe payment: calculate discount from USD amounts
+    if (isStripePayment) {
+      // Calculate discountable subtotal in cents (USD smallest unit)
+      const discountableSubtotalCents = items.reduce((sum, item) => {
+        // Only include discountable items
+        if (!(item as any).discountable) {
+          return sum;
+        }
+
+        const price = item.upsell_price || item.price;
+
+        // Skip recurring items during trial
+        if (trialing && price?.type === 'recurring') {
+          return sum;
+        }
+
+        // Skip metered items
+        if (price?.type === 'recurring' && price?.recurring?.usage_type === 'metered') {
+          return sum;
+        }
+
+        // For dynamic pricing, use base_amount (USD dollars), not unit_amount (token wei)
+        const isDynamic = (price as any)?.pricing_type === 'dynamic';
+        const baseAmount = (price as any)?.base_amount;
+
+        let amountCents: number;
+        if (isDynamic && baseAmount !== undefined && baseAmount !== null) {
+          // base_amount is in dollars, convert to cents
+          amountCents = Number(baseAmount) * 100;
+        } else {
+          // For non-dynamic pricing, unit_amount is in cents
+          const unitAmount = price?.unit_amount;
+          if (!unitAmount) {
+            return sum;
+          }
+          amountCents = Number(unitAmount);
+        }
+
+        const quantity = item.quantity || 1;
+        return sum + amountCents * quantity;
+      }, 0);
+
+      if (discountableSubtotalCents <= 0) {
+        return null;
+      }
+
+      // Percent off discount: subtotal * percent_off / 100
+      if (couponDetails.percent_off && couponDetails.percent_off > 0) {
+        const discountCents = Math.round((discountableSubtotalCents * couponDetails.percent_off) / 100);
+        return discountCents.toString();
+      }
+
+      // Fixed amount discount: min(amount_off, subtotal)
+      if (couponDetails.amount_off) {
+        // For Stripe, use USD amount_off directly (should be in cents)
+        const amountOffCents = Number(couponDetails.amount_off);
+        if (Number.isFinite(amountOffCents) && amountOffCents > 0) {
+          return Math.min(amountOffCents, discountableSubtotalCents).toString();
+        }
+      }
+
+      return null;
+    }
+
+    // Dynamic pricing: calculate discount from token amounts
+    if (!hasDynamicPricing || !liveRate?.rate) {
+      return null;
+    }
+
+    const rateNum = Number(liveRate.rate);
+    if (rateNum <= 0) {
+      return null;
+    }
+
+    // Calculate discountable subtotal in tokens (shared by both percent_off and amount_off)
+    const discountableSubtotal = items.reduce((sum, item) => {
+      // Only include discountable items
+      if (!(item as any).discountable) {
+        return sum;
+      }
+
+      const price = item.upsell_price || item.price;
+
+      // Skip recurring items during trial
+      if (trialing && price?.type === 'recurring') {
+        return sum;
+      }
+
+      // Skip metered items
+      if (price?.type === 'recurring' && price?.recurring?.usage_type === 'metered') {
+        return sum;
+      }
+
+      const baseAmount = (price as any)?.base_amount;
+      if (!baseAmount) {
+        return sum;
+      }
+
+      const quantity = item.quantity || 1;
+      const tokenAmount = (Number(baseAmount) * quantity) / rateNum;
+      return sum + tokenAmount;
+    }, 0);
+
+    if (discountableSubtotal <= 0) {
+      return null;
+    }
+
+    // Percent off discount: subtotal * percent_off / 100
+    if (couponDetails.percent_off && couponDetails.percent_off > 0) {
+      const discountAmount = (discountableSubtotal * couponDetails.percent_off) / 100;
+      const discountAmountUnit = fromTokenToUnit(discountAmount.toFixed(currency.decimal || 8), currency.decimal || 8);
+      return discountAmountUnit.toString();
+    }
+
+    // Fixed amount discount: min(amount_off, subtotal)
+    // When subtotal changes due to rate change, discount may also change
+    if (couponDetails.amount_off) {
+      // Get amount_off for current currency
+      const amountOff =
+        couponDetails.currency_id === currency.id
+          ? couponDetails.amount_off
+          : couponDetails.currency_options?.[currency.id]?.amount_off;
+
+      if (!amountOff) {
+        return null;
+      }
+
+      // Convert subtotal to unit for comparison
+      const subtotalUnit = fromTokenToUnit(discountableSubtotal.toFixed(currency.decimal || 8), currency.decimal || 8);
+      const amountOffBN = new BN(amountOff);
+      const subtotalBN = new BN(subtotalUnit);
+
+      // Return min(amount_off, subtotal)
+      return BN.min(amountOffBN, subtotalBN).toString();
+    }
+
+    return null;
+  }, [isStripePayment, hasDynamicPricing, liveRate?.rate, discounts, items, trialing, currency.decimal, currency.id]);
+
+  // Format rate for display
+  const rateDisplay = useMemo(() => {
+    if (!rateInfo.exchangeRate) {
+      return null;
+    }
+    const formattedRate = formatExchangeRate(rateInfo.exchangeRate);
+    if (!formattedRate) {
+      return null;
+    }
+    if (rateInfo.baseCurrency === 'USD') {
+      return `$${formattedRate}`;
+    }
+    return `${formattedRate} ${rateInfo.baseCurrency}`;
+  }, [rateInfo]);
+
+  // Quote lock status
+  const quoteLockedAt = useMemo(
+    () => extractQuoteLockedAt(paymentIntent, checkoutSession),
+    [paymentIntent, checkoutSession]
+  );
+
+  const isPriceLocked = useMemo(() => {
+    if (!quoteLockedAt) return false;
+    const now = Math.floor(Date.now() / 1000);
+    const lockRemaining = quoteLockedAt + 180 - now;
+    return lockRemaining > 0;
+  }, [quoteLockedAt]);
+
+  const lockExpired = useMemo(() => {
+    if (!quoteLockedAt) return false;
+    const now = Math.floor(Date.now() / 1000);
+    const lockRemaining = quoteLockedAt + 180 - now;
+    return lockRemaining <= 0;
+  }, [quoteLockedAt]);
+
+  // Current slippage value
+  const currentSlippagePercent = useMemo(() => {
+    let slippageValue: number | null | undefined = quoteMeta?.slippagePercent;
+    if (slippageValue === null || slippageValue === undefined) {
+      slippageValue =
+        slippageConfig?.percent ??
+        (checkoutSession as any)?.metadata?.slippage?.percent ??
+        (checkoutSession as any)?.slippage_percent;
+    }
+    if (slippageValue === null || slippageValue === undefined) {
+      slippageValue = 0.5; // default
+    }
+    return slippageValue as number;
+  }, [quoteMeta?.slippagePercent, slippageConfig?.percent, checkoutSession]);
+
+  // Provider display string - use provider_display from backend for human-readable format
+  const providerDisplay = useMemo(() => {
+    const fallback = '—';
+    // Prefer provider_display from liveRate (e.g., "CoinGecko (2 sources)")
+    if (liveRate?.provider_display) {
+      return liveRate.provider_display;
+    }
+    // Fallback to provider name/id
+    if (!rateInfo.providerName && !rateInfo.providerId) {
+      return fallback;
+    }
+    return rateInfo.providerName || rateInfo.providerId || fallback;
+  }, [liveRate?.provider_display, rateInfo.providerName, rateInfo.providerId]);
+
+  // Format total amount for display
+  const formatTotalDisplay = (totalAmountValue: string, fallback = '—') => {
+    // Final Freeze: Use calculated token amount from live rate
+    if (hasDynamicPricing && calculatedTokenAmount) {
+      const displayAmount = fromUnitToToken(calculatedTokenAmount, currency.decimal);
+      const numericValue = Number(displayAmount);
+      if (Number.isFinite(numericValue)) {
+        return formatDynamicPrice(displayAmount, true, 6);
+      }
+    }
+    // Fallback to liveQuoteSnapshot if available (for backward compatibility)
+    if (hasDynamicPricing && liveQuoteSnapshot?.quoted_amount) {
+      const snapshotAmount = fromUnitToToken(liveQuoteSnapshot.quoted_amount, currency.decimal);
+      const numericValue = Number(snapshotAmount);
+      if (Number.isFinite(numericValue)) {
+        return formatDynamicPrice(snapshotAmount, true, 6);
+      }
+    }
+    if (totalAmountValue === null || totalAmountValue === undefined || totalAmountValue === '') {
+      return fallback;
+    }
+    const numericValue = Number(totalAmountValue);
+    if (!Number.isFinite(numericValue)) {
+      return fallback;
+    }
+    return formatDynamicPrice(totalAmountValue, hasDynamicPricing, 6);
+  };
+
+  // Calculate USD equivalent display
+  const calculateUsdDisplay = (totalAmountValue: string) => {
+    const fallback = '—';
+    if (!hasDynamicPricing || !totalAmountValue || totalAmountValue === fallback) {
+      return null;
+    }
+    const numericValue = Number(totalAmountValue);
+    if (!Number.isFinite(numericValue) || numericValue < 0) {
+      return null;
+    }
+    // For zero amount (e.g., free trial), display $0
+    if (numericValue === 0) {
+      return formatUsdAmount('0', locale);
+    }
+    const { exchangeRate } = rateInfo;
+    if (!exchangeRate) {
+      return null;
+    }
+    const totalAmountInUnits = fromTokenToUnit(totalAmountValue, currency.decimal);
+    const totalUsd = getUsdAmountFromTokenUnits(new BN(totalAmountInUnits), currency.decimal, exchangeRate);
+    if (!totalUsd) {
+      return null;
+    }
+    return formatUsdAmount(totalUsd, locale);
+  };
+
+  // Build quote detail rows for display
+  const buildQuoteDetailRows = (t: (key: string) => string) => {
+    if (!hasDynamicPricing) {
+      return [];
+    }
+
+    const rows: Array<{ label: string; value: string | React.ReactNode; isSlippage?: boolean; tooltip?: string }> = [];
+    const fallback = '—';
+
+    // Only show provider and updatedAt if we have rate info
+    if (rateDisplay) {
+      // Use fetched_at (when we fetched) instead of timestamp_ms (provider's data timestamp)
+      // This shows users that we're actively fetching, even if provider data hasn't changed
+      const displayTimestamp = rateInfo.fetchedAt || rateInfo.timestampMs;
+      const updatedAt = displayTimestamp ? formatDateTime(displayTimestamp) : fallback;
+
+      rows.push(
+        { label: t('payment.checkout.quote.detailProvider'), value: providerDisplay },
+        { label: t('payment.checkout.quote.detailUpdatedAt'), value: updatedAt }
+      );
+    }
+
+    // Always show slippage for subscriptions with dynamic pricing (even metered without current rate)
+    if (isSubscription) {
+      let slippageDisplay = `${currentSlippagePercent}%`;
+      if (slippageConfig?.mode === 'rate' && slippageConfig.min_acceptable_rate) {
+        const formattedRate = formatExchangeRate(slippageConfig.min_acceptable_rate);
+        const displayRate = formattedRate || slippageConfig.min_acceptable_rate;
+        const displayCurrency = slippageConfig.base_currency || rateInfo.baseCurrency || 'USD';
+        const displayText = displayCurrency === 'USD' ? `$${displayRate}` : `${displayRate} ${displayCurrency}`;
+        slippageDisplay = `${displayText}`;
+      }
+
+      rows.push({
+        label: t('payment.checkout.quote.detailSlippage'),
+        value: slippageDisplay,
+        isSlippage: true,
+        tooltip: t('payment.checkout.quote.slippage.tooltip'),
+      });
+    }
+
+    return rows;
+  };
+
+  return {
+    // Flags
+    hasDynamicPricing,
+    isPriceLocked,
+    lockExpired,
+
+    // Data
+    quoteMeta,
+    rateInfo,
+    quoteLockedAt,
+    calculatedTokenAmount,
+    calculatedDiscountAmount,
+    currentSlippagePercent,
+
+    // Display helpers
+    rateDisplay,
+    providerDisplay,
+    formatTotalDisplay,
+    calculateUsdDisplay,
+    buildQuoteDetailRows,
+  };
+}
+
+export default useDynamicPricing;

package/src/index.ts

@@ -26,6 +26,8 @@ import StripeForm from './payment/form/stripe';
 import Payment from './payment/index';
 import ProductSkeleton from './payment/product-skeleton';
 import PaymentSummary from './payment/summary';
+import PromotionSection from './payment/summary-section/promotion-section';
+import TotalSection from './payment/summary-section/total-section';
 import PricingItem from './components/pricing-item';
 import CountrySelect from './components/country-select';
 import TruncatedText from './components/truncated-text';
@@ -42,6 +44,8 @@ import AutoTopup from './components/auto-topup';
 import Collapse from './components/collapse';
 import PromotionCode from './components/promotion-code';
 import SourceDataViewer from './components/source-data-viewer';
+import SlippageConfig from './components/slippage-config';
+import DynamicPricingUnavailable from './components/dynamic-pricing-unavailable';
 
 export { PaymentThemeProvider } from './theme';
 
@@ -108,7 +112,12 @@ export {
   Collapse,
   PromotionCode,
   SourceDataViewer,
+  SlippageConfig,
+  DynamicPricingUnavailable,
+  PromotionSection,
+  TotalSection,
 };
 
 export type { CountrySelectProps } from './components/country-select';
 export type { StripePaymentActionProps } from './components/stripe-payment-action';
+export type { SlippageConfigValue, SlippageConfigProps } from './components/slippage-config';