payment-kit 1.15.17 → 1.15.19

package/api/src/libs/notification/template/subscription-trial-start.ts

@@ -14,6 +14,7 @@ import { getMainProductName } from '../../product';
 import { getCustomerSubscriptionPageUrl } from '../../subscription';
 import { formatTime, getPrettyMsI18nLocale } from '../../time';
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';
+import { getSubscriptionNotificationCustomActions } from '../../util';
 
 export interface SubscriptionTrialStartEmailTemplateOptions {
   subscriptionId: string;
@@ -41,6 +42,7 @@ interface SubscriptionTrialStartEmailTemplateContext {
   viewSubscriptionLink: string;
   viewInvoiceLink: string;
   oneTimeProductInfo?: Array<OneTimeProductInfo>;
+  customActions: any[];
 }
 
 export class SubscriptionTrialStartEmailTemplate
@@ -130,6 +132,12 @@ export class SubscriptionTrialStartEmailTemplate
       locale,
     });
 
+    const customActions = getSubscriptionNotificationCustomActions(
+      subscription,
+      'customer.subscription.trial_start',
+      locale
+    );
+
     return {
       locale,
       productName,
@@ -146,6 +154,7 @@ export class SubscriptionTrialStartEmailTemplate
       viewSubscriptionLink,
       viewInvoiceLink,
       oneTimeProductInfo,
+      customActions,
     };
   }
 
@@ -232,6 +241,7 @@ export class SubscriptionTrialStartEmailTemplate
       viewSubscriptionLink,
       viewInvoiceLink,
       oneTimeProductInfo,
+      customActions,
     } = await this.getContext();
 
     const hasOneTimeProduct = !isEmpty(oneTimeProductInfo);
@@ -342,6 +352,7 @@ export class SubscriptionTrialStartEmailTemplate
           title: translate('notification.common.viewInvoice', locale),
           link: viewInvoiceLink,
         },
+        ...customActions,
       ].filter(Boolean),
     };
 

package/api/src/libs/notification/template/subscription-trial-will-end.ts

@@ -14,6 +14,7 @@ import { getCustomerSubscriptionPageUrl } from '../../subscription';
 import { formatTime, getPrettyMsI18nLocale } from '../../time';
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';
 import dayjs from '../../dayjs';
+import { getSubscriptionNotificationCustomActions } from '../../util';
 
 export interface SubscriptionTrialWillEndEmailTemplateOptions {
   subscriptionId: string;
@@ -37,6 +38,7 @@ interface SubscriptionTrialWilEndEmailTemplateContext {
 
   viewSubscriptionLink: string;
   paymentMethod: PaymentMethod | null;
+  customActions: any[];
 }
 
 export class SubscriptionTrialWilEndEmailTemplate
@@ -105,6 +107,12 @@ export class SubscriptionTrialWilEndEmailTemplate
       userDid,
     });
 
+    const customActions = getSubscriptionNotificationCustomActions(
+      subscription,
+      'customer.subscription.trial_will_end',
+      locale
+    );
+
     return {
       locale,
       productName,
@@ -120,6 +128,7 @@ export class SubscriptionTrialWilEndEmailTemplate
 
       viewSubscriptionLink,
       paymentMethod,
+      customActions,
     };
   }
 
@@ -163,6 +172,7 @@ export class SubscriptionTrialWilEndEmailTemplate
       duration,
       paymentMethod,
       viewSubscriptionLink,
+      customActions,
     } = await this.getContext();
 
     // 如果当前时间大于试用结束时间，那么不发送通知
@@ -295,6 +305,7 @@ export class SubscriptionTrialWilEndEmailTemplate
           title: translate('notification.common.viewSubscription', locale),
           link: viewSubscriptionLink,
         },
+        ...customActions,
       ].filter(Boolean),
     };
 

package/api/src/libs/notification/template/subscription-upgraded.ts

@@ -19,7 +19,7 @@ import { getCustomerInvoicePageUrl } from '../../invoice';
 import { getMainProductName } from '../../product';
 import { getCustomerSubscriptionPageUrl } from '../../subscription';
 import { formatTime, getPrettyMsI18nLocale } from '../../time';
