@blocklet/payment-react-headless 1.26.0

package/src/checkout/core/pricing.ts

@@ -0,0 +1,347 @@
+import { BN, fromUnitToToken, fromTokenToUnit } from '@ocap/util';
+import type { TCheckoutSessionExpanded, TPaymentCurrency, TLineItemExpanded } from '@blocklet/payment-types';
+
+import {
+  formatDynamicPrice,
+  formatUsdAmount,
+  getUsdAmountFromTokenUnits,
+  getCheckoutAmount,
+  getPriceUnitAmountByCurrency,
+} from '../../shared/format';
+import type { CheckoutSessionRuntime } from '../../types/checkout-augmented';
+import type { SessionData } from '../hooks/useCheckoutSession';
+
+export interface CalculatedAmounts {
+  subtotal: string;
+  paymentAmount: string;
+  total: string;
+  discount: string | null;
+  tax: {
+    amount: string;
+    rate: number;
+    inclusive: boolean;
+  } | null;
+  staking: string | null;
+  usdEquivalent: string | null;
+  subtotalUsdEquivalent?: string | null;
+}
+
+// Calculate staking amount for subscription (mirrors original getStakingSetup in payment-react/summary.tsx)
+function getStakingSetup(items: TLineItemExpanded[], currency: TPaymentCurrency, billingThreshold = 0): string {
+  const staking = { licensed: new BN(0), metered: new BN(0) };
+
+  const recurringItems = items
+    .map((x) => x.upsell_price || x.price)
+    .filter((x) => x?.type === 'recurring' && x?.recurring);
+
+  if (recurringItems.length > 0) {
+    if (+billingThreshold) {
+      return fromTokenToUnit(billingThreshold, currency.decimal).toString();
+    }
+
+    items.forEach((x) => {
+      const price = x.upsell_price || x.price;
+      const unit = getPriceUnitAmountByCurrency(price, currency);
+      const amount = new BN(unit).mul(new BN(x.quantity));
+      if (price?.type === 'recurring' && price?.recurring) {
+        if (price.recurring.usage_type === 'licensed') {
+          staking.licensed = staking.licensed.add(amount);
+        }
+        if (price.recurring.usage_type === 'metered') {
+          staking.metered = staking.metered.add(amount);
+        }
+      }
+    });
+
+    return staking.licensed.add(staking.metered).toString();
+  }
+
+  return '0';
+}
+
+/**
+ * Calculate coupon discount amount.
+ * @param recurringOnly - if true, skip coupons with duration='once' (for "next charge" display)
+ */
+function calculateCouponDiscount(
+  items: TLineItemExpanded[],
+  currency: TPaymentCurrency,
+  session: TCheckoutSessionExpanded | undefined | null,
+  hasDynamicPricing: boolean,
+  exchangeRate: string | null,
+  trialing: boolean,
+  recurringOnly: boolean
+): BN {
+  const discounts = session?.discounts || [];
+  if (discounts.length === 0) return new BN(0);
+
+  const coupon = ((discounts[0] as Record<string, unknown>).coupon_details || {}) as {
+    percent_off?: number;
+    amount_off?: string;
+    currency_options?: Record<string, { amount_off?: string }>;
+    duration?: string;
+  };
+
+  // 'once' coupons only apply to the first charge, not recurring
+  if (recurringOnly && coupon.duration === 'once') return new BN(0);
+
+  const discountableItems = items.filter((item) => {
+    if (item.discountable === false) return false;
+    const price = item.upsell_price || item.price;
+    if (price?.recurring?.usage_type === 'metered') return false;
+    return true;
+  });
+  const discountableResult = getCheckoutAmount(discountableItems, currency, trialing, true, {
+    exchangeRate: hasDynamicPricing ? exchangeRate : null,
+  });
+  const discountableSubtotalBN = new BN(discountableResult.total);
+  if (discountableSubtotalBN.lte(new BN(0))) return new BN(0);
+
+  if (coupon.percent_off && coupon.percent_off > 0) {
+    return discountableSubtotalBN.mul(new BN(coupon.percent_off)).div(new BN(100));
+  }
+
+  if (coupon.amount_off && coupon.amount_off !== '0') {
+    const amountOff = coupon.currency_options?.[currency.id]?.amount_off || coupon.amount_off;
+    if (amountOff && amountOff !== '0') {
+      const amountOffBN = new BN(amountOff);
+      return amountOffBN.lt(discountableSubtotalBN) ? amountOffBN : discountableSubtotalBN;
+    }
+  }
+
+  return new BN(0);
+}
+
+export function calculateAmounts(
+  items: TLineItemExpanded[],
+  currency: TPaymentCurrency | null,
+  session: TCheckoutSessionExpanded | undefined | null,
+  exchangeRate: string | null,
+  hasDynamicPricing: boolean,
+  paymentMethodType?: string | null
+): CalculatedAmounts {
+  if (!currency || items.length === 0) {
+    return {
+      subtotal: '0',
+      paymentAmount: '0',
+      total: '0',
+      discount: null,
+      tax: null,
+      staking: null,
+      usdEquivalent: null,
+    };
+  }
+
+  const subData = session?.subscription_data;
+  const trialDays = Number(subData?.trial_period_days || 0);
+  const trialing = trialDays > 0;
+
+  const result = getCheckoutAmount(items, currency, trialing, true, {
+    exchangeRate: hasDynamicPricing ? exchangeRate : null,
+  });
+
+  const subtotalBN = new BN(result.total);
+  const subtotalFormatted = formatDynamicPrice(fromUnitToToken(subtotalBN, currency.decimal), hasDynamicPricing);
+
+  // Calculate discount client-side from coupon data
+  const discountBN = calculateCouponDiscount(items, currency, session, hasDynamicPricing, exchangeRate, trialing, false);
+  const discount = discountBN.gt(new BN(0))
+    ? formatDynamicPrice(fromUnitToToken(discountBN.toString(), currency.decimal), hasDynamicPricing)
+    : null;
+
+  // Tax from session (backend-calculated)
+  const taxAmount = session?.total_details?.amount_tax;
+  const taxBN = new BN(taxAmount || '0');
+  const totalDetails = session?.total_details as
+    | (typeof session extends undefined
+        ? never
+        : NonNullable<typeof session>['total_details'] & { tax_rate?: number; tax_inclusive?: boolean })
+    | undefined;
+  const tax =
+    taxAmount && taxAmount !== '0'
+      ? {
+          amount: fromUnitToToken(taxAmount, currency.decimal),
+          rate: totalDetails?.tax_rate || 0,
+          inclusive: totalDetails?.tax_inclusive || false,
+        }
+      : null;
+
+  // Staking calculation (for arcblock payment method, non-credit currencies)
+  const noStake = subData?.no_stake || false;
+  const billingThreshold = Math.max(
+    Number(subData?.billing_threshold_amount || 0),
+    Number(subData?.min_stake_amount || 0)
+  );
+  const shouldShowStaking = paymentMethodType === 'arcblock' && currency.type !== 'credit' && !noStake;
+  const stakingUnitStr = shouldShowStaking ? getStakingSetup(items, currency, billingThreshold) : '0';
+  const stakingBN = new BN(stakingUnitStr);
+
+  // Subtotal includes staking when trialing (payment=0 + staking)
+  const subtotalWithStakingBN = subtotalBN.add(stakingBN);
+
+  // Total = subtotal + staking - discount + tax
+  let totalBN = subtotalWithStakingBN.sub(discountBN);
+  if (taxBN.gt(new BN(0)) && !tax?.inclusive) {
+    totalBN = totalBN.add(taxBN);
+  }
+  if (totalBN.isNeg()) {
+    totalBN = new BN(0);
+  }
+  const totalFormatted = formatDynamicPrice(fromUnitToToken(totalBN, currency.decimal), hasDynamicPricing);
+
+  // For display: subtotal should reflect total before discount (includes staking)
+  const displaySubtotalBN = subtotalWithStakingBN;
+  const displaySubtotalFormatted = formatDynamicPrice(
+    fromUnitToToken(displaySubtotalBN, currency.decimal),
+    hasDynamicPricing
+  );
+
+  // USD equivalents for crypto
+  let usdEquivalent: string | null = null;
+  let subtotalUsdEquivalent: string | null = null;
+  if (hasDynamicPricing && exchangeRate && currency) {
+    const totalUsd = getUsdAmountFromTokenUnits(totalBN.toString(), currency.decimal, exchangeRate);
+    if (totalUsd) {
+      usdEquivalent = formatUsdAmount(totalUsd) || null;
+    }
+    const subtotalUsd = getUsdAmountFromTokenUnits(displaySubtotalBN.toString(), currency.decimal, exchangeRate);
+    if (subtotalUsd) {
+      subtotalUsdEquivalent = formatUsdAmount(subtotalUsd) || null;
+    }
+  }
+
+  const stakingFormatted = stakingBN.gt(new BN(0))
+    ? `${formatDynamicPrice(fromUnitToToken(stakingBN.toString(), currency.decimal), hasDynamicPricing)} ${currency.symbol}`
+    : null;
+
+  return {
+    subtotal: `${displaySubtotalFormatted} ${currency.symbol}`,
+    paymentAmount: `${subtotalFormatted} ${currency.symbol}`,
+    total: `${totalFormatted} ${currency.symbol}`,
+    discount: discount ? `${discount} ${currency.symbol}` : null,
+    tax,
+    staking: stakingFormatted,
+    usdEquivalent: usdEquivalent ? `$${usdEquivalent}` : null,
+    subtotalUsdEquivalent: subtotalUsdEquivalent ? `$${subtotalUsdEquivalent}` : null,
+  };
+}
+
+export interface QuoteMeta {
+  locked: boolean;
+  lockedAt: number | null;
+  expiresAt: number | null;
+  expired: boolean;
+  baseCurrency: string | null;
+  slippagePercent: number | null;
+}
+
+export function calculateQuoteMeta(
+  items: TLineItemExpanded[],
+  hasDynamicPricing: boolean,
+  sessionData: SessionData | null
+): QuoteMeta {
+  if (!items.length || !hasDynamicPricing) {
+    return {
+      locked: false,
+      lockedAt: null,
+      expiresAt: null,
+      expired: false,
+      baseCurrency: null,
+      slippagePercent: null,
+    };
+  }
+
+  const session = sessionData?.checkoutSession as CheckoutSessionRuntime | undefined;
+  let baseCurrency: string | null = null;
+  let expiresAt: number | null = null;
+  let slippagePercent: number | null = null;
+
+  items.forEach((item) => {
+    const price = item.upsell_price || item.price;
+    if (!baseCurrency && price?.base_currency) baseCurrency = price.base_currency;
+
+    const expires = item.expires_at as number | undefined;
+    if (expires) {
+      expiresAt = expiresAt === null ? expires : Math.min(expiresAt!, expires);
+    }
+
+    const itemSlippage = item.slippage_percent as number | undefined;
+    if (slippagePercent === null && Number.isFinite(Number(itemSlippage))) {
+      slippagePercent = Number(itemSlippage);
+    }
+  });
+
+  const piCreated = sessionData?.paymentIntent?.created_at
+    ? new Date(sessionData.paymentIntent.created_at).getTime()
+    : null;
+  const sessionLock = session?.quote_locked_at;
+  const lockedAt: number | null = piCreated || sessionLock || null;
+  const locked = !!lockedAt;
+
+  const now = Date.now();
+  const expired = expiresAt ? now > expiresAt : false;
+
+  return { locked, lockedAt, expiresAt, expired, baseCurrency, slippagePercent };
+}
+
+export function calculateTrial(
+  session: TCheckoutSessionExpanded | undefined | null,
+  currencyId: string | null | undefined,
+  items: TLineItemExpanded[],
+  currency: TPaymentCurrency | null,
+  hasDynamicPricing: boolean,
+  exchangeRate: string | null
+) {
+  const subData = session?.subscription_data;
+  let trialDays = Number(subData?.trial_period_days || 0);
+
+  if (trialDays > 0 && currencyId) {
+    const trialCurrencyIds = (subData?.trial_currency || '')
+      .split(',')
+      .map((s: string) => s.trim())
+      .filter(Boolean);
+    if (trialCurrencyIds.length > 0 && !trialCurrencyIds.includes(currencyId)) {
+      trialDays = 0;
+    }
+  }
+
+  const trialActive = trialDays > 0;
+
+  let afterTrialPrice: string | null = null;
+  let afterTrialInterval: string | null = null;
+  if (trialActive && currency && items.length > 0) {
+    const noTrialResult = getCheckoutAmount(items, currency, false, true, {
+      exchangeRate: hasDynamicPricing ? exchangeRate : null,
+    });
+    let afterTrialBN = new BN(noTrialResult.total);
+
+    // Apply recurring discount (repeating/forever coupons) to next charge amount
+    const recurringDiscount = calculateCouponDiscount(
+      items, currency, session, hasDynamicPricing, exchangeRate, false, true
+    );
+    if (recurringDiscount.gt(new BN(0))) {
+      afterTrialBN = afterTrialBN.sub(recurringDiscount);
+      if (afterTrialBN.isNeg()) afterTrialBN = new BN(0);
+    }
+
+    afterTrialPrice = `${formatDynamicPrice(
+      fromUnitToToken(afterTrialBN, currency.decimal),
+      hasDynamicPricing
+    )} ${currency.symbol}`;
+    const recurringItem = items.find((item) => {
+      const price = item.upsell_price || item.price;
+      return price?.type === 'recurring' && price?.recurring;
+    });
+    if (recurringItem) {
+      const price = recurringItem.upsell_price || recurringItem.price;
+      afterTrialInterval = price?.recurring?.interval || null;
+    }
+  }
+
+  return {
+    active: trialActive,
+    days: trialDays,
+    afterTrialPrice,
+    afterTrialInterval,
+  };
+}

