payment-kit 1.24.1 → 1.24.3

package/api/src/libs/env.ts

@@ -12,6 +12,8 @@ export const revokeStakeCronTime: string = process.env.REVOKE_STAKE_CRON_TIME ||
 export const daysUntilCancel: string | undefined = process.env.DAYS_UNTIL_CANCEL;
 export const meteringSubscriptionDetectionCronTime: string =
   process.env.METERING_SUBSCRIPTION_DETECTION_CRON_TIME || '0 0 10 * * *'; // 默认每天 10:00 执行
+export const overdueDetectionCronTime: string = process.env.OVERDUE_DETECTION_CRON_TIME || '0 0 10 * * *'; // 默认每天 10:00 执行
+export const overdueThreshold: number = process.env.OVERDUE_THRESHOLD ? +process.env.OVERDUE_THRESHOLD : 5; // 默认超额阈值为 5
 export const depositVaultCronTime: string = process.env.DEPOSIT_VAULT_CRON_TIME || '0 */5 * * * *'; // 默认每 5 min 执行一次
 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 执行一次

package/api/src/libs/notification/template/customer-auto-recharge-daily-limit-exceeded.ts

@@ -0,0 +1,222 @@
+/* eslint-disable @typescript-eslint/brace-style */
+/* eslint-disable @typescript-eslint/indent */
+import { withQuery } from 'ufo';
+import { getUserLocale } from '../../../integrations/blocklet/notification';
+import { translate } from '../../../locales';
+import { AutoRechargeConfig, Customer, PaymentMethod, Price, Product } from '../../../store/models';
+import { PaymentCurrency } from '../../../store/models/payment-currency';
+import { getRechargePaymentUrl } from '../../currency';
+import { formatTime } from '../../time';
+import { formatCurrencyInfo, getConnectQueryParam, getCustomerIndexUrl } from '../../util';
+import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';
+
+export interface CustomerAutoRechargeDailyLimitExceededEmailTemplateOptions {
+  customerId: string;
+  autoRechargeConfigId: string;
+  currencyId: string;
+  currentBalance: string;
+}
+
+interface CustomerAutoRechargeDailyLimitExceededEmailTemplateContext {
+  locale: string;
+  userDid: string;
+  at: string;
+  creditCurrencyName: string;
+  currentBalance: string;
+  dailyLimit: string;
+  dailyUsed: string;
+  rechargeUrl: string | null;
+  customerIndexUrl: string;
+}
+
+export class CustomerAutoRechargeDailyLimitExceededEmailTemplate
+  implements BaseEmailTemplate<CustomerAutoRechargeDailyLimitExceededEmailTemplateContext>
+{
+  options: CustomerAutoRechargeDailyLimitExceededEmailTemplateOptions;
+
+  constructor(options: CustomerAutoRechargeDailyLimitExceededEmailTemplateOptions) {
+    this.options = options;
+  }
+
+  async getContext(): Promise<CustomerAutoRechargeDailyLimitExceededEmailTemplateContext> {
+    const customer = await Customer.findByPk(this.options.customerId);
+    if (!customer) {
+      throw new Error(`Customer not found: ${this.options.customerId}`);
+    }
+
+    const autoRechargeConfig = await AutoRechargeConfig.findByPk(this.options.autoRechargeConfigId, {
+      include: [
+        {
+          model: Price,
+          as: 'price',
+          include: [{ model: Product, as: 'product' }],
+        },
+        {
+          model: PaymentMethod,
+          as: 'paymentMethod',
+        },
+        {
+          model: PaymentCurrency,
+          as: 'rechargeCurrency',
+        },
+      ],
+    });
+    if (!autoRechargeConfig) {
+      throw new Error(`AutoRechargeConfig not found: ${this.options.autoRechargeConfigId}`);
+    }
+
+    // Get credit currency
+    const creditCurrency = await PaymentCurrency.findByPk(autoRechargeConfig.currency_id);
+    if (!creditCurrency) {
+      throw new Error(`Credit currency not found: ${autoRechargeConfig.currency_id}`);
+    }
+
+    const rechargeCurrency = await PaymentCurrency.findByPk(autoRechargeConfig.recharge_currency_id);
+    const paymentMethod = await PaymentMethod.findByPk(autoRechargeConfig.payment_method_id);
+
+    const userDid: string = customer.did;
+    const locale = await getUserLocale(userDid);
+    const at: string = formatTime(Date.now());
+
+    const creditCurrencyName = creditCurrency.name || 'Credits';
+    const currentBalance = formatCurrencyInfo(this.options.currentBalance, creditCurrency, null);
+
+    // Format daily limit and usage
+    const dailyLimit = rechargeCurrency
+      ? formatCurrencyInfo(autoRechargeConfig.daily_limits?.max_amount || '0', rechargeCurrency, paymentMethod)
+      : autoRechargeConfig.daily_limits?.max_amount || '0';
+    const dailyUsed = rechargeCurrency
+      ? formatCurrencyInfo(autoRechargeConfig.daily_stats?.total_amount || '0', rechargeCurrency, paymentMethod)
+      : autoRechargeConfig.daily_stats?.total_amount || '0';
+
+    // Get recharge URL
+    let rechargeUrl: string | null = await getRechargePaymentUrl(creditCurrency);
+    if (rechargeUrl) {
+      rechargeUrl = withQuery(rechargeUrl, { ...getConnectQueryParam({ userDid }) });
+    }
+
+    // Get customer index URL for managing credits
+    const customerIndexUrl = getCustomerIndexUrl({
+      locale,
+      userDid,
+    });
+
+    return {
+      locale,
+      userDid,
+      at,
+      creditCurrencyName,
+      currentBalance,
+      dailyLimit,
+      dailyUsed,
+      rechargeUrl,
+      customerIndexUrl,
+    };
+  }
+
+  async getTemplate(): Promise<BaseEmailTemplateType> {
+    const {
+      locale,
+      userDid,
+      at,
+      creditCurrencyName,
+      currentBalance,
+      dailyLimit,
+      dailyUsed,
+      rechargeUrl,
+      customerIndexUrl,
+    } = await this.getContext();
+
+    const template: BaseEmailTemplateType = {
+      title: translate('notification.autoRechargeDailyLimitExceeded.title', locale),
+      body: translate('notification.autoRechargeDailyLimitExceeded.body', locale, {
+        at,
+        creditCurrencyName,
+      }),
+      // @ts-expect-error
+      attachments: [
+        {
+          type: 'section',
+          fields: [
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                color: '#9397A1',
+                text: translate('notification.common.account', locale),
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                text: userDid,
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                color: '#9397A1',
+                text: translate('notification.common.currentBalance', locale),
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                color: '#FF6B00',
+                text: currentBalance,
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                color: '#9397A1',
+                text: translate('notification.autoRechargeDailyLimitExceeded.dailyLimit', locale),
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                text: dailyLimit,
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                color: '#9397A1',
+                text: translate('notification.autoRechargeDailyLimitExceeded.dailyUsed', locale),
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                text: dailyUsed,
+              },
+            },
+          ].filter(Boolean),
+        },
+      ].filter(Boolean),
+      // @ts-ignore
+      actions: [
+        rechargeUrl && {
+          name: translate('notification.common.reloadCredits', locale),
+          title: translate('notification.common.reloadCredits', locale),
+          link: rechargeUrl,
+        },
+        {
+          name: translate('notification.common.manageCredit', locale),
+          title: translate('notification.common.manageCredit', locale),
+          link: customerIndexUrl,
+        },
+      ].filter(Boolean),
+    };
+
+    return template;
+  }
+}

