payment-kit 1.19.17 → 1.19.19

package/api/src/index.ts

@@ -43,6 +43,7 @@ import delegationHandlers from './routes/connect/delegation';
 import overdraftProtectionHandlers from './routes/connect/overdraft-protection';
 import rechargeAccountHandlers from './routes/connect/recharge-account';
 import reStakeHandlers from './routes/connect/re-stake';
+import autoRechargeAuthorizationHandlers from './routes/connect/auto-recharge-auth';
 import { initialize } from './store/models';
 import { sequelize } from './store/sequelize';
 import { initUserHandler } from './integrations/blocklet/user';
@@ -84,6 +85,7 @@ handlers.attach(Object.assign({ app: router }, rechargeAccountHandlers));
 handlers.attach(Object.assign({ app: router }, delegationHandlers));
 handlers.attach(Object.assign({ app: router }, overdraftProtectionHandlers));
 handlers.attach(Object.assign({ app: router }, reStakeHandlers));
+handlers.attach(Object.assign({ app: router }, autoRechargeAuthorizationHandlers));
 router.use('/api', routes);
 
 const isProduction = process.env.BLOCKLET_MODE === 'production';
@@ -99,7 +101,7 @@ if (isProduction) {
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 app.use(<ErrorRequestHandler>((err, req, res, _next) => {
-  logger.error(err);
+  logger.error('handle router error', err);
   if (err instanceof CustomError) {
     res.status(getStatusFromError(err)).json({ error: formatError(err) });
     return;

package/api/src/integrations/ethereum/tx.ts

@@ -78,3 +78,14 @@ export function broadcastEvmTransaction(checkoutSessionId: string, status: strin
     });
   }
 }
+
+export function broadcastAutoRechargeEvmTransaction(autoRechargeConfigId: string, status: string, claims: any[]) {
+  const claim = claims.find((x) => x.type === 'signature');
+  if (claim?.hash) {
+    broadcast('auto_recharge.evm_transaction', {
+      id: autoRechargeConfigId,
+      txHash: claim.hash,
+      status,
+    });
+  }
+}

package/api/src/integrations/stripe/handlers/invoice.ts

@@ -9,6 +9,7 @@ import { createEvent } from '../../../libs/audit';
 import { getLock } from '../../../libs/lock';
 import logger from '../../../libs/logger';
 import {
+  AutoRechargeConfig,
   CheckoutSession,
   Customer,
   Invoice,
@@ -110,6 +111,9 @@ export async function ensureStripeInvoice(stripeInvoice: any, subscription: Subs
   await lock.acquire();
 
   const customer = await Customer.findByPk(subscription.customer_id);
+  if (!customer) {
+    throw new Error('Customer not found');
+  }
   const checkoutSession = await CheckoutSession.findBySubscriptionId(subscription.id);
 
   let invoice = await Invoice.findOne({ where: { 'metadata.stripe_id': stripeInvoice.id } });
@@ -118,10 +122,10 @@ export async function ensureStripeInvoice(stripeInvoice: any, subscription: Subs
     return invoice;
   }
 
+  const invoiceNumber = await customer.getInvoiceNumber();
   // @ts-ignore
   invoice = await Invoice.create({
-    // @ts-ignore
-    number: await customer.getInvoiceNumber(),
+    number: invoiceNumber,
     ...pick(stripeInvoice, [
       'amount_due',
       'amount_paid',
@@ -313,9 +317,12 @@ export async function handleInvoiceEvent(event: TEventExpanded, client: Stripe)
 
   // in case we missed some of the events
   const subscriptionId = event.data.object.subscription_details?.metadata?.id;
-  const appPid = event.data.object.subscription_details?.metadata?.appPid;
+  const subscriptionAppPid = event.data.object.subscription_details?.metadata?.appPid;
+  const autoRechargeConfigId = event.data.object.metadata?.recharge_id;
+
   if (!localInvoiceId) {
-    if (subscriptionId && appPid && appPid === env.appPid) {
+    // Handle subscription invoices
+    if (subscriptionId && subscriptionAppPid && subscriptionAppPid === env.appPid) {
       logger.warn('try mirror invoice from stripe', { invoiceId: event.data.object.id });
       const subscription = await Subscription.findByPk(subscriptionId);
       if (subscription) {
@@ -332,7 +339,7 @@ export async function handleInvoiceEvent(event: TEventExpanded, client: Stripe)
         logger.error('wait for stripe invoice mirror error', { id: event.id, type: event.type, error: err });
       }
 
-      logger.warn('local invoice id not found in strip event', { id: event.id, type: event.type });
+      logger.warn('local invoice id not found in stripe event', { id: event.id, type: event.type });
       return;
     }
   }
@@ -390,12 +397,25 @@ export async function handleInvoiceEvent(event: TEventExpanded, client: Stripe)
 
   const failedEvents = ['invoice.marked_uncollectible', 'invoice.finalization_failed', 'invoice.payment_failed'];
   if (failedEvents.includes(event.type)) {
-    logger.info('Invoice failed', { invoiceId: invoice.id });
+    logger.info('invoice finalized and failed', { invoiceId: invoice.id });
+    // Handle subscription payment failures
     if (invoice.subscription_id) {
       const subscription = await Subscription.findByPk(invoice.subscription_id);
       if (subscription) {
         handleSubscriptionOnPaymentFailure(subscription, event.type, client);
       }
     }
+    if (autoRechargeConfigId && invoice) {
+      const autoRechargeConfig = await AutoRechargeConfig.findByPk(autoRechargeConfigId);
+      if (autoRechargeConfig) {
+        autoRechargeConfig.update({
+          enabled: false,
+          metadata: {
+            ...autoRechargeConfig.metadata,
+            failReason: `Payment failed: ${event.type}`,
+          },
+        });
+      }
+    }
   }
 }

package/api/src/integrations/stripe/handlers/setup-intent.ts

@@ -1,8 +1,15 @@
 import type Stripe from 'stripe';
 
 import logger from '../../../libs/logger';
-import { CheckoutSession, Lock, SetupIntent, Subscription, TEventExpanded } from '../../../store/models';
-import { updateGroupSubscriptionsPaymentMethod } from '../resource';
+import {
+  AutoRechargeConfig,
+  CheckoutSession,
+  Lock,
+  SetupIntent,
+  Subscription,
+  TEventExpanded,
+} from '../../../store/models';
+import { updateGroupSubscriptionsPaymentMethod, updateAutoRechargeConfigPaymentMethod } from '../resource';
 import { getCheckoutSessionSubscriptionIds } from '../../../libs/session';
 
 async function handleSubscriptionOnSetupSucceeded(event: TEventExpanded, stripeIntentId: string) {
@@ -119,6 +126,30 @@ async function handleCheckoutSessionOnSetupSucceeded(event: TEventExpanded, stri
   }
 }
 
+async function handleAutoRechargeOnSetupSucceeded(event: TEventExpanded, stripeIntentId: string) {
+  const autoRechargeConfig = await AutoRechargeConfig.findOne({
+    where: { 'payment_details.stripe.setup_intent_id': stripeIntentId },
+  });
+  if (!autoRechargeConfig) {
+    logger.warn('local auto recharge config not found for setup intent', {
+      id: event.id,
+      type: event.type,
+      stripeIntentId,
+    });
+    return;
+  }
+
+  if (event.type === 'setup_intent.succeeded') {
+    const stripePaymentMethod = event.data.object.payment_method;
+    if (stripePaymentMethod) {
+      await updateAutoRechargeConfigPaymentMethod({
+        stripePaymentMethodId: stripePaymentMethod,
+        autoRechargeConfig,
+      });
+    }
+  }
+}
+
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export async function handleSetupIntentEvent(event: TEventExpanded, _: Stripe) {
   const stripeIntentId = event.data.object.id;
@@ -127,4 +158,5 @@ export async function handleSetupIntentEvent(event: TEventExpanded, _: Stripe) {
   await handleSubscriptionOnSetupSucceeded(event, stripeIntentId);
   await handleSetupIntentOnSetupSucceeded(event, stripeIntentId);
   await handleCheckoutSessionOnSetupSucceeded(event, stripeIntentId);
+  await handleAutoRechargeOnSetupSucceeded(event, stripeIntentId);
 }

package/api/src/integrations/stripe/resource.ts

@@ -11,9 +11,11 @@ import { getPriceUintAmountByCurrency } from '../../libs/session';
 import { getSubscriptionItemPrice } from '../../libs/subscription';
 import { sleep } from '../../libs/util';
 import {
+  AutoRechargeConfig,
   CheckoutSession,
   Customer,
   Invoice,
+  InvoiceItem,
   PaymentCurrency,
   PaymentIntent,
   PaymentMethod,
@@ -208,7 +210,6 @@ export async function ensureStripePaymentIntent(
   let stripeIntent = null;
   if (internal.payment_details?.stripe?.payment_intent_id) {
     stripeIntent = await client.paymentIntents.retrieve(internal.payment_details.stripe.payment_intent_id);
-    // FIXME: update?
   } else {
     const customer = await ensureStripePaymentCustomer(internal, method);
     stripeIntent = await client.paymentIntents.create({
@@ -570,6 +571,94 @@ export async function batchHandleStripePayments() {
   }
 }
 
+export async function ensureStripeSetupIntentForAutoRecharge(
+  customer: Customer,
+  method: PaymentMethod,
+  autoRechargeConfig: AutoRechargeConfig,
+  forceReauthorize: boolean = false
+) {
+  const client = method.getStripeClient();
+  if (autoRechargeConfig.payment_details?.stripe?.setup_intent_id && !forceReauthorize) {
+    const setupIntent = await client.setupIntents.retrieve(autoRechargeConfig.payment_details.stripe.setup_intent_id);
+    return setupIntent;
+  }
+  const stripeCustomer = await ensureStripeCustomer(customer, method);
+
+  const setupIntent = await client.setupIntents.create({
+    customer: stripeCustomer.id,
+    payment_method_types: ['card'],
+    usage: 'off_session',
+    metadata: {
+      appPid: env.appPid,
+      auto_recharge_config_id: autoRechargeConfig.id,
+      customer_id: customer.id,
+    },
+  });
+
+  logger.info('stripe setup intent created for auto recharge', {
+    customerId: customer.id,
+    autoRechargeConfigId: autoRechargeConfig.id,
+    setupIntentId: setupIntent.id,
+  });
+
+  return setupIntent;
+}
+
+export async function updateAutoRechargeConfigPaymentMethod(params: {
+  stripePaymentMethodId: string;
+  autoRechargeConfig: AutoRechargeConfig;
+}) {
+  const { stripePaymentMethodId, autoRechargeConfig } = params;
+
+  try {
+    const paymentMethod = await PaymentMethod.findByPk(autoRechargeConfig.payment_method_id);
+    if (!paymentMethod) {
+      throw new Error(`Payment method not found: ${autoRechargeConfig.payment_method_id}`);
+    }
+
+    const customer = await Customer.findByPk(autoRechargeConfig.customer_id);
+    if (!customer) {
+      throw new Error(`Customer not found: ${autoRechargeConfig.customer_id}`);
+    }
+
+    const stripeClient = paymentMethod.getStripeClient();
+
+    const stripePaymentMethod = await stripeClient.paymentMethods.retrieve(stripePaymentMethodId);
+
+    const paymentSettings = {
+      payment_method_types: ['stripe'],
+      payment_method_options: {
+        ...(autoRechargeConfig.payment_settings?.payment_method_options || {}),
+        stripe: {
+          payer: stripePaymentMethodId,
+          card_last4: stripePaymentMethod.card?.last4,
+          card_brand: stripePaymentMethod.card?.brand,
+          exp_time: `${stripePaymentMethod.card?.exp_month}/${stripePaymentMethod.card?.exp_year}`,
+        },
+      },
+    };
+
+    await autoRechargeConfig.update({
+      payment_settings: paymentSettings,
+      payment_details: {
+        ...autoRechargeConfig.payment_details,
+        stripe: {
+          ...(autoRechargeConfig.payment_details?.stripe || {}),
+          payment_method_id: stripePaymentMethodId,
+        },
+      },
+    });
+    return autoRechargeConfig;
+  } catch (error: any) {
+    logger.error('Failed to update auto recharge config payment method', {
+      error: error.message,
+      configId: autoRechargeConfig.id,
+      paymentMethod: stripePaymentMethodId,
+    });
+    throw error;
+  }
+}
+
 export async function updateGroupSubscriptionsPaymentMethod(params: {
   stripePaymentMethodId: string;
   subscriptionIds: string[];
@@ -623,3 +712,98 @@ export async function updateGroupSubscriptionsPaymentMethod(params: {
     throw error;
   }
 }
+
+export async function createStripeInvoiceForAutoRecharge(params: {
+  autoRechargeConfig: AutoRechargeConfig;
+  customer: Customer;
+  paymentMethod: PaymentMethod;
+  currency: PaymentCurrency;
+  invoice: Invoice;
+}) {
+  const { autoRechargeConfig, customer, paymentMethod, currency, invoice } = params;
+  const client = paymentMethod.getStripeClient();
+
+  const stripePaymentMethodId = autoRechargeConfig.payment_settings?.payment_method_options?.stripe?.payer;
+  if (!stripePaymentMethodId) {
+    throw new Error('Stripe payment method not found');
+  }
+
+  try {
+    // Ensure stripe customer exists
+    const stripeCustomer = await ensureStripeCustomer(customer, paymentMethod);
+
+    const stripeInvoice = await client.invoices.create({
+      customer: stripeCustomer.id,
+      currency: currency.symbol.toLowerCase(),
+      description: invoice.description || 'Auto recharge',
+      collection_method: 'charge_automatically',
+      auto_advance: true,
+      default_payment_method: stripePaymentMethodId,
+      metadata: {
+        appPid: env.appPid,
+        recharge_id: autoRechargeConfig.id,
+        id: invoice.id,
+      },
+    });
+
+    logger.info('Stripe invoice created for auto recharge', {
+      stripeInvoiceId: stripeInvoice.id,
+      customerId: customer.id,
+    });
+
+    // Create invoice items from local invoice items
+    const invoiceItems = await InvoiceItem.findAll({ where: { invoice_id: invoice.id } });
+    for (const item of invoiceItems) {
+      const price = await Price.findByPk(item.price_id);
+      if (!price) {
+        continue;
+      }
+      const stripePrice = await ensureStripePrice(price as Price, paymentMethod, currency);
+      await client.invoiceItems.create({
+        customer: stripeCustomer.id,
+        invoice: stripeInvoice.id,
+        price: stripePrice.id,
+        quantity: item.quantity,
+        description: item.description || price.nickname || '',
+        metadata: {
+          appPid: env.appPid,
+          invoice_item_id: item.id,
+        },
+      });
+
+      logger.info('Stripe invoice item created', {
+        localItemId: item.id,
+        stripeInvoiceId: stripeInvoice.id,
+        priceId: price.id,
+        quantity: item.quantity,
+      });
+    }
+
+    // Finalize and pay the invoice automatically
+    const finalizedInvoice = await client.invoices.finalizeInvoice(stripeInvoice.id);
+    logger.info('Stripe invoice finalized', {
+      localInvoiceId: invoice.id,
+      stripeInvoiceId: stripeInvoice.id,
+    });
+
+    // Attempt automatic payment
+    if (finalizedInvoice.status === 'open') {
+      const paidInvoice = await client.invoices.pay(stripeInvoice.id);
+      logger.info('Stripe invoice payment attempted', {
+        localInvoiceId: invoice.id,
+        stripeInvoiceId: stripeInvoice.id,
+        status: paidInvoice.status,
+      });
+      return paidInvoice;
+    }
+
+    return finalizedInvoice;
+  } catch (error: any) {
+    logger.error('Failed to create Stripe invoice for auto recharge', {
+      localInvoiceId: invoice.id,
+      customerId: customer.id,
+      error,
+    });
+    throw error;
+  }
+}

package/api/src/libs/invoice.ts

@@ -437,6 +437,7 @@ async function createInvoiceWithItems(props: BaseInvoiceProps): Promise<{
     ...extraProps
   } = props;
 
+  const invoiceNumber = await customer.getInvoiceNumber();
   // create invoice
   const invoice = await Invoice.create({
     amount_shipping: '0',
@@ -453,7 +454,7 @@ async function createInvoiceWithItems(props: BaseInvoiceProps): Promise<{
     collection_method: 'charge_automatically',
     ...extraProps,
     livemode,
-    number: await customer.getInvoiceNumber(),
+    number: invoiceNumber,
     description,
     statement_descriptor: statementDescriptor,
     period_start: periodStart,

package/api/src/libs/notification/template/customer-credit-low-balance.ts

@@ -0,0 +1,155 @@
+/* eslint-disable @typescript-eslint/brace-style */
+/* eslint-disable @typescript-eslint/indent */
+import { fromUnitToToken } from '@ocap/util';
+import { getUserLocale } from '../../../integrations/blocklet/notification';
+import { translate } from '../../../locales';
+import { Customer, PaymentCurrency } from '../../../store/models';
+import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';
+import { formatNumber, getCustomerIndexUrl } from '../../util';
+
+export interface CustomerCreditLowBalanceEmailTemplateOptions {
+  customerId: string;
+  currencyId: string;
+  availableAmount: string; // unit amount
+  totalAmount: string; // unit amount
+  percentage: string; // 0-100 number string
+}
+
+interface CustomerCreditLowBalanceEmailTemplateContext {
+  locale: string;
+  userDid: string;
+  currencySymbol: string;
+  availableAmount: string; // formatted with symbol
+  totalAmount: string; // formatted with symbol
+  lowBalancePercentage: string; // with %
+  currencyName: string;
+}
+export class CustomerCreditLowBalanceEmailTemplate
+  implements BaseEmailTemplate<CustomerCreditLowBalanceEmailTemplateContext>
+{
+  options: CustomerCreditLowBalanceEmailTemplateOptions;
+
+  constructor(options: CustomerCreditLowBalanceEmailTemplateOptions) {
+    this.options = options;
+  }
+
+  async getContext(): Promise<CustomerCreditLowBalanceEmailTemplateContext> {
+    const { customerId, currencyId, availableAmount, totalAmount, percentage } = this.options;
+
+    const customer = await Customer.findByPk(customerId);
+    if (!customer) {
+      throw new Error(`Customer not found: ${customerId}`);
+    }
+
+    const paymentCurrency = await PaymentCurrency.findByPk(currencyId);
+    if (!paymentCurrency) {
+      throw new Error(`PaymentCurrency not found: ${currencyId}`);
+    }
+
+    const userDid = customer.did;
+    const locale = await getUserLocale(userDid);
+    const currencySymbol = paymentCurrency.symbol;
+
+    const available = formatNumber(fromUnitToToken(availableAmount, paymentCurrency.decimal));
+    const total = formatNumber(fromUnitToToken(totalAmount, paymentCurrency.decimal));
+
+    return {
+      locale,
+      userDid,
+      currencySymbol,
+      availableAmount: `${available}`,
+      totalAmount: `${total}`,
+      lowBalancePercentage: `${percentage}%`,
+      currencyName: paymentCurrency.name,
+    };
+  }
+
+  async getTemplate(): Promise<BaseEmailTemplateType> {
+    const context = await this.getContext();
+    const { locale, userDid, availableAmount, totalAmount, lowBalancePercentage, currencyName, currencySymbol } =
+      context;
+
+    const fields = [
+      {
+        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.creditInsufficient.availableCredit', locale),
+        },
+      },
+      {
+        type: 'text',
+        data: {
+          type: 'plain',
+          color: '#FF6600',
+          text: `${availableAmount} ${currencySymbol} (${lowBalancePercentage})`,
+        },
+      },
+      {
+        type: 'text',
+        data: {
+          type: 'plain',
+          color: '#9397A1',
+          text: translate('notification.creditLowBalance.totalAmount', locale),
+        },
+      },
+      {
+        type: 'text',
+        data: {
+          type: 'plain',
+          text: `${totalAmount} ${currencySymbol}`,
+        },
+      },
+    ];
+
+    const actions = [
+      {
+        name: translate('notification.common.viewCreditGrant', locale),
+        title: translate('notification.common.viewCreditGrant', locale),
+        link: getCustomerIndexUrl({
+          locale,
+          userDid,
+        }),
+      },
+    ];
+
+    const template: BaseEmailTemplateType = {
+      title: translate('notification.creditLowBalance.title', locale, {
+        lowBalancePercentage,
+        currency: currencyName,
+      }),
+      body: translate('notification.creditLowBalance.body', locale, {
+        currency: currencyName,
+        availableAmount,
+        totalAmount,
+        lowBalancePercentage,
+      }),
+      attachments: [
+        {
+          type: 'section',
+          fields,
+        },
+      ],
+      // @ts-ignore
+      actions,
+    };
+
+    return template;
+  }
+}

package/api/src/libs/session.ts

@@ -296,7 +296,7 @@ export function getFastCheckoutAmount(
 
   const { total, renew } = getCheckoutAmount(items, currencyId, trialing);
 
-  if (mode === 'payment') {
+  if (mode === 'payment' || mode === 'auto-recharge-auth') {
     return total;
   }
 
@@ -984,6 +984,11 @@ export function isCreditMeteredLineItems(lineItems: TLineItemExpanded[]) {
   return lineItems.every((item) => item.price && isCreditMetered(item.price));
 }
 
+export function validateStripePaymentAmounts(amount: string, currency: PaymentCurrency) {
+  const minAmountInUnits = fromTokenToUnit(0.5, currency.decimal);
+  return new BN(amount).gte(new BN(minAmountInUnits)); // 0.5 USD
+}
+
 /**
  * Validates payment amounts meet minimum requirements
  * @param lineItems Line items to validate

package/api/src/libs/ws.ts

@@ -106,8 +106,9 @@ export function initEventBroadcast() {
   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.low_balance', (data: Customer, extraParams?: Record<string, any>) => {
+    broadcast('customer.credit.low_balance', data, extraParams);
   });
   events.on('customer.credit_grant.depleted', (data: CreditGrant, extraParams?: Record<string, any>) => {
     broadcast('customer.credit_grant.depleted', data, extraParams);

package/api/src/locales/en.ts

@@ -241,8 +241,8 @@ export default flat({
       exhaustedBodyWithoutSubscription:
         'Your credit is fully exhausted (remaining balance: 0). Please top up to ensure uninterrupted service.',
       meterEventName: 'Service',
-      availableCredit: 'Available Credit',
-      requiredCredit: 'Required Credit',
+      availableCredit: 'Available Credit Amount',
+      requiredCredit: 'Required Credit Amount',
       topUpNow: 'Top Up Now',
     },
 
@@ -255,10 +255,10 @@ export default flat({
       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',
+    creditLowBalance: {
+      title: 'Your {currency} is below {lowBalancePercentage}',
+      body: 'Your {currency} available balance is below {lowBalancePercentage} of the total. Please top up to avoid service interruption.',
+      totalAmount: 'Total Credit Amount',
     },
   },
 });

package/api/src/locales/zh.ts

@@ -247,10 +247,10 @@ export default flat({
       neverExpires: '永不过期',
     },
 
-    creditGrantLowBalance: {
-      title: '额度余额不足提醒',
-      body: '您的额度已低于 10%，当前剩余额度为 {availableAmount}。请及时充值或联系管理员以避免服务受限。',
-      totalGrantedCredit: '总授予额度',
+    creditLowBalance: {
+      title: '您的{currency} 已低于 {lowBalancePercentage}',
+      body: '您的 {currency} 总可用额度已低于 {lowBalancePercentage}，请及时充值以避免服务受限。',
+      totalAmount: '总额度',
     },
   },
 });