package/src/checkout/core/promotion.ts

@@ -0,0 +1,59 @@
+import type { TCheckoutSessionExpanded } from '@blocklet/payment-types';
+
+import api, { API } from '../../shared/api';
+import { getErrorMessage } from '../../types/checkout-augmented';
+
+export function extractPromotionCodeFromSession(session: TCheckoutSessionExpanded | undefined | null): string | null {
+  const discounts = session?.discounts || [];
+  if (discounts.length === 0) return null;
+
+  const firstDiscount = discounts[0] as Record<string, unknown>;
+  const details = firstDiscount.promotion_code_details as { code?: string } | undefined;
+  const verification = firstDiscount.verification_data as { code?: string } | undefined;
+  return (
+    details?.code ||
+    verification?.code ||
+    (firstDiscount.promotion_code as string) ||
+    (firstDiscount.coupon as string) ||
+    null
+  );
+}
+
+export async function applyPromotionCode(
+  sessionId: string,
+  code: string,
+  currencyId: string | null | undefined
+): Promise<{ success: boolean; error?: string }> {
+  try {
+    const { data } = await api.post(API.APPLY_PROMOTION(sessionId), {
+      promotion_code: code,
+      currency_id: currencyId,
+    });
+
+    if (data.error) {
+      return { success: false, error: data.error };
+    }
+    return { success: true };
+  } catch (err: unknown) {
+    return { success: false, error: getErrorMessage(err) || 'Invalid promotion code' };
+  }
+}
+
+export async function removePromotionCode(sessionId: string): Promise<void> {
+  await api.delete(API.REMOVE_PROMOTION(sessionId));
+}
+
+export async function recalculatePromotion(sessionId: string, currencyId: string | null | undefined): Promise<void> {
+  await api.post(API.RECALCULATE_PROMOTION_SESSION(sessionId), {
+    currency_id: currencyId,
+  });
+}
+
+export function isPromotionActive(session: TCheckoutSessionExpanded | undefined | null): boolean {
+  return session?.allow_promotion_codes !== false;
+}
+
+export function hasAppliedDiscounts(session: TCheckoutSessionExpanded | undefined | null): boolean {
+  const discounts = session?.discounts || [];
+  return discounts.length > 0;
+}