package/api/src/libs/notification/template/customer-credit-insufficient.ts

@@ -29,9 +29,8 @@ interface CustomerCreditInsufficientEmailTemplateContext {
   currencySymbol: string;
   meterEventName: string;
   meterName: string;
-  requiredAmount: string;
-  availableAmount: string;
-  isExhausted: boolean;
+  pendingAmount: string;
+  hasPendingAmount: boolean;
   productName?: string;
   viewSubscriptionLink?: string;
   rechargeUrl: string | null;
@@ -63,9 +62,6 @@ export class CustomerCreditInsufficientEmailTemplate
     const currencySymbol = paymentCurrency.symbol;
     const at = formatTime(Date.now());
 
-    // 检查是否完全耗尽（可用额度为0或负数）
-    const isExhausted = new BN(this.options.availableAmount).lte(new BN(0));
-
     // 如果有订阅ID，获取订阅信息
     let productName: string | undefined;
     let viewSubscriptionLink: string | undefined;
@@ -87,10 +83,9 @@ export class CustomerCreditInsufficientEmailTemplate
       rechargeUrl = withQuery(rechargeUrl, { ...getConnectQueryParam({ userDid }) });
     }
 
-    const formattedRequired =
-      formatNumber(fromUnitToToken(this.options.requiredAmount, paymentCurrency.decimal)) || '0';
-    const formattedAvailable =
-      formatNumber(fromUnitToToken(this.options.availableAmount, paymentCurrency.decimal)) || '0';
+    const pendingAmountValue = this.options.pendingAmount || '0';
+    const pendingAmountBN = new BN(pendingAmountValue);
+    const formattedPending = formatNumber(fromUnitToToken(pendingAmountValue, paymentCurrency.decimal)) || '0';
 
     return {
       locale,
@@ -98,9 +93,8 @@ export class CustomerCreditInsufficientEmailTemplate
       currencySymbol,
       meterName: this.options.meterName,
       meterEventName: this.options.meterEventName,
-      requiredAmount: formatCreditAmount(formattedRequired, currencySymbol),
-      availableAmount: formatCreditAmount(formattedAvailable, currencySymbol),
-      isExhausted,
+      pendingAmount: formatCreditAmount(formattedPending, currencySymbol),
+      hasPendingAmount: pendingAmountBN.gt(new BN(0)),
       productName,
       viewSubscriptionLink,
       rechargeUrl,
@@ -114,9 +108,8 @@ export class CustomerCreditInsufficientEmailTemplate
       locale,
       userDid,
       meterName,
-      requiredAmount,
-      availableAmount,
-      isExhausted,
+      pendingAmount,
+      hasPendingAmount,
       productName,
       viewSubscriptionLink,
       rechargeUrl,
@@ -177,42 +170,22 @@ export class CustomerCreditInsufficientEmailTemplate
         ]
       : [];
 
