payment-kit 1.16.17 → 1.16.19

package/api/src/queues/notification.ts

@@ -65,6 +65,10 @@ import {
   BillingDiscrepancyEmailTemplate,
   BillingDiscrepancyEmailTemplateOptions,
 } from '../libs/notification/template/billing-discrepancy';
+import {
+  OverdraftProtectionExhaustedEmailTemplate,
+  OverdraftProtectionExhaustedEmailTemplateOptions,
+} from '../libs/notification/template/subscription.overdraft-protection.exhausted';
 
 export type NotificationQueueJobOptions = any;
 
@@ -75,7 +79,8 @@ export type NotificationQueueJobType =
   | 'customer.subscription.will_canceled'
   | 'customer.reward.succeeded'
   | 'usage.report.empty'
-  | 'billing.discrepancy';
+  | 'billing.discrepancy'
+  | 'subscription.overdraftProtection.exhausted';
 
 export type NotificationQueueJob = {
   type: NotificationQueueJobType;
@@ -130,6 +135,11 @@ function getNotificationTemplate(job: NotificationQueueJob): BaseEmailTemplate {
       job.options as SubscriptionStakeSlashSucceededEmailTemplateOptions
     );
   }
+  if (job.type === 'subscription.overdraftProtection.exhausted') {
+    return new OverdraftProtectionExhaustedEmailTemplate(
+      job.options as OverdraftProtectionExhaustedEmailTemplateOptions
+    );
+  }
 
   throw new Error(`Unknown job type: ${job.type}`);
 }
@@ -234,8 +244,8 @@ export async function startNotificationQueue() {
     });
   });
 