-import { getExplorerLink } from '../../util';
+import { getExplorerLink, getSubscriptionNotificationCustomActions } from '../../util';
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';
 
 export interface SubscriptionUpgradedEmailTemplateOptions {
@@ -41,6 +41,7 @@ interface SubscriptionUpgradedEmailTemplateContext {
   viewInvoiceLink: string;
   viewTxHashLink: string | undefined;
   skipInvoice: boolean;
+  customActions: any[];
 }
 
 export class SubscriptionUpgradedEmailTemplate implements BaseEmailTemplate<SubscriptionUpgradedEmailTemplateContext> {
@@ -131,6 +132,12 @@ export class SubscriptionUpgradedEmailTemplate implements BaseEmailTemplate<Subs
         chainHost,
       });
 
+    const customActions = getSubscriptionNotificationCustomActions(
+      subscription,
+      'customer.subscription.upgraded',
+      locale
+    );
+
     return {
       locale,
       productName,
@@ -148,6 +155,7 @@ export class SubscriptionUpgradedEmailTemplate implements BaseEmailTemplate<Subs
       viewInvoiceLink,
       viewTxHashLink,
       skipInvoice,
+      customActions,
     };
   }
 
@@ -167,6 +175,7 @@ export class SubscriptionUpgradedEmailTemplate implements BaseEmailTemplate<Subs
       viewInvoiceLink,
       viewTxHashLink,
       skipInvoice,
+      customActions,
     } = await this.getContext();
 
     const template: BaseEmailTemplateType = {
@@ -275,6 +284,7 @@ export class SubscriptionUpgradedEmailTemplate implements BaseEmailTemplate<Subs
             title: translate('notification.common.viewTxHash', locale),
             link: viewTxHashLink,
           },
+        ...customActions,
       ].filter(Boolean),
     };
 

package/api/src/libs/notification/template/subscription-will-canceled.ts

@@ -14,6 +14,7 @@ import { getMainProductName } from '../../product';
 import { getCustomerSubscriptionPageUrl } from '../../subscription';
 import { formatTime } from '../../time';
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';
+import { getSubscriptionNotificationCustomActions } from '../../util';
 
 export interface SubscriptionWillCanceledEmailTemplateOptions {
   subscriptionId: string;
@@ -33,6 +34,7 @@ interface SubscriptionWillCanceledEmailTemplateContext {
 
   viewSubscriptionLink: string;
   viewInvoiceLink: string;
+  customActions: any[];
 }
 
 export class SubscriptionWillCanceledEmailTemplate
@@ -91,6 +93,11 @@ export class SubscriptionWillCanceledEmailTemplate
       action: 'pay',
     });
 
+    const customActions = getSubscriptionNotificationCustomActions(
+      subscription,
+      'customer.subscription.will_canceled',
+      locale
+    );
     return {
       locale,
       productName,
@@ -102,6 +109,7 @@ export class SubscriptionWillCanceledEmailTemplate
 
       viewSubscriptionLink,
       viewInvoiceLink,
+      customActions,
     };
   }
 
@@ -142,6 +150,7 @@ export class SubscriptionWillCanceledEmailTemplate
 
       viewSubscriptionLink,
       viewInvoiceLink,
+      customActions,
     } = await this.getContext();
 
     // 如果当前时间大于订阅终止时间，那么不发送通知
@@ -223,6 +232,7 @@ export class SubscriptionWillCanceledEmailTemplate
           title: translate('notification.common.renewNow', locale),
           link: viewInvoiceLink,
         },
+        ...customActions,
       ].filter(Boolean),
     };
 

package/api/src/libs/notification/template/subscription-will-renew.ts

@@ -22,7 +22,7 @@ import { getPaymentAmountForCycleSubscription, type PaymentDetail } from '../../
 import { getMainProductName } from '../../product';
 import { getCustomerSubscriptionPageUrl } from '../../subscription';
 import { formatTime, getPrettyMsI18nLocale } from '../../time';