-    // 额度信息字段
-    const creditFields = [
-      {
-        type: 'text',
-        data: {
-          type: 'plain',
-          color: '#9397A1',
-          text: translate('notification.creditInsufficient.availableCredit', locale),
-        },
-      },
-      {
-        type: 'text',
-        data: {
-          type: 'plain',
-          color: isExhausted ? '#FF0000' : '#333333',
-          text: `${availableAmount}`,
-        },
-      },
-    ];
-
-    // 所需额度字段（仅在未完全耗尽时显示）
-    const requiredCreditFields = !isExhausted
+    const pendingFields = hasPendingAmount
       ? [
           {
             type: 'text',
             data: {
               type: 'plain',
               color: '#9397A1',
-              text: translate('notification.creditInsufficient.requiredCredit', locale),
+              text: translate('notification.creditInsufficient.pendingAmount', locale),
             },
           },
           {
             type: 'text',
             data: {
               type: 'plain',
-              text: `${requiredAmount}`,
+              color: '#FF0000',
+              text: `${pendingAmount}`,
             },
           },
         ]
@@ -243,31 +216,15 @@ export class CustomerCreditInsufficientEmailTemplate
     ].filter(Boolean);
 
     // 构建标题和正文
-    let title: string;
     let body: string;
 
-    if (isExhausted) {
-      title = translate('notification.creditInsufficient.exhaustedTitle', locale);
-      if (productName) {
-        body = translate('notification.creditInsufficient.exhaustedBodyWithSubscription', locale, {
-          subscriptionName: productName,
-        });
-      } else {
-        body = translate('notification.creditInsufficient.exhaustedBodyWithoutSubscription', locale);
-      }
+    const title = translate('notification.creditInsufficient.exhaustedTitle', locale);
+    if (productName) {
+      body = translate('notification.creditInsufficient.exhaustedBodyWithSubscription', locale, {
+        subscriptionName: productName,
+      });
     } else {
-      title = translate('notification.creditInsufficient.title', locale);
-      if (productName) {
-        body = translate('notification.creditInsufficient.bodyWithSubscription', locale, {
-          availableAmount,
-
-          subscriptionName: productName,
-        });
-      } else {
-        body = translate('notification.creditInsufficient.bodyWithoutSubscription', locale, {
-          availableAmount,
-        });
-      }
+      body = translate('notification.creditInsufficient.exhaustedBodyWithoutSubscription', locale);
     }
 
     const template: BaseEmailTemplateType = {
@@ -276,7 +233,7 @@ export class CustomerCreditInsufficientEmailTemplate
       attachments: [
         {
           type: 'section',
-          fields: [...baseFields, ...productFields, ...creditFields, ...requiredCreditFields].filter(Boolean),
+          fields: [...baseFields, ...productFields, ...pendingFields].filter(Boolean),
         },
       ],
       // @ts-ignore

package/api/src/libs/notification/template/customer-credit-low-balance.ts

@@ -1,10 +1,10 @@
 /* eslint-disable @typescript-eslint/brace-style */
 /* eslint-disable @typescript-eslint/indent */
 import { withQuery } from 'ufo';
-import { fromUnitToToken } from '@ocap/util';
+import { BN, fromUnitToToken } from '@ocap/util';
 import { getUserLocale } from '../../../integrations/blocklet/notification';
 import { translate } from '../../../locales';
-import { Customer, PaymentCurrency } from '../../../store/models';
+import { Customer, PaymentCurrency, CreditGrant } from '../../../store/models';
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';
 import { formatCreditAmount, getConnectQueryParam, getCustomerIndexUrl, formatNumber } from '../../util';
 import { getRechargePaymentUrl } from '../../currency';
@@ -29,6 +29,48 @@ interface CustomerCreditLowBalanceEmailTemplateContext {
 export class CustomerCreditLowBalanceEmailTemplate
   implements BaseEmailTemplate<CustomerCreditLowBalanceEmailTemplateContext>
 {
+  // Notification configuration: 10 minute grace period before sending
+  static readonly delay = 10 * 60; // seconds
+
+  /**
+   * Get low balance threshold percentage from environment variable
+   * @returns threshold percentage (default: 10)
+   */
+  static getLowBalanceThresholdPercent(): number {
+    return parseInt(process.env.CREDIT_LOW_BALANCE_THRESHOLD_PERCENTAGE || '10', 10);
+  }
+
+  /**
+   * Preflight check: verify if notification should still be sent
+   * Returns false if user has recharged during grace period
+   */
+  static async preflightCheck(options: CustomerCreditLowBalanceEmailTemplateOptions): Promise<boolean> {
+    try {
+      const { customerId, currencyId } = options;
+
+      const availableGrants = await CreditGrant.getAvailableCreditsForCustomer(customerId, currencyId);
+      const totalAmount = availableGrants.reduce((sum, grant) => sum.add(new BN(grant.amount)), new BN(0));
+      const remainingAmount = availableGrants.reduce(
+        (sum, grant) => sum.add(new BN(grant.remaining_amount)),
+        new BN(0)
+      );
+
+      // Skip if no credits exist
+      if (totalAmount.lte(new BN(0))) {
+        return false;
+      }
+
+      // Calculate current percentage
+      const currentPercentage = remainingAmount.mul(new BN(100)).div(totalAmount).toNumber();
+
+      // If balance is above threshold, user has recharged - skip notification
+      return currentPercentage <= CustomerCreditLowBalanceEmailTemplate.getLowBalanceThresholdPercent();
+    } catch {
+      // On error, proceed with sending to avoid missing important notifications
+      return true;
+    }
+  }
+
   options: CustomerCreditLowBalanceEmailTemplateOptions;
 
   constructor(options: CustomerCreditLowBalanceEmailTemplateOptions) {
@@ -36,7 +78,7 @@ export class CustomerCreditLowBalanceEmailTemplate
   }
 
   async getContext(): Promise<CustomerCreditLowBalanceEmailTemplateContext> {
-    const { customerId, currencyId, availableAmount, percentage } = this.options;
+    const { customerId, currencyId } = this.options;
 
     const customer = await Customer.findByPk(customerId);
     if (!customer) {
@@ -48,16 +90,24 @@ export class CustomerCreditLowBalanceEmailTemplate
       throw new Error(`PaymentCurrency not found: ${currencyId}`);
     }
 
+    // Fetch latest balance data instead of using stale data from options
+    const availableGrants = await CreditGrant.getAvailableCreditsForCustomer(customerId, currencyId);
+    const totalAmount = availableGrants.reduce((sum, grant) => sum.add(new BN(grant.amount)), new BN(0));
+    const remainingAmount = availableGrants.reduce((sum, grant) => sum.add(new BN(grant.remaining_amount)), new BN(0));
+
+    const currentPercentage = totalAmount.gt(new BN(0))
+      ? remainingAmount.mul(new BN(100)).div(totalAmount).toNumber()
+      : 0;
+
     const userDid = customer.did;
     const locale = await getUserLocale(userDid);
 
-    const formattedAmount = formatNumber(fromUnitToToken(availableAmount, paymentCurrency.decimal));
+    const formattedAmount = formatNumber(fromUnitToToken(remainingAmount.toString(), paymentCurrency.decimal));
     const available = formatCreditAmount(formattedAmount || '0', paymentCurrency.symbol);
-    const percentageNum = parseFloat(percentage);
-    const isCritical = percentageNum < 1;
+    const isCritical = currentPercentage < 1;
     const lowBalancePercentage = isCritical
       ? translate('notification.creditLowBalance.lessThanOnePercent', locale)
-      : `${percentage}%`;
+      : `${currentPercentage}%`;
 
     let rechargeUrl: string | null = await getRechargePaymentUrl(paymentCurrency);
     if (rechargeUrl) {