feat(auth): add churn stay subscribed email

Because:

- Want to remind customers that do not have auto-renew set that their
  subscription is expiring soon and potentially offer them a coupon.

This commit:

- Adds subscriptionEndingReminder email
- Update existing subscription-reminders script to also send
  subscriptionEndingReminder emails if enabled.

Closes #PAY-3366

Author: StaberindeZA

libs/payments/customer/src/index.ts

@@ -20,4 +20,5 @@ export * from './lib/factories/tax-address.factory';
 export * from './lib/customer.error';
 export * from './lib/util/stripeInvoiceToFirstInvoicePreviewDTO';
 export * from './lib/util/getSubplatInterval';
+export * from './lib/util/getSubplatIntervalFromSubscription';
 export * from './lib/util/retrieveSubscriptionItem';

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

@@ -12,10 +12,12 @@ import {
   StripeCustomerFactory,
   StripeSubscriptionFactory,
   MockStripeConfigProvider,
+  StripeRangeQueryParamFactory,
 } from '@fxa/payments/stripe';
 import { STRIPE_SUBSCRIPTION_METADATA } from './types';
 import { SubscriptionManager } from './subscription.manager';
 import { MockStatsDProvider } from '@fxa/shared/metrics/statsd';
+import { StripeSubscriptionAsyncGeneratorFactory } from 'libs/payments/stripe/src/lib/factories/subscription.factory';
 
 describe('SubscriptionManager', () => {
   let subscriptionManager: SubscriptionManager;
@@ -92,6 +94,46 @@ describe('SubscriptionManager', () => {
     });
   });
 
