feat: improve customer mover and cancellation scripts

Author: julianpoy

packages/fxa-auth-server/lib/payments/paypal/helper.ts

@@ -714,10 +714,10 @@ export class PayPalHelper {
 
       if (
         behavior.refundType === RefundType.Partial &&
-        behavior.amount >= invoice.amount_paid
+        behavior.amount >= invoice.amount_due
       ) {
         throw new RefundError(
-          'Partial refunds must be less than the amount paid on the invoice'
+          'Partial refunds must be less than the amount due on the invoice'
         );
       }
       const amount =

packages/fxa-auth-server/scripts/cancel-subscriptions-to-plan.ts

@@ -32,6 +32,13 @@ const parseRemainingValueMode = (
   return mode as "noaction" | "refund" | "prorate" | "proratedRefund";
 };
 
+const parseProratedRefundRate = (proratedRefundRate: string) => {
+  if (!proratedRefundRate) return null;
+  const value = parseInt(proratedRefundRate);
+  if (isNaN(value) || value <= 0) throw new Error("Invalid proratedRefundRate");
+  return value;
+};
+
 async function init() {
   program
     .version(pckg.version)
@@ -59,6 +66,10 @@ async function init() {
       'How to handle remaining subscription value: noaction, refund, prorate, proratedRefund',
       'noaction'
     )
+    .option(
+      '-p, --prorated-refund-rate [number]',
+      'The rate per day (in whole cents) at which to refund subscriptions in proratedRefund mode'
+    )
     .option(
       '--dry-run',
       'List the customers that would be cancelled without actually cancelling them'
@@ -87,13 +98,19 @@ async function init() {
   const rateLimit = parseRateLimit(program.rateLimit);
   const excludePlanIds = parseExcludePlanIds(program.exclude);
   const remainingValueMode = parseRemainingValueMode(program.mode);
+  const proratedRefundRate = parseProratedRefundRate(program.proratedRefundRate);
 
   const dryRun = !!program.dryRun;
   if (!program.price) throw new Error('--price must be provided');
 
+  if (remainingValueMode === 'proratedRefund' && proratedRefundRate === null) {
+    throw new Error('--prorated-refund-rate must be provided when using proratedRefund mode');
+  }
+
   const planCanceller = new PlanCanceller(
     program.price,
     remainingValueMode,
+    proratedRefundRate,
     excludePlanIds,
     program.outputFile,
     stripeHelper,

packages/fxa-auth-server/scripts/cancel-subscriptions-to-plan/cancel-subscriptions-to-plan.ts

@@ -10,6 +10,15 @@ import { StripeHelper } from '../../lib/payments/stripe';
 import { PayPalHelper } from 'packages/fxa-auth-server/lib/payments/paypal';
 import { RefundType } from '@fxa/payments/paypal';
 
+/**
+  * For RAM-preserving pruposes only
+  */
+const QUEUE_SIZE_LIMIT = 1000;
+/**
+  * For RAM-preserving pruposes only
+  */
+const QUEUE_CONCURRENCY_LIMIT = 100;
+
 export class PlanCanceller {
   private stripeQueue: PQueue;
   private stripe: Stripe;
@@ -18,6 +27,7 @@ export class PlanCanceller {
    * A tool to cancel all subscriptions under a plan
    * @param priceId A Stripe plan or price ID for which all subscriptions will be cancelled
    * @param remainingValueMode Configuration for how to handle remaining subscription value
+   * @param proratedRefundRate The rate per day (in whole cents) at which to refund subscriptions in proratedRefund mode
    * @param excludePlanIds A list of Stripe plan or price ID which if customers have will not be cancelled
    * @param outputFile A CSV file to output a report of affected subscriptions to
    * @param stripeHelper An instance of StripeHelper
@@ -28,13 +38,22 @@ export class PlanCanceller {
   constructor(
     private priceId: string,
     private remainingValueMode: "noaction" | "refund" | "prorate" | "proratedRefund",
+    private proratedRefundRate: number | null,
     private excludePlanIds: string[],
     private outputFile: string,
     private stripeHelper: StripeHelper,
     private paypalHelper: PayPalHelper,
     public dryRun: boolean,
     rateLimit: number
   ) {
+    if (remainingValueMode === 'proratedRefund' && proratedRefundRate === null) {
+      throw new Error("proratedRefundRate must be provided when using proratedRefund mode");
+    }
+
+    if (proratedRefundRate !== null && proratedRefundRate <= 0) {
+      throw new Error("proratedRefundRate must be greater than zero");
+    }
+
     this.stripe = this.stripeHelper.stripe;
 
     this.stripeQueue = new PQueue({
@@ -46,12 +65,22 @@ export class PlanCanceller {
   async run(): Promise<void> {
     await this.writeReportHeader();
 
-    await this.stripe.subscriptions.list({
+    const conversionQueue = new PQueue({ concurrency: QUEUE_CONCURRENCY_LIMIT });
+
+    for await (const subscription of this.stripe.subscriptions.list({
       price: this.priceId,
       limit: 100,
-    }).autoPagingEach((subscription) => {
-      return this.processSubscription(subscription);
-    });
+    })) {
+      if (conversionQueue.size + conversionQueue.pending >= QUEUE_SIZE_LIMIT) {
+        await conversionQueue.onSizeLessThan(QUEUE_SIZE_LIMIT - QUEUE_CONCURRENCY_LIMIT);
+      }
+
+      conversionQueue.add(() => {
+        return this.processSubscription(subscription);
+      });
+    }
+
+    await conversionQueue.onIdle();
   }
 
   async processSubscription(
@@ -64,6 +93,8 @@ export class PlanCanceller {
         : subscription.customer.id;
 
     try {
+      console.log(`Processing ${subscription.id}`);
+
       const customer = await this.fetchCustomer(customerId);
       if (!customer?.subscriptions?.data) {
         throw new Error(`Customer not found: ${customerId}`);
@@ -75,7 +106,7 @@ export class PlanCanceller {
       let approximateAmountWasOwed: number | null = null;
       let daysSinceLastBill: number | null = null;
       let daysUntilNextBill: number | null = null;
-      let previousInvoiceAmountPaid: number | null = null;
+      let previousInvoiceAmountDue: number | null = null;
       let isOwed = !isExcluded;
 
       if (!isExcluded) {
@@ -85,7 +116,7 @@ export class PlanCanceller {
             approximateAmountWasOwed = calculation.refundAmount;
             daysSinceLastBill = calculation.daysSinceBill;
             daysUntilNextBill = calculation.daysUntilNextBill;
-            previousInvoiceAmountPaid = calculation.invoice.amount_paid;
+            previousInvoiceAmountDue = calculation.invoice.amount_due;
           } catch(e) {
             console.warn(e);
           }
@@ -95,6 +126,9 @@ export class PlanCanceller {
           await this.enqueueRequest(() =>
             this.stripe.subscriptions.cancel(subscription.id, {
               prorate: this.remainingValueMode === "prorate",
+              cancellation_details: {
+                comment: "administrative_cancellation:subplat_script"
+              }
             })
           );
         }
@@ -131,7 +165,7 @@ export class PlanCanceller {
         approximateAmountWasOwed,
         daysSinceLastBill,
         daysUntilNextBill,
-        previousInvoiceAmountPaid,
+        previousInvoiceAmountDue,
         isOwed,
         error: false,
       });
@@ -147,7 +181,7 @@ export class PlanCanceller {
         approximateAmountWasOwed: null,
         daysSinceLastBill: null,
         daysUntilNextBill: null,
-        previousInvoiceAmountPaid: null,
+        previousInvoiceAmountDue: null,
         isOwed: false,
         error: true,
       });
@@ -213,7 +247,7 @@ export class PlanCanceller {
       }
     }
 
-    return invoice.amount_paid;
+    return invoice.amount_due;
   }
 
   /**
@@ -222,6 +256,10 @@ export class PlanCanceller {
    * @returns Object containing refundAmount, daysSinceBill, daysUntilNextBill, and invoice
    */
   async calculateRefundAmount(subscription: Stripe.Subscription): Promise<{ refundAmount: number, daysSinceBill: number, daysUntilNextBill: number, invoice: Stripe.Invoice }> {
+    if (this.proratedRefundRate === null) {
+      throw new Error("proratedRefundRate must be specified to use calculateRefundAmount");
+    }
+
     if (!subscription.latest_invoice) {
       throw new Error(`No latest invoice for ${subscription.id}`);
     }
@@ -245,15 +283,13 @@ export class PlanCanceller {
     const periodEnd = new Date(subscription.current_period_end * 1000);
     const now = new Date();
 
-    const totalPeriodMs = periodEnd.getTime() - periodStart.getTime();
     const timeElapsedMs = now.getTime() - periodStart.getTime();
     const timeRemainingMs = periodEnd.getTime() - now.getTime();
 
     const daysSinceBill = Math.floor(timeElapsedMs / oneDayMs);
-    const totalDaysInPeriod = Math.floor(totalPeriodMs / oneDayMs);
     const daysUntilNextBill = Math.floor(timeRemainingMs / oneDayMs);
 
-    const refundAmount = Math.floor((daysUntilNextBill / totalDaysInPeriod) * invoice.amount_paid);
+    const refundAmount = daysUntilNextBill * this.proratedRefundRate;
 
     return { refundAmount, daysSinceBill, daysUntilNextBill, invoice };
   }
@@ -263,16 +299,16 @@ export class PlanCanceller {
     const refundAmount = calculation.refundAmount;
     const invoice = calculation.invoice;
 
-    if (refundAmount > invoice.amount_paid) {
-      throw new Error(`Will not refund ${invoice.id} for ${refundAmount} as it would eclipse the amount paid on the invoice`);
+    if (refundAmount > invoice.amount_due) {
+      throw new Error(`Will not refund ${invoice.id} for ${refundAmount} as it would eclipse the amount due on the invoice`);
     }
 
     if (refundAmount <= 0) {
       throw new Error(`Will not refund ${invoice.id} for ${refundAmount} as it is less than or equal to zero`);
     }
 
     if (invoice.paid_out_of_band) {
-      const behavior = refundAmount === invoice.amount_paid ? {
+      const behavior = refundAmount === invoice.amount_due ? {
         refundType: RefundType.Full
       } as const : {
         refundType: RefundType.Partial,
@@ -333,7 +369,7 @@ export class PlanCanceller {
       "approximateAmountWasOwed",
       "daysSinceLastBill",
       "daysUntilNextBill",
-      "previousInvoiceAmountPaid",
+      "previousInvoiceAmountDue",
       "isOwed",
       "error"
     ];
@@ -354,7 +390,7 @@ export class PlanCanceller {
     approximateAmountWasOwed: number | null,
     daysSinceLastBill: number | null,
     daysUntilNextBill: number | null,
-    previousInvoiceAmountPaid: number | null,
+    previousInvoiceAmountDue: number | null,
     isOwed: boolean,
     error: boolean
   }) {
@@ -370,13 +406,14 @@ export class PlanCanceller {
       args.approximateAmountWasOwed ?? "null",
       args.daysSinceLastBill ?? "null",
       args.daysUntilNextBill ?? "null",
-      args.previousInvoiceAmountPaid ?? "null",
+      args.previousInvoiceAmountDue ?? "null",
       args.isOwed,
       args.error
     ];
 
     const reportCSV = data.join(',') + '\n';
 
+    console.log(reportCSV);
     await writeFile(this.outputFile, reportCSV, {
       flag: 'a+',
       encoding: 'utf-8',

packages/fxa-auth-server/scripts/move-customers-to-new-plan-v2.ts

@@ -82,6 +82,10 @@ async function init() {
       '--skip-subscription-if-set-to-cancel',
       'Skip subscriptions that are set to cancel at period end'
     )
+    .option(
+      '--reset-billing-cycle-anchor',
+      'Reset the billing cycle anchor to now when updating subscriptions. If not set, billing cycle anchor remains unchanged.'
+    )
     .parse(process.argv);
 
   const { stripeHelper, log } = await setupProcessingTaskObjects(
@@ -95,6 +99,7 @@ async function init() {
 
   const dryRun = !!program.dryRun;
   const skipSubscriptionIfSetToCancel = !!program.skipSubscriptionIfSetToCancel;
+  const resetBillingCycleAnchor = !!program.resetBillingCycleAnchor;
 
   const statsd = {
     increment: () => {},
@@ -123,6 +128,7 @@ async function init() {
     program.coupon,
     prorationBehavior,
     skipSubscriptionIfSetToCancel,
+    resetBillingCycleAnchor,
     paypalHelper,
   );