-  events.on('customer.subscription.renew_failed', async (subscription: Subscription) => {
-    const invoice = await Invoice.findByPk(subscription.latest_invoice_id);
+  events.on('customer.subscription.renew_failed', async (subscription: Subscription, { invoiceId }) => {
+    const invoice = await Invoice.findByPk(invoiceId || subscription.latest_invoice_id);
 
     logger.info('events.on', 'customer.subscription.renew_failed', {
       subscriptionId: subscription.id,
@@ -317,4 +327,16 @@ export async function startNotificationQueue() {
       },
     });
   });
+
+  events.on('subscription.overdraft_protection.exhausted', (subscription: Subscription) => {
+    notificationQueue.push({
+      id: `subscription.overdraftProtection.exhausted.${subscription.id}`,
+      job: {
+        type: 'subscription.overdraftProtection.exhausted',
+        options: {
+          subscriptionId: subscription.id,
+        },
+      },
+    });
+  });
 }

package/api/src/queues/payment.ts

@@ -1,5 +1,6 @@
 import isEmpty from 'lodash/isEmpty';
 
+import { BN } from '@ocap/util';
 import { ensureStakedForGas } from '../integrations/arcblock/stake';
 import { transferErc20FromUser } from '../integrations/ethereum/token';
 import { createEvent } from '../libs/audit';
@@ -9,7 +10,6 @@ import CustomError from '../libs/error';
 import { events } from '../libs/event';
 import logger from '../libs/logger';
 import { getGasPayerExtra, isDelegationSufficientForPayment } from '../libs/payment';
-import createQueue from '../libs/queue';
 import {
   checkRemainingStake,
   getDaysUntilCancel,
@@ -19,6 +19,7 @@ import {
   getMinRetryMail,
   getSubscriptionCreateSetup,
   getSubscriptionStakeAddress,
+  isSubscriptionOverdraftProtectionEnabled,
   shouldCancelSubscription,
 } from '../libs/subscription';
 import { MAX_RETRY_COUNT, MIN_RETRY_MAIL, getNextRetry } from '../libs/util';
@@ -34,6 +35,10 @@ import { Subscription } from '../store/models/subscription';
 import { SubscriptionItem } from '../store/models/subscription-item';
 import type { PaymentError, PaymentSettings } from '../store/models/types';
 import { notificationQueue } from './notification';
+import { ensureOverdraftProtectionInvoiceAndItems } from '../libs/invoice';
+import { Lock } from '../store/models';
+import { ensureOverdraftProtectionPrice } from '../libs/overdraft-protection';
+import createQueue from '../libs/queue';
 
 type PaymentJob = {
   paymentIntentId: string;
@@ -240,6 +245,59 @@ export const handlePaymentSucceed = async (
   }
 };
 
+export const doOverdraftProtection = async (
+  paymentIntent: PaymentIntent,
+  subscription: Subscription,
+  customer: Customer,
+  relatedInvoice?: Invoice
+) => {
+  const { enabled } = await isSubscriptionOverdraftProtectionEnabled(subscription);
+  if (!enabled) {
+    logger.warn('overdraft protection is not enabled', {
+      subscription: subscription.id,
+    });
+    return;
+  }
+  const existProtectedInvoice = await Invoice.findOne({
+    where: {
+      subscription_id: subscription.id,
+      billing_reason: 'overdraft_protection',
+      'metadata.payment_intent_id': paymentIntent.id,
+    },
+  });
+  if (existProtectedInvoice) {
+    logger.info('overdraft protection invoice already exists', {
+      invoice: existProtectedInvoice.id,
+    });
+    return;
+  }
+  try {
+    const { invoice, items } = await ensureOverdraftProtectionInvoiceAndItems({
+      customer,
+      subscription,
+      paymentIntent,
+      props: {
+        period_start: subscription.current_period_start,
+        period_end: subscription.current_period_end,
+        metadata: {
+          payment_intent_id: paymentIntent.id,
+          invoice_id: relatedInvoice?.id || '',
+        },
+      },
+    });
+    logger.info('ensure overdraft protection invoice and items done', {
+      invoice: invoice.id,
+      items: items.map((x) => x.id),
+    });
+  } catch (error) {
+    logger.error('ensure overdraft protection invoice and items failed', {
+      error,
+      subscription: subscription.id,
+    });
+    throw error;
+  }
+};
+
 type Updates = {
   retry: {
     payment: Partial<PaymentIntent>;
@@ -323,6 +381,49 @@ export const handlePaymentFailed = async (
     return updates.terminate;
   }
 
+  if (invoice.billing_reason === 'overdraft_protection') {
+    // overdraft protection invoice is always terminated
+    return updates.terminate;
+  }
+  // check overdraft protection, if protected, no need to check due
+  const customer = await Customer.findByPk(invoice.customer_id);
+
+  const { enabled: enableOverdraftProtection, unused: unusedAmount } =
+    await isSubscriptionOverdraftProtectionEnabled(subscription);
+  const { price } = await ensureOverdraftProtectionPrice(subscription.livemode);
+  const invoicePrice = (price.currency_options || []).find((x: any) => x.currency_id === paymentIntent?.currency_id);
+
+  if (subscription.overdraft_protection?.enabled && !enableOverdraftProtection) {
+    // overdraft protection is enabled but not enough
+    const lockKey = `${subscription.id}-${paymentIntent.currency_id}-overdraft-protection-exhausted`;
+    const isLock = await Lock.isLocked(lockKey);
+    if (!isLock) {
+      await Lock.acquire(lockKey, subscription.current_period_end);
+      createEvent('Subscription', 'subscription.overdraft_protection.exhausted', subscription).catch(console.error);
+    }
+  }
+
+  if (
+    enableOverdraftProtection &&
+    unusedAmount !== '0' &&
+    new BN(unusedAmount).gte(new BN(invoicePrice?.unit_amount || '0'))
+  ) {
+    logger.info('do overdraft protection', {
+      subscription: subscription.id,
+      payment: paymentIntent.id,
+      unusedAmount,
+    });
+    try {
+      await doOverdraftProtection(paymentIntent, subscription, customer!, invoice);
+      return updates.terminate;
+    } catch (err) {
+      logger.error('do overdraft protection failed', {
+        error: err,
+        subscription: subscription.id,
+      });
+    }
+  }
+
   if (subscription.isImmutable()) {
     logger.info('Subscription is immutable, no need to check due', { subscription: subscription.id });
     return updates.terminate;
@@ -543,6 +644,32 @@ export const handlePayment = async (job: PaymentJob) => {
 
   const invoice = await Invoice.findByPk(paymentIntent.invoice_id);
 
+  if (invoice?.status === 'void') {
+    await paymentIntent.update({
+      status: 'canceled',
+      canceled_at: dayjs().unix(),
+      cancellation_reason: 'void_invoice',
+    });
+    logger.info('PaymentIntent capture skipped because invoice is void', { id: paymentIntent.id });
+    return;
+  }
+
+  if (invoice && invoice.subscription_id) {
+    const subscription = await Subscription.findByPk(invoice.subscription_id);
+    if (
+      subscription &&
+      subscription.isActive() &&
+      subscription.overdraft_protection?.enabled &&
+      invoice?.billing_reason === 'overdraft_protection'
+    ) {
+      logger.info('PaymentIntent capture skipped because of overdraft protection', {
+        id: paymentIntent.id,
+        subscription: subscription.id,
+      });
+      return;
+    }
+  }
+
   // check max retry before doing any hard work
   if (invoice && invoice.attempt_count >= MAX_RETRY_COUNT) {
     logger.info('PaymentIntent capture aborted since max retry exceeded', { id: paymentIntent.id });
@@ -740,7 +867,9 @@ export const handlePayment = async (job: PaymentJob) => {
             invoiceId: invoice.id,
           });
           if (!subscription.isImmutable()) {
-            createEvent('Subscription', 'customer.subscription.renew_failed', subscription);
+            createEvent('Subscription', 'customer.subscription.renew_failed', subscription, {
+              invoiceId: invoice.id,
+            });
           }
         }
       }
@@ -773,7 +902,6 @@ export const paymentQueue = createQueue<PaymentJob>({
 });
 
 export const startPaymentQueue = async () => {
-  // Restore previous payments
   const payments = await PaymentIntent.findAll({
     where: {
       status: ['requires_capture', 'processing'],
@@ -804,3 +932,26 @@ events.on('payment_intent.succeeded', async (paymentIntent: PaymentIntent) => {
     ensureStakedForGas();
   }
 });
+
+events.on('payment.queued', async (id, job, args = {}) => {
+  const { sync, ...extraArgs } = args;
+  if (sync) {
+    try {
+      await paymentQueue.pushAndWait({
+        id,
+        job,
+        ...extraArgs,
+      });
+      events.emit('payment.queued.done');
+    } catch (error) {
+      logger.error('Error in payment.queued', { id, job, error });
+      events.emit('payment.queued.error', error);
+    }
+    return;
+  }
+  paymentQueue.push({
+    id,
+    job,
+    ...extraArgs,
+  });
+});

package/api/src/queues/refund.ts

@@ -347,13 +347,13 @@ const handleStakeReturnJob = async (
                 tokens: [{ address: paymentCurrency.contract, value: refund.amount }],
               },
             ],
-            message: 'stake_return_on_subscription_cancel',
+            message: refund.description || 'stake_return_on_subscription_cancel',
             data: {
               typeUrl: 'json',
               // @ts-ignore
               value: {
                 appId: wallet.address,
-                reason: 'subscription_cancel',
+                reason: refund?.metadata?.reason || 'subscription_cancel',
                 subscriptionId: refund.subscription_id,
               },
             },

package/api/src/queues/subscription.ts

@@ -21,9 +21,12 @@ import {
   getSubscriptionStakeAddress,
   getSubscriptionStakeReturnSetup,
   getSubscriptionStakeSlashSetup,
+  isSubscriptionOverdraftProtectionEnabled,
+  returnOverdraftProtectionStake,
   shouldCancelSubscription,
+  slashOverdraftProtectionStake,
 } from '../libs/subscription';
-import { ensureInvoiceAndItems } from '../routes/connect/shared';
+import { ensureInvoiceAndItems } from '../libs/invoice';
 import { PaymentCurrency, PaymentIntent, PaymentMethod, Refund, SetupIntent, UsageRecord } from '../store/models';
 import { Customer } from '../store/models/customer';
 import { Invoice } from '../store/models/invoice';
@@ -87,7 +90,18 @@ const doHandleSubscriptionInvoice = async ({
         billing_reason: `subscription_${reason}`,
       },
     });
-    if (previous && previous.isImmutable() === false) {
+    let existOverdraftProtection;
+    if (previous) {
+      existOverdraftProtection = await Invoice.findOne({
+        where: {
+          subscription_id: subscription.id,
+          billing_reason: 'overdraft_protection',
+          'metadata.invoice_id': previous.id,
+        },
+      });
+    }
+
+    if (previous && previous.isImmutable() === false && !existOverdraftProtection) {
       logger.warn(`Invoice for current period ${previous.id} not paid for subscription ${subscription.id}`);
       return null;
     }
@@ -747,6 +761,102 @@ const ensureRefundOnCancel = async (subscription: Subscription) => {
   });
 };
 
+const ensureReturnOverdraftProtectionStake = async (subscription: Subscription, paymentCurrencyId?: string) => {
+  const { enabled, remaining, revokedStake } = await isSubscriptionOverdraftProtectionEnabled(
+    subscription,
+    paymentCurrencyId
+  );
+  if (!enabled && remaining === '0' && revokedStake === '0') {
+    logger.info('Return overdraft protection stake skipped because no remaining', {
+      subscription: subscription.id,
+      remaining,
+      revokedStake,
+    });
+    return;
+  }
+  const paymentCurrency = await PaymentCurrency.findByPk(paymentCurrencyId || subscription.currency_id);
+  if (!paymentCurrency) {
+    logger.warn('Return overdraft protection stake skipped because currency not found', {
+      subscription: subscription.id,
+      currency: subscription.currency_id,
+    });
+    return;
+  }
+  const paymentMethod = await PaymentMethod.findByPk(paymentCurrency.payment_method_id);
+  if (!paymentMethod) {
+    logger.warn('Return overdraft protection stake skipped because payment method not found', {
+      subscription: subscription.id,
+      paymentMethod: paymentCurrency.payment_method_id,
+    });
+    return;
+  }
+  if (paymentMethod?.type !== 'arcblock') {
+    logger.info('Return overdraft protection stake skipped because payment method is not arcblock', {
+      subscription: subscription.id,
+      paymentMethod: paymentMethod?.type,
+    });
+    return;
+  }
+  await returnOverdraftProtectionStake(subscription, paymentCurrencyId);
+  logger.info('Overdraft protection stake returned', { subscription: subscription.id });
+  if (subscription.overdraft_protection?.enabled) {
+    await subscription.update({
+      // @ts-ignore
+      overdraft_protection: {
+        ...(subscription.overdraft_protection || {}),
+        enabled: false,
+      },
+    });
+    logger.info('Overdraft protection disabled', { subscription: subscription.id });
+  }
+};
+
+const ensureSlashOverdraftProtectionStake = async (subscription: Subscription) => {
+  const { remaining, revokedStake } = await isSubscriptionOverdraftProtectionEnabled(subscription);
+  if (remaining === '0' && revokedStake === '0') {
+    logger.info('Slash overdraft protection stake skipped because no remaining', {
+      subscription: subscription.id,
+      remaining,
+      revokedStake,
+    });
+    return;
+  }
+  const paymentCurrency = await PaymentCurrency.findByPk(subscription.currency_id);
+  if (!paymentCurrency) {
+    logger.warn('Slash overdraft protection stake skipped because currency not found', {
+      subscription: subscription.id,
+      currency: subscription.currency_id,
+    });
+    return;
+  }
+  const paymentMethod = await PaymentMethod.findByPk(paymentCurrency.payment_method_id);
+  if (!paymentMethod) {
+    logger.warn('Slash overdraft protection stake skipped because payment method not found', {
+      subscription: subscription.id,
+      paymentMethod: paymentCurrency.payment_method_id,
+    });
+    return;
+  }
+  if (paymentMethod?.type !== 'arcblock') {
+    logger.info('Slash overdraft protection stake skipped because payment method is not arcblock', {
+      subscription: subscription.id,
+      paymentMethod: paymentMethod?.type,
+    });
+    return;
+  }
+  await slashOverdraftProtectionStake(subscription);
+  logger.info('Overdraft protection stake slashed', { subscription: subscription.id });
+  if (subscription.overdraft_protection?.enabled) {
+    await subscription.update({
+      // @ts-ignore
+      overdraft_protection: {
+        ...(subscription.overdraft_protection || {}),
+        enabled: false,
+      },
+    });
+  }
+};
+
 // generate invoice for subscription periodically
 export const handleSubscription = async (job: SubscriptionJob) => {
   logger.info('handle subscription', job);
@@ -780,6 +890,12 @@ export const handleSubscription = async (job: SubscriptionJob) => {
       });
 
       if (previousStatus === 'past_due' && job.action === 'cancel') {
+        // slash overdraft protection stake
+        await slashOverdraftProtectionQueue.pushAndWait({
+          id: `slash-overdraft-protection-${subscription.id}`,
+          job: { subscriptionId: subscription.id },
+        });
+        logger.info('Overdraft protection stake slash job scheduled', { subscription: subscription.id });
         await handleStakeSlashAfterCancel(subscription);
       }
       return;
@@ -924,6 +1040,44 @@ export const subscriptionCancelRefund = createQueue({
   },
 });
 
+export const returnOverdraftProtectionQueue = createQueue({
+  name: 'returnOverdraftProtection',
+  onJob: async (job) => {
+    const { subscriptionId, paymentCurrencyId } = job;
+    const subscription = await Subscription.findByPk(subscriptionId);
+    if (!subscription) {
+      return;
+    }
+    await ensureReturnOverdraftProtectionStake(subscription, paymentCurrencyId);
+  },
+  options: {
+    concurrency: 1,
+    maxRetries: 5,
+    retryDelay: 1000,
+    maxTimeout: 60000,
+    enableScheduledJob: true,
+  },
+});
+
+export const slashOverdraftProtectionQueue = createQueue({
+  name: 'slashOverdraftProtection',
+  onJob: async (job) => {
+    const { subscriptionId } = job;
+    const subscription = await Subscription.findByPk(subscriptionId);
+    if (!subscription) {
+      return;
+    }
+    await ensureSlashOverdraftProtectionStake(subscription);
+  },
+  options: {
+    concurrency: 1,
+    maxRetries: 5,
+    retryDelay: 1000,
+    maxTimeout: 60000,
+    enableScheduledJob: true,
+  },
+});
+
 export async function addSubscriptionJob(
   subscription: Subscription,
   action: 'cycle' | 'cancel' | 'resume',
@@ -978,12 +1132,11 @@ events.on('customer.subscription.recovered', async (subscription: Subscription)
   await handleSubscriptionAfterRecover(doc!);
 });
 
-events.on('customer.subscription.deleted', (subscription: Subscription) => {
+events.on('customer.subscription.deleted', async (subscription: Subscription) => {
   ensurePassportRevoked(subscription).catch((err) => {
     logger.error('ensurePassportRevoked failed', { error: err, subscription: subscription.id });
   });
   // FIXME: ensure invoices that are open or uncollectible are voided
-
   if (
     subscription.cancelation_details?.refund &&
     ['last', 'proration'].includes(subscription.cancelation_details.refund)
@@ -993,6 +1146,15 @@ events.on('customer.subscription.deleted', (subscription: Subscription) => {
       job: { subscriptionId: subscription.id },
     });
   }
+  const { remaining, revokedStake } = await isSubscriptionOverdraftProtectionEnabled(subscription);
+  if (remaining !== '0' || revokedStake !== '0') {
+    // need return overdraft protection stake
+    await returnOverdraftProtectionQueue.pushAndWait({
+      id: `return-overdraft-protection-${subscription.id}`,
+      job: { subscriptionId: subscription.id },
+    });
+    logger.info('Overdraft protection stake return job scheduled', { subscription: subscription.id });
+  }
   if (subscription.cancelation_details?.slash_stake) {
     slashStakeQueue.push({
       id: `slash-stake-${subscription.id}`,
@@ -1016,6 +1178,25 @@ events.on('customer.stake.revoked', async ({ subscriptionId, tx }: { subscriptio
   if (!subscription) {
     return;
   }
+
+  const { address } = tx.tx.itxJson;
+  if (address === subscription.overdraft_protection?.payment_details?.arcblock?.staking?.address) {
+    // revoke overdraft protection stake
+    await subscription.update({
+      // @ts-ignore
+      overdraft_protection: {
+        ...(subscription.overdraft_protection || {}),
+        enabled: false,
+      },
+    });
+    slashOverdraftProtectionQueue.push({
+      id: `slash-overdraft-protection-${subscription.id}`,
+      job: { subscriptionId: subscription.id },
+    });
+    logger.info('Overdraft protection stake slash job scheduled', { subscription: subscription.id });
+    return;
+  }
+
   if (subscription.isActive() === false) {
     return;
   }
@@ -1030,7 +1211,18 @@ events.on('customer.stake.revoked', async ({ subscriptionId, tx }: { subscriptio
       feedback: 'other',
       comment: `Revoked by ${tx.tx.from} with tx ${tx.hash}`,
     },
+    // 关闭透支保护
+    // @ts-ignore
+    overdraft_protection: {
+      ...(subscription.overdraft_protection || {}),
+      enabled: false,
+    },
+  });
+  slashOverdraftProtectionQueue.push({
+    id: `slash-overdraft-protection-${subscription.id}`,
+    job: { subscriptionId: subscription.id },
   });
+  logger.info('Overdraft protection stake slash job scheduled', { subscription: subscription.id });
   await new SubscriptionWillCanceledSchedule().reScheduleSubscriptionTasks([subscription]);
   await addSubscriptionJob(subscription, 'cancel', true, subscription.current_period_end);
 });
@@ -1069,5 +1261,24 @@ events.on('setup_intent.succeeded', async (setupIntent: SetupIntent) => {
         paymentCurrencyId: setupIntent.metadata?.from_currency,
       });
     }
+    const { remaining, revokedStake } = await isSubscriptionOverdraftProtectionEnabled(
+      subscription,
+      setupIntent.metadata?.from_currency
+    );
+
+    if (remaining !== '0' || revokedStake !== '0') {
+      try {
+        returnOverdraftProtectionQueue.push({
+          id: `return-overdraft-protection-${subscription.id}`,
+          job: { subscriptionId: subscription.id, paymentCurrencyId: setupIntent.metadata?.from_currency },
+        });
+        logger.info('Overdraft protection stake return job scheduled', {
+          subscription: subscription.id,
+          paymentCurrencyId: setupIntent.metadata?.from_currency,
+        });
+      } catch (error) {
+        logger.error('create return overdraft protection stake job failed', { error, subscription: subscription.id });
+      }
+    }
   }
 });

package/api/src/queues/webhook.ts

@@ -103,6 +103,7 @@ export const handleWebhook = async (job: WebhookJob) => {
           id: getWebhookJobId(event.id, webhook.id),
           job: { eventId: event.id, webhookId: webhook.id },
           runAt: getNextRetry(retryCount),
+          persist: false,
         });
         logger.info('scheduled webhook job', { ...job, retryCount });
       });

package/api/src/routes/connect/change-payment.ts

@@ -4,13 +4,13 @@ import { getTxMetadata } from '../../libs/util';
 import { Lock, type TLineItemExpanded } from '../../store/models';
 import {
   ensureChangePaymentContext,
-  ensureStakeInvoice,
   executeOcapTransactions,
   getAuthPrincipalClaim,
   getDelegationTxClaim,
   getStakeTxClaim,
   updateStripeSubscriptionAfterChangePayment,
 } from './shared';
+import { ensureStakeInvoice } from '../../libs/invoice';
 
 export default {
   action: 'change-payment',

package/api/src/routes/connect/change-plan.ts

@@ -8,13 +8,13 @@ import { invoiceQueue } from '../../queues/invoice';
 import { addSubscriptionJob, subscriptionQueue } from '../../queues/subscription';
 import type { TLineItemExpanded } from '../../store/models';
 import {
-  ensureStakeInvoice,
   ensureSubscription,
   executeOcapTransactions,
   getAuthPrincipalClaim,
   getDelegationTxClaim,
   getStakeTxClaim,
 } from './shared';
+import { ensureStakeInvoice } from '../../libs/invoice';
 
 export default {
   action: 'change-plan',