@blocklet/payment-react-headless 1.26.0

package/src/shared/format.ts

@@ -0,0 +1,318 @@
+import { BN, fromUnitToToken, fromTokenToUnit } from '@ocap/util';
+import type { TPaymentCurrency, TPrice, TLineItemExpanded } from '@blocklet/payment-types';
+
+// ── Number Formatting ──
+
+export function formatNumber(
+  n: number | string,
+  precision: number = 6,
+  trim: boolean = true,
+  thousandSeparated: boolean = true
+): string {
+  if (!n || n === '0') {
+    return '0';
+  }
+  const num = Number(n);
+  if (!Number.isFinite(num)) {
+    return '0';
+  }
+
+  let result: string;
+  if (thousandSeparated) {
+    result = num.toLocaleString('en-US', {
+      minimumFractionDigits: precision,
+      maximumFractionDigits: precision,
+    });
+  } else {
+    result = num.toFixed(precision);
+  }
+
+  if (!trim) {
+    return result;
+  }
+  const [left, right] = result.split('.');
+  if (!right) return left;
+  const trimmed = right.replace(/0+$/, '');
+  return trimmed ? `${left}.${trimmed}` : left;
+}
+
+export function formatBNStr(
+  str: string = '',
+  decimals: number = 18,
+  precision: number = 6,
+  trim: boolean = true,
+  thousandSeparated: boolean = true
+): string {
+  if (!str) {
+    return '0';
+  }
+  return formatNumber(fromUnitToToken(str, decimals), precision, trim, thousandSeparated);
+}
+
+export function formatDynamicPrice(
+  n: number | string,
+  isDynamic: boolean,
+  precision: number = 6,
+  trim: boolean = true,
+  thousandSeparated: boolean = true
+): string {
+  if (!isDynamic) {
+    return formatNumber(n, precision, trim, thousandSeparated);
+  }
+  const num = Number(n);
+  if (!Number.isFinite(num)) {
+    return formatNumber(n, precision, trim, thousandSeparated);
+  }
+  const abs = Math.abs(num);
+  const targetPrecision = abs > 0 && abs < 0.01 ? precision : 2;
+  return formatNumber(n, targetPrecision, trim, thousandSeparated);
+}
+
+// ── USD Formatting ──
+
+const USD_DECIMALS = 8;
+
+export function getUsdAmountFromTokenUnits(
+  tokenAmount: BN | string,
+  tokenDecimals: number,
+  exchangeRate?: string | null
+): string | null {
+  if (!exchangeRate && exchangeRate !== '0') {
+    return null;
+  }
+  if (tokenDecimals === undefined || tokenDecimals === null) {
+    return null;
+  }
+
+  try {
+    const amountBN = tokenAmount instanceof BN ? tokenAmount : new BN(tokenAmount || '0');
+    const tokenScale = new BN(10).pow(new BN(tokenDecimals));
+    if (tokenScale.isZero()) {
+      return null;
+    }
+
+    const rateBN = new BN(exchangeRate.replace('.', ''));
+    const rateDecimalPlaces = exchangeRate.includes('.') ? exchangeRate.split('.')[1]?.length || 0 : 0;
+    const rateScale = new BN(10).pow(new BN(rateDecimalPlaces));
+
+    const usdPrecisionScale = new BN(10).pow(new BN(USD_DECIMALS));
+    const usdUnit = amountBN.mul(rateBN).mul(usdPrecisionScale).div(tokenScale.mul(rateScale));
+
+    return fromUnitToToken(usdUnit.toString(), USD_DECIMALS);
+  } catch {
+    return null;
+  }
+}
+
+export function formatUsdAmount(amount: string | null, locale: string = 'en'): string | null {
+  if (!amount && amount !== '0') {
+    return null;
+  }
+  const num = Number(amount);
+  if (!Number.isFinite(num)) {
+    return null;
+  }
+  return new Intl.NumberFormat(locale, {
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+  }).format(num);
+}
+
+export function formatExchangeRate(amount: string | null): string | null {
+  if (!amount && amount !== '0') {
+    return null;
+  }
+  const value = String(amount);
+  const num = Number(value);
+  if (!Number.isFinite(num)) {
+    return null;
+  }
+  return value;
+}
+
+export function formatExchangeRateDisplay(
+  rate: string | number | null | undefined,
+  currency: string = 'USD',
+  decimals: number = 2
+): string | null {
+  if (rate === null || rate === undefined) {
+    return null;
+  }
+  const num = Number(rate);
+  if (!Number.isFinite(num)) {
+    return null;
+  }
+  const formattedValue = num.toFixed(decimals);
+  if (currency === 'USD') {
+    return `$${formattedValue}`;
+  }
+  return `${formattedValue} ${currency}`;
+}
+
+// ── Amount Formatting ──
+
+export function formatAmount(amount: string, decimals: number, precision: number = 2): string {
+  const tokenAmount = fromUnitToToken(amount, decimals);
+  const numericValue = Number(tokenAmount);
+  if (!Number.isFinite(numericValue)) {
+    return formatBNStr(amount, decimals, precision, true, false);
+  }
+  const abs = Math.abs(numericValue);
+  const targetPrecision = abs > 0 && abs < 0.01 ? decimals : 2;
+  return formatNumber(tokenAmount, targetPrecision, true, false);
+}
+
+// ── Price Utilities ──
+
+export function getPriceCurrencyOptions(price: TPrice): Array<{
+  currency_id: string;
+  unit_amount: string;
+  custom_unit_amount: { preset?: string; presets: string[] } | null;
+  tiers: unknown;
+}> {
+  if (Array.isArray(price.currency_options)) {
+    return price.currency_options;
+  }
+
+  return [
+    {
+      currency_id: price.currency_id,
+      unit_amount: price.unit_amount,
+      custom_unit_amount: price.custom_unit_amount || null,
+      tiers: null,
+    },
+  ];
+}
+
+export function getPriceUnitAmountByCurrency(price: TPrice, currency: TPaymentCurrency): string {
+  const options = getPriceCurrencyOptions(price);
+  const option = options.find((x) => x.currency_id === currency?.id);
+  if (option) {
+    if (option.custom_unit_amount) {
+      return option.custom_unit_amount.preset || option.custom_unit_amount.presets[0];
+    }
+    return option.unit_amount;
+  }
+
+  if (price.currency_id === currency?.id) {
+    if (price.custom_unit_amount) {
+      return price.custom_unit_amount.preset || price.custom_unit_amount.presets[0];
+    }
+    return price.unit_amount;
+  }
+
+  return '0';
+}
+
+export function getLineItemAmounts(
+  item: TLineItemExpanded,
+  currency: TPaymentCurrency,
+  { useUpsell = true, exchangeRate = null }: { useUpsell?: boolean; exchangeRate?: string | null } = {}
+): { unitAmount: BN; totalAmount: BN; isDynamicQuote: boolean } {
+  if (!currency) {
+    return { unitAmount: new BN(0), totalAmount: new BN(0), isDynamicQuote: false };
+  }
+
+  const price = useUpsell ? item.upsell_price || item.price : item.price;
+  const quantity = new BN(item.quantity || 0);
+  const quoteAmount = item.quoted_amount as string | undefined;
+  const quoteCurrencyId = item.quote_currency_id as string | undefined;
+  const isDynamicPrice = price?.pricing_type === 'dynamic';
+
+  const isQuoteValidForCurrency = isDynamicPrice && quoteAmount && quoteCurrencyId === currency.id;
+
+  if (isQuoteValidForCurrency) {
+    const totalAmount = new BN(quoteAmount || '0');
+    const unitAmount = quantity.gt(new BN(0)) ? totalAmount.add(quantity).sub(new BN(1)).div(quantity) : new BN(0);
+    return { unitAmount, totalAmount, isDynamicQuote: true };
+  }
+
+  if (isDynamicPrice && exchangeRate && price?.base_amount) {
+    const rate = Number(exchangeRate);
+    if (rate > 0 && Number.isFinite(rate)) {
+      const baseAmountUsd = Number(price.base_amount);
+      if (baseAmountUsd > 0 && Number.isFinite(baseAmountUsd)) {
+        const tokenAmount = baseAmountUsd / rate;
+        const unitAmount = fromTokenToUnit(tokenAmount.toFixed(currency.decimal || 8), currency.decimal || 8);
+        return {
+          unitAmount,
+          totalAmount: unitAmount.mul(quantity),
+          isDynamicQuote: false,
+        };
+      }
+    }
+  }
+
+  // For Stripe/USD mode: use base_amount directly when no exchange rate
+  // (applies to both dynamic and standard pricing — unit_amount may be in crypto denomination)
+  if (!exchangeRate && price?.base_amount != null) {
+    const baseAmountUsd = Number(price.base_amount);
+    if (baseAmountUsd >= 0 && Number.isFinite(baseAmountUsd)) {
+      const dec = currency.decimal || 2;
+      const unitAmountBN = fromTokenToUnit(baseAmountUsd.toFixed(dec), dec);
+      return {
+        unitAmount: unitAmountBN,
+        totalAmount: unitAmountBN.mul(quantity),
+        isDynamicQuote: false,
+      };
+    }
+  }
+
+  const unitAmount = new BN(getPriceUnitAmountByCurrency(price, currency));
+  return {
+    unitAmount,
+    totalAmount: unitAmount.mul(quantity),
+    isDynamicQuote: false,
+  };
+}
+
+export function getCheckoutAmount(
+  items: TLineItemExpanded[],
+  currency: TPaymentCurrency,
+  trialing = false,
+  upsell = true,
+  { exchangeRate = null }: { exchangeRate?: string | null } = {}
+): { subtotal: string; total: string; renew: string; discount: string; shipping: string; tax: string } {
+  let renew = new BN(0);
+  const total = items
+    .filter((x) => {
+      const price = upsell ? x.upsell_price || x.price : x.price;
+      return price != null;
+    })
+    .reduce((acc, x) => {
+      const quoteCurrencyId = x.quote_currency_id as string | undefined;
+
+      // Determine totalAmount: prefer custom_amount only when quote_currency_id confirms it matches
+      // (when quote_currency_id is absent, custom_amount denomination is unknown)
+      let totalAmount: BN;
+      if (x.custom_amount && quoteCurrencyId && quoteCurrencyId === currency.id) {
+        totalAmount = new BN(x.custom_amount);
+      } else {
+        ({ totalAmount } = getLineItemAmounts(x, currency, { useUpsell: upsell, exchangeRate }));
+      }
+
+      const price = upsell ? x.upsell_price || x.price : x.price;
+
+      if (price?.type === 'recurring') {
+        renew = renew.add(totalAmount);
+        if (trialing) {
+          return acc;
+        }
+        if (price.recurring?.usage_type === 'metered') {
+          return acc;
+        }
+      }
+
+      return acc.add(totalAmount);
+    }, new BN(0))
+    .toString();
+
+  return {
+    subtotal: total,
+    total,
+    renew: formatDynamicPrice(renew.toString(), !!exchangeRate),
+    discount: '0',
+    shipping: '0',
+    tax: '0',
+  };
+}