package/src/checkout/core/session.ts

@@ -0,0 +1,62 @@
+import type { TCheckoutSessionExpanded } from '@blocklet/payment-types';
+
+export function parseProduct(session: TCheckoutSessionExpanded) {
+  const items = session.line_items || [];
+  if (items.length === 0) return null;
+
+  const firstItem = items[0];
+  const price = firstItem.upsell_price || firstItem.price;
+  const product = price?.product;
+  if (!product) return null;
+
+  const recurring = price?.recurring;
+  const mode = session.mode === 'subscription' ? 'subscription' : 'payment';
+
+  const intervalMap: Record<string, string> = {
+    day: 'daily',
+    week: 'weekly',
+    month: 'monthly',
+    year: 'yearly',
+  };
+
+  return {
+    name: product.name || '',
+    description: product.description || '',
+    images: product.images || [],
+    features: (product.features || []).map((f: { name?: string; icon?: string }) => ({
+      name: f.name || '',
+      icon: f.icon,
+    })),
+    billing: {
+      mode: mode as 'payment' | 'subscription',
+      interval: (recurring?.interval as 'month' | 'year' | 'week' | 'day' | undefined) || null,
+      intervalCount: recurring?.interval_count || 1,
+      displayInterval: recurring ? intervalMap[recurring.interval] || recurring.interval : '',
+    },
+    metadata: product.metadata || {},
+  };
+}
+
+export function parseSubscription(session: TCheckoutSessionExpanded) {
+  const subData = session.subscription_data;
+  if (!subData && session.mode === 'payment') return null;
+
+  return {
+    mode: (session.mode || 'payment') as 'payment' | 'subscription' | 'setup',
+    showStake: !subData?.no_stake,
+    confirmMessage: '',
+  };
+}
+
+export function parsePageInfo(session: TCheckoutSessionExpanded) {
+  const metadata = session.metadata as Record<string, any> | undefined;
+  const pageInfo = metadata?.page_info;
+
+  // show_product_features is stored as boolean string on metadata directly (V1 compat)
+  const showRaw = metadata?.show_product_features ?? pageInfo?.show_product_features;
+
+  return {
+    formPurposeDescription: pageInfo?.form_purpose_description,
+    showProductFeatures: `${showRaw}` === 'true',
+  };
+}