-import { getExplorerLink } from '../../util';
+import { getExplorerLink, getSubscriptionNotificationCustomActions } from '../../util';
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';
 
 export interface SubscriptionWillRenewEmailTemplateOptions {
@@ -49,6 +49,7 @@ interface SubscriptionWillRenewEmailTemplateContext {
   viewSubscriptionLink: string;
   addFundsLink: string;
   paymentMethod: PaymentMethod | null;
+  customActions: any[];
 }
 
 export class SubscriptionWillRenewEmailTemplate
@@ -145,6 +146,11 @@ export class SubscriptionWillRenewEmailTemplate
       },
     })!;
 
+    const customActions = getSubscriptionNotificationCustomActions(
+      subscription,
+      'customer.subscription.will_renew',
+      locale
+    );
     return {
       locale,
       productName,
@@ -162,6 +168,7 @@ export class SubscriptionWillRenewEmailTemplate
       viewSubscriptionLink,
       addFundsLink,
       paymentMethod,
+      customActions,
     };
   }
   async getPaymentCategory({ subscriptionId }: { subscriptionId: string }): Promise<{
@@ -249,6 +256,7 @@ export class SubscriptionWillRenewEmailTemplate
       viewSubscriptionLink,
       addFundsLink,
       paymentMethod,
+      customActions,
     } = await this.getContext();
 
     // 如果当前时间大于预计扣费时间，那么不发送通知
@@ -423,6 +431,7 @@ export class SubscriptionWillRenewEmailTemplate
           title: translate('notification.common.viewSubscription', locale),
           link: viewSubscriptionLink,
         },
+        ...customActions,
       ].filter(Boolean),
     };
 

package/api/src/libs/notification/template/usage-report-empty.ts

@@ -0,0 +1,158 @@
+import prettyMsI18n from 'pretty-ms-i18n';
+import { getOwnerDid } from '../../util';
+import { translate } from '../../../locales';
+import { Subscription } from '../../../store/models';
+import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';
+import { getUserLocale } from '../../../integrations/blocklet/notification';
+import { formatTime, getPrettyMsI18nLocale } from '../../time';
+import { getMainProductName } from '../../product';
+import { checkUsageReportEmpty, getAdminSubscriptionPageUrl } from '../../subscription';
+
+export interface UsageReportEmptyEmailTemplateOptions {
+  subscriptionId: string;
+  usageReportStart: number;
+  usageReportEnd: number;
+}
+
+interface UsageReportEmptyEmailTemplateContext {
+  locale: string;
+  userDid: string;
+  productName: string;
+  subscriptionId: string;
+  currentPeriodStart: string;
+  currentPeriodEnd: string;
+  viewSubscriptionLink: string;
+  duration: string;
+}
+
+export class UsageReportEmptyEmailTemplate implements BaseEmailTemplate<UsageReportEmptyEmailTemplateContext> {
+  options: UsageReportEmptyEmailTemplateOptions;
+
+  constructor(options: UsageReportEmptyEmailTemplateOptions) {
+    this.options = options;
+  }
+
+  async getContext(): Promise<UsageReportEmptyEmailTemplateContext> {
+    const { usageReportStart, usageReportEnd, subscriptionId } = this.options;
+    const subscription: Subscription | null = await Subscription.findByPk(subscriptionId);
+    if (!subscription) {
+      throw new Error(`Subscription not found: ${subscriptionId}`);
+    }
+    const userDid = await getOwnerDid();
+    if (!userDid) {
+      throw new Error('get owner did failed');
+    }
+    const usageReportEmpty = await checkUsageReportEmpty(subscription, usageReportStart, usageReportEnd);
+    if (!usageReportEmpty) {
+      throw new Error('Usage report is not empty, no need to send email');
+    }
+    const locale = await getUserLocale(userDid);
+    const productName = await getMainProductName(subscription.id);
+    const currentPeriodStart = formatTime(subscription.current_period_start * 1000);
+    const currentPeriodEnd = formatTime(subscription.current_period_end * 1000);
+    const duration: string = prettyMsI18n(
+      new Date(currentPeriodEnd).getTime() - new Date(currentPeriodStart).getTime(),
+      {
+        locale: getPrettyMsI18nLocale(locale),
+      }
+    );
+    const viewSubscriptionLink = getAdminSubscriptionPageUrl({
+      subscriptionId: subscription.id,
+      locale,
+      userDid,
+    });
+    return {
+      userDid,
+      locale,
+      productName,
+      subscriptionId: subscription.id,
+      currentPeriodStart,
+      currentPeriodEnd,
+      viewSubscriptionLink,
+      duration,
+    };
+  }
+
+  async getTemplate(): Promise<BaseEmailTemplateType> {
+    const {
+      locale,
+      productName,
+      subscriptionId,
+      currentPeriodStart,
+      currentPeriodEnd,
+      viewSubscriptionLink,
+      duration,
+    } = await this.getContext();
+
+    const template: BaseEmailTemplateType = {
+      title: translate('notification.usageReportEmpty.title', locale, {
+        productName,
+      }),
+      body: translate('notification.usageReportEmpty.body', locale, {
+        productName,
+      }),
+      attachments: [
+        {
+          type: 'section',
+          fields: [
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                color: '#9397A1',
+                text: translate('notification.common.product', locale),
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                text: productName,
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                color: '#9397A1',
+                text: translate('notification.common.subscriptionId', locale),
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                text: subscriptionId,
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                color: '#9397A1',
+                text: translate('notification.common.validityPeriod', locale),
+              },
+            },
+            {
+              type: 'text',
+              data: {
+                type: 'plain',
+                text: `${currentPeriodStart} ~ ${currentPeriodEnd}(${duration})`,
+              },
+            },
+          ].filter(Boolean),
+        },
+      ],
+      // @ts-ignore
+      actions: [
+        {
+          name: translate('notification.common.viewSubscription', locale),
+          title: translate('notification.common.viewSubscription', locale),
+          link: viewSubscriptionLink,
+        },
+      ].filter(Boolean),
+    };
+
+    return template;
+  }
+}

