payment-kit 1.24.2 → 1.24.4

package/api/src/queues/notification.ts

@@ -1,4 +1,5 @@
 import { Op } from 'sequelize';
+import debounce from 'lodash/debounce';
 /* eslint-disable @typescript-eslint/indent */
 import { events } from '../libs/event';
 import logger from '../libs/logger';
@@ -102,6 +103,10 @@ import {
   CustomerAutoRechargeFailedEmailTemplate,
   CustomerAutoRechargeFailedEmailTemplateOptions,
 } from '../libs/notification/template/customer-auto-recharge-failed';
+import {
+  CustomerAutoRechargeDailyLimitExceededEmailTemplate,
+  CustomerAutoRechargeDailyLimitExceededEmailTemplateOptions,
+} from '../libs/notification/template/customer-auto-recharge-daily-limit-exceeded';
 import {
   CustomerRevenueSucceededEmailTemplate,
   CustomerRevenueSucceededEmailTemplateOptions,
@@ -139,6 +144,7 @@ export type NotificationQueueJobType =
   | 'customer.credit_grant.granted'
   | 'customer.credit.low_balance'
   | 'customer.auto_recharge.failed'
+  | 'customer.auto_recharge.daily_limit_exceeded'
   | 'webhook.endpoint.failed';
 
 export type NotificationQueueJob = {
@@ -285,6 +291,12 @@ async function getNotificationTemplate(job: NotificationQueueJob): Promise<BaseE
     return new CustomerAutoRechargeFailedEmailTemplate(job.options as CustomerAutoRechargeFailedEmailTemplateOptions);
   }
 
+  if (job.type === 'customer.auto_recharge.daily_limit_exceeded') {
+    return new CustomerAutoRechargeDailyLimitExceededEmailTemplate(
+      job.options as CustomerAutoRechargeDailyLimitExceededEmailTemplateOptions
+    );
+  }
+
   if (job.type === 'webhook.endpoint.failed') {
     return new WebhookEndpointFailedEmailTemplate(job.options as WebhookEndpointFailedEmailTemplateOptions);
   }
@@ -296,6 +308,18 @@ async function handleNotificationJob(job: NotificationQueueJob): Promise<void> {
   try {
     const template = await getNotificationTemplate(job);
 
+    // Check if template class has a preflightCheck
+    const TemplateClass = template.constructor as any;
+    if (TemplateClass.preflightCheck) {
+      const shouldSend = await TemplateClass.preflightCheck(job.options);
+      if (!shouldSend) {
+        logger.info('handleNotificationJob.skipped: preflight check returned false', {
+          type: job.type,
+        });
+        return;
+      }
+    }
+
     await new Notification(template, job.type).send();
     logger.info('handleImmediateNotificationJob.success', { job });
   } catch (error) {
@@ -314,6 +338,8 @@ interface NotificationItem<T = Record<string, any>> {
 
 // 内存缓存，记录最近发送的通知
 const notificationCache = new Map<string, number>();
+// 去抖函数（按 key 去重）
+const debounceHandlers = new Map<string, ReturnType<typeof debounce>>();
 
 // 清理过期缓存的定时器
 setInterval(
@@ -329,6 +355,19 @@ setInterval(
   60 * 60 * 1000
 ); // 每小时清理一次
 
+/**
+ * Clear notification cache entries that match given prefix
+ * Used to reset rate limiting when conditions change (e.g., credit recharged)
+ */
+function clearNotificationCache(prefix: string) {
+  for (const [key] of notificationCache.entries()) {
+    if (key.startsWith(prefix)) {
+      notificationCache.delete(key);
+      logger.info('Notification cache cleared', { key });
+    }
+  }
+}
+
 /**
  * Handles immediate notifications by pushing them directly to the notification queue
  */
@@ -624,7 +663,7 @@ export async function startNotificationQueue() {
   });
 
   events.on('customer.credit.low_balance', (customer: Customer, { metadata }: { metadata: any }) => {
-    addNotificationJob(
+    addNotificationJobWithDelay(
       'customer.credit.low_balance',
       {
         customerId: customer.id,
@@ -678,6 +717,54 @@ export async function startNotificationQueue() {
       }
     }
   );
+
+  events.on(
+    'customer.auto_recharge.daily_limit_exceeded',
+    (customer: Customer, { autoRechargeConfigId, currencyId, currentBalance }) => {
+      logger.info('addNotificationJob:customer.auto_recharge.daily_limit_exceeded', {
+        customerId: customer.id,
+        autoRechargeConfigId,
+        currencyId,
+      });
+      addNotificationJob(
+        'customer.auto_recharge.daily_limit_exceeded',
+        {
+          customerId: customer.id,
+          autoRechargeConfigId,
+          currencyId,
+          currentBalance,
+        },
+        [customer.id, autoRechargeConfigId, currencyId],
+        true, // prevent duplicate
+        24 * 3600 // 24 hours
+      );
+    }
+  );
+
+  // Clear credit notification cache when customer recharges
+  // This allows customer to receive insufficient/low_balance notifications again
+  events.on('customer.credit_grant.granted', (creditGrant: CreditGrant) => {
+    const cacheKeyBase = `${creditGrant.customer_id}.${creditGrant.currency_id}`;
+    const debounceKey = `credit_grant_clear.${cacheKeyBase}`;
+    const delayMs = 5 * 60 * 1000;
+
+    let handler = debounceHandlers.get(debounceKey);
+    if (!handler) {
+      handler = debounce(() => {
+        clearNotificationCache(`customer.credit.insufficient.${cacheKeyBase}`);
+        clearNotificationCache(`customer.credit.low_balance.${cacheKeyBase}`);
+        debounceHandlers.delete(debounceKey);
+        logger.info('Notification cache cleared after delay', {
+          customerId: creditGrant.customer_id,
+          currencyId: creditGrant.currency_id,
+          delayMs,
+        });
+      }, delayMs);
+      debounceHandlers.set(debounceKey, handler);
+    }
+
+    handler();
+  });
 }
 
 export async function handleNotificationPreferenceChange(
@@ -812,3 +899,55 @@ export function addNotificationJob(
     },
   });
 }
+
+/**
+ * Add a notification job with delay support
+ * Use this when the template class has a static `delay` property
+ */
+export async function addNotificationJobWithDelay(
+  type: NotificationQueueJobType,
+  options: NotificationQueueJobOptions,
+  extraIds: string[] = [],
+  preventDuplicate: boolean = false,
+  duplicateWindow: number = 600
+) {
+  const idParts = [type];
+
+  if (extraIds.length) {
+    idParts.push(...extraIds);
+  } else {
+    idParts.push(Date.now().toString());
+  }
+
+  if (preventDuplicate) {
+    const cacheKey = `${type}.${extraIds.join('.')}`;
+    const lastSent = notificationCache.get(cacheKey);
+    const now = Date.now();
+
+    if (lastSent && now - lastSent < duplicateWindow * 1000) {
+      logger.info('Notification skipped due to duplicate prevention', {
+        type,
+        cacheKey,
+        lastSent: new Date(lastSent),
+        duplicateWindow,
+      });
+      return Promise.resolve();
+    }
+
+    notificationCache.set(cacheKey, now);
+  }
+
+  // Get delay from template class
+  const template = await getNotificationTemplate({ type, options });
+  const TemplateClass = template.constructor as any;
+  const { delay } = TemplateClass;
+
+  return notificationQueue.push({
+    id: idParts.join('.'),
+    job: {
+      type,
+      options,
+    },
+    ...(delay && delay > 0 ? { delay } : {}),
+  });
+}

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

@@ -15,6 +15,7 @@ import {
   Subscription,
   PaymentCurrency,
   PaymentMethod,
+  Invoice,
   TCreditTransactionExpanded,
 } from '../store/models';
 
@@ -118,7 +119,12 @@ router.get('/', authMine, async (req, res) => {
               { model: Meter, as: 'meter' },
               { model: Subscription, as: 'subscription', attributes: ['id', 'description', 'status'], required: false },
               { model: CreditGrant, as: 'creditGrant', attributes: ['id', 'name', 'currency_id'] },
-              { model: MeterEvent, as: 'meterEvent', attributes: ['id', 'source_data'], required: false },
+              {
+                model: MeterEvent,
+                as: 'meterEvent',
+                attributes: ['id', 'source_data', 'timestamp', 'processed_at', 'created_at'],
+                required: false,
+              },
             ],
           });
           // Transform transactions
@@ -135,6 +141,9 @@ router.get('/', authMine, async (req, res) => {
         customer_id: query.customer_id,
         status: ['granted', 'depleted', 'expired'],
       };
+      if (query.subscription_id) {
+        grantWhere['metadata.subscription_id'] = query.subscription_id;
+      }
       if (query.start) {
         grantWhere.created_at = {
           [Op.gte]: new Date(query.start * 1000),
@@ -162,11 +171,80 @@ router.get('/', authMine, async (req, res) => {
               },
             ],
           });
-          // Transform grants
-          return rows.map((item: any) => ({
-            ...item.toJSON(),
-            activity_type: 'grant',
-          }));
+
+          // Fetch invoice info for paid grants
+          const invoiceIds = rows
+            .map((item: any) => item.metadata?.invoice_id)
+            .filter((id: string | undefined): id is string => !!id);
+
+          // For first scheduled grants (schedule_seq === 1) without invoice_id, find invoice by subscription_id
+          const subscriptionIdsForFirstGrant = rows
+            .filter(
+              (item: any) =>
+                item.metadata?.schedule_seq === 1 && !item.metadata?.invoice_id && item.metadata?.subscription_id
+            )
+            .map((item: any) => item.metadata.subscription_id);
+
+          const [invoicesByIds, invoicesBySubscription] = await Promise.all([
+            invoiceIds.length > 0
+              ? Invoice.findAll({
+                  where: { id: { [Op.in]: invoiceIds } },
+                  attributes: ['id', 'total', 'amount_paid', 'currency_id', 'billing_reason', 'subscription_id'],
+                  include: [
+                    {
+                      model: PaymentCurrency,
+                      as: 'paymentCurrency',
+                      attributes: ['id', 'symbol', 'decimal', 'type'],
+                    },
+                  ],
+                })
+              : [],
+            subscriptionIdsForFirstGrant.length > 0
+              ? Invoice.findAll({
+                  where: {
+                    subscription_id: { [Op.in]: subscriptionIdsForFirstGrant },
+                    status: 'paid',
+                  },
+                  attributes: ['id', 'total', 'amount_paid', 'currency_id', 'billing_reason', 'subscription_id'],
+                  include: [
+                    {
+                      model: PaymentCurrency,
+                      as: 'paymentCurrency',
+                      attributes: ['id', 'symbol', 'decimal', 'type'],
+                    },
+                  ],
+                  order: [['created_at', 'ASC']],
+                })
+              : [],
+          ]);
+
+          const invoiceMap = new Map(invoicesByIds.map((inv: any) => [inv.id, inv]));
+          for (const inv of invoicesBySubscription) {
+            const subId = inv.subscription_id as string;
+            if (subId && !invoiceMap.has(subId)) {
+              invoiceMap.set(subId, inv);
+            }
+          }
+
+          // Transform grants with invoice info
+          return rows.map((item: any) => {
+            const grantData = item.toJSON();
+            const invoice = invoiceMap.get(grantData.metadata.invoice_id);
+            return {
+              ...grantData,
+              activity_type: 'grant',
+              invoice: invoice
+                ? {
+                    total: invoice.total,
+                    amount_paid: invoice.amount_paid,
+                    currency_id: invoice.currency_id,
+                    billing_reason: invoice.billing_reason,
+                    subscription_id: invoice.subscription_id,
+                    paymentCurrency: invoice.paymentCurrency,
+                  }
+                : null,
+            };
+          });
         },
         meta: { type: 'database' },
       };
@@ -344,7 +422,7 @@ router.get('/:id', authPortal, async (req, res) => {
         {
           model: MeterEvent,
           as: 'meterEvent',
-          attributes: ['id', 'source_data'],
+          attributes: ['id', 'source_data', 'timestamp', 'processed_at', 'created_at'],
           required: false,
         },
       ],

package/api/src/routes/invoices.ts

@@ -311,6 +311,18 @@ router.get('/', authMine, async (req, res) => {
             { model: PaymentCurrency, as: 'paymentCurrency' },
             { model: PaymentMethod, as: 'paymentMethod' },
             { model: Subscription, as: 'subscription', attributes: ['id', 'description'] },
+            {
+              model: InvoiceItem,
+              as: 'lines',
+              include: [
+                {
+                  model: Price,
+                  as: 'price',
+                  attributes: ['id', 'metadata'],
+                  include: [{ model: Product, as: 'product', attributes: ['id', 'type', 'name'] }],
+                },
+              ],
+            },
             { model: Customer, as: 'customer' },
           ],
         });

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

@@ -352,6 +352,178 @@ router.get('/pending-amount', authMine, async (req, res) => {
     return res.status(400).json({ error: err?.message });
   }
 });
+
+// Get overdue summary by credit currency (action-required amounts grouped by currency)
+router.get('/overdue-summary', auth, async (req, res) => {
+  try {
+    // Query to aggregate credit_pending by currency, showing overdue amounts per credit currency
+    const results = await MeterEvent.sequelize!.query<{
+      currency_id: string;
+      total_pending: string;
+      customer_count: number;
+      event_count: number;
+    }>(
+      `SELECT 
+        m.currency_id,
+        SUM(CAST(me.credit_pending AS DECIMAL(40,0))) as total_pending,
+        COUNT(DISTINCT json_extract(me.payload, '$.customer_id')) as customer_count,
+        COUNT(*) as event_count
+      FROM meter_events me
+      JOIN meters m ON me.event_name = m.event_name
+      WHERE me.livemode = :livemode 
+        AND me.status IN ('requires_capture', 'requires_action')
+        AND m.status = 'active'
+      GROUP BY m.currency_id
+      HAVING total_pending > 0
+      ORDER BY total_pending DESC`,
+      {
+        replacements: { livemode: req.livemode ? 1 : 0 },
+        type: QueryTypes.SELECT,
+      }
+    );
+
+    // Fetch currency details
+    const currencyIds = results.map((r) => r.currency_id);
+    const currencies =
+      currencyIds.length > 0 ? await PaymentCurrency.findAll({ where: { id: { [Op.in]: currencyIds } } }) : [];
+    const currencyMap = new Map(currencies.map((c) => [c.id, c]));
+
+    const list = results.map((r) => ({
+      currency: currencyMap.get(r.currency_id),
+      total_pending: r.total_pending,
+      customer_count: r.customer_count,
+      event_count: r.event_count,
+    }));
+
+    return res.json({ list });
+  } catch (err) {
+    logger.error('Error getting overdue summary', err);
+    return res.status(400).json({ error: err?.message });
+  }
+});
+
+// Get all customers with credit overdue (action-required amount > 0), grouped by customer + currency
+router.get('/overdue-customers', auth, async (req, res) => {
+  try {
+    const page = Math.max(1, parseInt(String(req.query.page || '1'), 10));
+    const pageSize = Math.min(100, Math.max(1, parseInt(String(req.query.pageSize || '20'), 10)));
+    const offset = (page - 1) * pageSize;
+    const currencyId = req.query.currency_id as string | undefined;
+    const searchQuery = req.query.q as string | undefined;
+
+    // If search query provided, first find matching customer IDs
+    let customerFilter = '';
+    const replacements: any = { livemode: req.livemode ? 1 : 0, limit: pageSize, offset };
+    const countReplacements: any = { livemode: req.livemode ? 1 : 0 };
+
+    // Build currency filter
+    let currencyFilter = '';
+    if (currencyId) {
+      currencyFilter = 'AND m.currency_id = :currencyId';
+      replacements.currencyId = currencyId;
+      countReplacements.currencyId = currencyId;
+    }
+
+    if (searchQuery) {
+      // Escape LIKE wildcards to prevent unintended matches
+      const escapedQuery = searchQuery.replace(/[%_]/g, '\\$&');
+      const searchCustomers = await Customer.findAll({
+        where: {
+          [Op.or]: [
+            { name: { [Op.like]: `%${escapedQuery}%` } },
+            { email: { [Op.like]: `%${escapedQuery}%` } },
+            { did: { [Op.like]: `%${escapedQuery}%` } },
+          ],
+        },
+        attributes: ['id'],
+      });
+      const searchCustomerIds = searchCustomers.map((c) => c.id);
+      if (searchCustomerIds.length === 0) {
+        return res.json({ list: [], count: 0, paging: { page, pageSize } });
+      }
+      // Generate parameterized placeholders for customer IDs
+      const placeholders = searchCustomerIds.map((_, i) => `:searchId${i}`);
+      customerFilter = `AND json_extract(me.payload, '$.customer_id') IN (${placeholders.join(',')})`;
+      searchCustomerIds.forEach((id, i) => {
+        replacements[`searchId${i}`] = id;
+        countReplacements[`searchId${i}`] = id;
+      });
+    }
+
+    // Query to aggregate credit_pending by customer + currency, order by event_count DESC
+    const results = await MeterEvent.sequelize!.query<{
+      customer_id: string;
+      currency_id: string;
+      total_pending: string;
+      event_count: number;
+    }>(
+      `SELECT 
+        json_extract(me.payload, '$.customer_id') as customer_id,
+        m.currency_id as currency_id,
+        SUM(CAST(me.credit_pending AS DECIMAL(40,0))) as total_pending,
+        COUNT(*) as event_count
+      FROM meter_events me
+      JOIN meters m ON me.event_name = m.event_name
+      WHERE me.livemode = :livemode 
+        AND me.status IN ('requires_capture', 'requires_action')
+        AND m.status = 'active'
+        ${currencyFilter}
+        ${customerFilter}
+      GROUP BY json_extract(me.payload, '$.customer_id'), m.currency_id
+      HAVING total_pending > 0
+      ORDER BY event_count DESC
+      LIMIT :limit OFFSET :offset`,
+      {
+        replacements,
+        type: QueryTypes.SELECT,
+      }
+    );
+
+    // Get total count
+    const countResult = await MeterEvent.sequelize!.query<{ count: number }>(
+      `SELECT COUNT(*) as count FROM (
+        SELECT json_extract(me.payload, '$.customer_id') as customer_id, m.currency_id
+        FROM meter_events me
+        JOIN meters m ON me.event_name = m.event_name
+        WHERE me.livemode = :livemode 
+          AND me.status IN ('requires_capture', 'requires_action')
+          AND m.status = 'active'
+          ${currencyFilter}
+          ${customerFilter}
+        GROUP BY json_extract(me.payload, '$.customer_id'), m.currency_id
+        HAVING SUM(CAST(me.credit_pending AS DECIMAL(40,0))) > 0
+      )`,
+      {
+        replacements: countReplacements,
+        type: QueryTypes.SELECT,
+      }
+    );
+
+    const count = countResult[0]?.count || 0;
+    const customerIds = [...new Set(results.map((r) => r.customer_id))];
+    const currencyIds = [...new Set(results.map((r) => r.currency_id))];
+
+    // Fetch customer and currency details
+    const customers = customerIds.length > 0 ? await Customer.findAll({ where: { id: { [Op.in]: customerIds } } }) : [];
+    const customerMap = new Map(customers.map((c) => [c.id, c]));
+
+    const currencies =
+      currencyIds.length > 0 ? await PaymentCurrency.findAll({ where: { id: { [Op.in]: currencyIds } } }) : [];
+    const currencyMap = new Map(currencies.map((c) => [c.id, c]));
+
+    const list = results.map((r) => ({
+      customer: customerMap.get(r.customer_id),
+      currency: currencyMap.get(r.currency_id),
+      total_pending: r.total_pending,
+      event_count: r.event_count,
+    }));
+
+    return res.json({ list, count, paging: { page, pageSize } });
+  } catch (err) {
+    logger.error('Error getting overdue customers', err);
+    return res.status(400).json({ error: err?.message });
+  }
+});
 router.get('/:id', authMine, async (req, res) => {
   try {
     logger.info('get meter event', { id: req.params.id });

package/blocklet.yml

@@ -14,7 +14,7 @@ repository:
   type: git
   url: git+https://github.com/blocklet/payment-kit.git
 specVersion: 1.2.8
-version: 1.24.2
+version: 1.24.4
 logo: logo.png
 files:
   - dist

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "payment-kit",
-  "version": "1.24.2",
+  "version": "1.24.4",
   "scripts": {
     "dev": "blocklet dev --open",
     "prelint": "npm run types",
@@ -59,9 +59,9 @@
     "@blocklet/error": "^0.3.5",
     "@blocklet/js-sdk": "^1.17.8-beta-20260104-120132-cb5b1914",
     "@blocklet/logger": "^1.17.8-beta-20260104-120132-cb5b1914",
-    "@blocklet/payment-broker-client": "1.24.2",
-    "@blocklet/payment-react": "1.24.2",
-    "@blocklet/payment-vendor": "1.24.2",
+    "@blocklet/payment-broker-client": "1.24.4",
+    "@blocklet/payment-react": "1.24.4",
+    "@blocklet/payment-vendor": "1.24.4",
     "@blocklet/sdk": "^1.17.8-beta-20260104-120132-cb5b1914",
     "@blocklet/ui-react": "^3.4.7",
     "@blocklet/uploader": "^0.3.19",
@@ -131,7 +131,7 @@
   "devDependencies": {
     "@abtnode/types": "^1.17.8-beta-20260104-120132-cb5b1914",
     "@arcblock/eslint-config-ts": "^0.3.3",
-    "@blocklet/payment-types": "1.24.2",
+    "@blocklet/payment-types": "1.24.4",
     "@types/cookie-parser": "^1.4.9",
     "@types/cors": "^2.8.19",
     "@types/debug": "^4.1.12",
@@ -178,5 +178,5 @@
       "parser": "typescript"
     }
   },
-  "gitHead": "8cefbfb9066513c7fb33beb2185ea4e58968aad7"
+  "gitHead": "d4a5f67e657cafa8862912bb8de38a3d56a7919d"
 }

package/src/components/customer/credit-overview.tsx

@@ -259,7 +259,13 @@ export default function CreditOverview({ customerId, settings, mode = 'portal' }
 
   const filteredCreditCurrencies = useMemo(() => {
     return creditCurrencies.filter((currency: TPaymentCurrency) => {
-      return creditSummary?.grants?.[currency.id];
+      const grantData = creditSummary?.grants?.[currency.id];
+      if (!grantData) return false;
+      // Filter out credits with zero balance
+      if (grantData.remainingAmount === '0') {
+        return false;
+      }
+      return true;
     });
   }, [creditCurrencies, creditSummary?.grants]);
 

package/src/locales/en.tsx

@@ -98,6 +98,7 @@ export default flat({
     creditGrant: 'Grant',
     date: 'Date',
     subscription: 'Subscription',
+    meter: 'Meter',
     meterEvent: 'Meter Event',
     creditAmount: 'Credit',
     createdAt: 'Created At',
@@ -181,6 +182,14 @@ export default flat({
         transaction: 'Transaction Metrics',
         essential: 'Essential Metrics',
       },
+      overdue: {
+        title: 'Pending Consumption',
+        subtitle: 'Unpaid credit consumption',
+        customers: '{count} customers',
+        events: '{count} pending records',
+        viewAll: 'View All',
+        noOverdue: 'No pending consumption',
+      },
     },
     payments: 'Payments',
     connections: 'Connections',
@@ -270,6 +279,13 @@ export default flat({
     meterEvents: {
       title: 'Meter Events',
     },
+    overdue: {
+      title: 'Pending Consumption',
+      pendingAmount: 'Pending Amount',
+      eventCount: 'Pending Records',
+      noOverdue: 'No pending consumption',
+      selectCurrency: 'Currency',
+    },
     meter: {
       add: 'Add meter',
       edit: 'Edit meter',
@@ -482,6 +498,7 @@ export default flat({
     },
     meterEvent: {
       title: 'Meter Event Details',
+      id: 'Event ID',
       totalEvents: 'Total events: {count}',
       noEvents: 'No events found',
       noEventsHint: 'You can manually add test events in test mode.',
@@ -492,6 +509,9 @@ export default flat({
       subscription: 'Subscription',
       creditConsumed: 'Credit Consumed',
       usageValue: 'Usage Value',
+      settlementAmount: 'Settlement Amount',
+      reportedAmount: 'Reported Amount',
+      overdueAmount: 'Overdue Amount',
       reportedAt: 'Reported At',
       processedAt: 'Processed At',
       eventIdentifier: 'Event Identifier',