package/src/checkout/core/submit.ts

@@ -0,0 +1,109 @@
+import type { TCheckoutSessionExpanded, TLineItemExpanded } from '@blocklet/payment-types';
+
+import api, { API } from '../../shared/api';
+import { generateIdempotencyKey } from '../../shared/polling';
+import type { CheckoutFormData } from '../types';
+
+// Quote-related error codes that trigger auto-refresh
+export const QUOTE_ERROR_CODES = [
+  'QUOTE_LOCK_EXPIRED',
+  'QUOTE_AMOUNT_MISMATCH',
+  'QUOTE_EXPIRED_OR_USED',
+  'QUOTE_NOT_FOUND',
+  'QUOTE_REQUIRED',
+  'QUOTE_MAX_PAYABLE_EXCEEDED',
+  'quote_validation_failed',
+] as const;
+
+// WebSocket relay utilities
+export const RELAY_SOCKET_PREFIX = '/.well-known/service/relay';
+
+export function getAppId(): string {
+  // appPid/appId are injected at runtime by blocklet-server but not in the static type declaration
+  const blocklet = window.blocklet as { appPid?: string; appId?: string } | undefined;
+  return blocklet?.appPid || blocklet?.appId || '';
+}
+
+export function getRelayChannel(token: string): string {
+  return `relay:${getAppId()}:${token}`;
+}
+
+export function getRelayProtocol(): string {
+  return window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+}
+
+export function getSocketHost(): string {
+  return new URL(window.location.href).host;
+}
+
+/**
+ * Compute a fingerprint of the payment context for idempotency key stability.
+ * Key changes only when session state actually changes (quantity, upsell, currency).
+ * Same fingerprint → reuse Quote (intent: "retry with same Quote").
+ */
+export function getSessionFingerprint(
+  session: TCheckoutSessionExpanded | undefined | null,
+  currencyId: string | null
+): string {
+  if (!session) return '';
+  const items = (session.line_items || []) as TLineItemExpanded[];
+  const sig = items.map((i) => `${i.upsell_price_id || i.price_id}:${i.quantity}`).join('|');
+  return `${session.id}-${currencyId}-${sig}`;
+}
+
+export function buildSubmitPayload(
+  sessionId: string,
+  currencyId: string | null,
+  formValues: CheckoutFormData,
+  session: TCheckoutSessionExpanded | undefined | null,
+  priceConfirmed = false,
+  idempotencyKey?: string
+) {
+  const lineItems = (session?.line_items || []) as TLineItemExpanded[];
+  const matchedItem = lineItems.find((item) => item.exchange_rate);
+  const previewRate = matchedItem?.exchange_rate as string | undefined;
+
+  return {
+    ...formValues,
+    idempotency_key: idempotencyKey || generateIdempotencyKey(sessionId, currencyId || ''),
+    preview_rate: previewRate || undefined,
+    ...(priceConfirmed && { price_confirmed: true }),
+  };
+}
+
+export function isQuoteError(errorCode: string): boolean {
+  return (QUOTE_ERROR_CODES as readonly string[]).includes(errorCode) || errorCode === 'QUOTE_UPDATED';
+}
+
+export async function abortStripePayment(sessionId: string): Promise<void> {
+  try {
+    await api.post(API.ABORT_STRIPE(sessionId));
+  } catch {
+    // Ignore abort error
+  }
+}
+
+export async function submitCheckout(
+  sessionId: string,
+  isDonation: boolean,
+  payload: Record<string, unknown>
+): Promise<Record<string, unknown>> {
+  const url = isDonation ? API.DONATE_SUBMIT(sessionId) : API.SUBMIT(sessionId);
+  const { data } = await api.put(url, payload);
+  return data;
+}
+
+export async function confirmFastCheckout(sessionId: string): Promise<Record<string, unknown>> {
+  const { data } = await api.post(API.FAST_CHECKOUT_CONFIRM(sessionId), {});
+  return data;
+}
+
+export async function updateSlippage(
+  sessionId: string,
+  config: { mode: string; percent: number }
+): Promise<Record<string, unknown>> {
+  const { data } = await api.put(API.SLIPPAGE(sessionId), {
+    slippage_config: config,
+  });
+  return data;
+}

