payment-kit 1.24.4 → 1.25.0

package/api/src/index.ts

@@ -30,6 +30,7 @@ import { startCreditGrantQueue } from './queues/credit-grant';
 import { startReconciliationQueue } from './queues/credit-reconciliation';
 import { startDiscountStatusQueue } from './queues/discount-status';
 import { startEventQueue } from './queues/event';
+import { startExchangeRateHealthQueue } from './queues/exchange-rate-health';
 import { startInvoiceQueue } from './queues/invoice';
 import { startNotificationQueue } from './queues/notification';
 import { startPaymentQueue } from './queues/payment';
@@ -147,6 +148,8 @@ export const server = app.listen(port, (err?: any) => {
   startTokenTransferQueue().then(() => logger.info('token transfer queue started'));
   startReconciliationQueue().then(() => logger.info('credit reconciliation queue started'));
   startDiscountStatusQueue().then(() => logger.info('discount status queue started'));
+  startExchangeRateHealthQueue();
+  logger.info('exchange rate health queue started');
   startUploadBillingInfoListener();
 
   if (process.env.BLOCKLET_MODE === 'production') {

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

@@ -0,0 +1,21 @@
+/**
+ * Credit-related utility functions
+ * Extracted to break circular dependency between payment.ts, session.ts, and subscription.ts
+ */
+import type { TLineItemExpanded, TPriceExpanded } from '../store/models';
+import { Price as TPrice } from '../store/models/price';
+
+export function isCreditMetered(price: TPrice | TPriceExpanded) {
+  return price.type === 'recurring' && price.recurring?.usage_type === 'metered' && !!price.recurring?.meter_id;
+}
+
+export function isCreditMeteredLineItems(lineItems: TLineItemExpanded[]) {
+  return lineItems.every((item) => item.price && isCreditMetered(item.price));
+}
+
+/**
+ * Get the effective price for a subscription item (upsell_price takes precedence)
+ */
+export function getSubscriptionItemPrice(item: TLineItemExpanded) {
+  return item.upsell_price || item.price;
+}

package/api/src/libs/discount/discount.ts

@@ -11,6 +11,9 @@ const getItemsTotalAmount = (lineItems: TLineItemExpanded[], currencyId: string,
 
   lineItems.forEach((item) => {
     const price = item.upsell_price || item.price;
+
+    const dynamicAmount =
+      price?.pricing_type === 'dynamic' ? (item as any).custom_amount || (item as any).quoted_amount : undefined;
     const unitPrice = getPriceUintAmountByCurrency(price, currencyId);
 
     if (price?.type === 'recurring') {
@@ -22,6 +25,11 @@ const getItemsTotalAmount = (lineItems: TLineItemExpanded[], currencyId: string,
       }
     }
 
+    if (dynamicAmount) {
+      totalUnitPrice = totalUnitPrice.add(new BN(dynamicAmount));
+      return;
+    }
+
     totalUnitPrice = totalUnitPrice.add(new BN(unitPrice).mul(new BN(item.quantity)));
   });
   return totalUnitPrice.toString();
@@ -29,6 +37,11 @@ const getItemsTotalAmount = (lineItems: TLineItemExpanded[], currencyId: string,
 
 const getItemAmount = (item: TLineItemExpanded, currencyId: string) => {
   const price = item.upsell_price || item.price;
+  const dynamicAmount =
+    price?.pricing_type === 'dynamic' ? (item as any).custom_amount || (item as any).quoted_amount : undefined;
+  if (dynamicAmount) {
+    return new BN(dynamicAmount).toString();
+  }
   const unitPrice = getPriceUintAmountByCurrency(price, currencyId);
   return new BN(unitPrice).mul(new BN(item.quantity)).toString();
 };

package/api/src/libs/env.ts

@@ -18,6 +18,7 @@ export const depositVaultCronTime: string = process.env.DEPOSIT_VAULT_CRON_TIME
 export const creditConsumptionCronTime: string = process.env.CREDIT_CONSUMPTION_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
 export const vendorStatusCheckCronTime: string = process.env.VENDOR_STATUS_CHECK_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
 export const vendorReturnScanCronTime: string = process.env.VENDOR_RETURN_SCAN_CRON_TIME || '0 */10 * * * *'; // 默认每 10 min 执行一次
+export const quoteCleanupCronTime: string = process.env.QUOTE_CLEANUP_CRON_TIME || '0 0 2 * * *'; // 默认每天凌晨 2 点执行一次
 export const vendorTimeoutMinutes: number = process.env.VENDOR_TIMEOUT_MINUTES
   ? +process.env.VENDOR_TIMEOUT_MINUTES
   : 10; // 默认 10 分钟超时
@@ -46,6 +47,10 @@ export const updateDataConcurrency: number = process.env.UPDATE_DATA_CONCURRENCY
   ? +process.env.UPDATE_DATA_CONCURRENCY
   : 5; // 默认并发数为 5
 
+export const exchangeRateCacheTTLSeconds: number = process.env.EXCHANGE_RATE_CACHE_TTL_SECONDS
+  ? +process.env.EXCHANGE_RATE_CACHE_TTL_SECONDS
+  : 10 * 60;
+
 // System-level maximum pending amount limit (in token format, e.g., "10")
 // Default is 0 (disabled). Set PAYMENT_KIT_MAX_PENDING_AMOUNT to enable this limit.
 export const systemMaxPendingAmount: number = process.env.PAYMENT_KIT_MAX_PENDING_AMOUNT

package/api/src/libs/error.ts

@@ -1,3 +1,4 @@
+/* eslint-disable max-classes-per-file */
 export default class CustomError extends Error {
   code: string;
 
@@ -11,3 +12,16 @@ export default class CustomError extends Error {
     this.code = code;
   }
 }
+
+/**
+ * NonRetryableError - Used for errors that should not be retried
+ * Typical cases: configuration errors, missing data, validation failures
+ */
+export class NonRetryableError extends CustomError {
+  nonRetryable: boolean = true;
+
+  constructor(code: string, message: string) {
+    super(code, message);
+    this.name = 'NonRetryableError';
+  }
+}

package/api/src/libs/exchange-rate/coingecko-provider.ts

@@ -0,0 +1,193 @@
+import axios from 'axios';
+import BigNumber from 'bignumber.js';
+
+import logger from '../logger';
+import { getTokenInfo } from './token-address-mapping';
+import type { ExchangeRateData, IExchangeRateProvider, ProviderConfig } from './types';
+import { SymbolNotSupportedError } from './types';
+
+/**
+ * CoinGecko Exchange Rate Provider
+ *
+ * Fetches token prices from CoinGecko API
+ * Uses the /simple/token_price/ethereum endpoint which supports contract addresses
+ * Uses Ethereum mainnet (chainId: 1) contract addresses
+ */
+export class CoinGeckoProvider implements IExchangeRateProvider {
+  public readonly name = 'coingecko';
+
+  private baseUrl: string;
+  private timeout: number;
+  private apiKey?: string;
+  private zeroAddress = '0x0000000000000000000000000000000000000000';
+
+  constructor(config: ProviderConfig = {}) {
+    this.baseUrl = config.base_url || 'https://api.coingecko.com/api/v3';
+    this.timeout = config.timeout || 10000; // 10 seconds default
+    this.apiKey = config.api_key;
+  }
+
+  async fetch(symbol: string): Promise<ExchangeRateData> {
+    try {
+      // Get token info from mapping
+      const tokenInfo = getTokenInfo(symbol);
+      if (!tokenInfo) {
+        // Symbol not in mapping - this is a data issue, not a service issue
+        throw new SymbolNotSupportedError(symbol, this.name);
+      }
+
+      const { address, coinGeckoId } = tokenInfo;
+      const addressLower = address?.toLowerCase();
+      const useTokenPriceEndpoint = !!address && addressLower !== this.zeroAddress;
+
+      if (!useTokenPriceEndpoint) {
+        return await this.fetchByCoinId(symbol, coinGeckoId);
+      }
+
+      // Use contract address endpoint for Ethereum tokens
+      const url = `${this.baseUrl}/simple/token_price/ethereum`;
+      const params: any = {
+        contract_addresses: address,
+        // IMPORTANT: Must be 'usd' because the entire dynamic pricing system uses USD as the sole base currency
+        // All exchange rates are defined as "USD per Token" (e.g., 1 ABT = 0.258 USD)
+        // This is a P0 architectural constraint - see plan.md "USD 是唯一价值锚点"
+        vs_currencies: 'usd',
+        include_last_updated_at: true,
+      };
+
+      // Add API key if configured (for rate limit increase)
+      if (this.apiKey) {
+        params.x_cg_pro_api_key = this.apiKey;
+      }
+
+      logger.debug('Fetching exchange rate from CoinGecko', { symbol, address, url });
+
+      const response = await axios.get(url, {
+        params,
+        timeout: this.timeout,
+        headers: {
+          'User-Agent': 'PaymentKit/1.0',
+          Accept: 'application/json',
+        },
+      });
+
+      if (!response.data || typeof response.data !== 'object') {
+        throw new Error('Invalid response format from CoinGecko');
+      }
+
+      // CoinGecko returns data keyed by lowercase address
+      const tokenData = response.data[addressLower];
+
+      if (!tokenData) {
+        if (coinGeckoId) {
+          return await this.fetchByCoinId(symbol, coinGeckoId);
+        }
+        throw new SymbolNotSupportedError(symbol, this.name);
+      }
+
+      return this.buildRateResult(tokenData.usd, tokenData.last_updated_at, tokenInfo);
+    } catch (error: any) {
+      // Log the error
+      logger.error('Failed to fetch exchange rate from CoinGecko', {
+        symbol,
+        error: error.message,
+        response: error.response?.data,
+      });
+
+      // Determine error type and throw appropriate error
+      // Re-throw SymbolNotSupportedError as-is (don't wrap it)
+      if (error instanceof SymbolNotSupportedError) {
+        throw error;
+      }
+      if (error.response) {
+        if (error.response.status === 404) {
+          throw new SymbolNotSupportedError(symbol, this.name);
+        } else if (error.response.status === 429) {
+          throw new Error('CoinGecko rate limit exceeded');
+        } else if (error.response.status >= 500) {
+          throw new Error(`CoinGecko server error: ${error.response.status}`);
+        } else {
+          throw new Error(`CoinGecko request failed: ${error.response.status}`);
+        }
+      } else if (error.code === 'ECONNABORTED') {
+        throw new Error(`CoinGecko request timeout after ${this.timeout}ms`);
+      } else if (error.code === 'ENOTFOUND' || error.code === 'ECONNREFUSED') {
+        throw new Error(`Cannot connect to CoinGecko: ${error.message}`);
+      } else {
+        throw new Error(`CoinGecko fetch error: ${error.message}`);
+      }
+    }
+  }
+
+  private async fetchByCoinId(symbol: string, coinGeckoId?: string): Promise<ExchangeRateData> {
+    if (!coinGeckoId) {
+      throw new SymbolNotSupportedError(symbol, this.name, `CoinGecko ID is missing for ${symbol}`);
+    }
+
+    const url = `${this.baseUrl}/simple/price`;
+    const params: any = {
+      ids: coinGeckoId,
+      vs_currencies: 'usd',
+      include_last_updated_at: true,
+    };
+
+    if (this.apiKey) {
+      params.x_cg_pro_api_key = this.apiKey;
+    }
+
+    logger.debug('Fetching exchange rate from CoinGecko by coin id', { symbol, coinGeckoId, url });
+
+    const response = await axios.get(url, {
+      params,
+      timeout: this.timeout,
+      headers: {
+        'User-Agent': 'PaymentKit/1.0',
+        Accept: 'application/json',
+      },
+    });
+
+    if (!response.data || typeof response.data !== 'object') {
+      throw new Error('Invalid response format from CoinGecko');
+    }
+
+    const tokenData = response.data[coinGeckoId];
+    if (!tokenData) {
+      throw new SymbolNotSupportedError(symbol, this.name);
+    }
+
+    const tokenInfo = getTokenInfo(symbol);
+    if (!tokenInfo) {
+      throw new SymbolNotSupportedError(symbol, this.name);
+    }
+
+    return this.buildRateResult(tokenData.usd, tokenData.last_updated_at, tokenInfo);
+  }
+
+  private buildRateResult(
+    usdPrice: number,
+    lastUpdatedAt: number | undefined,
+    tokenInfo: ReturnType<typeof getTokenInfo>
+  ): ExchangeRateData {
+    if (!usdPrice || typeof usdPrice !== 'number') {
+      throw new Error(`No valid USD price found for ${tokenInfo?.symbol || 'token'}`);
+    }
+
+    const rate = new BigNumber(usdPrice);
+    if (rate.lte(0) || !rate.isFinite()) {
+      throw new Error(`Invalid price value: ${usdPrice}`);
+    }
+
+    const timestampMs = lastUpdatedAt ? lastUpdatedAt * 1000 : Date.now();
+
+    return {
+      rate: rate.toString(),
+      timestamp_ms: timestampMs,
+      metadata: {
+        source: 'coingecko',
+        address: tokenInfo?.address,
+        symbol: tokenInfo?.symbol,
+        coin_id: tokenInfo?.coinGeckoId,
+      },
+    };
+  }
+}

package/api/src/libs/exchange-rate/coinmarketcap-provider.ts

@@ -0,0 +1,180 @@
+import axios from 'axios';
+import BigNumber from 'bignumber.js';
+
+import logger from '../logger';
+import type { ExchangeRateData, IExchangeRateProvider, ProviderConfig } from './types';
+import { SymbolNotSupportedError } from './types';
+
+/**
+ * CoinMarketCap Exchange Rate Provider
+ *
+ * Fetches token prices from CoinMarketCap API
+ * This is the upstream data source for token-data service
+ *
+ * API Documentation: https://coinmarketcap.com/api/documentation/v1/
+ */
+export class CoinMarketCapProvider implements IExchangeRateProvider {
+  public readonly name = 'coinmarketcap';
+
+  private baseUrl: string;
+  private timeout: number;
+  private apiKey?: string;
+
+  constructor(config: ProviderConfig = {}) {
+    this.baseUrl = config.base_url || 'https://pro-api.coinmarketcap.com/v1';
+    this.timeout = config.timeout || 10000; // 10 seconds default
+    this.apiKey = config.api_key;
+
+    if (!this.apiKey) {
+      logger.warn('CoinMarketCap API key not configured. Please set api_key in provider config.');
+    }
+  }
+
+  async fetch(symbol: string): Promise<ExchangeRateData> {
+    if (!this.apiKey) {
+      throw new Error('CoinMarketCap API key is required. Please configure api_key in provider settings.');
+    }
+
+    try {
+      const url = `${this.baseUrl}/cryptocurrency/quotes/latest`;
+
+      logger.debug('Fetching exchange rate from CoinMarketCap', { symbol, url });
+
+      const response = await axios.get(url, {
+        params: {
+          symbol: symbol.toUpperCase(),
+          convert: 'USD',
+        },
+        timeout: this.timeout,
+        headers: {
+          'X-CMC_PRO_API_KEY': this.apiKey,
+          Accept: 'application/json',
+          'User-Agent': 'PaymentKit/1.0',
+        },
+      });
+
+      if (!response.data || typeof response.data !== 'object') {
+        throw new Error('Invalid response format from CoinMarketCap');
+      }
+
+      const { data, status } = response.data;
+
+      // Check API status
+      if (status?.error_code !== 0) {
+        throw new Error(`CoinMarketCap API error: ${status?.error_message || 'Unknown error'}`);
+      }
+
+      // Get token data
+      const tokenData = data?.[symbol.toUpperCase()];
+      if (!tokenData) {
+        // Symbol not found - this is a data issue, not a service issue
+        throw new SymbolNotSupportedError(symbol, this.name);
+      }
+
+      // Extract USD price from quote
+      const quote = tokenData.quote?.USD;
+      if (!quote) {
+        throw new Error(`No USD quote found for ${symbol}`);
+      }
+
+      const usdPrice = quote.price;
+      if (!usdPrice || typeof usdPrice !== 'number') {
+        throw new Error(`No valid USD price found for ${symbol}`);
+      }
+
+      // Validate price is positive
+      const rate = new BigNumber(usdPrice);
+      if (rate.lte(0) || !rate.isFinite()) {
+        throw new Error(`Invalid price value: ${usdPrice}`);
+      }
+
+      // Get timestamp
+      const timestampMs = quote.last_updated ? new Date(quote.last_updated).getTime() : Date.now();
+
+      return {
+        rate: rate.toString(),
+        timestamp_ms: timestampMs,
+        metadata: {
+          source: 'coinmarketcap',
+          symbol: tokenData.symbol,
+          name: tokenData.name,
+          cmc_id: tokenData.id,
+          cmc_rank: tokenData.cmc_rank,
+          market_cap: quote.market_cap,
+          volume_24h: quote.volume_24h,
+          percent_change_24h: quote.percent_change_24h,
+        },
+      };
+    } catch (error: any) {
+      // Log the error
+      logger.error('Failed to fetch exchange rate from CoinMarketCap', {
+        symbol,
+        error: error.message,
+        response: error.response?.data,
+      });
+
+      // Determine error type and throw appropriate error
+      if (error.response) {
+        const { status, data } = error.response;
+
+        // Check for CoinMarketCap specific error codes
+        if (data?.status?.error_code) {
+          const errorCode = data.status.error_code;
+          const errorMessage = data.status.error_message;
+
+          switch (errorCode) {
+            case 1001: // API key invalid
+              throw new Error('CoinMarketCap API key is invalid');
+            case 1002: // API key missing
+              throw new Error('CoinMarketCap API key is missing');
+            case 1003: // API key plan rate limit
+              throw new Error('CoinMarketCap API rate limit exceeded for your plan');
+            case 1004: // API key plan payment overdue
+              throw new Error('CoinMarketCap API key payment overdue');
+            case 1005: // API key plan payment failed
+              throw new Error('CoinMarketCap API key payment failed');
+            case 1006: // API key plan upgrade required
+              throw new Error('CoinMarketCap API plan upgrade required');
+            case 1007: // API key disabled
+              throw new Error('CoinMarketCap API key has been disabled');
+            case 1008: // API key plan minute rate limit
+              throw new Error('CoinMarketCap API minute rate limit exceeded');
+            case 1009: // API key plan daily rate limit
+              throw new Error('CoinMarketCap API daily rate limit exceeded');
+            case 1010: // API key plan monthly rate limit
+              throw new Error('CoinMarketCap API monthly rate limit exceeded');
+            case 400: // Bad Request
+              throw new Error(`CoinMarketCap bad request: ${errorMessage}`);
+            case 401: // Unauthorized
+              throw new Error('CoinMarketCap API authentication failed');
+            case 403: // Forbidden
+              throw new Error('CoinMarketCap API access forbidden');
+            case 429: // Too Many Requests
+              throw new Error('CoinMarketCap rate limit exceeded');
+            case 500: // Internal Server Error
+              throw new Error('CoinMarketCap server error');
+            default:
+              throw new Error(`CoinMarketCap API error (${errorCode}): ${errorMessage}`);
+          }
+        }
+
+        // Generic HTTP error handling
+        if (status === 404) {
+          throw new SymbolNotSupportedError(symbol, this.name);
+        } else if (status === 429) {
+          throw new Error('CoinMarketCap rate limit exceeded');
+        } else if (status >= 500) {
+          throw new Error(`CoinMarketCap server error: ${status}`);
+        } else {
+          throw new Error(`CoinMarketCap request failed: ${status}`);
+        }
+      } else if (error.code === 'ECONNABORTED') {
+        throw new Error(`CoinMarketCap request timeout after ${this.timeout}ms`);
+      } else if (error.code === 'ENOTFOUND' || error.code === 'ECONNREFUSED') {
+        throw new Error(`Cannot connect to CoinMarketCap: ${error.message}`);
+      } else {
+        throw new Error(`CoinMarketCap fetch error: ${error.message}`);
+      }
+    }
+  }
+}

package/api/src/libs/exchange-rate/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './token-data-provider';
+export * from './service';
+export * from './validator';
+export * from './token-address-mapping';