payment-kit 1.19.0 → 1.19.2

package/api/src/libs/payment.ts

@@ -19,6 +19,8 @@ import {
   TCustomer,
   TLineItemExpanded,
   Payout,
+  CreditGrant,
+  Customer,
 } from '../store/models';
 import type { TPaymentCurrency } from '../store/models/payment-currency';
 import { blocklet, ethWallet, wallet, getVaultAddress } from './auth';
@@ -26,6 +28,7 @@ import logger from './logger';
 import { getBlockletJson, getUserOrAppInfo, OCAP_PAYMENT_TX_TYPE, resolveAddressChainTypes } from './util';
 import { CHARGE_SUPPORTED_CHAIN_TYPES, EVM_CHAIN_TYPES } from './constants';
 import { getTokenByAddress } from '../integrations/arcblock/stake';
+import { isCreditMetered } from './session';
 
 export interface SufficientForPaymentResult {
   sufficient: boolean;
@@ -38,6 +41,10 @@ export interface SufficientForPaymentResult {
     | 'NO_TOKEN'
     | 'NO_ENOUGH_ALLOWANCE'
     | 'NO_ENOUGH_TOKEN'
+    | 'NO_CUSTOMER'
+    | 'NO_CREDIT_GRANTS'
+    | 'NO_ENOUGH_CREDIT'
+    | 'CREDIT_CHECK_ERROR'
     | 'NOT_SUPPORTED',
     string
   >;
@@ -139,12 +146,61 @@ export async function checkTokenBalance(args: {
   };
 }
 
+export async function isCreditGrantSufficientForPayment(args: {
+  paymentMethod: PaymentMethod;
+  paymentCurrency: TPaymentCurrency;
+  userDid: string;
+  amount: string;
+  lineItems?: TLineItemExpanded[];
+}): Promise<SufficientForPaymentResult> {
+  const { paymentMethod, paymentCurrency, userDid, amount, lineItems } = args;
+  if (paymentMethod.type === 'arcblock' && paymentCurrency.type === 'credit') {
+    const customer = await Customer.findOne({ where: { did: userDid } });
+    if (!customer) {
+      return { sufficient: false, reason: 'NO_CUSTOMER' };
+    }
+
+    const priceIds: string[] = [];
+    if (lineItems && lineItems.length > 0) {
+      lineItems.forEach((item) => {
+        if (isCreditMetered(item.price)) {
+          priceIds.push(item.price_id);
+        }
+      });
+    }
+
+    const creditSummary = await CreditGrant.getEffectiveCreditSummary({
+      customerId: customer.id,
+      currencyId: paymentCurrency.id,
+      priceIds,
+    });
+    if (!creditSummary) {
+      return { sufficient: false, reason: 'NO_CREDIT_GRANTS' };
+    }
+    const availableCredit = new BN(creditSummary[paymentCurrency.id]?.remainingAmount || '0');
+    if (availableCredit.lt(new BN(amount))) {
+      return { sufficient: false, reason: 'NO_ENOUGH_CREDIT' };
+    }
+
+    return {
+      sufficient: true,
+      token: { address: paymentCurrency.id, balance: availableCredit.toString() },
+      requestedAmount: amount,
+    };
+  }
+  return {
+    sufficient: false,
+    reason: 'NOT_SUPPORTED',
+  };
+}
+
 export async function isDelegationSufficientForPayment(args: {
   paymentMethod: PaymentMethod;
   paymentCurrency: TPaymentCurrency;
   userDid: string;
   amount: string;
   delegatorAmounts?: string[];
+  lineItems?: TLineItemExpanded[];
 }): Promise<SufficientForPaymentResult> {
   const { paymentCurrency, paymentMethod, userDid, amount, delegatorAmounts } = args;
   const tokenAddress = paymentCurrency.contract as string;
@@ -156,6 +212,19 @@ export async function isDelegationSufficientForPayment(args: {
   }
 
   if (paymentMethod.type === 'arcblock') {
+    // Check if this is a credit currency type
+    if (paymentCurrency.type === 'credit') {
+      const result = await isCreditGrantSufficientForPayment({
+        paymentMethod,
+        paymentCurrency,
+        userDid,
+        amount,
+        lineItems: args.lineItems,
+      });
+      return result;
+    }
+
+    // Regular token handling for non-credit currencies
     // user have bond wallet did?
     const { user } = await blocklet.getUser(userDid, { enableConnectedAccount: true });
     const delegator = getWalletDid(user);

package/api/src/libs/queue/index.ts

@@ -8,6 +8,7 @@ import { nanoid } from 'nanoid';
 import { AsyncLocalStorage } from 'async_hooks';
 import logger from '../logger';
 import { sleep, tryWithTimeout } from '../util';
+import dayjs from '../dayjs';
 import createQueueStore from './store';
 import { Job } from '../../store/models/job';
 import { sequelize } from '../../store/sequelize';
@@ -112,6 +113,7 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
       queueEvents.emit(e, data);
       jobEvents.emit(e, data);
     };
+    const now = dayjs().unix();
 
     if (!job) {
       throw new Error('Can not queue empty job');
@@ -119,7 +121,7 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
 
     const jobId = getJobId(id, job);
 
-    if (delay || runAt) {
+    if ((delay && delay >= MIN_DELAY) || (runAt && runAt > now)) {
       if (!enableScheduledJob) {
         throw new Error('Must set options.enableScheduledJob to true to run delay jobs');
       }
@@ -135,7 +137,6 @@ export default function createQueue<T = any>({ name, onJob, options = defaults }
         attrs.will_run_at = Date.now() + delay * 1000;
       }
       if (runAt) {
-        // 如果 runAt 大于当前时间，则延迟执行，否则直接执行
         attrs.delay = 1;
         attrs.will_run_at = runAt * 1000;
       }

package/api/src/libs/session.ts

@@ -975,3 +975,11 @@ export async function getSubscriptionLineItems(
 
   return subItems;
 }
+
+export function isCreditMetered(price: TPrice | TPriceExpanded) {
+  return price.type === 'recurring' && price.recurring?.usage_type === 'metered' && !!price.recurring?.meter_id;
+}
+
+export function isCreditMeteredLineItems(lineItems: TLineItemExpanded[]) {
+  return lineItems.every((item) => item.price && isCreditMetered(item.price));
+}

package/api/src/libs/subscription.ts

@@ -189,15 +189,76 @@ export function getSubscriptionStakeSetup(items: TLineItemExpanded[], currencyId
   return staking;
 }
 
-export function getSubscriptionCycleSetup(recurring: PriceRecurring, previousPeriodEnd: number) {
+export function getSubscriptionCycleSetup(
+  recurring: PriceRecurring,
+  previousPeriodEnd: number,
+  options?: {
+    catchUp?: boolean;
+    maxMissedPeriods?: number;
+  }
+) {
   const cycle = getRecurringPeriod(recurring);
+  const now = dayjs().unix();
+
+  // Basic setup without catch-up
+  if (!options?.catchUp) {
+    return {
+      recurring,
+      cycle,
+      period: {
+        start: previousPeriodEnd,
+        end: dayjs.unix(previousPeriodEnd).add(cycle, 'millisecond').unix(),
+      },
+      missedPeriods: 0,
+    };
+  }
+
+  // Calculate missed periods if catch-up is enabled
+  const expectedEnd = dayjs.unix(previousPeriodEnd).add(cycle, 'millisecond').unix();
+
+  if (now <= expectedEnd) {
+    // No catch-up needed
+    return {
+      recurring,
+      cycle,
+      period: {
+        start: previousPeriodEnd,
+        end: expectedEnd,
+      },
+      missedPeriods: 0,
+    };
+  }
+
+  // Calculate how many periods we've missed
+  const timeSinceExpected = now - expectedEnd;
+  const cycleInSeconds = cycle / 1000;
+  const missedPeriods = Math.floor(timeSinceExpected / cycleInSeconds);
+  const maxMissedPeriods = options.maxMissedPeriods || 100; // Default limit to prevent excessive catch-up
+
+  const actualMissedPeriods = Math.min(missedPeriods, maxMissedPeriods);
+
+  // Calculate the current period we should be in
+  const currentPeriodStart = dayjs
+    .unix(previousPeriodEnd)
+    .add((actualMissedPeriods + 1) * cycle, 'millisecond')
+    .unix();
+  const currentPeriodEnd = dayjs.unix(currentPeriodStart).add(cycle, 'millisecond').unix();
 
   return {
     recurring,
     cycle,
     period: {
-      start: previousPeriodEnd,
-      end: dayjs.unix(previousPeriodEnd).add(cycle, 'millisecond').unix(),
+      start: currentPeriodStart,
+      end: currentPeriodEnd,
+    },
+    missedPeriods: actualMissedPeriods,
+    // Additional info for recovery handling
+    recovery: {
+      originalPeriodEnd: previousPeriodEnd,
+      expectedPeriodEnd: expectedEnd,
+      timeMissed: timeSinceExpected,
+      periodsSkipped: actualMissedPeriods,
+      wasLimited: missedPeriods > maxMissedPeriods,
     },
   };
 }
@@ -1627,3 +1688,13 @@ export function calculateRecommendedRechargeAmount(subscriptions: any[], currenc
     interval: recommendedInterval,
   };
 }
+
+export async function getMeterPriceIdsFromSubscription(subscription: Subscription): Promise<string[]> {
+  const subscriptionItems = (await SubscriptionItem.findAll({
+    where: { subscription_id: subscription.id },
+    include: [{ model: Price, as: 'price' }],
+  })) as (SubscriptionItem & { price: Price })[];
+
+  const meterItems = subscriptionItems.filter((x) => x.price.recurring?.meter_id);
+  return meterItems.map((m) => m.price.id);
+}

package/api/src/libs/util.ts

@@ -12,6 +12,7 @@ import { joinURL, withQuery, withTrailingSlash } from 'ufo';
 import axios from 'axios';
 import { ethers } from 'ethers';
 import { fromUnitToToken } from '@ocap/util';
+import get from 'lodash/get';
 import dayjs from './dayjs';
 import { blocklet, wallet } from './auth';
 import type { PaymentCurrency, PaymentMethod, Subscription } from '../store/models';
@@ -268,11 +269,12 @@ export async function getUserOrAppInfo(
   }
   const { user } = await blocklet.getUser(address);
   if (user) {
+    const locale = get(user, 'locale', 'en');
     return {
       name: user?.fullName,
       avatar: joinURL(process.env.BLOCKLET_APP_URL!, user?.avatar),
       type: 'user',
-      url: getCustomerProfileUrl({ userDid: address, locale: 'en' }),
+      url: getCustomerProfileUrl({ userDid: address, locale }),
     };
   }
   return {

package/api/src/libs/ws.ts

@@ -1,6 +1,14 @@
 import { sendToRelay } from '@blocklet/sdk/service/notification';
 import { publish } from '@blocklet/sdk/service/eventbus';
-import type { CheckoutSession, Invoice, PaymentIntent, Subscription, Refund } from '../store/models';
+import type {
+  CheckoutSession,
+  Invoice,
+  PaymentIntent,
+  Subscription,
+  Refund,
+  CreditGrant,
+  Customer,
+} from '../store/models';
 import { events } from './event';
 
 export function broadcast(eventName: string, data: any, extraParams?: Record<string, any>) {
@@ -93,4 +101,18 @@ export function initEventBroadcast() {
   events.on('manual.notification', (data: Record<string, any>) => {
     broadcast('manual.notification', data);
   });
+
+  // credit
+  events.on('customer.credit_grant.granted', (data: CreditGrant, extraParams?: Record<string, any>) => {
+    broadcast('customer.credit_grant.granted', data, extraParams);
+  });
+  events.on('customer.credit_grant.low_balance', (data: CreditGrant, extraParams?: Record<string, any>) => {
+    broadcast('customer.credit_grant.low_balance', data, extraParams);
+  });
+  events.on('customer.credit_grant.depleted', (data: CreditGrant, extraParams?: Record<string, any>) => {
+    broadcast('customer.credit_grant.depleted', data, extraParams);
+  });
+  events.on('customer.credit.insufficient', (data: Customer, extraParams?: Record<string, any>) => {
+    broadcast('customer.credit.insufficient', data, extraParams);
+  });
 }

package/api/src/locales/en.ts

@@ -48,6 +48,7 @@ export default flat({
       subscriptionId: 'Subscription ID',
       shouldPayAmount: 'Should pay amount',
       billedAmount: 'Billed amount',
+      viewCreditGrant: 'View Credit Balance',
     },
 
     billingDiscrepancy: {
@@ -217,5 +218,37 @@ export default flat({
       title: '{count} Subscriptions Renewed',
       body: 'During {startTime} - {endTime}, {count} subscriptions were successfully renewed, total amount: {totalAmount}.\n\nSubscription List:\n{subscriptionList}',
     },
+
+    creditInsufficient: {
+      title: 'Insufficient Credit',
+      bodyWithSubscription:
+        'Your available credit is only {availableAmount}, which is not enough to cover your subscription to {subscriptionName}. Please top up to avoid service interruption.',
+      bodyWithoutSubscription:
+        'Your available credit is only {availableAmount}, which is not enough to continue using the service. Please top up to avoid restrictions.',
+      exhaustedTitle: 'Credit Exhausted – Please Top Up',
+      exhaustedBodyWithSubscription:
+        'Your credit is fully exhausted and can no longer cover your subscription to {subscriptionName}. Please top up to avoid service interruption.',
+      exhaustedBodyWithoutSubscription:
+        'Your credit is fully exhausted (remaining balance: 0). Please top up to ensure uninterrupted service.',
+      meterEventName: 'Service',
+      availableCredit: 'Available Credit',
+      requiredCredit: 'Required Credit',
+      topUpNow: 'Top Up Now',
+    },
+
+    creditGrantGranted: {
+      title: 'Congratulations! Your granted credit is now active',
+      body: 'You have been granted {grantedAmount} credit, activated on {at}, valid until {expiresAt}. Enjoy your service!',
+      bodyNoExpire: 'You have been granted {grantedAmount} credit, activated on {at}. Enjoy your service!',
+      grantedCredit: 'Granted Credit',
+      validUntil: 'Valid Until',
+      neverExpires: 'Never Expires',
+    },
+
+    creditGrantLowBalance: {
+      title: 'Low Granted Credit Balance Warning',
+      body: 'Your granted credit balance is below 10%. Current available credit is {availableAmount}. Please top up or contact support to avoid service interruption.',
+      totalGrantedCredit: 'Total Granted Credit',
+    },
   },
 });

package/api/src/locales/zh.ts

@@ -48,6 +48,7 @@ export default flat({
       subscriptionId: '订阅 ID',
       shouldPayAmount: '应收金额',
       billedAmount: '实缴金额',
+      viewCreditGrant: '查看额度',
     },
 
     sendTo: '发送给',
@@ -211,5 +212,35 @@ export default flat({
       title: '{count} 个订阅续费成功',
       body: '在 {startTime} - {endTime} 期间，共有 {count} 个订阅成功续费，总金额：{totalAmount}。\n\n订阅清单：\n{subscriptionList}',
     },
+
+    creditInsufficient: {
+      title: '额度不足，服务可能受限',
+      bodyWithSubscription:
+        '您的信用额度仅剩 {availableAmount}，不足以支付您订阅的 {subscriptionName}。请及时充值以避免服务中断。',
+      bodyWithoutSubscription: '您的信用额度仅剩 {availableAmount}，不足以继续使用服务。请及时充值以避免服务受限。',
+      exhaustedTitle: '额度已用尽，请尽快充值',
+      exhaustedBodyWithSubscription:
+        '您的信用额度已用尽，无法继续支付您订阅的 {subscriptionName}。为确保服务不中断，请及时充值。',
+      exhaustedBodyWithoutSubscription: '您的信用额度已用尽（剩余额度为 0）。为确保服务正常使用，请及时充值。',
+      meterEventName: '服务项目',
+      availableCredit: '剩余额度',
+      requiredCredit: '所需额度',
+      topUpNow: '立即充值',
+    },
+
+    creditGrantGranted: {
+      title: '恭喜！您的额度授予已激活',
+      body: '您已获得 {grantedAmount} 的额度授予，激活时间为 {at}，有效期至 {expiresAt}。祝您使用愉快！',
+      bodyNoExpire: '您已获得 {grantedAmount} 的额度授予，激活时间为 {at}。祝您使用愉快！',
+      grantedCredit: '授予额度',
+      validUntil: '有效期至',
+      neverExpires: '永不过期',
+    },
+
+    creditGrantLowBalance: {
+      title: '额度授予余额不足提醒',
+      body: '您的额度授予余额已低于 10%，当前剩余额度为 {availableAmount}。请及时充值或联系管理员以避免服务受限。',
+      totalGrantedCredit: '总授予额度',
+    },
   },
 });