package/src/shared/polling.ts

@@ -0,0 +1,49 @@
+import pWaitFor from 'p-wait-for';
+
+import api, { API } from './api';
+import type { CheckoutResult } from '../checkout/types';
+
+/**
+ * Poll for checkout session completion.
+ * Extracted from react/src/payment/form/index.tsx:72-99
+ *
+ * Uses p-wait-for with 2s interval and 3 minute timeout.
+ * Completion condition: session.status === 'complete' && payment_status in ['paid', 'no_payment_required']
+ * Throws if paymentIntent has last_payment_error.
+ */
+export async function waitForCheckoutComplete(sessionId: string): Promise<CheckoutResult> {
+  let result: CheckoutResult;
+
+  await pWaitFor(
+    async () => {
+      const { data } = await api.get(API.RETRIEVE_SESSION(sessionId));
+
+      if (
+        data.paymentIntent &&
+        data.paymentIntent.status === 'requires_action' &&
+        data.paymentIntent.last_payment_error
+      ) {
+        throw new Error(data.paymentIntent.last_payment_error.message);
+      }
+
+      result = data;
+
+      return (
+        data.checkoutSession?.status === 'complete' &&
+        ['paid', 'no_payment_required'].includes(data.checkoutSession?.payment_status)
+      );
+    },
+    { interval: 2000, timeout: 3 * 60 * 1000 }
+  );
+
+  // @ts-expect-error result is assigned inside the polling callback
+  return result;
+}
+
+/**
+ * Generate unique idempotency key for submit (Final Freeze Architecture).
+ * Format: ${sessionId}-${currencyId}-${timestamp}-${random}
+ */
+export function generateIdempotencyKey(sessionId: string, currencyId: string): string {
+  return `${sessionId}-${currencyId}-${Date.now()}-${Math.random().toString(36).substring(2, 10)}`;
+}

