payment-kit 1.19.0 → 1.19.2

package/api/src/queues/notification.ts

@@ -38,7 +38,7 @@ import {
   SubscriptionTrialStartEmailTemplateOptions,
 } from '../libs/notification/template/subscription-trial-start';
 import {
-  SubscriptionTrialWilEndEmailTemplate,
+  SubscriptionTrialWillEndEmailTemplate,
   SubscriptionTrialWillEndEmailTemplateOptions,
 } from '../libs/notification/template/subscription-trial-will-end';
 import {
@@ -67,6 +67,7 @@ import {
   Refund,
   Subscription,
   Customer,
+  CreditGrant,
 } from '../store/models';
 import {
   UsageReportEmptyEmailTemplate,
@@ -80,6 +81,18 @@ import {
   OverdraftProtectionExhaustedEmailTemplate,
   OverdraftProtectionExhaustedEmailTemplateOptions,
 } from '../libs/notification/template/subscription-overdraft-protection-exhausted';
+import {
+  CustomerCreditInsufficientEmailTemplate,
+  CustomerCreditInsufficientEmailTemplateOptions,
+} from '../libs/notification/template/customer-credit-insufficient';
+import {
+  CustomerCreditGrantGrantedEmailTemplate,
+  CustomerCreditGrantGrantedEmailTemplateOptions,
+} from '../libs/notification/template/customer-credit-grant-granted';
+import {
+  CustomerCreditGrantLowBalanceEmailTemplate,
+  CustomerCreditGrantLowBalanceEmailTemplateOptions,
+} from '../libs/notification/template/customer-credit-grant-low-balance';
 import {
   CustomerRevenueSucceededEmailTemplate,
   CustomerRevenueSucceededEmailTemplateOptions,
@@ -108,7 +121,10 @@ export type NotificationQueueJobType =
   | 'customer.reward.succeeded'
   | 'usage.report.empty'
   | 'billing.discrepancy'
-  | 'subscription.overdraftProtection.exhausted';
+  | 'subscription.overdraftProtection.exhausted'
+  | 'customer.credit.insufficient'
+  | 'customer.credit_grant.granted'
+  | 'customer.credit_grant.low_balance';
 
 export type NotificationQueueJob = {
   type: NotificationQueueJobType;
@@ -200,7 +216,7 @@ function getNotificationTemplate(job: NotificationQueueJob): BaseEmailTemplate {
     return new SubscriptionWillRenewEmailTemplate(job.options as SubscriptionWillRenewEmailTemplateOptions);
   }
   if (job.type === 'customer.subscription.trial_will_end') {
-    return new SubscriptionTrialWilEndEmailTemplate(job.options as SubscriptionTrialWillEndEmailTemplateOptions);
+    return new SubscriptionTrialWillEndEmailTemplate(job.options as SubscriptionTrialWillEndEmailTemplateOptions);
   }
   if (job.type === 'customer.subscription.will_canceled') {
     return new SubscriptionWillCanceledEmailTemplate(job.options as SubscriptionWillCanceledEmailTemplateOptions);
@@ -229,6 +245,20 @@ function getNotificationTemplate(job: NotificationQueueJob): BaseEmailTemplate {
     return new CustomerRevenueSucceededEmailTemplate(job.options as CustomerRevenueSucceededEmailTemplateOptions);
   }
 
+  if (job.type === 'customer.credit.insufficient') {
+    return new CustomerCreditInsufficientEmailTemplate(job.options as CustomerCreditInsufficientEmailTemplateOptions);
+  }
+
+  if (job.type === 'customer.credit_grant.granted') {
+    return new CustomerCreditGrantGrantedEmailTemplate(job.options as CustomerCreditGrantGrantedEmailTemplateOptions);
+  }
+
+  if (job.type === 'customer.credit_grant.low_balance') {
+    return new CustomerCreditGrantLowBalanceEmailTemplate(
+      job.options as CustomerCreditGrantLowBalanceEmailTemplateOptions
+    );
+  }
+
   throw new Error(`Unknown job type: ${job.type}`);
 }
 
@@ -252,24 +282,28 @@ interface NotificationItem<T = Record<string, any>> {
   data: T;
 }
 
+// 内存缓存，记录最近发送的通知
+const notificationCache = new Map<string, number>();
+
+// 清理过期缓存的定时器
+setInterval(
+  () => {
+    const now = Date.now();
+    for (const [key, timestamp] of notificationCache.entries()) {
+      // 清理超过24小时的缓存记录
+      if (now - timestamp > 24 * 60 * 60 * 1000) {
+        notificationCache.delete(key);
+      }
+    }
+  },
+  60 * 60 * 1000
+); // 每小时清理一次
+
 /**
  * Handles immediate notifications by pushing them directly to the notification queue
  */
 function handleImmediateNotification(type: string, data: Record<string, any>, extraIds: string[] = []) {
-  const idParts = [type];
-  if (extraIds.length) {
-    idParts.push(...extraIds);
-  } else {
-    idParts.push(Date.now().toString());
-  }
-
-  return notificationQueue.push({
-    id: idParts.join('.'),
-    job: {
-      type,
-      options: data,
-    },
-  });
+  return addNotificationJob(type as NotificationQueueJobType, data, extraIds);
 }
 
 /**
@@ -423,29 +457,13 @@ export const aggregatedNotificationQueue = createQueue<AggregatedNotificationJob
 export async function startNotificationQueue() {
   // 试用期开始
   events.on('customer.subscription.trial_start', (subscription: Subscription) => {
-    notificationQueue.push({
-      id: `customer.subscription.trial_start.${subscription.id}`,
-      job: {
-        type: 'customer.subscription.trial_start',
-        options: {
-          subscriptionId: subscription.id,
-        },
-      },
-    });
+    addNotificationJob('customer.subscription.trial_start', { subscriptionId: subscription.id }, [subscription.id]);
   });
 
   events.on('customer.subscription.started', (subscription: Subscription) => {
     if (!subscription.trial_start) {
       // 没有试用期的 subscription 通知
-      notificationQueue.push({
-        id: `customer.subscription.started.${subscription.id}`,
-        job: {
-          type: 'customer.subscription.started',
-          options: {
-            subscriptionId: subscription.id,
-          },
-        },
-      });
+      addNotificationJob('customer.subscription.started', { subscriptionId: subscription.id }, [subscription.id]);
     }
   });
 
@@ -454,27 +472,13 @@ export async function startNotificationQueue() {
     if (checkoutSession.mode === 'payment') {
       const paymentLink = await PaymentLink.findByPk(checkoutSession.payment_link_id);
       if (paymentLink?.submit_type === 'donate') {
-        notificationQueue.push({
-          id: `customer.reward.succeeded.${checkoutSession.id}`,
-          job: {
-            type: 'customer.reward.succeeded',
-            options: {
-              checkoutSessionId: checkoutSession.id,
-            },
-          },
-        });
+        addNotificationJob('customer.reward.succeeded', { checkoutSessionId: checkoutSession.id }, [
+          checkoutSession.id,
+        ]);
         return;
       }
 
-      notificationQueue.push({
-        id: `checkout.session.completed.${checkoutSession.id}`,
-        job: {
-          type: 'checkout.session.completed',
-          options: {
-            checkoutSessionId: checkoutSession.id,
-          },
-        },
-      });
+      addNotificationJob('checkout.session.completed', { checkoutSessionId: checkoutSession.id }, [checkoutSession.id]);
     }
   });
 
@@ -523,106 +527,95 @@ export async function startNotificationQueue() {
     });
 
     if (invoice && subscription.metadata.renew_failed_reason) {
-      notificationQueue.push({
-        id: `customer.subscription.renew_failed.${subscription.id}.${invoice.id}`,
-        job: {
-          type: 'customer.subscription.renew_failed',
-          options: {
-            invoice,
-            result: subscription.metadata.renew_failed_reason,
-          },
-        },
-      });
+      addNotificationJob(
+        'customer.subscription.renew_failed',
+        { invoice, result: subscription.metadata.renew_failed_reason },
+        [subscription.id, invoice.id]
+      );
     }
   });
 
   events.on('customer.subscription.upgraded', (subscription: Subscription) => {
-    notificationQueue.push({
-      id: `customer.subscription.upgraded.${subscription.id}.${subscription.latest_invoice_id}`,
-      job: {
-        type: 'customer.subscription.upgraded',
-        options: {
-          subscriptionId: subscription.id,
-        },
-      },
-    });
+    const extraIds = [subscription.id];
+    if (subscription.latest_invoice_id) {
+      extraIds.push(subscription.latest_invoice_id);
+    }
+    addNotificationJob('customer.subscription.upgraded', { subscriptionId: subscription.id }, extraIds);
   });
 
   events.on('refund.succeeded', (refund: Refund) => {
-    notificationQueue.push({
-      id: `refund.succeeded.${refund.subscription_id}.${refund.id}`,
-      job: {
-        type: 'refund.succeeded',
-        options: {
-          refundId: refund.id,
-        },
-      },
-    });
+    const extraIds = [refund.id];
+    if (refund.subscription_id) {
+      extraIds.unshift(refund.subscription_id);
+    }
+    addNotificationJob('refund.succeeded', { refundId: refund.id }, extraIds);
   });
 
   events.on('customer.subscription.deleted', (subscription: Subscription) => {
-    notificationQueue.push({
-      id: `customer.subscription.deleted.${subscription.id}`,
-      job: {
-        type: 'customer.subscription.deleted',
-        options: {
-          subscriptionId: subscription.id,
-        },
-      },
-    });
+    addNotificationJob('customer.subscription.deleted', { subscriptionId: subscription.id }, [subscription.id]);
   });
 
   events.on('usage.report.empty', (subscription: Subscription, { usageReportStart, usageReportEnd }) => {
-    notificationQueue.push({
-      id: `usage.report.empty.${subscription.id}`,
-      job: {
-        type: 'usage.report.empty',
-        options: {
-          subscriptionId: subscription.id,
-          usageReportStart,
-          usageReportEnd,
-        },
-      },
-    });
+    addNotificationJob('usage.report.empty', { subscriptionId: subscription.id, usageReportStart, usageReportEnd }, [
+      subscription.id,
+    ]);
   });
 
   events.on('billing.discrepancy', (invoice: Invoice) => {
-    notificationQueue.push({
-      id: `billing.discrepancy.${invoice.id}`,
-      job: {
-        type: 'billing.discrepancy',
-        options: {
-          invoiceId: invoice.id,
-        },
-      },
-    });
+    addNotificationJob('billing.discrepancy', { invoiceId: invoice.id }, [invoice.id]);
   });
 
   events.on('subscription.overdraft_protection.exhausted', (subscription: Subscription) => {
-    notificationQueue.push({
-      id: `subscription.overdraftProtection.exhausted.${subscription.id}`,
-      job: {
-        type: 'subscription.overdraftProtection.exhausted',
-        options: {
-          subscriptionId: subscription.id,
-        },
-      },
-    });
+    addNotificationJob('subscription.overdraftProtection.exhausted', { subscriptionId: subscription.id }, [
+      subscription.id,
+    ]);
   });
 
   events.on('payout.paid', (payout: Payout) => {
     if (payout.customer_id) {
-      notificationQueue.push({
-        id: `payout.paid.${payout.id}`,
-        job: {
-          type: 'payout.paid',
-          options: {
-            payoutId: payout.id,
-          },
-        },
-      });
+      addNotificationJob('payout.paid', { payoutId: payout.id }, [payout.id]);
     }
   });
+
+  events.on('customer.credit_grant.granted', (creditGrant: CreditGrant) => {
+    addNotificationJob(
+      'customer.credit_grant.granted',
+      {
+        creditGrantId: creditGrant.id,
+      },
+      [creditGrant.id]
+    );
+  });
+
+  events.on('customer.credit_grant.low_balance', (creditGrant: CreditGrant) => {
+    addNotificationJob(
+      'customer.credit_grant.low_balance',
+      {
+        creditGrantId: creditGrant.id,
+      },
+      [creditGrant.id],
+      true,
+      24 * 3600 // 1 天
+    );
+  });
+
+  events.on('customer.credit.insufficient', (customer: Customer, { metadata }: { metadata: any }) => {
+    addNotificationJob(
+      'customer.credit.insufficient',
+      {
+        customerId: customer.id,
+        currencyId: metadata.currency_id,
+        meterEventName: metadata.meter_event_name || 'Service',
+        requiredAmount: metadata.required_amount,
+        availableAmount: metadata.available_amount,
+        pendingAmount: metadata.pending_amount || '0',
+        subscriptionId: metadata.subscription_id,
+      },
+      [customer.id, metadata.currency_id, metadata.subscription_id],
+      true,
+      600
+    );
+  });
 }
 
 export async function handleNotificationPreferenceChange(
@@ -705,3 +698,55 @@ export async function handleNotificationPreferenceChange(
     /* eslint-enable no-await-in-loop */
   }
 }
+
+/**
+ * Add a notification job to the queue
+ * @param type Notification type
+ * @param options Notification options
+ * @param extraIds Extra IDs for building a unique job ID, if not provided, use timestamp
+ * @param preventDuplicate Whether to prevent duplicate, if true, will check the cache
+ * @param duplicateWindow Duplicate prevention time window (seconds), default 600 seconds (10 minutes)
+ */
+export function addNotificationJob(
+  type: NotificationQueueJobType,
+  options: NotificationQueueJobOptions,
+  extraIds: string[] = [],
+  preventDuplicate: boolean = false,
+  duplicateWindow: number = 600 // 10分钟
+) {
+  const idParts = [type];
+
+  if (extraIds.length) {
+    idParts.push(...extraIds);
+  } else {
+    idParts.push(Date.now().toString());
+  }
+
+  // if prevent duplicate, check the cache
+  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);
+  }
+
+  return notificationQueue.push({
+    id: idParts.join('.'),
+    job: {
+      type,
+      options,
+    },
+  });
+}