feat(subplat): add free access program to billing-and-subscriptions API

Because:

 * Relying parties fetch current subscriptions via GET v1/billing-and-subscriptions,
   but Free Access Program grants were not represented.

This commit:

 * Adds a `free_access` subscription type sourcing product identity from the
   related offering.
 * Filters grants by the projection's per-client capabilities.
 * Gates the code behind a FreeAccessProgramConfig feature flag (default off).

Closes #PAY-3790

Author: StaberindeZA

apps/payments/api/.env

@@ -109,3 +109,6 @@ SENTRY_CONFIG__SAMPLE_RATE=1
 SENTRY_CONFIG__TRACES_SAMPLE_RATE=0
 
 SWAGGER_UI=false
+
+# Free Access Program
+FREE_ACCESS_PROGRAM_CONFIG__ENABLED=false

apps/payments/api/src/app/app.module.ts

@@ -72,6 +72,7 @@ import { AccountManager } from '@fxa/shared/account/account';
 import { CartManager } from '@fxa/payments/cart';
 import {
   CmsContentValidationManager,
+  FreeAccessProgramConfigurationManager,
   MeteringConfigurationManager,
   ProductConfigurationManager,
   StrapiClient,
@@ -124,6 +125,7 @@ import { PaymentsMetricsAggregatorService } from '@fxa/payments/metrics-aggregat
     BillingAndSubscriptionsService,
     CapabilityManager,
     ProductConfigurationManager,
+    FreeAccessProgramConfigurationManager,
     CartManager,
     SubscriptionEventsService,
     PaymentsGleanFactory,

apps/payments/api/src/config/index.ts

@@ -7,6 +7,7 @@ import { AppleIapClientConfig, GoogleIapClientConfig } from '@fxa/payments/iap';
 import { PaymentsGleanConfig } from '@fxa/payments/metrics';
 import { PaypalClientConfig } from '@fxa/payments/paypal';
 import { StripeConfig } from '@fxa/payments/stripe';
+import { FreeAccessProgramConfig } from '@fxa/payments/api-server';
 import { StrapiClientConfig } from '@fxa/shared/cms';
 import { MySQLConfig } from '@fxa/shared/db/mysql/core';
 import { FxaWebhookConfig, StripeEventConfig } from '@fxa/payments/webhooks';
@@ -99,4 +100,9 @@ export class RootConfig {
   @IsBoolean()
   @IsDefined()
   public readonly swaggerUi!: boolean;
+
+  @Type(() => FreeAccessProgramConfig)
+  @ValidateNested()
+  @IsDefined()
+  public readonly freeAccessProgramConfig!: Partial<FreeAccessProgramConfig>;
 }

libs/payments/api-server/src/index.ts

@@ -8,3 +8,4 @@ export * from './lib/billing-and-subscriptions.schema';
 export * from './lib/billing-and-subscriptions.factories';
 export * from './lib/util/openapi';
 export * from './lib/util/response-validation.interceptor';
+export * from './lib/free-access-program.config';

libs/payments/api-server/src/lib/billing-and-subscriptions.controller.spec.ts

@@ -41,16 +41,19 @@ import {
   StripeClient,
 } from '@fxa/payments/stripe';
 import {
+  FreeAccessProgramConfigurationManager,
   MockStrapiClientConfigProvider,
   ProductConfigurationManager,
   StrapiClient,
 } from '@fxa/shared/cms';
+import { AccountManager } from '@fxa/shared/account/account';
 import { MockFirestoreProvider } from '@fxa/shared/db/firestore';
 import { MockAccountDatabaseNestFactory } from '@fxa/shared/db/mysql/account';
 import { MockStatsDProvider } from '@fxa/shared/metrics/statsd';
 
 import { BillingAndSubscriptionsController } from './billing-and-subscriptions.controller';
 import { BillingAndSubscriptionsService } from './billing-and-subscriptions.service';
+import { MockFreeAccessProgramConfigProvider } from './free-access-program.config';
 
 const FxaOAuthUserFactory = (
   override?: Partial<FxaOAuthUser>
@@ -79,6 +82,9 @@ describe('BillingAndSubscriptionsController', () => {
         ProductManager,
         CapabilityManager,
         ProductConfigurationManager,
+        FreeAccessProgramConfigurationManager,
+        MockFreeAccessProgramConfigProvider,
+        AccountManager,
         AppleIapPurchaseManager,
         AppleIapClient,
         MockAppleIapClientConfigProvider,

libs/payments/api-server/src/lib/billing-and-subscriptions.schema.ts

@@ -131,6 +131,27 @@ export const appleIapSubscriptionSchema = z.object({
  */
 export type AppleIapSubscription = z.infer<typeof appleIapSubscriptionSchema>;
 
+/**
+ * Zod schema for a Free Access Program grant.
+ *
+ * A Free Access Program customer is not subscribed to a Stripe Price, so the
+ * product identity is sourced from the related offering. There is no price,
+ * subscription id, or billing interval behind a free grant, so none of those
+ * fields are reported — only the product the grant provides access to.
+ */
+export const freeAccessSubscriptionSchema = z.object({
+  _subscription_type: z.literal('free_access'),
+  offering_api_identifier: z.string(),
+  product_id: z.string(),
+});
+
+/**
+ * A Free Access Program grant.
+ */
+export type FreeAccessSubscription = z.infer<
+  typeof freeAccessSubscriptionSchema
+>;
+
 /**
  * Zod schema for a subscription returned by the billing-and-subscriptions
  * endpoint, discriminated on `_subscription_type`.
@@ -139,6 +160,7 @@ export const subscriptionSchema = z.discriminatedUnion('_subscription_type', [
   webSubscriptionSchema,
   googleIapSubscriptionSchema,
   appleIapSubscriptionSchema,
+  freeAccessSubscriptionSchema,
 ]);
 
 /**