package/src/shared/types.ts

@@ -0,0 +1,13 @@
+// Shared types used across all domains
+
+export interface ApiConfig {
+  baseUrl?: string;
+  authToken?: string;
+  locale?: string;
+  livemode?: boolean;
+}
+
+export interface LoadingState {
+  isLoading: boolean;
+  error: string | null;
+}

package/src/shared/validation.ts

@@ -0,0 +1,254 @@
+import isEmail from 'validator/lib/isEmail';
+
+import type { CheckoutFormData } from '../checkout/types';
+
+// ── Postal Code Patterns ──
+
+const fourDigit = /^\d{4}$/;
+const fiveDigit = /^\d{5}$/;
+const sixDigit = /^\d{6}$/;
+
+export const postalCodePatterns: Record<string, RegExp> = {
+  GB: /^GIR[ ]?0AA|((AB|AL|B|BA|BB|BD|BH|BL|BN|BR|BS|BT|CA|CB|CF|CH|CM|CO|CR|CT|CV|CW|DA|DD|DE|DG|DH|DL|DN|DT|DY|E|EC|EH|EN|EX|FK|FY|G|GL|GY|GU|HA|HD|HG|HP|HR|HS|HU|HX|IG|IM|IP|IV|JE|KA|KT|KW|KY|L|LA|LD|LE|LL|LN|LS|LU|M|ME|MK|ML|N|NE|NG|NN|NP|NR|NW|OL|OX|PA|PE|PH|PL|PO|PR|RG|RH|RM|S|SA|SE|SG|SK|SL|SM|SN|SO|SP|SR|SS|ST|SW|SY|TA|TD|TF|TN|TQ|TR|TS|TW|UB|W|WA|WC|WD|WF|WN|WR|WS|WV|YO|ZE)(\d[\dA-Z]?[ ]?\d[ABD-HJLN-UW-Z]{2}))|BFPO[ ]?\d{1,4}$/i,
+  JE: /^JE\d[\dA-Z]?[ ]?\d[ABD-HJLN-UW-Z]{2}$/i,
+  GG: /^GY\d[\dA-Z]?[ ]?\d[ABD-HJLN-UW-Z]{2}$/i,
+  IM: /^IM\d[\dA-Z]?[ ]?\d[ABD-HJLN-UW-Z]{2}$/i,
+  US: /^\d{5}([ -]\d{4})?$/,
+  CA: /^[ABCEGHJKLMNPRSTVXY]\d[ABCEGHJ-NPRSTV-Z][ ]?\d[ABCEGHJ-NPRSTV-Z]\d$/i,
+  DE: fiveDigit,
+  JP: /^\d{3}-?\d{4}$/,
+  FR: /^\d{2}[ ]?\d{3}$/,
+  AU: fourDigit,
+  IT: fiveDigit,
+  CH: fourDigit,
+  AT: fourDigit,
+  ES: fiveDigit,
+  NL: /^\d{4}[ ]?[A-Z]{2}$/i,
+  BE: fourDigit,
+  DK: fourDigit,
+  SE: /^\d{3}[ ]?\d{2}$/,
+  NO: fourDigit,
+  BR: /^\d{5}-?\d{3}$/,
+  PT: /^\d{4}(-\d{3})?$/,
+  FI: fiveDigit,
+  KR: fiveDigit,
+  CN: sixDigit,
+  TW: /^\d{3}(\d{2})?$/,
+  SG: sixDigit,
+  IN: /^[1-9]\d{5}$/,
+  RU: sixDigit,
+  PL: /^\d{2}-\d{3}$/,
+  CZ: /^\d{3}[ ]?\d{2}$/,
+  HU: fourDigit,
+  RO: sixDigit,
+  BG: fourDigit,
+  HR: fiveDigit,
+  SK: /^\d{3}[ ]?\d{2}$/,
+  SI: fourDigit,
+  TR: fiveDigit,
+  IL: fiveDigit,
+  ZA: fourDigit,
+  MX: fiveDigit,
+  AR: /^([A-HJ-NP-Z])?\d{4}([A-Z]{3})?$/i,
+  CL: /^\d{7}$/,
+  CO: sixDigit,
+  NZ: fourDigit,
+  MY: fiveDigit,
+  TH: fiveDigit,
+  PH: fourDigit,
+  ID: fiveDigit,
+  VN: sixDigit,
+};
+
+export function validatePostalCode(postalCode: string, country?: string): boolean {
+  if (!postalCode) return true;
+  try {
+    const countryUpper = country?.toUpperCase();
+    if (!countryUpper) return false;
+    const pattern = postalCodePatterns[countryUpper];
+    return !pattern || pattern.test(postalCode);
+  } catch {
+    return false;
+  }
+}
+
+// ── Field Validation (custom rules from metadata) ──
+
+export function getFieldValidation(
+  fieldName: string,
+  validations?: Record<string, { pattern?: string; pattern_message?: Record<string, string> }>,
+  locale: string = 'en'
+): { pattern?: { value: RegExp; message: string } } {
+  if (!validations || !validations[fieldName]) return {};
+  const fieldValidation = validations[fieldName];
+  const rules: { pattern?: { value: RegExp; message: string } } = {};
+  if (fieldValidation.pattern) {
+    rules.pattern = {
+      value: new RegExp(fieldValidation.pattern),
+      message: fieldValidation.pattern_message?.[locale] || 'Invalid format',
+    };
+  }
+  return rules;
+}
+
+// ── Phone Validation (google-libphonenumber, matching payment-react) ──
+
+let phoneUtil: any = null;
+
+async function getPhoneUtil() {
+  if (!phoneUtil) {
+    const result = await import('google-libphonenumber');
+    const PhoneNumberUtil = (result.default || result)?.PhoneNumberUtil;
+    if (!PhoneNumberUtil) {
+      throw new Error('PhoneNumberUtil not found');
+    }
+    phoneUtil = PhoneNumberUtil.getInstance();
+  }
+  return phoneUtil;
+}
+
+const PHONE_REGEX_FALLBACK = /^[+]?[(]?[0-9]{3}[)]?[-\s.]?[0-9]{3}[-\s.]?[0-9]{4,6}$/im;
+
+export async function validatePhone(phone: string): Promise<boolean> {
+  if (!phone || phone.trim() === '') return false;
+  try {
+    const util = await getPhoneUtil();
+    const parsed = util.parseAndKeepRawInput(phone);
+    return util.isValidNumber(parsed);
+  } catch {
+    // Fallback to regex if google-libphonenumber fails to load
+    return PHONE_REGEX_FALLBACK.test(phone);
+  }
+}
+
+// ── Email Validation ──
+
+export function validateEmail(email: string): boolean {
+  if (!email || email.trim() === '') return false;
+  return isEmail(email);
+}
+
+// ── Form Validation (pure function extracted from react/src/payment/form/index.tsx:617-713) ──
+
+export interface ValidateFormOptions {
+  phoneEnabled: boolean;
+  addressMode: 'auto' | 'required' | null;
+  fieldValidation?: Record<string, { pattern?: string; pattern_message?: Record<string, string> }>;
+  locale?: string;
+}
+
+export interface FormErrors {
+  customer_name?: string;
+  customer_email?: string;
+  customer_phone?: string;
+  'billing_address.country'?: string;
+  'billing_address.state'?: string;
+  'billing_address.line1'?: string;
+  'billing_address.city'?: string;
+  'billing_address.postal_code'?: string;
+  [key: string]: string | undefined;
+}
+
+export async function validateForm(
+  values: CheckoutFormData | null,
+  options: ValidateFormOptions
+): Promise<{ valid: boolean; errors: FormErrors }> {
+  const errors: FormErrors = {};
+  const { phoneEnabled, addressMode, fieldValidation, locale = 'en' } = options;
+
+  if (!values) {
+    return { valid: false, errors: { customer_name: 'Required' } };
+  }
+
+  // Name
+  const customerName = values.customer_name;
+  if (!customerName || customerName.trim() === '') {
+    errors.customer_name = 'Required';
+  } else {
+    const nameRule = getFieldValidation('customer_name', fieldValidation, locale);
+    if (nameRule.pattern && !nameRule.pattern.value.test(customerName)) {
+      errors.customer_name = nameRule.pattern.message;
+    }
+  }
+
+  // Email
+  const customerEmail = values.customer_email;
+  if (!customerEmail || !validateEmail(customerEmail)) {
+    errors.customer_email = !customerEmail ? 'Required' : 'Invalid email';
+  } else {
+    const emailRule = getFieldValidation('customer_email', fieldValidation, locale);
+    if (emailRule.pattern && !emailRule.pattern.value.test(customerEmail)) {
+      errors.customer_email = emailRule.pattern.message;
+    }
+  }
+
+  // Phone
+  if (phoneEnabled) {
+    const customerPhone = values.customer_phone;
+    if (!customerPhone || customerPhone.trim() === '') {
+      errors.customer_phone = 'Required';
+    } else if (!(await validatePhone(customerPhone))) {
+      errors.customer_phone = 'Invalid phone number';
+    } else {
+      const phoneRule = getFieldValidation('customer_phone', fieldValidation, locale);
+      if (phoneRule.pattern && !phoneRule.pattern.value.test(customerPhone)) {
+        errors.customer_phone = phoneRule.pattern.message;
+      }
+    }
+  }
+
+  // Billing address
+  const billingAddress = values.billing_address;
+  const postalCode = billingAddress?.postal_code;
+  const country = billingAddress?.country;
+  const state = billingAddress?.state;
+  const line1 = billingAddress?.line1;
+  const city = billingAddress?.city;
+
+  // Postal code & state are required in both auto and required modes (matching V1 behavior)
+  if (!postalCode) {
+    errors['billing_address.postal_code'] = 'Required';
+  } else if (!validatePostalCode(postalCode, country)) {
+    errors['billing_address.postal_code'] = 'Invalid postal code';
+  } else {
+    const postalRule = getFieldValidation('billing_address.postal_code', fieldValidation, locale);
+    if (postalRule.pattern && !postalRule.pattern.value.test(postalCode)) {
+      errors['billing_address.postal_code'] = postalRule.pattern.message;
+    }
+  }
+
+  if (!state) {
+    errors['billing_address.state'] = 'Required';
+  } else {
+    const stateRule = getFieldValidation('billing_address.state', fieldValidation, locale);
+    if (stateRule.pattern && !stateRule.pattern.value.test(state)) {
+      errors['billing_address.state'] = stateRule.pattern.message;
+    }
+  }
+
+  // Full address fields required only in 'required' mode
+  if (addressMode === 'required') {
+    if (!country) errors['billing_address.country'] = 'Required';
+    if (!line1) {
+      errors['billing_address.line1'] = 'Required';
+    } else {
+      const line1Rule = getFieldValidation('billing_address.line1', fieldValidation, locale);
+      if (line1Rule.pattern && !line1Rule.pattern.value.test(line1)) {
+        errors['billing_address.line1'] = line1Rule.pattern.message;
+      }
+    }
+    if (!city) {
+      errors['billing_address.city'] = 'Required';
+    } else {
+      const cityRule = getFieldValidation('billing_address.city', fieldValidation, locale);
+      if (cityRule.pattern && !cityRule.pattern.value.test(city)) {
+        errors['billing_address.city'] = cityRule.pattern.message;
+      }
+    }
+  }
+
+  return {
+    valid: Object.keys(errors).length === 0,
+    errors,
+  };
+}