payment-kit 1.24.3 → 1.25.0

package/api/src/libs/invoice-quote.ts

@@ -0,0 +1,158 @@
+import { Price, PaymentCurrency } from '../store/models';
+import { getQuoteService, type RateResult } from './quote-service';
+import { getExchangeRateService } from './exchange-rate';
+import logger from './logger';
+
+export interface InvoiceItemInput {
+  price_id: string;
+  quantity: number;
+  amount: string;
+  subscription_item_id?: string;
+  description: string;
+  period?: { start: number; end: number };
+  metadata?: Record<string, any>;
+  discountable?: boolean;
+  discount_amounts?: any[];
+}
+
+export interface InvoiceItemWithQuote extends InvoiceItemInput {
+  quote_id?: string;
+}
+
+/**
+ * Generate quotes for dynamic pricing invoice items
+ * This function checks each invoice item's price and generates a quote if it uses dynamic pricing
+ */
+export async function generateQuotesForInvoiceItems(params: {
+  invoiceId: string;
+  items: InvoiceItemInput[];
+  currencyId: string;
+}): Promise<InvoiceItemWithQuote[]> {
+  const { invoiceId, items, currencyId } = params;
+
+  if (!items || items.length === 0) {
+    return [];
+  }
+
+  // Load currency with payment method
+  const currency = await PaymentCurrency.findByPk(currencyId, {
+    include: [{ association: 'payment_method' }],
+  });
+  if (!currency) {
+    throw new Error(`Currency ${currencyId} not found`);
+  }
+
+  // Get exchange rate once for all dynamic prices (for efficiency)
+  // For ArcBlock payment method, always use ABT for exchange rate
+  const exchangeRateService = getExchangeRateService();
+  const rateSymbol = (currency as any).payment_method?.type === 'arcblock' ? 'ABT' : currency.symbol;
+  let rateResult: RateResult | null = null;
+
+  const quoteService = getQuoteService();
+  const enrichedItems: InvoiceItemWithQuote[] = [];
+
+  // Note: Sequential processing is intentional here
+  // 1. Prices may not exist (early continue)
+  // 2. Exchange rate is fetched once and reused (rateResult)
+  // 3. Quote failures must be handled immediately (P0 critical)
+  // eslint-disable-next-line no-restricted-syntax
+  for (const item of items) {
+    // eslint-disable-next-line no-await-in-loop
+    const price = await Price.findByPk(item.price_id);
+    if (!price) {
+      logger.warn('Price not found for invoice item', { priceId: item.price_id, invoiceId });
+      enrichedItems.push(item);
+      // eslint-disable-next-line no-continue
+      continue;
+    }
+
+    // Skip items with zero or negative quantity (free trial, metered billing outside billing period)
+    // These items don't require quote generation
+    if (item.quantity <= 0) {
+      enrichedItems.push(item);
+      // eslint-disable-next-line no-continue
+      continue;
+    }
+
+    // Check if price uses dynamic pricing
+    if (price.pricing_type !== 'dynamic') {
+      // Fixed pricing - use item amount as-is
+      enrichedItems.push(item);
+      // eslint-disable-next-line no-continue
+      continue;
+    }
+
+    // Dynamic pricing - generate quote
+    try {
+      // Get exchange rate if not already fetched
+      if (!rateResult) {
+        // eslint-disable-next-line no-await-in-loop
+        rateResult = await exchangeRateService.getRate(rateSymbol);
+      }
+
+      // Create quote for this invoice item
+      // eslint-disable-next-line no-await-in-loop
+      const { quote } = await quoteService.createQuoteWithRate({
+        price_id: item.price_id,
+        invoice_id: invoiceId,
+        target_currency_id: currencyId,
+        quantity: item.quantity,
+        rateResult,
+      });
+
+      logger.info('Generated quote for invoice item', {
+        invoiceId,
+        priceId: item.price_id,
+        quoteId: quote.id,
+        quotedAmount: quote.quoted_amount,
+      });
+
+      // Update item with quote info
+      // Only store quote_id in metadata - full quote info is attached dynamically when querying
+      // See: invoices.ts attachQuoteMetadataToLines()
+      enrichedItems.push({
+        ...item,
+        amount: quote.quoted_amount,
+        quote_id: quote.id,
+        metadata: {
+          ...item.metadata,
+          quote_id: quote.id,
+        },
+      });
+    } catch (error: any) {
+      logger.error('Failed to generate quote for invoice item', {
+        invoiceId,
+        priceId: item.price_id,
+        error: error.message,
+      });
+
+      // P0 CRITICAL: Do not allow fallback for dynamic pricing
+      // Quote is the only source of truth for dynamic pricing amounts
+      // If quote generation fails, the invoice creation must fail
+      throw new Error(`Failed to generate quote for dynamic price ${item.price_id}: ${error.message}`);
+    }
+  }
+
+  return enrichedItems;
+}
+
+/**
+ * Check if any invoice items use dynamic pricing
+ */
+export async function hasDynamicPricingItems(items: InvoiceItemInput[]): Promise<boolean> {
+  if (!items || items.length === 0) {
+    return false;
+  }
+
+  const priceIds = items.map((item) => item.price_id).filter(Boolean);
+  if (priceIds.length === 0) {
+    return false;
+  }
+
+  const prices = await Price.findAll({
+    where: { id: priceIds },
+    attributes: ['id', 'pricing_type'],
+  });
+
+  return prices.some((price) => price.pricing_type === 'dynamic');
+}