package/src/checkout/hooks/index.ts

@@ -0,0 +1,41 @@
+// Backward-compatible orchestrator (no Provider needed)
+export { useCheckout } from './useCheckout';
+
+// Param-based hooks (used by useCheckout internally, also usable standalone)
+export { useCheckoutSession } from './useCheckoutSession';
+export type { UseCheckoutSessionReturn, SessionData } from './useCheckoutSession';
+export { usePaymentMethod } from './usePaymentMethod';
+export type { UsePaymentMethodReturn } from './usePaymentMethod';
+export { usePricing } from './usePricing';
+export type { UsePricingReturn } from './usePricing';
+export { useCustomerForm } from './useCustomerForm';
+export type { UseCustomerFormReturn } from './useCustomerForm';
+export { useSubmit } from './useSubmit';
+export type { UseSubmitReturn, VendorStatus, VendorOrderStatus } from './useSubmit';
+
+// Feature hooks (require <CheckoutProvider>)
+export { useProduct } from './useProduct';
+export type { UseProductReturn } from './useProduct';
+export { useLineItems } from './useLineItems';
+export type { UseLineItemsReturn } from './useLineItems';
+export { useBillingInterval } from './useBillingInterval';
+export type { UseBillingIntervalReturn, BillingIntervalData } from './useBillingInterval';
+export { useUpsell } from './useUpsell';
+export type { UseUpsellReturn } from './useUpsell';
+export { useCrossSell } from './useCrossSell';
+export type { UseCrossSellReturn } from './useCrossSell';
+export { usePromotion } from './usePromotion';
+export type { UsePromotionReturn } from './usePromotion';
+export { useExchangeRate } from './useExchangeRate';
+export type { UseExchangeRateReturn } from './useExchangeRate';
+export { useSlippage } from './useSlippage';
+export type { UseSlippageReturn } from './useSlippage';
+export { useCheckoutStatus } from './useCheckoutStatus';
+export type { UseCheckoutStatusReturn } from './useCheckoutStatus';
+
+// Context-aware wrappers for existing hooks (require <CheckoutProvider>)
+export { usePricingFeature } from './usePricingFeature';
+export type { UsePricingFeatureReturn } from './usePricingFeature';
+export { usePaymentMethodFeature } from './usePaymentMethodFeature';
+export { useCustomerFormFeature } from './useCustomerFormFeature';
+export { useSubmitFeature } from './useSubmitFeature';

