payment-kit 1.19.0 → 1.19.2

package/api/src/queues/payment.ts

@@ -36,7 +36,7 @@ import { SubscriptionItem } from '../store/models/subscription-item';
 import type { EVMChainType, PaymentError, PaymentSettings } from '../store/models/types';
 import { notificationQueue } from './notification';
 import { ensureOverdraftProtectionInvoiceAndItems } from '../libs/invoice';
-import { Lock } from '../store/models';
+import { Lock, MeterEvent } from '../store/models';
 import { ensureOverdraftProtectionPrice } from '../libs/overdraft-protection';
 import createQueue from '../libs/queue';
 import { CHARGE_SUPPORTED_CHAIN_TYPES, EVM_CHAIN_TYPES } from '../libs/constants';
@@ -111,6 +111,200 @@ export const depositVaultQueue = createQueue<DepositVaultJob>({
   },
 });
 
+export async function updateSubscriptionOnPaymentSuccess(
+  paymentIntent: PaymentIntent | null,
+  subscription: Subscription,
+  invoice?: Invoice | null,
+  triggerRenew: boolean = true
+) {
+  // Handle incomplete subscription activation
+  if (subscription.status === 'incomplete' && invoice && invoice.id === subscription.latest_invoice_id) {
+    const started = await subscription.start();
+    if (started) {
+      logger.info(`Subscription ${subscription.id} activated on payment done ${invoice.id}`);
+    }
+    return;
+  }
+
+  // Handle past_due subscription recovery
+  if (subscription.status === 'past_due' && subscription.cancelation_details?.reason === 'payment_failed') {
+    await handlePastDueSubscriptionRecovery(subscription, paymentIntent);
+    return;
+  }
+  if (subscription.status === 'past_due' && subscription.cancelation_details?.reason === 'insufficient_credit') {
+    await handlePastDueSubscriptionRecovery(subscription, paymentIntent);
+    return;
+  }
+
+  // Handle trialing subscription
+  if (subscription.status === 'trialing') {
+    const started = await subscription.start();
+    if (started) {
+      logger.info(`Subscription ${subscription.id} trialing ended on payment done ${invoice?.id || 'credit'}`);
+    }
+    return;
+  }
+
+  // Trigger renewal and upgrade events
+  if (triggerRenew && (!invoice || invoice.billing_reason !== 'subscription_update')) {
+    if (!invoice || invoice.billing_reason === 'subscription_cycle' || paymentIntent?.capture_method === 'manual') {
+      createEvent('Subscription', 'customer.subscription.renewed', subscription).catch(console.error);
+    }
+  }
+  if (invoice?.billing_reason === 'subscription_update') {
+    createEvent('Subscription', 'customer.subscription.upgraded', subscription).catch(console.error);
+  }
+}
+
+export async function handlePastDueSubscriptionRecovery(
+  subscription: Subscription,
+  paymentIntent: PaymentIntent | null
+) {
+  // For credit mode with insufficient_credit reason, check meter events instead of uncollectible invoices
+  if (subscription.cancelation_details?.reason === 'insufficient_credit') {
+    // Check if all meter events for this subscription are completed with zero pending amount
+    const [summary, detail] = await MeterEvent.getPendingAmounts({
+      subscriptionId: subscription.id,
+      livemode: subscription.livemode,
+      currencyId: subscription.currency_id,
+    });
+
+    if (summary[subscription.currency_id] && summary[subscription.currency_id] !== '0') {
+      logger.info('Subscription recovery skipped: pending meter events exist', {
+        subscription: subscription.id,
+        pendingEventsCount: detail[subscription.currency_id]?.length,
+        pendingEventIds: detail[subscription.currency_id],
+      });
+      return;
+    }
+  } else {
+    // For payment_failed reason, check uncollectible invoices
+    const [result] = await Invoice.getUncollectibleAmount({ subscriptionId: subscription.id });
+    if (!isEmpty(result)) {
+      return;
+    }
+  }
+
+  const now = dayjs().unix();
+
+  // Reset billing cycle anchor and cancel_* if we are recovering from payment failed or insufficient credit
+  if (subscription.cancel_at && subscription.cancel_at !== subscription.current_period_end) {
+    if (now <= subscription.current_period_end) {
+      // If payment succeeds before current_period_end, we should activate this subscription
+      await subscription.update({
+        status: 'active',
+        cancel_at: 0,
+        cancel_at_period_end: false,
+        // @ts-ignore
+        cancelation_details: null,
+      });
+      const recoveryReason =
+        subscription.cancelation_details?.reason === 'insufficient_credit' ? 'credit replenished' : 'payment done';
+      logger.info(
+        `Subscription ${subscription.id} recovered on ${recoveryReason} ${paymentIntent?.id || 'credit'}: cancel rest`
+      );
+      if (paymentIntent) {
+        await syncStripeSubscriptionAfterRecovery(subscription, paymentIntent.id);
+      }
+      return;
+    }
+
+    // Reset billing cycle
+    const subscriptionItems = await SubscriptionItem.findAll({ where: { subscription_id: subscription.id } });
+    const lineItems = await Price.expand(subscriptionItems.map((x) => x.toJSON()));
+    const setup = getSubscriptionCreateSetup(lineItems, subscription.currency_id, 0);
+    await subscription.update({
+      status: 'active',
+      pending_invoice_item_interval: setup.recurring,
+      current_period_start: setup.period.start,
+      current_period_end: setup.period.end,
+      billing_cycle_anchor: setup.cycle.anchor,
+      cancel_at: 0,
+      cancel_at_period_end: false,
+      // @ts-ignore
+      cancelation_details: null,
+    });
+
+    createEvent('Subscription', 'customer.subscription.recovered', subscription).catch(console.error);
+    const recoveryReason =
+      subscription.cancelation_details?.reason === 'insufficient_credit' ? 'credit replenished' : 'payment done';
+    logger.info(
+      `Subscription ${subscription.id} recovered on ${recoveryReason} ${paymentIntent?.id || 'credit'}: cancel and billing cycle reset`
+    );
+    if (paymentIntent) {
+      await syncStripeSubscriptionAfterRecovery(subscription, paymentIntent.id);
+    }
+  } else if (subscription.cancel_at_period_end) {
+    // Reset cancel_at_period_end if we are recovering from payment failed or insufficient credit
+    // @ts-ignore
+    await subscription.update({ status: 'active', cancel_at_period_end: false, cancelation_details: null });
+    const recoveryReason =
+      subscription.cancelation_details?.reason === 'insufficient_credit' ? 'credit replenished' : 'payment done';
+    logger.info(
+      `Subscription ${subscription.id} recovered on ${recoveryReason} ${paymentIntent?.id || 'credit'}: cancel reset`
+    );
+    if (paymentIntent) {
+      await syncStripeSubscriptionAfterRecovery(subscription, paymentIntent.id);
+    }
+  } else {
+    await subscription.update({ status: 'active' });
+    const recoveryReason =
+      subscription.cancelation_details?.reason === 'insufficient_credit' ? 'credit replenished' : 'payment done';
+    logger.info(`Subscription ${subscription.id} recovered on ${recoveryReason} ${paymentIntent?.id || 'credit'}`);
+  }
+}
+
+async function updateCheckoutSessionOnPaymentSuccess(
+  paymentIntent: PaymentIntent,
+  checkoutSession: CheckoutSession,
+  invoice?: Invoice
+) {
+  if (checkoutSession.status !== 'open') {
+    return;
+  }
+
+  // Update quantity sold for line items
+  updateQuantitySold(checkoutSession).catch((err) => {
+    logger.error('Updating quantity_sold for line items failed', {
+      error: err,
+      checkoutSessionId: checkoutSession.id,
+    });
+  });
+
+  // Handle subscription mode checkout sessions
+  if (['subscription', 'setup'].includes(checkoutSession.mode) && invoice?.subscription_id) {
+    await checkoutSession.increment('success_subscription_count', { by: 1 });
+    await checkoutSession.reload();
+    const subscriptionIds = getCheckoutSessionSubscriptionIds(checkoutSession);
+
+    if (
+      checkoutSession.success_subscription_count &&
+      checkoutSession.success_subscription_count >= subscriptionIds.length
+    ) {
+      await checkoutSession.update({
+        status: 'complete',
+        payment_status: 'paid',
+        payment_details: paymentIntent?.payment_details || {},
+      });
+      logger.info('checkout session become complete on payment done', {
+        id: checkoutSession.id,
+      });
+    }
+  } else {
+    // Handle non-subscription mode checkout sessions
+    await checkoutSession.update({
+      status: 'complete',
+      payment_status: 'paid',
+      payment_details: paymentIntent?.payment_details || {},
+    });
+    logger.info('checkout session become complete on payment done', {
+      id: checkoutSession.id,
+    });
+  }
+
+  logger.info(`CheckoutSession ${checkoutSession.id} updated on payment done ${paymentIntent.id}`);
+}
+
 export const handlePaymentSucceed = async (
   paymentIntent: PaymentIntent,
   triggerRenew: boolean = true,
@@ -189,25 +383,17 @@ export const handlePaymentSucceed = async (
   if (paymentIntent.invoice_id) {
     invoice = await Invoice.findByPk(paymentIntent.invoice_id);
   }
+
+  // Handle checkout session when no invoice exists
   if (!invoice && !slashStake) {
     const checkoutSession = await CheckoutSession.findOne({ where: { payment_intent_id: paymentIntent.id } });
-    if (checkoutSession && checkoutSession.status === 'open') {
-      updateQuantitySold(checkoutSession).catch((err) => {
-        logger.error('Updating quantity_sold for line items failed', {
-          error: err,
-          checkoutSessionId: checkoutSession.id,
-        });
-      });
-      await checkoutSession.update({
-        status: 'complete',
-        payment_status: 'paid',
-        payment_details: paymentIntent.payment_details,
-      });
-      logger.info(`CheckoutSession ${checkoutSession.id} updated on payment done ${paymentIntent.id}`);
+    if (checkoutSession) {
+      await updateCheckoutSessionOnPaymentSuccess(paymentIntent, checkoutSession);
     }
     return;
   }
 
+  // Update invoice status
   if (invoice && invoice?.status !== 'paid') {
     await invoice.update({
       paid: true,
@@ -221,122 +407,19 @@ export const handlePaymentSucceed = async (
     logger.info(`Invoice ${invoice.id} updated on payment done: ${paymentIntent.id}`);
   }
 
+  // Update subscription status
   if (invoice && invoice.subscription_id && !slashStake) {
     const subscription = await Subscription.findByPk(invoice.subscription_id);
-
-    // We only update subscription status when the invoice is the latest one
     if (subscription) {
-      if (subscription.status === 'incomplete' && invoice.id === subscription.latest_invoice_id) {
-        const started = await subscription.start();
-        if (started) {
-          logger.info(`Subscription ${subscription.id} activated on payment done ${invoice.id}`);
-        }
-      } else if (subscription.status === 'past_due' && subscription.cancelation_details?.reason === 'payment_failed') {
-        // ensure no uncollectible amount before recovering from payment failed
-        const [result] = await Invoice.getUncollectibleAmount({ subscriptionId: subscription.id });
-        if (isEmpty(result)) {
-          // reset billing cycle anchor and cancel_* if we are recovering from payment failed
-          if (subscription.cancel_at && subscription.cancel_at !== subscription.current_period_end) {
-            const now = dayjs().unix();
-            if (now <= subscription.current_period_end) {
-              // if payment succeeds before current_period_end, we should active this subscription
-              await subscription.update({
-                status: 'active',
-                cancel_at: 0,
-                cancel_at_period_end: false,
-                // @ts-ignore
-                cancelation_details: null,
-              });
-              logger.info(`Subscription ${subscription.id} recovered on payment done ${paymentIntent.id}: cancel rest`);
-              await syncStripeSubscriptionAfterRecovery(subscription, paymentIntent.id);
-              return;
-            }
-            const subscriptionItems = await SubscriptionItem.findAll({ where: { subscription_id: subscription.id } });
-            const lineItems = await Price.expand(subscriptionItems.map((x) => x.toJSON()));
-            const setup = getSubscriptionCreateSetup(lineItems, subscription.currency_id, 0);
-            await subscription.update({
-              status: 'active',
-              pending_invoice_item_interval: setup.recurring,
-              current_period_start: setup.period.start,
-              current_period_end: setup.period.end,
-              billing_cycle_anchor: setup.cycle.anchor,
-              cancel_at: 0,
-              cancel_at_period_end: false,
-              // @ts-ignore
-              cancelation_details: null,
-            });
-
-            createEvent('Subscription', 'customer.subscription.recovered', subscription).catch(console.error);
-            logger.info(
-              `Subscription ${subscription.id} recovered on payment done ${paymentIntent.id}: cancel and billing cycle reset`
-            );
-            await syncStripeSubscriptionAfterRecovery(subscription, paymentIntent.id);
-          } else if (subscription.cancel_at_period_end) {
-            // reset cancel_at_period_end if we are recovering from payment failed
-            // @ts-ignore
-            await subscription.update({ status: 'active', cancel_at_period_end: false, cancelation_details: null });
-            logger.info(`Subscription ${subscription.id} recovered on payment done ${paymentIntent.id}: cancel reset`);
-            await syncStripeSubscriptionAfterRecovery(subscription, paymentIntent.id);
-          } else {
-            await subscription.update({ status: 'active' });
-            logger.info(`Subscription ${subscription.id} recovered on payment done ${paymentIntent.id}`);
-          }
-        }
-      } else if (subscription.status === 'trialing') {
-        const started = await subscription.start();
-        if (started) {
-          logger.info(`Subscription ${subscription.id} trialing ended on payment done ${invoice.id}`);
-        }
-      }
-
-      if (triggerRenew && invoice.billing_reason !== 'subscription_update') {
-        if (invoice.billing_reason === 'subscription_cycle' || paymentIntent.capture_method === 'manual') {
-          createEvent('Subscription', 'customer.subscription.renewed', subscription).catch(console.error);
-        }
-      }
-      if (invoice.billing_reason === 'subscription_update') {
-        createEvent('Subscription', 'customer.subscription.upgraded', subscription).catch(console.error);
-      }
+      await updateSubscriptionOnPaymentSuccess(paymentIntent, subscription, invoice, triggerRenew);
     }
   }
 
+  // Update checkout session
   if (invoice && invoice.checkout_session_id && !slashStake) {
     const checkoutSession = await CheckoutSession.findByPk(invoice.checkout_session_id);
-    if (checkoutSession && checkoutSession.status === 'open') {
-      updateQuantitySold(checkoutSession).catch((err) => {
-        logger.error('Updating quantity_sold for line items failed', {
-          error: err,
-          checkoutSessionId: checkoutSession.id,
-        });
-      });
-      if (['subscription', 'setup'].includes(checkoutSession.mode) && invoice.subscription_id) {
-        await checkoutSession.increment('success_subscription_count', { by: 1 });
-        await checkoutSession.reload();
-        const subscriptionIds = getCheckoutSessionSubscriptionIds(checkoutSession);
-        if (
-          checkoutSession.success_subscription_count &&
-          checkoutSession.success_subscription_count >= subscriptionIds.length
-        ) {
-          await checkoutSession.update({
-            status: 'complete',
-            payment_status: 'paid',
-            payment_details: paymentIntent.payment_details,
-          });
-          logger.info('checkout session become complete on payment done', {
-            id: checkoutSession.id,
-          });
-        }
-      } else {
-        await checkoutSession.update({
-          status: 'complete',
-          payment_status: 'paid',
-          payment_details: paymentIntent.payment_details,
-        });
-        logger.info('checkout session become complete on payment done', {
-          id: checkoutSession.id,
-        });
-      }
-      logger.info(`CheckoutSession ${checkoutSession.id} updated on payment done ${paymentIntent.id}`);
+    if (checkoutSession) {
+      await updateCheckoutSessionOnPaymentSuccess(paymentIntent, checkoutSession, invoice);
     }
   }
 };
@@ -733,6 +816,11 @@ export const handlePayment = async (job: PaymentJob) => {
     return;
   }
 
+  if (paymentCurrency.isCredit()) {
+    logger.info('PaymentIntent capture skipped because paymentCurrency is credit', { id: paymentIntent.id });
+    return;
+  }
+
   const customer = await Customer.findByPk(paymentIntent.customer_id);
   if (!customer) {
     logger.warn('Customer not found', { id: paymentIntent.customer_id });

package/api/src/queues/subscription.ts

@@ -230,6 +230,15 @@ export async function handleSubscriptionInvoice(args: Parameters<typeof doHandle
 }
 
 const handleSubscriptionBeforeCancel = async (subscription: Subscription) => {
+  const paymentCurrency = await PaymentCurrency.findByPk(subscription.currency_id);
+  if (!paymentCurrency) {
+    logger.warn('Payment currency not found for subscription', { subscription: subscription.id });
+    return;
+  }
+  if (paymentCurrency.isCredit()) {
+    logger.info('Skip invoice creation for credit subscription', { subscription: subscription.id });
+    return;
+  }
   const invoice = await handleSubscriptionInvoice({
     subscription,
     filter: (x) => x.price.recurring?.usage_type === 'metered', // include only metered items
@@ -268,6 +277,75 @@ const handleSubscriptionWhenActive = async (subscription: Subscription) => {
     subscription.status === 'trialing' ? subscription.trial_end : subscription.current_period_end;
   const setup = getSubscriptionCycleSetup(subscription.pending_invoice_item_interval, previousPeriodEnd as number);
 
+  // Check if this is a credit subscription
+  const isCredit = await subscription.isConsumesCredit();
+  const paymentCurrency = await PaymentCurrency.findByPk(subscription.currency_id);
+
+  if (isCredit && paymentCurrency?.isCredit()) {
+    // For credit subscriptions, check credit availability instead of creating invoices
+    const customer = await Customer.findByPk(subscription.customer_id);
+    const paymentMethod = await PaymentMethod.findByPk(subscription.default_payment_method_id);
+
+    if (!customer || !paymentMethod || !paymentCurrency) {
+      logger.warn('Credit subscription cycle skipped due to missing dependencies', {
+        subscription: subscription.id,
+        customer: !!customer,
+        paymentMethod: !!paymentMethod,
+        paymentCurrency: !!paymentCurrency,
+      });
+      return;
+    }
+
+    if (subscription.status === 'trialing') {
+      const now = dayjs().unix();
+      if (subscription.trial_end && subscription.trial_end <= now) {
+        await subscription.update({ status: 'active' });
+        logger.info('Subscription status updated from trialing to active', {
+          subscription: subscription.id,
+        });
+      }
+    }
+    // Check if we need to catch up on missed periods
+    const now = dayjs().unix();
+    let nextPeriod = setup;
+
+    if (now > setup.period.end) {
+      // Enable catch-up for missed periods
+      nextPeriod = getSubscriptionCycleSetup(subscription.pending_invoice_item_interval, previousPeriodEnd as number, {
+        catchUp: true,
+      });
+
+      if (nextPeriod.missedPeriods > 0) {
+        logger.warn(`Credit subscription recovered with ${nextPeriod.missedPeriods} missed periods`, {
+          subscription: subscription.id,
+          missedPeriods: nextPeriod.missedPeriods,
+          originalPeriodEnd: nextPeriod.recovery?.originalPeriodEnd,
+          currentPeriodStart: nextPeriod.period.start,
+          currentPeriodEnd: nextPeriod.period.end,
+          wasLimited: nextPeriod.recovery?.wasLimited,
+        });
+      }
+    }
+
+    await subscription.update({
+      current_period_start: nextPeriod.period.start,
+      current_period_end: nextPeriod.period.end,
+    });
+
+    if (subscription.isActive()) {
+      logger.info(`Credit subscription updated for billing cycle: ${subscription.id}`, {
+        periodStart: nextPeriod.period.start,
+        periodEnd: nextPeriod.period.end,
+        missedPeriods: nextPeriod.missedPeriods || 0,
+      });
+      await addSubscriptionJob(subscription, 'cycle', false, nextPeriod.period.end);
+      logger.info(`Credit subscription job scheduled for next billing cycle: ${subscription.id}`);
+    }
+
+    return;
+  }
+
+  // Original logic for non-credit subscriptions
   // set invoice status if subscription paused
   let status = 'open';
   if (subscription.pause_collection) {
@@ -1065,6 +1143,103 @@ export const subscriptionQueue = createQueue<SubscriptionJob>({
   },
 });
 
+/**
+ * Handle credit subscription recovery after system restart
+ * Checks for subscriptions that may have missed billing periods during downtime
+ */
+export const handleCreditSubscriptionRecovery = async () => {
+  const lock = getLock('creditSubscriptionRecovery');
+  if (lock.locked) {
+    return;
+  }
+
+  logger.info('Starting credit subscription recovery check');
+  try {
+    await lock.acquire();
+
+    // Find active credit subscriptions that might need recovery
+    const creditSubscriptions = await Subscription.findAll({
+      where: {
+        status: ['active', 'trialing'],
+      },
+      include: [
+        {
+          model: PaymentCurrency,
+          as: 'paymentCurrency',
+          where: {
+            type: 'credit',
+          },
+        },
+      ],
+    });
+
+    const now = dayjs().unix();
+    const recoveredSubscriptions: string[] = [];
+
+    const results = await Promise.allSettled(
+      creditSubscriptions.map(async (subscription) => {
+        // Check if subscription period has ended
+        if (subscription.current_period_end && now > subscription.current_period_end) {
+          const previousPeriodEnd =
+            subscription.status === 'trialing' ? subscription.trial_end : subscription.current_period_end;
+
+          const setup = getSubscriptionCycleSetup(
+            subscription.pending_invoice_item_interval,
+            previousPeriodEnd as number,
+            { catchUp: true, maxMissedPeriods: 100 }
+          );
+
+          if (setup.missedPeriods > 0) {
+            logger.info('Credit subscription requires recovery', {
+              subscription: subscription.id,
+              missedPeriods: setup.missedPeriods,
+              originalPeriodEnd: setup.recovery?.originalPeriodEnd,
+              newPeriodStart: setup.period.start,
+              newPeriodEnd: setup.period.end,
+            });
+
+            // Update subscription to current period
+            await subscription.update({
+              current_period_start: setup.period.start,
+              current_period_end: setup.period.end,
+            });
+
+            // Schedule next billing cycle
+            await addSubscriptionJob(subscription, 'cycle', true, setup.period.end);
+
+            // Create audit event
+            await createEvent('Subscription', 'system.recovery', subscription, {
+              missedPeriods: setup.missedPeriods,
+              recovery: setup.recovery,
+              recoveryType: 'startup',
+            });
+
+            recoveredSubscriptions.push(subscription.id);
+          }
+        }
+      })
+    );
+
+    const failed = results.filter((r) => r.status === 'rejected').length;
+    if (failed > 0) {
+      logger.warn(`Failed to process ${failed} credit subscriptions in recovery`);
+    }
+
+    if (recoveredSubscriptions.length > 0) {
+      logger.info('Credit subscription recovery completed', {
+        recoveredCount: recoveredSubscriptions.length,
+        subscriptions: recoveredSubscriptions,
+      });
+    } else {
+      logger.info('No credit subscriptions required recovery');
+    }
+  } catch (error) {
+    logger.error('Error in credit subscription recovery:', error);
+  } finally {
+    lock.release();
+  }
+};
+
 export const startSubscriptionQueue = async () => {
   const lock = getLock('startSubscriptionQueue');
   if (lock.locked) {
@@ -1073,6 +1248,10 @@ export const startSubscriptionQueue = async () => {
   logger.info('startSubscriptionQueue');
   try {
     await lock.acquire();
+
+    // First handle credit subscription recovery
+    await handleCreditSubscriptionRecovery();
+
     const subscriptions = await Subscription.findAll({
       where: {
         status: EXPECTED_SUBSCRIPTION_STATUS,