payment-kit 1.23.8 → 1.23.10

package/api/src/libs/env.ts

@@ -43,6 +43,13 @@ export const sequelizeOptionsPoolIdle: number = process.env.SEQUELIZE_OPTIONS_PO
 export const updateDataConcurrency: number = process.env.UPDATE_DATA_CONCURRENCY
   ? +process.env.UPDATE_DATA_CONCURRENCY
   : 5; // 默认并发数为 5
+
+// 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
+  ? +process.env.PAYMENT_KIT_MAX_PENDING_AMOUNT
+  : 5;
+
 export default {
   ...env,
 };

package/api/src/queues/auto-recharge.ts

@@ -7,6 +7,7 @@ import {
   CreditGrant,
   Customer,
   Invoice,
+  Meter,
   PaymentCurrency,
   PaymentMethod,
   Price,
@@ -51,6 +52,22 @@ export async function processAutoRecharge(job: AutoRechargeJobData) {
     return;
   }
 
+  // Check if the associated meter is inactive
+  if (currency.type === 'credit') {
+    // Find meter by currency_id (meter.currency_id -> PaymentCurrency) or by metadata.meter_id
+    const meter = await Meter.findOne({
+      where: { currency_id: currencyId },
+    });
+    if (meter && meter.status === 'inactive') {
+      logger.info('Meter is inactive, skipping auto recharge', {
+        customerId,
+        currencyId,
+        meterId: meter.id,
+      });
+      return;
+    }
+  }
+
   // 1. find auto recharge config
   const config = (await AutoRechargeConfig.findOne({
     where: {
@@ -302,6 +319,24 @@ export async function checkAndTriggerAutoRecharge(
       currencyId,
       currentBalance,
     });
+
+    // Check if the associated meter is inactive
+    const currency = await PaymentCurrency.findByPk(currencyId);
+    if (currency?.type === 'credit') {
+      // Find meter by currency_id (meter.currency_id -> PaymentCurrency)
+      const meter = await Meter.findOne({
+        where: { currency_id: currencyId },
+      });
+      if (meter && meter.status === 'inactive') {
+        logger.info('Meter is inactive, skipping auto recharge check', {
+          customerId: customer.id,
+          currencyId,
+          meterId: meter.id,
+        });
+        return;
+      }
+    }
+
     const config = await AutoRechargeConfig.findOne({
       where: {
         customer_id: customer.id,

package/api/src/routes/auto-recharge-configs.ts

@@ -10,6 +10,7 @@ import {
   AutoRechargeConfig,
   Customer,
   EVMChainType,
+  Meter,
   PaymentCurrency,
   PaymentMethod,
   Price,
@@ -339,6 +340,16 @@ router.post('/submit', async (req, res) => {
     throw new CustomError(400, `Currency not found: ${value.currency_id}`);
   }
 
+  // Check if the associated meter is active when enabling auto-recharge
+  if (configData.enabled && currency.type === 'credit') {
+    const meter = await Meter.findOne({
+      where: { currency_id: value.currency_id },
+    });
+    if (meter && meter.status === 'inactive') {
+      throw new CustomError(400, 'Cannot enable auto top-up: the associated meter is inactive');
+    }
+  }
+
   if (currency.recharge_config?.base_price_id && currency.recharge_config?.base_price_id !== value.price_id) {
     throw new CustomError(400, 'Price is not the base price');
   }

package/api/src/routes/checkout-sessions.ts

@@ -1555,8 +1555,6 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
         });
 
         try {
-          // eslint-disable-next-line no-console
-          console.time('updateUserAddress');
           await blocklet.updateUserAddress(
             {
               did: customer.did,
@@ -1570,8 +1568,6 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
               },
             }
           );
-          // eslint-disable-next-line no-console
-          console.timeEnd('updateUserAddress');
           logger.info('updateUserAddress success', {
             did: customer.did,
           });

package/api/src/routes/credit-grants.ts

@@ -2,7 +2,7 @@ import { Router } from 'express';
 import Joi from 'joi';
 import { BN, fromTokenToUnit } from '@ocap/util';
 
-import { literal, OrderItem } from 'sequelize';
+import { literal, OrderItem, fn, col, Op } from 'sequelize';
 import pick from 'lodash/pick';
 import { createListParamSchema, getOrder, getWhereFromKvQuery, MetadataSchema } from '../libs/api';
 import logger from '../libs/logger';
@@ -25,6 +25,8 @@ import { blocklet } from '../libs/auth';
 import { formatMetadata } from '../libs/util';
 import { getPriceUintAmountByCurrency } from '../libs/price';
 import { checkTokenBalance } from '../libs/payment';
+import { trimDecimals } from '../libs/math-utils';
+import { systemMaxPendingAmount } from '../libs/env';
 
 const router = Router();
 const auth = authenticate<CreditGrant>({ component: true, roles: ['owner', 'admin'] });
@@ -163,10 +165,97 @@ router.get('/summary', authMine, async (req, res) => {
   }
 });
 
+const holdersSchema = Joi.object({
+  currency_id: Joi.string().required(),
+  page: Joi.number().integer().min(1).default(1),
+  pageSize: Joi.number().integer().min(0).optional(), // 0 or undefined = return all
+  livemode: Joi.boolean().optional(),
+});
+
+// Get all holders (customers with balance) for a specific credit currency
+router.get('/holders', auth, async (req, res) => {
+  try {
+    const { error, value } = holdersSchema.validate(req.query, { stripUnknown: true });
+    if (error) {
+      return res.status(400).json({ error: error.message });
+    }
+
+    const { currency_id: currencyId, page, pageSize, livemode } = value;
+
+    const currency = await PaymentCurrency.findByPk(currencyId);
+    if (!currency) {
+      return res.status(404).json({ error: `PaymentCurrency ${currencyId} not found` });
+    }
+
+    if (currency.type !== 'credit') {
+      return res.status(400).json({ error: 'Currency must be of type credit' });
+    }
+
+    // Build where clause for credit grants
+    const grantWhere: any = {
+      currency_id: currencyId,
+      status: { [Op.in]: ['granted', 'pending'] }, // Only active grants
+    };
+    if (typeof livemode === 'boolean') {
+      grantWhere.livemode = livemode;
+    }
+
+    // Use database aggregation - only customer_id, no JOIN needed
+    const aggregatedData = (await CreditGrant.findAll({
+      where: grantWhere,
+      attributes: [
+        'customer_id',
+        [fn('COUNT', col('id')), 'grantCount'],
+        [fn('SUM', literal('CAST(remaining_amount AS DECIMAL(40,0))')), 'totalBalance'],
+      ],
+      group: ['customer_id'], // Only group by customer_id - much faster!
+      order: [[literal('totalBalance'), 'DESC']],
+      raw: true,
+    })) as any[];
+
+    const totalCount = aggregatedData.length;
+
+    // Paginate (pageSize = 0 or undefined means return all)
+    const shouldPaginate = pageSize && pageSize > 0;
+    const paginatedData = shouldPaginate
+      ? aggregatedData.slice((page - 1) * pageSize, page * pageSize)
+      : aggregatedData;
+
+    const holders = paginatedData.map((item) => ({
+      customer_id: item.customer_id,
+      balance: (item.totalBalance || '0').toString(),
+      grantCount: parseInt(item.grantCount || '0', 10),
+    }));
+
+    return res.json({
+      holders,
+      currency: {
+        id: currency.id,
+        name: currency.name,
+        symbol: currency.symbol,
+        decimal: currency.decimal,
+      },
+      paging: {
+        page: shouldPaginate ? page : 1,
+        pageSize: shouldPaginate ? pageSize : totalCount,
+        total: totalCount,
+        totalPages: shouldPaginate ? Math.ceil(totalCount / pageSize) : 1,
+      },
+    });
+  } catch (err: any) {
+    logger.error('Error getting credit holders', { error: err.message });
+    return res.status(400).json({ error: err.message });
+  }
+});
+
 const checkAutoRechargeSchema = Joi.object({
   customer_id: Joi.string().required(),
   currency_id: Joi.string().required(),
   pending_amount: Joi.string().optional(),
+  max_recharge_times: Joi.number().integer().min(1).max(10).optional().default(3),
+  max_pending_amount: Joi.string()
+    .pattern(/^\d+(\.\d+)?$/)
+    .optional(),
 });
 
 router.get('/verify-availability', authMine, async (req, res) => {
@@ -255,6 +344,7 @@ router.get('/verify-availability', authMine, async (req, res) => {
       });
     }
 
+    // totalAmount: payment amount required for one auto recharge (priceAmount * quantity)
     const totalAmount = new BN(priceAmount).mul(new BN(config.quantity ?? 1));
 
     // 4. Get pending amount if not provided
@@ -267,46 +357,45 @@ router.get('/verify-availability', authMine, async (req, res) => {
       pendingAmount = pendingSummary?.[currencyId] || '0';
     }
 
-    // 5. Check daily limit
     const pendingAmountBN = new BN(pendingAmount);
-    const today = new Date().toISOString().split('T')[0];
-    const isNewDay = config.last_recharge_date !== today;
-
-    // Calculate required recharge times: if pendingAmount > 0, calculate needed times; otherwise check if at least one recharge is possible
-    const requiredRechargeTimes = pendingAmountBN.gt(new BN(0))
-      ? pendingAmountBN.add(totalAmount).sub(new BN(1)).div(totalAmount).toNumber()
-      : 1;
-
-    if (!isNewDay && config.daily_stats && config.daily_limits) {
-      // Check attempt limit
-      const maxAttempts = Number(config.daily_limits.max_attempts);
-      if (maxAttempts > 0) {
-        const remainingAttempts = maxAttempts - Number(config.daily_stats.attempt_count);
-        if (requiredRechargeTimes > remainingAttempts) {
-          return res.json({
-            can_continue: false,
-            reason: 'daily_limit_reached',
-            detail: 'attempt_limit_exceeded',
-          });
-        }
+
+    // 5. Check system-level maximum pending amount limit (highest priority, cannot be bypassed)
+    // systemMaxPendingAmount is configured via PAYMENT_KIT_MAX_PENDING_AMOUNT (in token format)
+    if (systemMaxPendingAmount > 0 && pendingAmountBN.gt(new BN(0))) {
+      const systemMaxPendingAmountBN = fromTokenToUnit(
+        trimDecimals(String(systemMaxPendingAmount), currency.decimal),
+        currency.decimal
+      );
+      if (pendingAmountBN.gt(systemMaxPendingAmountBN)) {
+        return res.json({
+          can_continue: false,
+          reason: 'system_pending_limit_exceeded',
+          pending_amount: pendingAmount,
+          system_max_pending_amount: systemMaxPendingAmountBN.toString(),
+          detail: 'Pending amount exceeds system maximum limit configured in Payment Kit',
+        });
       }
+    }
 
-      // Check amount limit
-      const maxAmount = new BN(config.daily_limits.max_amount || '0');
-      if (maxAmount.gt(new BN(0))) {
-        const requiredTotalAmount = totalAmount.mul(new BN(requiredRechargeTimes));
-        const remainingAmount = maxAmount.sub(new BN(config.daily_stats.total_amount || '0'));
-        if (requiredTotalAmount.gt(remainingAmount)) {
-          return res.json({
-            can_continue: false,
-            reason: 'daily_limit_reached',
-            detail: 'amount_limit_exceeded',
-          });
-        }
+    // 6. Check caller-specified max pending amount limit (if provided)
+    // Note: max_pending_amount is in token format (e.g., "100"), need to convert to unit format for comparison
+    if (value.max_pending_amount && pendingAmountBN.gt(new BN(0))) {
+      const maxPendingAmountBN = fromTokenToUnit(
+        trimDecimals(value.max_pending_amount, currency.decimal),
+        currency.decimal
+      );
+      if (pendingAmountBN.gt(maxPendingAmountBN)) {
+        return res.json({
+          can_continue: false,
+          reason: 'pending_amount_exceeds_limit',
+          pending_amount: pendingAmount,
+          max_pending_amount: maxPendingAmountBN.toString(),
+          detail: 'Current pending amount exceeds the maximum allowed limit',
+        });
       }
     }
 
-    // 6. Check payment account balance
+    // 7. Get payer
     const payer =
       config.payment_settings?.payment_method_options?.[
         config.paymentMethod.type as keyof typeof config.payment_settings.payment_method_options
@@ -319,29 +408,130 @@ router.get('/verify-availability', authMine, async (req, res) => {
       });
     }
 
-    // Check token balance: if pendingAmount > 0, check if balance can cover pending; otherwise check if balance can cover at least one recharge
-    const amountToCheck = pendingAmountBN.gt(new BN(0)) ? pendingAmount : totalAmount.toString();
-    const balanceResult = await checkTokenBalance({
-      paymentMethod: config.paymentMethod,
-      paymentCurrency: config.rechargeCurrency,
-      userDid: payer,
-      amount: amountToCheck,
-      skipUserCheck: true,
-    });
+    let balanceResult: { sufficient: boolean; token?: { balance: string } } | null = null;
+    // 8. If user has pending amount, check if they can pay it off
+    if (pendingAmountBN.gt(new BN(0))) {
+      // Get credit amount per recharge from price metadata
+      const creditConfig = config.price.metadata?.credit_config;
+      if (!creditConfig || !creditConfig.credit_amount) {
+        return res.json({
+          can_continue: false,
+          reason: 'credit_config_not_found',
+        });
+      }
 
-    if (!balanceResult.sufficient) {
-      return res.json({
-        can_continue: false,
-        reason: 'insufficient_balance',
-        payment_account_balance: balanceResult.token?.balance || '0',
-        pending_amount: pendingAmount,
+      // Convert credit_amount from token to unit, then multiply by quantity
+      // creditAmountPerRecharge: credits amount obtained from one auto recharge
+      const creditAmountPerUnit = fromTokenToUnit(creditConfig.credit_amount, currency.decimal);
+      const creditAmountPerRecharge = new BN(creditAmountPerUnit).mul(new BN(config.quantity ?? 1));
+
+      // Calculate how many recharges are needed to pay off the pending amount
+      // Formula: ceil(pendingAmount / creditAmountPerRecharge)
+      const requiredRechargeTimesBN = pendingAmountBN
+        .add(creditAmountPerRecharge)
+        .sub(new BN(1))
+        .div(creditAmountPerRecharge);
+
+      // Check if required recharge times exceeds limit
+      const maxRechargeTimes = value.max_recharge_times;
+      if (requiredRechargeTimesBN.gt(new BN(maxRechargeTimes))) {
+        return res.json({
+          can_continue: false,
+          reason: 'too_many_recharges_required',
+          pending_amount: pendingAmount,
+          required_recharge_times: requiredRechargeTimesBN.toString(),
+          max_allowed_times: maxRechargeTimes,
+        });
+      }
+
+      // Calculate required payment amount to pay off pending
+      // requiredPaymentAmount = totalAmount (one recharge cost) * requiredRechargeTimes
+      const requiredPaymentAmount = totalAmount.mul(requiredRechargeTimesBN);
+
+      // Check daily limit
+      const today = new Date().toISOString().split('T')[0];
+      const isNewDay = config.last_recharge_date !== today;
+
+      if (!isNewDay && config.daily_stats && config.daily_limits) {
+        const { max_attempts: maxAttemptsRaw, max_amount: maxAmountRaw } = config.daily_limits;
+        const { attempt_count: attemptCount, total_amount: totalAmountStats } = config.daily_stats;
+
+        // Check attempt limit
+        const maxAttempts = Number(maxAttemptsRaw);
+        if (maxAttempts > 0) {
+          // Safe to convert to number since requiredRechargeTimesBN is already checked to be <= 3
+          const requiredRechargeTimes = requiredRechargeTimesBN.toNumber();
+          const remainingAttempts = maxAttempts - Number(attemptCount);
+          if (requiredRechargeTimes > remainingAttempts) {
+            return res.json({
+              can_continue: false,
+              reason: 'daily_limit_reached',
+              detail: 'attempt_limit_exceeded',
+            });
+          }
+        }
+
+        // Check amount limit
+        const maxAmount = new BN(maxAmountRaw || '0');
+        if (maxAmount.gt(new BN(0))) {
+          const remainingAmount = maxAmount.sub(new BN(totalAmountStats || '0'));
+          if (requiredPaymentAmount.gt(remainingAmount)) {
+            return res.json({
+              can_continue: false,
+              reason: 'daily_limit_reached',
+              detail: 'amount_limit_exceeded',
+            });
+          }
+        }
+      }
+
+      // Check payment account balance: balance must be sufficient to pay off pending AND cover at least one more recharge
+      // This ensures user can pay off pending amount and still have balance for continued usage
+      // minimumRequiredBalance = requiredPaymentAmount (to pay off pending) + totalAmount (for one more recharge)
+      const minimumRequiredBalance = requiredPaymentAmount.add(totalAmount);
+      balanceResult = await checkTokenBalance({
+        paymentMethod: config.paymentMethod,
+        paymentCurrency: config.rechargeCurrency,
+        userDid: payer,
+        amount: minimumRequiredBalance.toString(),
+        skipUserCheck: true,
+      });
+
+      if (!balanceResult.sufficient) {
+        return res.json({
+          can_continue: false,
+          reason: 'insufficient_balance',
+          payment_account_balance: balanceResult.token?.balance || '0',
+          pending_amount: pendingAmount,
+          required_amount: minimumRequiredBalance.toString(),
+          detail: 'balance_must_cover_pending_plus_one_recharge',
+        });
+      }
+    } else {
+      // No pending amount: check if balance can cover at least one recharge
+      balanceResult = await checkTokenBalance({
+        paymentMethod: config.paymentMethod,
+        paymentCurrency: config.rechargeCurrency,
+        userDid: payer,
+        amount: totalAmount.toString(),
+        skipUserCheck: true,
       });
+
+      if (!balanceResult.sufficient) {
+        return res.json({
+          can_continue: false,
+          reason: 'insufficient_balance',
+          payment_account_balance: balanceResult.token?.balance || '0',
+          pending_amount: pendingAmount,
+          required_amount: totalAmount.toString(),
+        });
+      }
     }
 
     return res.json({
       can_continue: true,
       payment_account_sufficient: true,
-      payment_account_balance: balanceResult.token?.balance || '0',
+      payment_account_balance: balanceResult?.token?.balance || '0',
       pending_amount: pendingAmount,
     });
   } catch (err: any) {

package/api/src/routes/meter-events.ts

@@ -59,12 +59,14 @@ const listSchema = createListParamSchema<{
   customer_id?: string;
   start?: number;
   end?: number;
+  status?: string;
 }>({
   event_name: Joi.string().empty(''),
   meter_id: Joi.string().empty(''),
   customer_id: Joi.string().empty(''),
   start: Joi.number().integer().optional(),
   end: Joi.number().integer().optional(),
+  status: Joi.string().empty(''),
 });
 
 const statsSchema = Joi.object({
@@ -111,6 +113,15 @@ router.get('/', authMine, async (req, res) => {
       }
     }
 
+    if (query.status) {
+      where.status = {
+        [Op.in]: query.status
+          ?.split(',')
+          .map((x) => x.trim())
+          .filter(Boolean),
+      };
+    }
+
     const { rows: list, count } = await MeterEvent.findAndCountAll({
       where,
       order: getOrder(query, [['created_at', query.o === 'asc' ? 'ASC' : 'DESC']]),
@@ -335,11 +346,7 @@ router.get('/pending-amount', authMine, async (req, res) => {
       }
       params.customerId = customer.id;
     }
-    // eslint-disable-next-line no-console
-    console.time('pending-amount: getPendingAmounts');
     const [summary] = await MeterEvent.getPendingAmounts(params);
-    // eslint-disable-next-line no-console
-    console.timeEnd('pending-amount: getPendingAmounts');
     return res.json(summary);
   } catch (err) {
     logger.error('Error getting meter event pending amount', err);