package/src/checkout/hooks/useBillingInterval.ts

@@ -0,0 +1,71 @@
+import { useState, useMemo } from 'react';
+import { useMemoizedFn } from 'ahooks';
+
+import { getErrorMessage } from '../../types/checkout-augmented';
+import { useSessionContext } from '../context/SessionContext';
+import { usePaymentMethodContext } from '../context/PaymentMethodContext';
+import { parseBillingInterval, type BillingIntervalType } from '../core/billingInterval';
+import { performUpsell, performDownsell } from '../core/lineItems';
+
+export interface BillingIntervalData {
+  current: BillingIntervalType | null;
+  available: Array<{
+    interval: BillingIntervalType;
+    priceId: string;
+    amount: string;
+    savings: string | null;
+  }>;
+  switch: (interval: BillingIntervalType) => Promise<void>;
+  switching: boolean;
+}
+
+export type UseBillingIntervalReturn = BillingIntervalData | null;
+
+export function useBillingInterval(): UseBillingIntervalReturn {
+  const { items, session, effectiveSessionId, refresh } = useSessionContext();
+  const { currency } = usePaymentMethodContext();
+  const currencyId = currency?.id || null;
+  const [switching, setSwitching] = useState(false);
+
+  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 useMemo(() => {
+    const parsed = parseBillingInterval(items);
+    if (!parsed) return null;
+
+    return {
+      current: parsed.current,
+      available: parsed.available,
+      switching,
+      switch: async (interval: BillingIntervalType) => {
+        const target = parsed.available.find((a) => a.interval === interval);
+        if (!target || switching) return;
+
+        setSwitching(true);
+        try {
+          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);
+          }
+        } finally {
+          setSwitching(false);
+        }
+      },
+    };
+  }, [items, effectiveSessionId, switching]); // eslint-disable-line react-hooks/exhaustive-deps
+}