package/api/src/libs/subscription.ts

@@ -49,6 +49,40 @@ export function getCustomerSubscriptionPageUrl({
   );
 }
 
+export function getAdminSubscriptionPageUrl({
+  subscriptionId,
+  locale = 'en',
+  userDid,
+}: {
+  subscriptionId: string;
+  locale: LiteralUnion<'en' | 'zh', string>;
+  userDid: string;
+}) {
+  return component.getUrl(
+    withQuery(`admin/billing/${subscriptionId}`, {
+      locale,
+      ...getConnectQueryParam({ userDid }),
+    })
+  );
+}
+
+export function getAdminInvoicePageUrl({
+  invoiceId,
+  locale = 'en',
+  userDid,
+}: {
+  invoiceId: string;
+  locale: LiteralUnion<'en' | 'zh', string>;
+  userDid: string;
+}) {
+  return component.getUrl(
+    withQuery(`admin/billing/${invoiceId}`, {
+      locale,
+      ...getConnectQueryParam({ userDid }),
+    })
+  );
+}
+
 export function parseIntegerConfig(alternatives: any[], defaultValue: number) {
   for (const raw of alternatives) {
     const days = parseInt(raw, 10);
@@ -909,3 +943,36 @@ export async function getSubscriptionStakeAmountSetup(subscription: Subscription
   logger.info('get subscription stake amount setup success', { txHash, amountRes });
   return amountRes;
 }
+
+// check if usage report is empty
+export async function checkUsageReportEmpty(
+  subscription: Subscription,
+  usageReportStart: number,
+  usageReportEnd: number
+) {
+  const subscriptionItems = await SubscriptionItem.findAll({ where: { subscription_id: subscription.id } });
+  const expandedItems = await Price.expand(
+    subscriptionItems.map((x) => ({ id: x.id, price_id: x.price_id, quantity: x.quantity })),
+    { product: true }
+  );
+  const meteredItems = expandedItems.filter((x: any) => x?.price?.recurring?.usage_type === 'metered');
+  if (meteredItems.length === 0) {
+    return false;
+  }
+  const usageReportEmpty = await Promise.all(
+    meteredItems.map(async (x: any) => {
+      const usageRecords = await UsageRecord.findAll({
+        where: {
+          subscription_item_id: x.id,
+          billed: false,
+          timestamp: {
+            [Op.gt]: usageReportStart,
+            [Op.lte]: usageReportEnd,
+          },
+        },
+      });
+      return usageRecords.length === 0;
+    })
+  );
+  return usageReportEmpty.every(Boolean);
+}

package/api/src/libs/util.ts

@@ -10,6 +10,8 @@ import { joinURL, withQuery } from 'ufo';
 
 import dayjs from './dayjs';
 import { blocklet, wallet } from './auth';
+import type { Subscription } from '../store/models';
+import logger from './logger';
 
 export const OCAP_PAYMENT_TX_TYPE = 'fg:t:transfer_v2';
 
@@ -289,3 +291,31 @@ export function getCustomerProfileUrl({
     })
   );
 }