package/api/src/libs/invoice.ts

@@ -14,6 +14,7 @@ import {
   PaymentMethod,
   PaymentSettings,
   Price,
+  PriceQuote,
   Product,
   Refund,
   SetupIntent,
@@ -42,6 +43,10 @@ import { ensureOverdraftProtectionPrice } from './overdraft-protection';
 import { CHARGE_SUPPORTED_CHAIN_TYPES } from './constants';
 import { emitAsync } from './event';
 import { getPriceUintAmountByCurrency } from './price';
+import { generateQuotesForInvoiceItems } from './invoice-quote';
+import { getExchangeRateService, getExchangeRateSymbol } from './exchange-rate';
+import { getQuoteService } from './quote-service';
+import type { ChainType } from '../store/models';
 
 export function getCustomerInvoicePageUrl({
   invoiceId,
@@ -121,6 +126,27 @@ export async function getInvoiceShouldPayTotal(invoice: Invoice) {
     const subscriptionItems = await SubscriptionItem.findAll({
       where: { subscription_id: subscription.id },
     });
+    const invoiceItems = await InvoiceItem.findAll({
+      where: { invoice_id: invoice.id },
+    });
+    const invoiceQuoteIds = invoiceItems
+      .map((item) => item.metadata?.quote_id)
+      .filter((id): id is string => typeof id === 'string' && id.length > 0);
+    const invoiceQuotes = invoiceQuoteIds.length ? await PriceQuote.findAll({ where: { id: invoiceQuoteIds } }) : [];
+    const invoiceQuotesById = new Map(invoiceQuotes.map((quote) => [quote.id, quote]));
+    const invoiceQuoteBySubscriptionItemId = new Map<string, { quotedAmount?: string; amount?: string }>();
+    invoiceItems.forEach((item) => {
+      if (!item.subscription_item_id) {
+        return;
+      }
+      const quoteId = typeof item.metadata?.quote_id === 'string' ? item.metadata?.quote_id : undefined;
+      const quote = quoteId ? invoiceQuotesById.get(quoteId) : undefined;
+      const quotedAmount = quote?.quoted_amount || (item.metadata as any)?.quote?.quoted_amount;
+      invoiceQuoteBySubscriptionItemId.set(item.subscription_item_id, {
+        quotedAmount,
+        amount: item.amount,
+      });
+    });
 
     let expandedItems = await Price.expand(
       subscriptionItems.map((x) => ({ id: x.id, price_id: x.price_id, quantity: x.quantity })),
@@ -163,6 +189,28 @@ export async function getInvoiceShouldPayTotal(invoice: Invoice) {
       })
     );
 
+    if (invoiceQuoteBySubscriptionItemId.size > 0) {
+      expandedItems = expandedItems.map((item: any) => {
+        const { price } = item;
+        if (price?.pricing_type !== 'dynamic') {
+          return item;
+        }
+        const quoteInfo = invoiceQuoteBySubscriptionItemId.get(item.id);
+        if (!quoteInfo) {
+          return item;
+        }
+        const quotedAmount = quoteInfo.quotedAmount || quoteInfo.amount;
+        if (!quotedAmount) {
+          return item;
+        }
+        return {
+          ...item,
+          custom_amount: quotedAmount,
+          quoted_amount: quotedAmount,
+        };
+      });
+    }
+
     const baseAmount = getSubscriptionCycleAmount(expandedItems, subscription.currency_id);
     let shouldPayTotal = baseAmount?.total || invoice.total;
 
@@ -431,6 +479,8 @@ type BaseInvoiceProps = {
   ending_token_balance?: Record<string, string>;
   subtotal_excluding_tax?: string;
   collection_method?: 'charge_automatically' | 'send_invoice';
+  id?: string;
+  quote_id?: string;
 };
 
 async function createInvoiceWithItems(props: BaseInvoiceProps): Promise<{
@@ -519,9 +569,19 @@ async function createInvoiceWithItems(props: BaseInvoiceProps): Promise<{
   if (!itemsData) {
     return { invoice, items: [] };
   }
+
+  // Generate quotes for dynamic pricing items (subscription invoices)
+  const enrichedItemsData = subscription
+    ? await generateQuotesForInvoiceItems({
+        invoiceId: invoice.id,
+        items: itemsData,
+        currencyId,
+      })
+    : itemsData;
+
   // create invoice items
   const items = await Promise.all(
-    itemsData.map(async (item) => {
+    enrichedItemsData.map(async (item) => {
       // Match tax rate for this specific item
       let taxRateId: string | undefined;
       if (customer.address?.country && item.price_id) {
@@ -565,7 +625,11 @@ async function createInvoiceWithItems(props: BaseInvoiceProps): Promise<{
           [],
         proration: false,
         proration_details: {},
-        metadata: item.metadata || {},
+        metadata: {
+          ...(item.metadata || {}),
+          // Include quote_id in metadata if it exists (for dynamic pricing)
+          ...((item as any).quote_id && { quote_id: (item as any).quote_id }),
+        },
       });
     })
   );
@@ -618,6 +682,7 @@ export async function ensureInvoiceAndItems({
 
   function getLineSetup(x: TLineItemExpanded) {
     const price = getSubscriptionItemPrice(x);
+
     if (price.type === 'recurring' && trialing) {
       return {
         price,
@@ -631,11 +696,13 @@ export async function ensureInvoiceAndItems({
       };
     }
 
+    const calculatedAmount =
+      x.custom_amount ||
+      new BN(getPriceUintAmountByCurrency(price, props.currency_id)).mul(new BN(x.quantity)).toString();
+
     return {
       price,
-      amount:
-        x.custom_amount ||
-        new BN(getPriceUintAmountByCurrency(price, props.currency_id)).mul(new BN(x.quantity)).toString(),
+      amount: calculatedAmount,
       description: price.product.name,
       period: undefined,
     };
@@ -665,6 +732,8 @@ export async function ensureInvoiceAndItems({
       // Discount fields from pre-calculated line items
       discountable: x.discountable || false,
       discount_amounts: x.discount_amounts || [],
+      // Pass quote_id for dynamic pricing audit trail
+      quote_id: (x as any).quote_id,
     };
   });
 
@@ -1361,7 +1430,74 @@ export const migrateSubscriptionPaymentMethodInvoice = async (
       const metadata: Record<string, any> = {
         prev_invoice_id: preInvoice.id,
       };
-      const amount = getSubscriptionCycleAmount(subscriptionItemsExpanded, newCurrencyId);
+
+      // For dynamic pricing items, we need to create new quotes with the new currency's exchange rate
+      const dynamicItems = subscriptionItemsExpanded.filter(
+        (item) => ((item as any)?.upsell_price || (item as any)?.price)?.pricing_type === 'dynamic'
+      );
+
+      let enrichedLineItems = subscriptionItemsExpanded;
+
+      if (dynamicItems.length > 0 && newPaymentMethod.type !== 'stripe') {
+        // Get fresh exchange rate for the new currency
+        const exchangeRateService = getExchangeRateService();
+        const quoteService = getQuoteService();
+        const rateSymbol = getExchangeRateSymbol(newPaymentCurrency.symbol, newPaymentMethod.type as ChainType);
+        const rateResult = await exchangeRateService.getRate(rateSymbol);
+
+        logger.info('Creating new quotes for dynamic pricing items during payment method change', {
+          subscriptionId: subscription.id,
+          newCurrencyId,
+          rateSymbol,
+          exchangeRate: rateResult.rate,
+          dynamicItemCount: dynamicItems.length,
+        });
+
+        // Create quotes for each dynamic pricing item
+        const quoteResults = await Promise.all(
+          dynamicItems.map(async (item) => {
+            const targetPrice: any = (item as any).upsell_price || (item as any).price;
+            const quoteResponse = await quoteService.createQuoteWithRate({
+              price_id: targetPrice.id,
+              target_currency_id: newCurrencyId,
+              quantity: item.quantity,
+              rateResult,
+            });
+            return { item, quoteResponse };
+          })
+        );
+
+        // Build a map for quick lookup
+        const quoteMap = new Map<string, (typeof quoteResults)[number]>();
+        quoteResults.forEach((result) => {
+          const targetPrice: any = (result.item as any).upsell_price || (result.item as any).price;
+          quoteMap.set(targetPrice.id, result);
+        });
+
+        // Enrich line items with quote information
+        enrichedLineItems = subscriptionItemsExpanded.map((item) => {
+          const targetPrice: any = (item as any).upsell_price || (item as any).price;
+          const hit = quoteMap.get(targetPrice?.id);
+          if (!hit) {
+            return item;
+          }
+          const { quoteResponse } = hit;
+          return {
+            ...item,
+            quote_id: quoteResponse.quote.id,
+            quoted_amount: quoteResponse.computed_unit_amount,
+            exchange_rate: quoteResponse.quote.exchange_rate,
+            rate_provider_name: quoteResponse.quote.rate_provider_name,
+            rate_provider_id: quoteResponse.quote.rate_provider_id,
+            custom_amount: quoteResponse.computed_unit_amount,
+          } as any;
+        });
+
+        // Store quote IDs in metadata for audit trail
+        metadata.quote_ids = quoteResults.map((r) => r.quoteResponse.quote.id);
+      }
+
+      const amount = getSubscriptionCycleAmount(enrichedLineItems, newCurrencyId);
 
       const { invoice } = await ensureInvoiceAndItems({
         customer,
@@ -1369,7 +1505,7 @@ export const migrateSubscriptionPaymentMethodInvoice = async (
         subscription,
         trialing: subscription.status === 'trialing',
         metered: false,
-        lineItems: subscriptionItemsExpanded,
+        lineItems: enrichedLineItems,
         applyCredit: false,
         props: {
           status: 'open',

package/api/src/libs/math-utils.ts

@@ -1,6 +1,52 @@
+import { BN } from '@ocap/util';
+
 export function trimDecimals(value: string | number, maxDecimals: number): string {
   const num = typeof value === 'number' ? value : parseFloat(value || '0');
   const multiplier = 10 ** maxDecimals;
   const rounded = Math.round(num * multiplier) / multiplier;
   return rounded.toString();
 }
+
+/**
+ * Limit precision of token amount in smallest unit to avoid meaningless precision
+ *
+ * For dynamic pricing, we limit precision to at most 10 decimal places in token amount.
+ * This is done by rounding to the nearest 10^(decimal - MAX_SIGNIFICANT_DECIMALS) unit.
+ *
+ * @param amountInSmallestUnit - Amount in token's smallest unit (e.g., wei for 18 decimals)
+ * @param tokenDecimals - Token decimal places (e.g., 18 for most ERC20 tokens)
+ * @param maxSignificantDecimals - Maximum significant decimal places to keep (default: 10)
+ * @returns Rounded amount with limited precision
+ *
+ * @example
+ * // Token with 18 decimals, amount = 1234567890123456789 wei (1.234567890123456789 tokens)
+ * // With maxSignificantDecimals = 10, we round to nearest 10^8 wei
+ * // Result: 1234567890200000000 wei (1.2345678902 tokens)
+ * limitTokenPrecision('1234567890123456789', 18, 10) // Returns BN of 1234567890200000000
+ */
+export function limitTokenPrecision(
+  amountInSmallestUnit: any, // BN type
+  tokenDecimals: number,
+  maxSignificantDecimals: number = 10
+): any {
+  const amount = new BN(amountInSmallestUnit.toString());
+
+  // If token has fewer decimals than our max, no need to limit
+  if (tokenDecimals <= maxSignificantDecimals) {
+    return amount;
+  }
+
+  // Calculate the precision unit to round to
+  // For example, if tokenDecimals = 18 and maxSignificantDecimals = 6
+  // precisionUnit = 10^(18-6) = 10^12
+  const precisionExponent = tokenDecimals - maxSignificantDecimals;
+  const precisionUnit = new BN(10).pow(new BN(precisionExponent));
+
+  // Round to nearest precisionUnit using ceiling division
+  // This ensures we don't undercharge the customer
+  // Formula: ceil(amount / precisionUnit) * precisionUnit
+  const quotient = amount.add(precisionUnit).sub(new BN(1)).div(precisionUnit);
+  const roundedAmount = quotient.mul(precisionUnit);
+
+  return roundedAmount;
+}

package/api/src/libs/notification/template/billing-discrepancy.ts

@@ -1,6 +1,5 @@
-import { fromUnitToToken } from '@ocap/util';
 import prettyMsI18n from 'pretty-ms-i18n';
-import { getOwnerDid } from '../../util';
+import { formatTokenAmount, getOwnerDid } from '../../util';
 import { translate } from '../../../locales';
 import { Invoice, PaymentCurrency, Subscription } from '../../../store/models';
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';
@@ -78,13 +77,13 @@ export class BillingDiscrepancyEmailTemplate implements BaseEmailTemplate<Billin
       locale,
     });
 
-    const billingAmount = `${fromUnitToToken(invoice.total, paymentCurrency.decimal)} ${paymentCurrency.symbol}`;
+    const billingAmount = `${formatTokenAmount(invoice.total, paymentCurrency.decimal)} ${paymentCurrency.symbol}`;
 
     const shouldPayTotal = await getInvoiceShouldPayTotal(invoice);
     if (shouldPayTotal === invoice.total) {
       throw new Error('should pay total is equal to invoice total, no need to send billing discrepancy notification');
     }
-    const shouldPayAmount = `${fromUnitToToken(shouldPayTotal, paymentCurrency.decimal)} ${paymentCurrency.symbol}`;
+    const shouldPayAmount = `${formatTokenAmount(shouldPayTotal, paymentCurrency.decimal)} ${paymentCurrency.symbol}`;
     return {
       userDid,
       locale,