payment-kit 1.13.130 → 1.13.132

package/api/src/index.ts

@@ -21,6 +21,7 @@ import { startEventQueue } from './queues/event';
 import { startInvoiceQueue } from './queues/invoice';
 import { startNotificationQueue } from './queues/notification';
 import { startPaymentQueue } from './queues/payment';
+import { startRefundQueue } from './queues/refund';
 import { startSubscriptionQueue } from './queues/subscription';
 import routes from './routes';
 import collectHandlers from './routes/connect/collect';
@@ -108,6 +109,7 @@ export const server = app.listen(port, (err?: any) => {
   startEventQueue().then(() => logger.info('event queue started'));
   startCheckoutSessionQueue().then(() => logger.info('checkoutSession queue started'));
   startNotificationQueue().then(() => logger.info('notification queue started'));
+  startRefundQueue().then(() => logger.info('refund queue started'));
 
   if (process.env.BLOCKLET_MODE === 'production') {
     ensureWebhookRegistered().catch(console.error);

package/api/src/libs/payment.ts

@@ -104,7 +104,7 @@ export async function isDelegationSufficientForPayment(args: {
   throw new Error(`Payment method ${paymentMethod.type} not supported`);
 }
 
-export function isBalanceSufficientForPayment(args: {
+export function isCreditSufficientForPayment(args: {
   paymentMethod: PaymentMethod;
   paymentCurrency: TPaymentCurrency;
   customer: TCustomer;
@@ -255,3 +255,32 @@ export async function getTokenLimitsForDelegation(
 
   return [entry];
 }
+
+export async function isBalanceSufficientForPayment(args: {
+  paymentMethod: PaymentMethod;
+  paymentCurrency: TPaymentCurrency;
+  amount: string;
+}): Promise<SufficientForPaymentResult> {
+  const { paymentCurrency, paymentMethod, amount } = args;
+  const tokenAddress = paymentCurrency.contract as string;
+
+  if (paymentMethod.type === 'arcblock') {
+    const client = paymentMethod.getOcapClient();
+    const { tokens } = await client.getAccountTokens({ address: wallet.address, token: tokenAddress });
+    const [token] = tokens;
+    if (!token) {
+      return { sufficient: false, reason: 'NO_TOKEN' };
+    }
+    if (new BN(token.balance).lt(new BN(amount))) {
+      return { sufficient: false, reason: 'NO_ENOUGH_TOKEN', token };
+    }
+
+    return { sufficient: true, token };
+  }
+
+  if (paymentMethod.type === 'stripe') {
+    return { sufficient: false, reason: 'NOT_SUPPORTED' };
+  }
+
+  throw new Error(`Payment method ${paymentMethod.type} not supported`);
+}

package/api/src/libs/session.ts

@@ -60,13 +60,13 @@ export function getCheckoutAmount(items: TLineItemExpanded[], currencyId: string
   const total = items
     .reduce((acc, x) => {
       const price = x.upsell_price || x.price;
-      if (price.type === 'recurring') {
+      if (price?.type === 'recurring') {
         renew = renew.add(new BN(getPriceUintAmountByCurrency(price, currencyId)).mul(new BN(x.quantity)));
 
         if (includeFreeTrial) {
           return acc;
         }
-        if (price.recurring?.usage_type === 'metered') {
+        if (price?.recurring?.usage_type === 'metered') {
           return acc;
         }
       }

package/api/src/libs/subscription.ts

@@ -1,8 +1,18 @@
 import component from '@blocklet/sdk/lib/component';
 import { BN } from '@ocap/util';
 
-import type { PriceRecurring, TLineItemExpanded } from '../store/models';
+import {
+  Customer,
+  Invoice,
+  InvoiceItem,
+  Price,
+  PriceRecurring,
+  Subscription,
+  SubscriptionItem,
+  TLineItemExpanded,
+} from '../store/models';
 import dayjs from './dayjs';
+import logger from './logger';
 import { getPriceUintAmountByCurrency, getRecurringPeriod } from './session';
 
 export function getCustomerSubscriptionPageUrl(subscriptionId: string, locale: string = 'en') {
@@ -129,3 +139,126 @@ export function getSubscriptionCycleAmount(items: TLineItemExpanded[], currencyI
     total: amount.toString(),
   };
 }
+
+export async function createProration(
+  subscription: Subscription,
+  setup: ReturnType<typeof getSubscriptionCreateSetup>,
+  anchor: number
+) {
+  // FIXME: should we enforce cycle invoices here?
+  const lastInvoice = await Invoice.findByPk(subscription.latest_invoice_id);
+  if (!lastInvoice) {
+    throw new Error('Subscription should have latest invoice when create proration');
+  }
+
+  const customer = await Customer.findByPk(subscription.customer_id);
+  if (!customer) {
+    throw new Error('Subscription should have customer when create proration');
+  }
+
+  // 1. get last invoice, and invoice items, filter invoice items that are in licensed recurring mode
+  const invoiceItems = await InvoiceItem.findAll({ where: { invoice_id: lastInvoice.id, proration: false } });
+  const invoiceItemsExpanded = await Price.expand(invoiceItems.map((x) => x.toJSON()));
+  const prorationItems = invoiceItemsExpanded.filter(
+    (x) => x.price.type === 'recurring' && x.price.recurring?.usage_type === 'licensed'
+  );
+
+  // 2. calculate proration args based on the filtered invoice items
+  const precision = 10000;
+  const prorationStart = lastInvoice.period_start;
+  const prorationEnd = lastInvoice.period_end;
+  if (anchor > prorationEnd) {
+    throw new Error('Subscription proration anchor should not be larger than prorationEnd');
+  }
+
+  const prorationRate = Math.ceil(((prorationEnd - anchor) / (prorationEnd - prorationStart)) * precision);
+  let unused = new BN(0);
+  const prorations = await Promise.all(
+    prorationItems.map((x: TLineItemExpanded & { [key: string]: any }) => {
+      const unitAmount = getPriceUintAmountByCurrency(x.price, subscription.currency_id);
+      const amount = new BN(unitAmount)
+        .mul(new BN(x.quantity))
+        .mul(new BN(prorationRate))
+        .div(new BN(precision))
+        .toString();
+      logger.info('subscription proration item', {
+        subscription: subscription.id,
+        invoice: x.invoice_id,
+        invoiceItem: x.id,
+        amount,
+      });
+      unused = unused.add(new BN(amount));
+
+      return {
+        price_id: x.price_id,
+        amount: `-${amount}`,
+        quantity: x.quantity,
+        // @ts-ignore
+        description: `Unused time on ${x.price.product.name} after ${dayjs().format('lll')}`,
+        period: {
+          start: lastInvoice.period_start,
+          end: lastInvoice.period_end,
+        },
+        proration: true,
+        proration_details: {
+          credited_items: {
+            invoice_id: lastInvoice.id,
+            // @ts-ignore
+            invoice_line_items: [x.id],
+          },
+        },
+      };
+    })
+  );
+  logger.info('subscription prorations created', {
+    subscription: subscription.id,
+    prorations,
+  });
+
+  // 5. adjust invoice total && update customer token balance
+  const total = setup.amount.setup;
+  let due = setup.amount.setup;
+  let newCredit = '0';
+  let appliedCredit = '0';
+  if (new BN(total).gte(unused)) {
+    // Proration amount is less than total, all proration are used,
+    due = new BN(total).sub(unused).toString();
+    // Besides, we need to try to apply customer credit
+    appliedCredit = customer.getBalanceToApply(subscription.currency_id, due);
+    due = new BN(due).sub(new BN(appliedCredit)).toString();
+  } else {
+    // Proration amount is greater than total, we need to increase customer credit
+    newCredit = unused.sub(new BN(total)).toString();
+    due = '0';
+  }
+
+  logger.info('subscription proration result', {
+    subscription: subscription.id,
+    prorationStart,
+    prorationEnd,
+    prorationRate,
+    unused: unused.toString(),
+    total,
+    due,
+    newCredit,
+    appliedCredit,
+  });
+
+  return {
+    lastInvoice,
+    total,
+    due,
+    used: new BN(lastInvoice.amount_due).sub(unused).toString(),
+    unused: unused.toString(),
+    prorations,
+    newCredit,
+    appliedCredit,
+  };
+}
+
+export async function getSubscriptionRefundSetup(subscription: Subscription, anchor: number) {
+  const items = await SubscriptionItem.findAll({ where: { subscription_id: subscription.id } });
+  const expanded = await Price.expand(items.map((x) => x.toJSON()));
+  const setup = getSubscriptionCreateSetup(expanded, subscription.currency_id, 0);
+  return createProration(subscription, setup, anchor);
+}

package/api/src/queues/invoice.ts

@@ -94,6 +94,7 @@ export const handleInvoice = async (job: InvoiceJob) => {
       subscription_create: 'Subscription creation',
       subscription_cycle: 'Subscription cycle',
       subscription_update: 'Subscription update',
+      subscription_threshold: 'Subscription threshold',
     };
     // TODO: support partial payment from user balance
     paymentIntent = await PaymentIntent.create({

package/api/src/queues/payment.ts

@@ -329,6 +329,7 @@ export const handlePayment = async (job: PaymentJob) => {
             // @ts-ignore
             value: {
               appId: wallet.address,
+              reason: invoice ? invoice.billing_reason : 'payment',
               paymentIntentId: paymentIntent.id,
             },
           },
@@ -346,6 +347,7 @@ export const handlePayment = async (job: PaymentJob) => {
 
     await paymentIntent.update({
       status: 'succeeded',
+      last_payment_error: null,
       amount_received: paymentIntent.amount,
       payment_details: {
         arcblock: {

package/api/src/queues/refund.ts

@@ -0,0 +1,212 @@
+import { wallet } from '../libs/auth';
+import CustomError from '../libs/error';
+import { events } from '../libs/event';
+import logger from '../libs/logger';
+import { getGasPayerExtra, isBalanceSufficientForPayment } from '../libs/payment';
+import createQueue from '../libs/queue';
+import { MAX_RETRY_COUNT, getNextRetry } from '../libs/util';
+import { Customer } from '../store/models/customer';
+import { PaymentCurrency } from '../store/models/payment-currency';
+import { PaymentMethod } from '../store/models/payment-method';
+import { Refund } from '../store/models/refund';
+import type { PaymentError } from '../store/models/types';
+
+type RefundJob = {
+  refundId: string;
+  retryOnError?: boolean;
+};
+
+type Updates = {
+  retry: {
+    refund: Partial<Refund>;
+  };
+  terminate: {
+    refund: Partial<Refund>;
+  };
+};
+
+export const handleRefundFailed = (refund: Refund, error: PaymentError) => {
+  const attemptCount = refund.attempt_count + 1;
+  const updates: Updates = {
+    retry: {
+      refund: {
+        status: 'pending',
+        last_attempt_error: error,
+        attempt_count: attemptCount,
+        attempted: true,
+        next_attempt: getNextRetry(attemptCount),
+      },
+    },
+    terminate: {
+      refund: {
+        status: 'requires_action',
+        last_attempt_error: error,
+        attempt_count: attemptCount,
+        attempted: true,
+      },
+    },
+  };
+
+  // check max retry
+  if (refund.attempt_count > MAX_RETRY_COUNT) {
+    return updates.terminate;
+  }
+
+  return updates.retry;
+};
+
+export const handleRefund = async (job: RefundJob) => {
+  logger.info('handle refund', job);
+
+  const refund = await Refund.findByPk(job.refundId);
+  if (!refund) {
+    logger.warn(`refund not found: ${job.refundId}`);
+    return;
+  }
+
+  if (['pending'].includes(refund.status) === false) {
+    logger.warn(`refund status not expected: ${refund.status}`);
+    return;
+  }
+
+  // check max retry before doing any hard work
+  if (refund.attempt_count > MAX_RETRY_COUNT) {
+    logger.info(`refund transfer aborted since max retry exceeded: ${refund.id}`);
+    const updates = handleRefundFailed(refund, {
+      type: 'card_error',
+      code: 'max_retry_exceeded',
+      message: 'max_retry_exceeded',
+    });
+    await refund.update(updates.refund);
+    return;
+  }
+
+  const paymentCurrency = await PaymentCurrency.findByPk(refund.currency_id);
+  if (!paymentCurrency) {
+    logger.warn(`PaymentCurrency not found: ${refund.currency_id}`);
+    return;
+  }
+  const paymentMethod = await PaymentMethod.findByPk(paymentCurrency.payment_method_id);
+  if (!paymentMethod) {
+    logger.warn(`PaymentMethod not found: ${paymentCurrency.payment_method_id}`);
+    return;
+  }
+  const supportAutoCharge = await PaymentMethod.supportAutoCharge(paymentCurrency.payment_method_id);
+  if (supportAutoCharge === false) {
+    logger.warn(`PaymentMethod does not support auto charge: ${paymentCurrency.payment_method_id}`);
+    return;
+  }
+
+  const customer = await Customer.findByPk(refund.customer_id);
+  if (!customer) {
+    logger.warn(`Customer not found: ${refund.customer_id}`);
+    return;
+  }
+
+  // try refund transfer and reschedule on error
+  logger.info(`refund transfer attempt: ${refund.id}`);
+  let result;
+  try {
+    const client = paymentMethod.getOcapClient();
+
+    // check balance before transfer with transaction
+    result = await isBalanceSufficientForPayment({ paymentMethod, paymentCurrency, amount: refund.amount });
+    if (result.sufficient === false) {
+      logger.error('refund transfer aborted on preCheck', { id: refund.id, result });
+      throw new CustomError(result.reason, 'app balance not sufficient for this refund');
+    }
+
+    // do the transfer
+    const signed = await client.signTransferV2Tx({
+      tx: {
+        itx: {
+          to: customer.did,
+          value: '0',
+          assets: [],
+          tokens: [{ address: paymentCurrency.contract, value: refund.amount }],
+          data: {
+            typeUrl: 'json',
+            // @ts-ignore
+            value: {
+              appId: wallet.address,
+              reason: refund.reason,
+              refundId: refund.id,
+            },
+          },
+        },
+      },
+      wallet,
+    });
+    // @ts-ignore
+    const { buffer } = await client.encodeTransferV2Tx({ tx: signed });
+    // @ts-ignore
+    const txHash = await client.sendTransferV2Tx({ tx: signed, wallet }, getGasPayerExtra(buffer));
+
+    logger.info('refund transfer done', { id: refund.id, txHash });
+    await refund.update({
+      status: 'succeeded',
+      last_attempt_error: null,
+      payment_details: {
+        arcblock: {
+          tx_hash: txHash,
+          payer: wallet.address,
+        },
+      },
+    });
+  } catch (err) {
+    logger.error('refund transfer failed', { error: err, id: refund.id });
+
+    const error: PaymentError = {
+      type: 'card_error',
+      code: err.code,
+      message: err.message,
+      payment_method_id: paymentMethod.id,
+      payment_method_type: paymentMethod.type,
+    };
+
+    const updates = await handleRefundFailed(refund, error);
+    await refund.update(updates.refund);
+
+    // reschedule next attempt
+    const retryAt = updates.refund.next_attempt;
+    if (retryAt) {
+      refundQueue.push({
+        id: refund.id,
+        job: { refundId: refund.id, retryOnError: job.retryOnError },
+        runAt: retryAt,
+      });
+      logger.error('refund transfer retry scheduled', { id: refund.id, retryAt });
+    } else {
+      logger.info('refund job deleted since no retry', { id: refund.id });
+      refundQueue.delete(refund.id);
+    }
+  }
+};
+
+export const refundQueue = createQueue<RefundJob>({
+  name: 'refund',
+  onJob: handleRefund,
+  options: {
+    concurrency: 1,
+    maxRetries: 0,
+    enableScheduledJob: true,
+  },
+});
+
+export const startRefundQueue = async () => {
+  events.on('refund.created', (refund: Refund) => {
+    refundQueue.push({ id: refund.id, job: { refundId: refund.id } });
+  });
+
+  const refunds = await Refund.findAll({ where: { status: ['pending'] } });
+  refunds.forEach(async (x) => {
+    const exist = await refundQueue.get(x.id);
+    if (!exist) {
+      refundQueue.push({ id: x.id, job: { refundId: x.id } });
+    }
+  });
+};
+
+refundQueue.on('failed', ({ id, job, error }) => {
+  logger.error('refund job failed', { id, job, error });
+});

package/api/src/routes/checkout-sessions.ts

@@ -18,7 +18,7 @@ import { handleStripeSubscriptionSucceed } from '../integrations/stripe/handlers
 import { ensureStripePaymentIntent, ensureStripeSubscription } from '../integrations/stripe/resource';
 import dayjs from '../libs/dayjs';
 import logger from '../libs/logger';
-import { isBalanceSufficientForPayment, isDelegationSufficientForPayment } from '../libs/payment';
+import { isCreditSufficientForPayment, isDelegationSufficientForPayment } from '../libs/payment';
 import { authenticate } from '../libs/security';
 import {
   canUpsell,
@@ -714,7 +714,7 @@ router.put('/:id/submit', user, ensureCheckoutSessionOpen, async (req, res) => {
     };
 
     // if we can complete purchase with customer balance
-    const balance = isBalanceSufficientForPayment({
+    const balance = isCreditSufficientForPayment({
       paymentMethod,
       paymentCurrency,
       customer,

package/api/src/routes/index.ts

@@ -15,6 +15,7 @@ import prices from './prices';
 import pricingTables from './pricing-table';
 import products from './products';
 import redirect from './redirect';
+import refunds from './refunds';
 import settings from './settings';
 import subscriptionItems from './subscription-items';
 import subscriptions from './subscriptions';
@@ -57,6 +58,7 @@ router.use('/prices', prices);
 router.use('/pricing-tables', pricingTables);
 router.use('/products', products);
 router.use('/redirect', redirect);
+router.use('/refunds', refunds);
 router.use('/settings', settings);
 router.use('/subscription-items', subscriptionItems);
 router.use('/subscriptions', subscriptions);

package/api/src/routes/refunds.ts

@@ -0,0 +1,93 @@
+/* eslint-disable consistent-return */
+import { Router } from 'express';
+import Joi from 'joi';
+import type { WhereOptions } from 'sequelize';
+
+import { authenticate } from '../libs/security';
+import {
+  Customer,
+  Invoice,
+  PaymentCurrency,
+  PaymentIntent,
+  PaymentMethod,
+  Refund,
+  Subscription,
+} from '../store/models';
+
+const router = Router();
+const auth = authenticate<Refund>({ component: true, roles: ['owner', 'admin'] });
+
+const paginationSchema = Joi.object<{
+  page: number;
+  pageSize: number;
+  livemode?: boolean;
+  status?: string;
+}>({
+  page: Joi.number().integer().min(1).default(1),
+  pageSize: Joi.number().integer().min(1).max(100).default(20),
+  livemode: Joi.boolean().empty(''),
+  status: Joi.string().empty(''),
+});
+router.get('/', auth, async (req, res) => {
+  const { page, pageSize, livemode, status, ...query } = await paginationSchema.validateAsync(req.query, {
+    stripUnknown: false,
+    allowUnknown: true,
+  });
+  const where: WhereOptions<Refund> = {};
+
+  if (typeof livemode === 'boolean') {
+    where.livemode = livemode;
+  }
+  if (status) {
+    where.status = status
+      .split(',')
+      .map((x) => x.trim())
+      .filter(Boolean);
+  }
+
+  Object.keys(query)
+    .filter((x) => x.startsWith('metadata.'))
+    .forEach((key: string) => {
+      // @ts-ignore
+      where[key] = query[key];
+    });
+
+  const { rows: list, count } = await Refund.findAndCountAll({
+    where,
+    order: [['created_at', 'DESC']],
+    offset: (page - 1) * pageSize,
+    limit: pageSize,
+    include: [
+      { model: Customer, as: 'customer' },
+      { model: PaymentCurrency, as: 'paymentCurrency' },
+      // { model: PaymentIntent, as: 'paymentIntent' },
+      // { model: Invoice, as: 'invoice' },
+      // { model: Subscription, as: 'subscription' },
+    ],
+    distinct: true,
+  });
+
+  res.json({ count, list });
+});
+
+router.get('/:id', auth, async (req, res) => {
+  const doc = await Refund.findByPk(req.params.id as string, {
+    include: [
+      { model: Customer, as: 'customer' },
+      { model: PaymentCurrency, as: 'paymentCurrency' },
+      { model: PaymentIntent, as: 'paymentIntent' },
+      { model: Invoice, as: 'invoice' },
+      { model: Subscription, as: 'subscription' },
+    ],
+  });
+
+  if (doc) {
+    // @ts-ignore
+    const paymentMethod = await PaymentMethod.findByPk(doc.paymentCurrency.payment_method_id);
+    return res.json({ ...doc.toJSON(), paymentMethod: paymentMethod?.toJSON() });
+  }
+
+  return res.status(404).json(null);
+});
+
+export default router;