+
+export async function getOwnerDid() {
+  try {
+    const { user } = await blocklet.getOwner();
+    return user?.did;
+  } catch (error) {
+    logger.error('getOwnerDid error', error);
+    return undefined;
+  }
+}
+
+export function getSubscriptionNotificationCustomActions(
+  subscription: Subscription,
+  eventType: string,
+  locale: string
+) {
+  if (!subscription || !subscription?.service_actions || !subscription?.service_actions?.length) {
+    return [];
+  }
+  const actions = subscription.service_actions?.filter(
+    (x: any) => x?.type === 'notification' && x?.triggerEvents?.includes(eventType)
+  );
+  return actions?.map((x: any) => ({
+    name: x?.name || x?.text?.[locale],
+    title: x?.text?.[locale],
+    link: x?.link,
+  }));
+}

package/api/src/locales/en.ts

@@ -45,6 +45,14 @@ export default flat({
       qty: '{count} unit',
       failReason: 'Failure reason',
       balanceReminder: 'Balance reminder',
+      subscriptionId: 'Subscription ID',
+      shouldPayAmount: 'Should pay amount',
+      billedAmount: 'Billed amount',
+    },
+
+    billingDiscrepancy: {
+      title: '{productName} billing discrepancy',
+      body: 'Detected billing discrepancy for {productName}, please check.',
     },
 
     sendTo: 'Sent to',
@@ -53,6 +61,11 @@ export default flat({
       message: 'A new {collection} NFT is minted and sent to your wallet, please check it out.',
     },
 
+    usageReportEmpty: {
+      title: 'No usage report for {productName}',
+      body: 'No usage report for {productName} detected, please check.',
+    },
+
     subscriptionTrialStart: {
       title: 'Welcome to the start of your {productName} trial',
       body: 'Congratulations on your {productName} trial! The length of the trial is {trialDuration} and will end at {subscriptionTrialEnd}. Have fun with {productName}!',

package/api/src/locales/zh.ts

@@ -45,6 +45,9 @@ export default flat({
       qty: '{count} 件',
       failReason: '失败原因',
       balanceReminder: '余额提醒',
+      subscriptionId: '订阅 ID',
+      shouldPayAmount: '应收金额',
+      billedAmount: '实缴金额',
     },
 
     sendTo: '发送给',
@@ -53,6 +56,16 @@ export default flat({
       message: '{collection} NFT 已经铸造完成并发送到你的钱包，请查收',
     },
 
+    usageReportEmpty: {
+      title: '{productName} 未上报用量',
+      body: '检测到 {productName} 未上报用量，请留意。',
+    },
+
+    billingDiscrepancy: {
+      title: '{productName} 账单金额核算不一致',
+      body: '检测到 {productName} 账单金额核算不一致，请留意。',
+    },
+
     subscriptionTrialStart: {
       title: '欢迎开始您的 {productName} 试用之旅',
       body: '恭喜您获得了 {productName} 的试用资格！试用期时长为 {trialDuration}，将于 {subscriptionTrialEnd} 结束。祝您使用愉快！',

package/api/src/queues/invoice.ts

@@ -1,5 +1,6 @@
 import { Op } from 'sequelize';
 
+import { getInvoiceShouldPayTotal } from '../libs/invoice';
 import { batchHandleStripeInvoices } from '../integrations/stripe/resource';
 import { createEvent } from '../libs/audit';
 import dayjs from '../libs/dayjs';
@@ -12,6 +13,7 @@ import { Subscription } from '../store/models/subscription';
 import { paymentQueue } from './payment';
 
 import { getLock } from '../libs/lock';
+import { events } from '../libs/event';
 
 type InvoiceJob = {
   invoiceId: string;
@@ -240,3 +242,19 @@ export const startInvoiceQueue = async () => {
 invoiceQueue.on('failed', ({ id, job, error }) => {
   logger.error('Invoice job failed', { id, job, error });
 });
+
+events.on('invoice.paid', async ({ id: invoiceId }) => {
+  const invoice = await Invoice.findByPk(invoiceId);
+  if (!invoice) {
+    logger.error('Invoice not found', { invoiceId });
+    return;
+  }
+  const checkBillingReason = ['subscription_cycle', 'subscription_cancel'];
+  if (checkBillingReason.includes(invoice.billing_reason)) {
+    const shouldPayTotal = await getInvoiceShouldPayTotal(invoice);
+    if (shouldPayTotal !== invoice.total) {
+      createEvent('Invoice', 'billing.discrepancy', invoice);
+      logger.info('create billing discrepancy event', { invoiceId, shouldPayTotal, invoiceTotal: invoice.total });
+    }
+  }
+});

package/api/src/queues/notification.ts

@@ -57,6 +57,14 @@ import {
 } from '../libs/notification/template/subscription-stake-slash-succeeded';
 import createQueue from '../libs/queue';
 import { CheckoutSession, EventType, Invoice, PaymentLink, Refund, Subscription } from '../store/models';
+import {
+  UsageReportEmptyEmailTemplate,
+  UsageReportEmptyEmailTemplateOptions,
+} from '../libs/notification/template/usage-report-empty';
+import {
+  BillingDiscrepancyEmailTemplate,
+  BillingDiscrepancyEmailTemplateOptions,
+} from '../libs/notification/template/billing-discrepancy';
 
 export type NotificationQueueJobOptions = any;
 
@@ -65,7 +73,9 @@ export type NotificationQueueJobType =
   | 'customer.subscription.will_renew'
   | 'customer.subscription.trial_will_end'
   | 'customer.subscription.will_canceled'
-  | 'customer.reward.succeeded';
+  | 'customer.reward.succeeded'
+  | 'usage.report.empty'
+  | 'billing.discrepancy';
 
 export type NotificationQueueJob = {
   type: NotificationQueueJobType;
@@ -73,6 +83,12 @@ export type NotificationQueueJob = {
 };
 
 function getNotificationTemplate(job: NotificationQueueJob): BaseEmailTemplate {
+  if (job.type === 'usage.report.empty') {
+    return new UsageReportEmptyEmailTemplate(job.options as UsageReportEmptyEmailTemplateOptions);
+  }
+  if (job.type === 'billing.discrepancy') {
+    return new BillingDiscrepancyEmailTemplate(job.options as BillingDiscrepancyEmailTemplateOptions);
+  }
   if (job.type === 'customer.subscription.started') {
     return new SubscriptionSucceededEmailTemplate(job.options as SubscriptionSucceededEmailTemplateOptions);
   }
@@ -275,4 +291,30 @@ export async function startNotificationQueue() {
       },
     });
   });
+
+  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,
+        },
+      },
+    });
+  });
+
+  events.on('billing.discrepancy', (invoice: Invoice) => {
+    notificationQueue.push({
+      id: `billing.discrepancy.${invoice.id}`,
+      job: {
+        type: 'billing.discrepancy',
+        options: {
+          invoiceId: invoice.id,
+        },
+      },
+    });
+  });
 }