+  describe('listCancelOnDateGenerator', () => {
+    const mockCurrentPeriodEnd = StripeRangeQueryParamFactory();
+    it('returns generator that yields subscriptions', async () => {
+      const mockSubscription = StripeSubscriptionFactory({
+        cancel_at_period_end: true,
+      });
+      const mockGenerator = StripeSubscriptionAsyncGeneratorFactory([
+        mockSubscription,
+      ]);
+      const expected = mockSubscription;
+
+      jest
+        .spyOn(stripeClient, 'subscriptionsListGenerator')
+        .mockReturnValue(mockGenerator);
+
+      const generator =
+        subscriptionManager.listCancelOnDateGenerator(mockCurrentPeriodEnd);
+      const result = (await generator.next()).value;
+
+      expect(result).toEqual(expected);
+    });
+
+    it('returns generator that yields no subscriptions', async () => {
+      const mockSubscription = StripeSubscriptionFactory();
+      const mockGenerator = StripeSubscriptionAsyncGeneratorFactory([
+        mockSubscription,
+      ]);
+
+      jest
+        .spyOn(stripeClient, 'subscriptionsListGenerator')
+        .mockReturnValue(mockGenerator);
+
+      const generator =
+        subscriptionManager.listCancelOnDateGenerator(mockCurrentPeriodEnd);
+      const result = (await generator.next()).value;
+
+      expect(result).toEqual(undefined);
+    });
+  });
+
   describe('cancel', () => {
     it('calls stripeclient', async () => {
       const mockSubscription = StripeSubscriptionFactory();

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

@@ -22,7 +22,7 @@ export class SubscriptionManager {
 
   async create(
     params: Omit<Stripe.SubscriptionCreateParams, 'metadata'> & {
-      metadata?: StripeSubscriptionMetadataInput
+      metadata?: StripeSubscriptionMetadataInput;
     },
     options?: Stripe.RequestOptions
   ) {
@@ -36,8 +36,8 @@ export class SubscriptionManager {
   async update(
     subscriptionId: string,
     params: Omit<Stripe.SubscriptionUpdateParams, 'metadata'> & {
-      metadata?: StripeSubscriptionMetadataInput
-    },
+      metadata?: StripeSubscriptionMetadataInput;
+    }
   ) {
     return this.stripeClient.subscriptionsUpdate(subscriptionId, params);
   }
@@ -50,6 +50,16 @@ export class SubscriptionManager {
     return result.data;
   }
 
+  async *listCancelOnDateGenerator(currentPeriodEnd: Stripe.RangeQueryParam) {
+    for await (const subscription of this.stripeClient.subscriptionsListGenerator(
+      { current_period_end: currentPeriodEnd }
+    )) {
+      if (subscription.cancel_at_period_end) {
+        yield subscription;
+      }
+    }
+  }
+
   async cancelIncompleteSubscriptionsToPrice(
     customerId: string,
     priceId: string

libs/payments/customer/src/lib/util/getSubplatIntervalFromSubscription.spec.ts

@@ -0,0 +1,52 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import {
+  StripePriceFactory,
+  StripePriceRecurringFactory,
+  StripeSubscriptionFactory,
+  StripeSubscriptionItemFactory,
+} from '@fxa/payments/stripe';
+import { SubplatInterval } from '../types';
+import {
+  getSubplatIntervalFromSubscription,
+  PriceNotRecurringError,
+} from './getSubplatIntervalFromSubscription';
+
+describe('getSubplatIntervalFromSubscription', () => {
+  const priceRecurring = StripePriceRecurringFactory({
+    interval: 'month',
+    interval_count: 1,
+  });
+  const price = StripePriceFactory({ recurring: priceRecurring });
+  const subscription = StripeSubscriptionFactory({
+    items: {
+      object: 'list',
+      data: [StripeSubscriptionItemFactory({ price })],
+      has_more: false,
+      url: `/v1/subscription_items?subscription=`,
+    },
+  });
+
+  it('returns the correct offering and interval', () => {
+    expect(getSubplatIntervalFromSubscription(subscription)).toBe(
+      SubplatInterval.Monthly
+    );
+  });
+
+  it('does not find offering and interval', () => {
+    price.recurring = StripePriceRecurringFactory({
+      interval: 'day',
+      interval_count: 5,
+    });
+    expect(getSubplatIntervalFromSubscription(subscription)).toBe(undefined);
+  });
+
+  it('does not find offering and interval', async () => {
+    price.recurring = null;
+    expect(() => getSubplatIntervalFromSubscription(subscription)).toThrow(
+      PriceNotRecurringError
+    );
+  });
+});

libs/payments/customer/src/lib/util/getSubplatIntervalFromSubscription.ts

@@ -0,0 +1,29 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import type { StripeSubscription } from '@fxa/payments/stripe';
+import { getPriceFromSubscription } from './getPriceFromSubscription';
+import { getSubplatInterval } from './getSubplatInterval';
+
+export class PriceNotRecurringError extends Error {
+  private info: { priceId: string };
+  constructor(priceId: string) {
+    super('Plan is not recurring');
+    this.name = 'SubscriptionRemindersPlanRecurringError';
+    this.info = { priceId };
+  }
+}
+
+export const getSubplatIntervalFromSubscription = (
+  subscription: StripeSubscription
+) => {
+  const price = getPriceFromSubscription(subscription);
+  if (!price.recurring) {
+    throw new PriceNotRecurringError(price.id);
+  }
+  return getSubplatInterval(
+    price.recurring.interval,
+    price.recurring.interval_count
+  );
+};

libs/payments/stripe/src/index.ts

@@ -40,6 +40,7 @@ export { StripeTaxRateFactory } from './lib/factories/tax-rate.factory';
 export { StripeTotalDiscountAmountsFactory } from './lib/factories/total-discount-amounts.factory';
 export { StripeTotalTaxAmountsFactory } from './lib/factories/total-tax-amounts.factory';
 export { StripeUpcomingInvoiceFactory } from './lib/factories/upcoming-invoice.factory';
+export { StripeRangeQueryParamFactory } from './lib/factories/utils.factory';
 export * from './lib/stripe.client';
 export * from './lib/stripe.client.types';
 export * from './lib/stripe.config';

libs/payments/stripe/src/lib/factories/api-list.factory.ts

@@ -1,5 +1,13 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
 import { faker } from '@faker-js/faker';
-import { StripeApiList, StripeResponse } from '../stripe.client.types';
+import {
+  StripeApiList,
+  StripeResponse,
+  type StripeApiListPromise,
+} from '../stripe.client.types';
 
 export const StripeApiListFactory = <T extends Array<any>>(
   data: T,
@@ -24,3 +32,33 @@ export const StripeResponseFactory = <T>(
   ...data,
   ...override,
 });
+
+export const StripeApiListPromiseFactory = <T>(
+  data: T[]
+): StripeApiListPromise<T> => {
+  let index = 0;
+
+  const promise = Promise.resolve(
+    StripeApiListFactory(data)
+  ) as StripeApiListPromise<T>;
+
+  promise.next = async (): Promise<IteratorResult<T>> => {
+    if (index < data.length) {
+      return { value: data[index++], done: false };
+    }
+    return { value: undefined as any, done: true };
+  };
+  promise[Symbol.asyncIterator] = function () {
+    return promise;
+  };
+
+  promise.autoPagingEach = async (handler: (item: T) => any) => {
+    for (const item of data) {
+      await handler(item);
+    }
+  };
+
+  promise.autoPagingToArray = async () => [...data];
+
+  return promise;
+};

libs/payments/stripe/src/lib/factories/subscription.factory.ts

@@ -114,3 +114,11 @@ export const StripeSubscriptionItemFactory = (
   tax_rates: [],
   ...override,
 });
+
+export async function* StripeSubscriptionAsyncGeneratorFactory(
+  subscriptions: StripeSubscription[]
+): AsyncGenerator<StripeSubscription, void, unknown> {
+  for (const sub of subscriptions) {
+    yield sub;
+  }
+}

libs/payments/stripe/src/lib/factories/utils.factory.ts

@@ -0,0 +1,11 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import { Stripe } from 'stripe';
+
+export const StripeRangeQueryParamFactory = (
+  override?: Partial<Stripe.RangeQueryParam>
+): Stripe.RangeQueryParam => ({
+  ...override,
+});

libs/payments/stripe/src/lib/stripe.client.spec.ts

@@ -8,6 +8,7 @@ import { Stripe } from 'stripe';
 
 import {
   StripeApiListFactory,
+  StripeApiListPromiseFactory,
   StripeResponseFactory,
 } from './factories/api-list.factory';
 import { StripeCustomerFactory } from './factories/customer.factory';
@@ -167,6 +168,20 @@ describe('StripeClient', () => {
     });
   });
 
+  describe('subscriptionsListGenerator', () => {
+    it('returns generator that yields subscriptions from Stripe', async () => {
+      const mockSubscription = StripeSubscriptionFactory();
+
+      mockStripeSubscriptionsList.mockResolvedValue(
+        StripeApiListPromiseFactory([mockSubscription])
+      );
+
+      const generator = stripeClient.subscriptionsListGenerator();
+      const result = (await generator.next()).value;
+      expect(result).toEqual(mockSubscription);
+    });
+  });
+
   describe('subscriptionsCreate', () => {
     it('creates subscription within Stripe', async () => {
       const mockCustomer = StripeCustomerFactory();