feat(payments-next): Update page: Subscription Management

Because:

* We want to reduce churn by giving customers offers when they either go to cancel their subscription, or encourage them to stay subscribed to a subscription that will soon expire.

This commit:

* Determines customer's eligibility, and either displays appropriate messages + takes them to corresponding links, or keeps existing behaviour.

Closes #PAY-3365

Author: elizabeth-ilina

apps/payments/next/app/[locale]/subscriptions/manage/page.tsx

@@ -67,7 +67,7 @@ export default async function Manage({
     subscriptions,
     appleIapSubscriptions,
     googleIapSubscriptions,
-  } = await getSubManPageContentAction(session.user?.id);
+  } = await getSubManPageContentAction(session.user?.id, acceptLanguage, locale);
   const {
     billingAgreementId,
     brand,

libs/payments/customer/src/lib/customer.error.ts

@@ -36,6 +36,21 @@ export class PriceForCurrencyNotFoundError extends CustomerError {
   }
 }
 
+export class SubscriptionCustomerMismatchError extends CustomerError {
+  constructor(
+    customerId: string,
+    subscriptionCustomerId: string,
+    subscriptionId: string,
+  ) {
+    super('Subscription customer does not match provided customer', {
+      customerId,
+      subscriptionCustomerId,
+      subscriptionId,
+    });
+    this.name = 'SubscriptionCustomerMismatchError';
+  }
+}
+
 export class PromotionCodeError extends CustomerError {
   constructor(message: string, info: Record<string, any>) {
     super(message, info);

libs/payments/customer/src/lib/subscription.manager.spec.ts

@@ -16,6 +16,7 @@ import {
 import { STRIPE_SUBSCRIPTION_METADATA } from './types';
 import { SubscriptionManager } from './subscription.manager';
 import { MockStatsDProvider } from '@fxa/shared/metrics/statsd';
+import { SubscriptionCustomerMismatchError} from './customer.error'
 
 describe('SubscriptionManager', () => {
   let subscriptionManager: SubscriptionManager;
@@ -298,4 +299,144 @@ describe('SubscriptionManager', () => {
       expect(result).toEqual('paypal');
     });
   });
+
+  describe('getSubscriptionStatus', () => {
+    it('correctly returns active and cancelAtPeriodEnd when customerId matches', async () => {
+      const mockCustomer = StripeCustomerFactory();
+      const mockSubscription = StripeSubscriptionFactory({
+        status: 'active',
+        cancel_at_period_end: true,
+        customer: mockCustomer.id,
+      });
+      const mockResponse = StripeResponseFactory(mockSubscription);
+
+      jest
+        .spyOn(subscriptionManager, 'retrieve')
+        .mockResolvedValue(mockResponse);
+
+      const result = await subscriptionManager.getSubscriptionStatus(
+        mockCustomer.id,
+        mockSubscription.id
+      );
+
+      expect(subscriptionManager.retrieve).toHaveBeenCalledWith(
+        mockSubscription.id
+      );
+      expect(result).toEqual({
+        active: true,
+        cancelAtPeriodEnd: true,
+      });
+    });
+
+    it('throws an error when customerId does not match', async () => {
+      const mockCustomer1 = StripeCustomerFactory();
+      const mockCustomer2 = StripeCustomerFactory();
+      const mockSubscription = StripeSubscriptionFactory({
+        customer: mockCustomer2.id,
+      });
+      const mockResponse = StripeResponseFactory(mockSubscription);
+
+      jest
+        .spyOn(subscriptionManager, 'retrieve')
+        .mockResolvedValueOnce(mockResponse);
+
+      await expect(
+        subscriptionManager.getSubscriptionStatus(mockCustomer1.id, mockSubscription.id)
+      ).rejects.toThrow(SubscriptionCustomerMismatchError);
+
+      expect(subscriptionManager.retrieve).toHaveBeenCalledWith(
+        mockSubscription.id
+      );
+    });
+  });
+
+  describe('applyStripeCouponToSubscription', () => {
+    it('successfully applies coupon without setCancelAtPeriodEnd', async () => {
+      const mockCustomer = StripeCustomerFactory();
+      const mockSubscription = StripeSubscriptionFactory({
+        customer: mockCustomer.id,
+      });
+      const mockResponse = StripeResponseFactory(mockSubscription);
+      const mockCouponId = 'coupon_123';
+      const mockUpdatedSubscription = StripeSubscriptionFactory({
+        customer: mockCustomer.id,
+      });
+      const mockUpdatedResponse = StripeResponseFactory(mockUpdatedSubscription);
+
+      jest
+        .spyOn(subscriptionManager, 'retrieve')
+        .mockResolvedValue(mockResponse);
+      jest
+        .spyOn(subscriptionManager, 'update')
+        .mockResolvedValue(mockUpdatedResponse);
+
+      const result = await subscriptionManager.applyStripeCouponToSubscription({
+        customerId: mockCustomer.id,
+        subscriptionId: mockSubscription.id,
+        stripeCouponId: mockCouponId
+      });
+
+      expect(subscriptionManager.retrieve).toHaveBeenCalledWith(mockSubscription.id);
+      expect(subscriptionManager.update).toHaveBeenCalledWith(mockSubscription.id, {
+        discounts: [{ coupon: mockCouponId }],
+      });
+      expect(result).toEqual(mockUpdatedResponse);
+    });
+
+    it('successfully applies coupon with setCancelAtPeriodEnd', async () => {
+      const mockCustomer = StripeCustomerFactory();
+      const mockSubscription = StripeSubscriptionFactory({
+        customer: mockCustomer.id,
+      });
+      const mockResponse = StripeResponseFactory(mockSubscription);
+      const mockCouponId = 'coupon_123';
+      const mockUpdatedSubscription = StripeSubscriptionFactory({
+        customer: mockCustomer.id,
+      });
+      const mockUpdatedResponse = StripeResponseFactory(mockUpdatedSubscription);
+
+      jest
+        .spyOn(subscriptionManager, 'retrieve')
+        .mockResolvedValue(mockResponse);
+      jest
+        .spyOn(subscriptionManager, 'update')
+        .mockResolvedValue(mockUpdatedResponse);
+
+      const result = await subscriptionManager.applyStripeCouponToSubscription({
+        customerId: mockCustomer.id,
+        subscriptionId: mockSubscription.id,
+        stripeCouponId: mockCouponId,
+        setCancelAtPeriodEnd: true
+      });
+
+      expect(subscriptionManager.update).toHaveBeenCalledWith(mockSubscription.id, {
+        discounts: [{ coupon: mockCouponId }],
+        cancel_at_period_end: true,
+      });
+      expect(result).toEqual(mockUpdatedResponse);
+    });
+
+    it('throws an error when customerId does not match', async () => {
+      const mockCustomer1 = StripeCustomerFactory();
+      const mockCustomer2 = StripeCustomerFactory();
+      const mockSubscription = StripeSubscriptionFactory({
+        customer: mockCustomer2.id,
+      });
+      const mockResponse = StripeResponseFactory(mockSubscription);
+      const mockCouponId = 'coupon_123';
+
+      jest
+        .spyOn(subscriptionManager, 'retrieve')
+        .mockResolvedValueOnce(mockResponse);
+
+      await expect(
+        subscriptionManager.applyStripeCouponToSubscription({
+          customerId: mockCustomer1.id,
+          subscriptionId: mockSubscription.id,
+          stripeCouponId: mockCouponId
+        })
+      ).rejects.toThrow(SubscriptionCustomerMismatchError);
+      expect(jest.spyOn(subscriptionManager, 'update')).not.toHaveBeenCalled();
+    });
+  });
 });

libs/payments/customer/src/lib/subscription.manager.ts

@@ -8,6 +8,7 @@ import { Stripe } from 'stripe';
 import { StripeClient, StripeSubscription } from '@fxa/payments/stripe';
 import { ACTIVE_SUBSCRIPTION_STATUSES } from '@fxa/payments/stripe';
 import { type StripeSubscriptionMetadataInput } from './types';
+import { SubscriptionCustomerMismatchError} from './customer.error'
 
 @Injectable()
 export class SubscriptionManager {
@@ -88,4 +89,58 @@ export class SubscriptionManager {
         this.getPaymentProvider(sub) === 'paypal'
     );
   }
+
+  async getSubscriptionStatus(
+    customerId: string,
+    subscriptionId: string
+  ): Promise<{
+    active: boolean;
+    cancelAtPeriodEnd: boolean;
+  }> {
+    const subscription = await this.retrieve(subscriptionId);
+
+    if (subscription.customer !== customerId) {
+      throw new SubscriptionCustomerMismatchError(
+        customerId,
+        subscription.customer,
+        subscriptionId
+      );
+    }
+
+    return {
+      active: subscription.status === 'active',
+      cancelAtPeriodEnd: subscription.cancel_at_period_end,
+    };
+  }
+
+  async applyStripeCouponToSubscription(args: {
+    customerId: string;
+    subscriptionId: string;
+    stripeCouponId: string;
+    setCancelAtPeriodEnd?: boolean;
+  }) {
+    const { customerId, subscriptionId, stripeCouponId, setCancelAtPeriodEnd } = args;
+
+    const subscription = await this.retrieve(subscriptionId);
+
+    if (subscription.customer !== customerId) {
+      throw new SubscriptionCustomerMismatchError(
+        customerId,
+        subscription.customer,
+        subscriptionId
+      );
+    }
+    try {
+      const updatedSubscription = await this.update(
+        subscriptionId,
+        {
+          discounts: [{ coupon: stripeCouponId }],
+          ...(setCancelAtPeriodEnd ? { cancel_at_period_end: true } : {}),
+        }
+      );
+      return updatedSubscription;
+    } catch (error) {
+      return null;
+    }
+  }
 }