payment-kit 1.19.0 → 1.19.1

package/api/src/crons/index.ts

@@ -7,6 +7,7 @@ import {
   batchHandleStripeSubscriptions,
 } from '../integrations/stripe/resource';
 import {
+  creditConsumptionCronTime,
   depositVaultCronTime,
   expiredSessionCleanupCronTime,
   meteringSubscriptionDetectionCronTime,
@@ -27,6 +28,7 @@ import { SubscriptionWillCanceledSchedule } from './subscription-will-canceled';
 import { SubscriptionWillRenewSchedule } from './subscription-will-renew';
 import { createMeteringSubscriptionDetection } from './metering-subscription-detection';
 import { startDepositVaultQueue } from '../queues/payment';
+import { startCreditConsumeQueue } from '../queues/credit-consume';
 
 function init() {
   Cron.init({
@@ -107,6 +109,12 @@ function init() {
         fn: () => startDepositVaultQueue(),
         options: { runOnInit: true },
       },
+      {
+        name: 'credit.consumption',
+        time: creditConsumptionCronTime,
+        fn: () => startCreditConsumeQueue(),
+        options: { runOnInit: true },
+      },
     ],
     onError: (error: Error, name: string) => {
       logger.error('run job failed', { name, error });

package/api/src/index.ts

@@ -28,6 +28,8 @@ import { startPaymentQueue } from './queues/payment';
 import { startPayoutQueue } from './queues/payout';
 import { startRefundQueue } from './queues/refund';
 import { startSubscriptionQueue } from './queues/subscription';
+import { startCreditConsumeQueue } from './queues/credit-consume';
+import { startCreditGrantQueue } from './queues/credit-grant';
 import routes from './routes';
 import changePaymentHandlers from './routes/connect/change-payment';
 import changePlanHandlers from './routes/connect/change-plan';
@@ -118,6 +120,8 @@ export const server = app.listen(port, (err?: any) => {
   startCheckoutSessionQueue().then(() => logger.info('checkoutSession queue started'));
   startNotificationQueue().then(() => logger.info('notification queue started'));
   startRefundQueue().then(() => logger.info('refund queue started'));
+  startCreditConsumeQueue().then(() => logger.info('credit queue started'));
+  startCreditGrantQueue().then(() => logger.info('credit grant queue started'));
   startUploadBillingInfoListener();
 
   if (process.env.BLOCKLET_MODE === 'production') {

package/api/src/libs/credit-grant.ts

@@ -0,0 +1,146 @@
+import { BN } from '@ocap/util';
+
+import { CreditGrant, Customer, PaymentCurrency, Subscription } from '../store/models';
+import { formatMetadata } from './util';
+import logger from './logger';
+import dayjs from './dayjs';
+import { getMeterPriceIdsFromSubscription } from './subscription';
+
+/**
+ * 创建 CreditGrant - 抽象重复的创建逻辑
+ * 注意：amount应该已经是Unit格式（在路由层处理fromTokenToUnit转换）
+ */
+export async function createCreditGrant(params: {
+  amount: string; // Unit格式的金额
+  currency_id?: string;
+  customer_id: string;
+  name?: string;
+  category: 'paid' | 'promotional';
+  priority?: number;
+  effective_at?: number;
+  expires_at?: number;
+  applicability_config?: {
+    scope: {
+      prices?: string[];
+      price_type?: 'metered';
+    };
+  };
+  metadata?: Record<string, any>;
+  livemode?: boolean;
+  created_via?: string;
+  created_by?: string;
+}): Promise<CreditGrant> {
+  const customer = await Customer.findByPk(params.customer_id);
+  if (!customer) {
+    throw new Error(`Customer ${params.customer_id} not found`);
+  }
+
+  const amount = new BN(params.amount);
+  if (amount.lte(new BN(0))) {
+    throw new Error('Amount must be greater than 0');
+  }
+
+  const currencyId = params.currency_id;
+  if (!currencyId) {
+    throw new Error('currency_id is required');
+  }
+
+  const now = dayjs().unix();
+  if (params.expires_at && params.expires_at < now) {
+    throw new Error('expires_at must be in the future');
+  }
+  const isEffectiveNow = !params.effective_at || params.effective_at <= now;
+  const initialStatus = isEffectiveNow ? 'granted' : 'pending';
+  const applicabilityConfig = params.applicability_config || {
+    scope: {
+      type: 'metered',
+    },
+  };
+
+  const grantData: any = {
+    amount: params.amount,
+    currency_id: currencyId,
+    customer_id: params.customer_id,
+    name: params.name,
+    category: params.category,
+    priority: params.priority || 50,
+    effective_at: params.effective_at || now,
+    expires_at: params.expires_at,
+    applicability_config: applicabilityConfig,
+    livemode: !!params.livemode,
+    created_via: params.created_via || 'api',
+    created_by: params.created_by,
+    remaining_amount: params.amount,
+    status: initialStatus,
+    metadata: formatMetadata(params.metadata),
+  };
+
+  const creditGrant = await CreditGrant.create(grantData);
+
+  logger.info('Credit grant created', {
+    grantId: creditGrant.id,
+    customerId: params.customer_id,
+    amount: params.amount,
+    currencyId,
+  });
+
+  return creditGrant;
+}
+
+export async function getCustomerCreditBalance(customerId: string, currencyId: string, subscriptionId?: string) {
+  let priceIds: string[] = [];
+  if (subscriptionId) {
+    const subscription = await Subscription.findByPk(subscriptionId);
+    if (!subscription) {
+      throw new Error(`Subscription ${subscriptionId} not found`);
+    }
+    priceIds = await getMeterPriceIdsFromSubscription(subscription);
+  }
+
+  const availableGrants = await CreditGrant.getAvailableCreditsForCustomer(customerId, currencyId, priceIds);
+
+  const totalBalance = availableGrants
+    .reduce((sum, grant) => sum.add(new BN(grant.remaining_amount)), new BN(0))
+    .toString();
+
+  const paymentCurrency = await PaymentCurrency.findByPk(currencyId);
+
+  return {
+    customer_id: customerId,
+    currency_id: currencyId,
+    paymentCurrency,
+    totalBalance,
+    availableGrants,
+  };
+}
+
+export function calculateExpiresAt(validDurationValue: number, validDurationUnit: string): number | undefined {
+  if (!validDurationValue || validDurationValue <= 0) {
+    return undefined;
+  }
+
+  const now = dayjs();
+  let expiresAt: dayjs.Dayjs;
+
+  switch (validDurationUnit) {
+    case 'hours':
+      expiresAt = now.add(validDurationValue, 'hour');
+      break;
+    case 'days':
+      expiresAt = now.add(validDurationValue, 'day');
+      break;
+    case 'weeks':
+      expiresAt = now.add(validDurationValue, 'week');
+      break;
+    case 'months':
+      expiresAt = now.add(validDurationValue, 'month');
+      break;
+    case 'years':
+      expiresAt = now.add(validDurationValue, 'year');
+      break;
+    default:
+      expiresAt = now.add(validDurationValue, 'day');
+  }
+
+  return expiresAt.unix();
+}

package/api/src/libs/env.ts

@@ -13,6 +13,7 @@ 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 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 执行一次
 // sequelize 配置相关
 export const sequelizeOptionsPoolMin: number = process.env.SEQUELIZE_OPTIONS_POOL_MIN
   ? +process.env.SEQUELIZE_OPTIONS_POOL_MIN

package/api/src/libs/invoice.ts

@@ -543,7 +543,7 @@ export async function ensureInvoiceAndItems({
   // apply possible balance to invoice
   let remaining = props.total;
   let result = { starting: {}, ending: {} };
-  if (applyCredit && props.total > '0') {
+  if (applyCredit && props.total > '0' && !props.amount_remaining) {
     const balance = customer.getBalanceToApply(currency.id, props.total);
     result = await customer.decreaseTokenBalance(currency.id, balance);
     remaining = new BN(props.total).sub(new BN(balance)).toString();
@@ -1053,8 +1053,9 @@ export async function retryUncollectibleInvoices(options: {
     };
 
     const settledResults = await Promise.allSettled(
-      overdueInvoices.map(async (invoice) => {
+      overdueInvoices.map(async (invoice, index) => {
         const { paymentIntent } = invoice;
+        const delay = index * 2;
         if (!paymentIntent) {
           throw new Error('No payment intent found');
         }
@@ -1064,7 +1065,7 @@ export async function retryUncollectibleInvoices(options: {
           'payment.queued',
           paymentIntent.id,
           { paymentIntentId: paymentIntent.id, retryOnError: true, ignoreMaxRetryCheck: true },
-          { sync: false }
+          { sync: false, delay }
         );
 
         return invoice;

package/api/src/libs/notification/template/base.ts

@@ -1,14 +1,400 @@
 import type { TNotification, TNotificationInput } from '@blocklet/sdk/lib/types/notification';
+import prettyMsI18n from 'pretty-ms-i18n';
+import { getUserLocale } from '../../../integrations/blocklet/notification';
+import { translate } from '../../../locales';
+import {
+  Customer,
+  PaymentMethod,
+  Subscription,
+  PaymentCurrency,
+  Invoice,
+  CheckoutSession,
+  NFTMintChainType,
+  NftMintItem,
+} from '../../../store/models';
+import { getMainProductName } from '../../product';
+import { getCustomerSubscriptionPageUrl } from '../../subscription';
+import { getCustomerInvoicePageUrl } from '../../invoice';
+import { formatTime, getPrettyMsI18nLocale } from '../../time';
+import { formatCurrencyInfo, getSubscriptionNotificationCustomActions } from '../../util';
 
 export type BaseEmailTemplateType = TNotificationInput | TNotification;
+
 export type BaseEmailTemplateContext = {
   userDid: string;
 };
 
 export interface BaseEmailTemplate<C = BaseEmailTemplateContext> {
   getTemplate(): Promise<BaseEmailTemplateType | null>;
-
   getContext(): Promise<C>;
-
   options: Record<string, any>;
 }
+
+// 基础订阅数据接口
+export interface BaseSubscriptionData {
+  subscription: Subscription;
+  customer: Customer;
+  userDid: string;
+  locale: string;
+  productName: string;
+  paymentCurrency: PaymentCurrency;
+  isCreditSubscription: boolean;
+}
+
+// 链接生成结果接口
+export interface SubscriptionLinks {
+  viewSubscriptionLink: string;
+  viewInvoiceLink?: string;
+  viewTxHashLink?: string;
+  customActions: any[];
+}
+
+// NFT 信息接口
+export interface NftInfo {
+  hasNft: boolean;
+  nftMintItem?: NftMintItem;
+  chainHost?: string;
+}
+
+// 支付信息接口
+export interface PaymentInfo {
+  paymentMethod?: PaymentMethod;
+  paymentInfo: string;
+  invoice?: Invoice;
+}
+
+// 抽象基类
+export abstract class BaseSubscriptionEmailTemplate<C extends BaseEmailTemplateContext = BaseEmailTemplateContext>
+  // eslint-disable-next-line prettier/prettier
+  implements BaseEmailTemplate<C> {
+  abstract options: Record<string, any>;
+
+  abstract getContext(): Promise<C>;
+  abstract getTemplate(): Promise<BaseEmailTemplateType | null>;
+
+  // 1. 基础数据获取逻辑
+  protected async getSubscriptionBasicData(subscriptionId: string): Promise<BaseSubscriptionData> {
+    const subscription = await this.validateSubscriptionExists(subscriptionId);
+    const customer = await this.validateCustomerExists(subscription.customer_id);
+
+    const userDid = customer.did;
+    const locale = await getUserLocale(userDid);
+    const productName = await getMainProductName(subscription.id);
+    const paymentCurrency = (await PaymentCurrency.findOne({
+      where: { id: subscription.currency_id },
+    })) as PaymentCurrency;
+
+    const isCreditSubscription = await this.isCreditSubscription(subscription, paymentCurrency);
+
+    return {
+      subscription,
+      customer,
+      userDid,
+      locale,
+      productName,
+      paymentCurrency,
+      isCreditSubscription,
+    };
+  }
+
+  // 2. Credit 订阅检测
+  protected async isCreditSubscription(
+    subscription: Subscription,
+    paymentCurrency?: PaymentCurrency
+  ): Promise<boolean> {
+    let currency = paymentCurrency;
+    if (!currency) {
+      currency = (await PaymentCurrency.findOne({
+        where: { id: subscription.currency_id },
+      })) as PaymentCurrency;
+    }
+
+    const isConsumesCredit = await subscription.isConsumesCredit();
+    return isConsumesCredit && currency.type === 'credit';
+  }
+
+  // 3. 支付信息处理（根据 Credit 订阅条件处理）
+  protected async getPaymentInfo(
+    subscription: Subscription,
+    paymentCurrency: PaymentCurrency,
+    isCreditSubscription: boolean,
+    invoiceId?: string
+  ): Promise<PaymentInfo> {
+    const paymentMethod = (await PaymentMethod.findByPk(paymentCurrency.payment_method_id)) as PaymentMethod;
+    if (isCreditSubscription) {
+      // Credit 订阅不需要显示支付信息
+      return {
+        paymentInfo: '',
+        paymentMethod,
+        invoice: undefined,
+      };
+    }
+
+    // 非 Credit 订阅需要获取发票和支付信息
+    const invoice = invoiceId
+      ? await Invoice.findByPk(invoiceId)
+      : await Invoice.findByPk(subscription.latest_invoice_id);
+
+    if (!invoice) {
+      throw new Error(`Invoice not found for subscription: ${subscription.id}`);
+    }
+
+    const paymentInfo = formatCurrencyInfo(invoice.total, paymentCurrency, paymentMethod);
+
+    return {
+      paymentMethod,
+      paymentInfo,
+      invoice,
+    };
+  }
+
+  // 4. 链接生成逻辑
+  protected generateSubscriptionLinks(
+    subscription: Subscription,
+    locale: string,
+    userDid: string,
+    actionType: string,
+    invoiceId?: string,
+    isCreditSubscription: boolean = false
+  ): SubscriptionLinks {
+    const viewSubscriptionLink = getCustomerSubscriptionPageUrl({
+      subscriptionId: subscription.id,
+      locale,
+      userDid,
+    });
+
+    // Credit 订阅不显示发票链接
+    const viewInvoiceLink =
+      !isCreditSubscription && invoiceId
+        ? getCustomerInvoicePageUrl({
+            invoiceId,
+            userDid,
+            locale,
+          })
+        : undefined;
+
+    const customActions = getSubscriptionNotificationCustomActions(subscription, actionType, locale);
+
+    return {
+      viewSubscriptionLink,
+      viewInvoiceLink,
+      customActions,
+    };
+  }
+
+  // 5. NFT 信息获取
+  protected async getNftMintInfo(subscriptionId: string): Promise<NftInfo> {
+    const checkoutSession = await CheckoutSession.findBySubscriptionId(subscriptionId);
+    const hasNft = checkoutSession?.nft_mint_status === 'minted';
+
+    const nftMintItem = hasNft
+      ? checkoutSession?.nft_mint_details?.[checkoutSession?.nft_mint_details?.type as NFTMintChainType]
+      : undefined;
+
+    return {
+      hasNft,
+      nftMintItem,
+    };
+  }
+
+  // 6. 时间和持续时间处理
+  protected formatSubscriptionPeriod(
+    startTime: number,
+    endTime: number,
+    locale: string
+  ): {
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    duration: string;
+  } {
+    const currentPeriodStart = formatTime(startTime * 1000);
+    const currentPeriodEnd = formatTime(endTime * 1000);
+    const duration = prettyMsI18n(new Date(currentPeriodEnd).getTime() - new Date(currentPeriodStart).getTime(), {
+      locale: getPrettyMsI18nLocale(locale),
+    });
+
+    return {
+      currentPeriodStart,
+      currentPeriodEnd,
+      duration,
+    };
+  }
+
+  // 7. 模板字段构建 - 基础字段
+  protected buildCommonFields(userDid: string, productName: string, locale: string): any[] {
+    return [
+      {
+        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.product', locale),
+        },
+      },
+      {
+        type: 'text',
+        data: {
+          type: 'plain',
+          text: productName,
+        },
+      },
+    ];
+  }
+
+  // 支付金额字段（Credit 订阅时不显示）
+  protected buildPaymentField(paymentInfo: string, locale: string, isCreditSubscription: boolean): any[] {
+    if (isCreditSubscription) {
+      return [];
+    }
+
+    return [
+      {
+        type: 'text',
+        data: {
+          type: 'plain',
+          color: '#9397A1',
+          text: translate('notification.common.paymentAmount', locale),
+        },
+      },
+      {
+        type: 'text',
+        data: {
+          type: 'plain',
+          text: paymentInfo,
+        },
+      },
+    ];
+  }
+
+  // 有效期字段（Credit 订阅时不显示）
+  protected buildPeriodField(
+    currentPeriodStart: string,
+    currentPeriodEnd: string,
+    duration: string,
+    locale: string,
+    isCreditSubscription: boolean
+  ): any[] {
+    if (isCreditSubscription) {
+      return [];
+    }
+
+    return [
+      {
+        type: 'text',
+        data: {
+          type: 'plain',
+          color: '#9397A1',
+          text: translate('notification.common.validityPeriod', locale),
+        },
+      },
+      {
+        type: 'text',
+        data: {
+          type: 'plain',
+          text: `${currentPeriodStart} ~ ${currentPeriodEnd}(${duration})`,
+        },
+      },
+    ];
+  }
+
+  // 8. 模板操作按钮构建
+  protected buildCommonActions(
+    viewSubscriptionLink: string,
+    viewInvoiceLink: string | undefined,
+    locale: string,
+    isCreditSubscription: boolean,
+    customActions: any[] = []
+  ): any[] {
+    const actions = [
+      {
+        name: translate('notification.common.viewSubscription', locale),
+        title: translate('notification.common.viewSubscription', locale),
+        link: viewSubscriptionLink,
+      },
+    ];
+
+    // Credit 订阅不显示发票链接
+    if (!isCreditSubscription && viewInvoiceLink) {
+      actions.push({
+        name: translate('notification.common.viewInvoice', locale),
+        title: translate('notification.common.viewInvoice', locale),
+        link: viewInvoiceLink,
+      });
+    }
+
+    return [...actions, ...customActions].filter(Boolean);
+  }
+
+  // 9. 错误处理方法
+  protected async validateSubscriptionExists(subscriptionId: string): Promise<Subscription> {
+    const subscription = await Subscription.findByPk(subscriptionId);
+    if (!subscription) {
+      throw new Error(`Subscription not found: ${subscriptionId}`);
+    }
+    return subscription;
+  }
+
+  protected async validateCustomerExists(customerId: string): Promise<Customer> {
+    const customer = await Customer.findByPk(customerId);
+    if (!customer) {
+      throw new Error(`Customer not found: ${customerId}`);
+    }
+    return customer;
+  }
+
+  // 10. Credit 订阅条件判断辅助方法
+  protected shouldShowPaymentAmount(isCreditSubscription: boolean): boolean {
+    return !isCreditSubscription;
+  }
+
+  protected shouldShowPeriod(isCreditSubscription: boolean): boolean {
+    return !isCreditSubscription;
+  }
+
+  protected shouldShowInvoiceLink(isCreditSubscription: boolean): boolean {
+    return !isCreditSubscription;
+  }
+
+  // 11. 字段和操作过滤方法
+  protected filterFieldsForCredit(fields: any[], isCreditSubscription: boolean): any[] {
+    if (!isCreditSubscription) {
+      return fields;
+    }
+
+    // 移除支付相关字段
+    return fields.filter((field) => {
+      const text = field?.data?.text;
+      return (
+        !text ||
+        (!text.includes('notification.common.paymentAmount') && !text.includes('notification.common.validityPeriod'))
+      );
+    });
+  }
+
+  protected filterActionsForCredit(actions: any[], isCreditSubscription: boolean): any[] {
+    if (!isCreditSubscription) {
+      return actions;
+    }
+
+    // 移除发票相关操作
+    return actions.filter((action) => {
+      const name = action?.name;
+      return !name || !name.includes('notification.common.viewInvoice');
+    });
+  }
+}