@forklaunch/implementation-billing-stripe 1.2.12 → 1.3.0

package/lib/eject/domain/types/paymentLink.mapper.types.ts

@@ -9,12 +9,26 @@ export type StripePaymentLinkMappers<
   Dto extends StripePaymentLinkDtos<StatusEnum>
 > = {
   PaymentLinkMapper: {
+    /** Validate and restore declared DTO fields after a JSON cache read. */
+    normalizeCachedDto?: (
+      value: Dto['PaymentLinkMapper']
+    ) => Dto['PaymentLinkMapper'];
     entity: Entities['PaymentLinkMapper'];
     toDto: (
       entity: InferEntity<Entities['PaymentLinkMapper']>
     ) => Promise<Dto['PaymentLinkMapper']>;
+    validateCachedRead?: (existing: Dto['PaymentLinkMapper']) => void;
+    /** Opt-in cached reference lookup; does not prove provider account ownership. */
+    readCachedDto?: (
+      existing: Dto['PaymentLinkMapper'],
+      retrieve: (providerId: string) => Promise<Stripe.PaymentLink>
+    ) => Promise<Dto['PaymentLinkMapper']>;
   };
   CreatePaymentLinkMapper: {
+    /** Provider effects already occurred; validate shape before local persistence. */
+    validateProviderCreate?: (provider: Stripe.PaymentLink) => Promise<void>;
+    /** Pure configured validation before any provider creation effects. */
+    validateCreate?: (dto: Dto['CreatePaymentLinkMapper']) => Promise<void>;
     entity: Entities['CreatePaymentLinkMapper'];
     toEntity: (
       dto: Dto['CreatePaymentLinkMapper'],
@@ -24,6 +38,28 @@ export type StripePaymentLinkMappers<
     ) => Promise<InferEntity<Entities['CreatePaymentLinkMapper']>>;
   };
   UpdatePaymentLinkMapper: {
+    /** Validate the already-applied provider result and prepare one local update.
+     * `provider.id` is the stored Stripe id, which the service has already
+     * matched; `dto.id` stays the public id. Does not resolve aliases or
+     * establish provider account ownership.
+     */
+    toLocalUpdate?: (
+      dto: Dto['UpdatePaymentLinkMapper'],
+      provider: Stripe.PaymentLink
+    ) => Promise<Dto['UpdatePaymentLinkMapper']>;
+    toCachedDto?: (
+      dto: Dto['UpdatePaymentLinkMapper'],
+      existing: Dto['PaymentLinkMapper'],
+      em: EntityManager,
+      ...args: unknown[]
+    ) => Promise<Dto['PaymentLinkMapper']>;
+    /** Validate a patch against the normalized cached DTO before provider I/O.
+     * This hook does not resolve provider IDs or authorize provider mutations.
+     */
+    validateCachedUpdate?: (
+      dto: Dto['UpdatePaymentLinkMapper'],
+      existing: Dto['PaymentLinkMapper']
+    ) => Promise<void>;
     entity: Entities['UpdatePaymentLinkMapper'];
     toEntity: (
       dto: Dto['UpdatePaymentLinkMapper'],

package/lib/eject/domain/types/plan.mapper.types.ts

@@ -8,12 +8,21 @@ export type StripePlanMappers<
   Dto extends StripePlanDtos
 > = {
   PlanMapper: {
+    /** Read-result identity check; does not establish provider account ownership. */
+    validateProviderRead?: (
+      expectedExternalId: string,
+      provider: Stripe.Plan
+    ) => Promise<void>;
     entity: Entities['PlanMapper'];
     toDto: (
       entity: InferEntity<Entities['PlanMapper']>
     ) => Promise<Dto['PlanMapper']>;
   };
   CreatePlanMapper: {
+    /** Provider effects already occurred; validate shape before local persistence. */
+    validateProviderCreate?: (provider: Stripe.Plan) => Promise<void>;
+    /** Pure configured validation before any provider creation effects. */
+    validateCreate?: (dto: Dto['CreatePlanMapper']) => Promise<void>;
     entity: Entities['CreatePlanMapper'];
     toEntity: (
       dto: Dto['CreatePlanMapper'],
@@ -23,6 +32,13 @@ export type StripePlanMappers<
     ) => Promise<InferEntity<Entities['CreatePlanMapper']>>;
   };
   UpdatePlanMapper: {
+    /** Validate consumed provider references before a subsequent mutation. */
+    validateProviderUpdate?: (
+      dto: Dto['UpdatePlanMapper'],
+      provider: Stripe.Plan
+    ) => Promise<void>;
+    /** Pure configured validation before any provider replacement effects. */
+    validateUpdate?: (dto: Dto['UpdatePlanMapper']) => Promise<void>;
     entity: Entities['UpdatePlanMapper'];
     toEntity: (
       dto: Dto['UpdatePlanMapper'],

package/lib/eject/domain/types/stripe.dto.types.ts

@@ -84,7 +84,7 @@ export type StripeCreateBillingPortalDto = Omit<
   CreateBillingPortalDto,
   'providerFields'
 > & {
-  stripeFields: Omit<
+  stripeFields?: Omit<
     StripeBillingPortalSessionCreateParams,
     BillingPortalOmissions
   >;
@@ -126,10 +126,9 @@ export type StripeCreateCheckoutSessionDto<StatusEnum> = Omit<
     typeof CurrencyEnum,
     StatusEnum
   >,
-  'providerFields' | 'uri'
+  'providerFields'
 > & {
-  uri: string;
-  stripeFields: Omit<
+  stripeFields?: Omit<
     StripeCheckoutSessionCreateParams,
     CheckoutSessionOmissions
   >;
@@ -151,9 +150,8 @@ export type StripeUpdateCheckoutSessionDto<StatusEnum> = Omit<
 
 export type StripeCheckoutSessionDto<StatusEnum> = Omit<
   CheckoutSessionDto<typeof PaymentMethodEnum, typeof CurrencyEnum, StatusEnum>,
-  'providerFields' | 'uri'
+  'providerFields'
 > & {
-  uri: string;
   stripeFields: StripeCheckoutSession;
 };
 
@@ -210,7 +208,7 @@ export type StripeCreatePlanDto = Omit<
   >,
   'providerFields'
 > & {
-  stripeFields: Omit<StripePlanCreateParams, PlanOmissions>;
+  stripeFields?: Omit<StripePlanCreateParams, PlanOmissions>;
 };
 
 export type StripeUpdatePlanDto = Omit<
@@ -248,7 +246,7 @@ export type StripeCreateSubscriptionDto<PartyType> = Omit<
   CreateSubscriptionDto<PartyType, typeof BillingProviderEnum>,
   'providerFields'
 > & {
-  stripeFields: Omit<StripeSubscriptionCreateParams, SubscriptionOmissions>;
+  stripeFields?: Omit<StripeSubscriptionCreateParams, SubscriptionOmissions>;
 };
 
 export type StripeUpdateSubscriptionDto<PartyType> = Omit<

package/lib/eject/domain/types/stripe.entity.types.ts

@@ -6,12 +6,6 @@ import {
   Plan,
   Subscription
 } from '../../persistence/entities';
-import {
-  BillingProviderEnum,
-  CurrencyEnum,
-  PaymentMethodEnum,
-  PlanCadenceEnum
-} from '../enum';
 
 // Billing Portal Types
 export type StripeBillingPortalEntities = {

package/lib/eject/domain/types/subscription.mapper.types.ts

@@ -9,12 +9,23 @@ export type StripeSubscriptionMappers<
   Dto extends StripeSubscriptionDtos<PartyTypeEnum>
 > = {
   SubscriptionMapper: {
+    /** Read-result identity check; does not establish provider account ownership. */
+    validateProviderRead?: (
+      expectedExternalId: string,
+      provider: Stripe.Subscription
+    ) => Promise<void>;
+    /** Trusted persisted party discriminators for local subscription lookups. */
+    partyTypes?: Readonly<{ user: string; organization: string }>;
     entity: Entities['SubscriptionMapper'];
     toDto: (
       entity: InferEntity<Entities['SubscriptionMapper']>
     ) => Promise<Dto['SubscriptionMapper']>;
   };
   CreateSubscriptionMapper: {
+    /** Provider effects already occurred; validate shape before local persistence. */
+    validateProviderCreate?: (provider: Stripe.Subscription) => Promise<void>;
+    /** Pure configured validation before any provider creation effects. */
+    validateCreate?: (dto: Dto['CreateSubscriptionMapper']) => Promise<void>;
     entity: Entities['CreateSubscriptionMapper'];
     toEntity: (
       dto: Dto['CreateSubscriptionMapper'],
@@ -24,6 +35,16 @@ export type StripeSubscriptionMappers<
     ) => Promise<InferEntity<Entities['CreateSubscriptionMapper']>>;
   };
   UpdateSubscriptionMapper: {
+    /** Validate consumed provider references before a subsequent mutation. */
+    validateProviderUpdate?: (
+      dto: Dto['UpdateSubscriptionMapper'],
+      provider: Stripe.Subscription
+    ) => Promise<void>;
+    /** Configured preflight; changing customer ownership needs a separate workflow. */
+    validateUpdate?: (
+      dto: Dto['UpdateSubscriptionMapper'],
+      existing: Dto['SubscriptionMapper']
+    ) => Promise<void>;
     entity: Entities['UpdateSubscriptionMapper'];
     toEntity: (
       dto: Dto['UpdateSubscriptionMapper'],

package/lib/eject/services/billingPortal.service.ts

@@ -78,11 +78,15 @@ export class StripeBillingPortalService<
     billingPortalDto: StripeCreateBillingPortalDto,
     ...args: unknown[]
   ): Promise<Dto['BillingPortalMapper']> {
+    await this.mappers.CreateBillingPortalMapper.validateCreate?.(billingPortalDto);
+
     const session = await this.stripeClient.billingPortal.sessions.create({
       ...billingPortalDto.stripeFields,
       customer: billingPortalDto.customerId
     });
 
+    await this.mappers.CreateBillingPortalMapper.validateProviderCreate?.(session);
+
     return await this.baseBillingPortalService.createBillingPortalSession(
       {
         ...billingPortalDto,
@@ -116,11 +120,31 @@ export class StripeBillingPortalService<
       await this.baseBillingPortalService.getBillingPortalSession({
         id: billingPortalDto.id
       });
+    if (
+      !this.options?.enableDatabaseBackup &&
+      this.mappers.UpdateBillingPortalMapper.toCachedDto &&
+      billingPortalDto.customerId !== undefined &&
+      billingPortalDto.customerId !== existingSession.customerId
+    ) {
+      throw new Error('Cached session identity cannot change');
+    }
+    if (
+      !this.options?.enableDatabaseBackup &&
+      this.mappers.UpdateBillingPortalMapper.toCachedDto &&
+      this.mappers.UpdateBillingPortalMapper.validateCachedUpdate
+    ) {
+      await this.mappers.UpdateBillingPortalMapper.validateCachedUpdate(
+        billingPortalDto,
+        existingSession
+      );
+    }
     const session = await this.stripeClient.billingPortal.sessions.create({
       ...billingPortalDto.stripeFields,
       customer: billingPortalDto.customerId || existingSession.customerId
     });
 
+    await this.mappers.CreateBillingPortalMapper.validateProviderCreate?.(session);
+
     return await this.baseBillingPortalService.updateBillingPortalSession(
       {
         ...billingPortalDto,

package/lib/eject/services/checkoutSession.service.ts

@@ -93,6 +93,8 @@ export class StripeCheckoutSessionService<
     checkoutSessionDto: StripeCreateCheckoutSessionDto<StatusEnum>,
     ...args: unknown[]
   ): Promise<Dto['CheckoutSessionMapper']> {
+    await this.mappers.CreateCheckoutSessionMapper.validateCreate?.(checkoutSessionDto);
+
     const session = await this.stripeClient.checkout.sessions.create({
       ...checkoutSessionDto.stripeFields,
       mode: 'subscription',
@@ -102,6 +104,8 @@ export class StripeCheckoutSessionService<
       cancel_url: checkoutSessionDto.cancelRedirectUri
     });
 
+    await this.mappers.CreateCheckoutSessionMapper.validateProviderCreate?.(session);
+
     return await this.baseCheckoutSessionService.createCheckoutSession(
       {
         ...checkoutSessionDto,
@@ -119,6 +123,17 @@ export class StripeCheckoutSessionService<
   async getCheckoutSession(
     idDto: IdDto
   ): Promise<Dto['CheckoutSessionMapper']> {
+    const readCachedDto = this.mappers.CheckoutSessionMapper.readCachedDto;
+    if (readCachedDto) {
+      const existing =
+        await this.baseCheckoutSessionService.getCheckoutSession(idDto);
+      if (existing.id !== idDto.id) {
+        throw new Error('Cached checkout identity does not match');
+      }
+      return readCachedDto(existing, (providerId) =>
+        this.stripeClient.checkout.sessions.retrieve(providerId)
+      );
+    }
     const session = await this.stripeClient.checkout.sessions.retrieve(
       idDto.id
     );
@@ -130,26 +145,56 @@ export class StripeCheckoutSessionService<
     return databaseCheckoutSession;
   }
 
+  /**
+   * The Stripe id (`cs_...`) stored with a checkout session when it was
+   * created. Public ids are local; Stripe only knows its own id. The stored
+   * provider object's id wins; a record without one is still usable when its
+   * own id is a Stripe id. Anything else fails here rather than sending Stripe
+   * a local id.
+   */
+  protected async stripeCheckoutSessionId(id: string): Promise<string> {
+    const checkoutSession =
+      await this.baseCheckoutSessionService.getCheckoutSession({ id });
+    const stored = (
+      checkoutSession?.stripeFields as { id?: unknown } | undefined
+    )?.id;
+    const stripeId = stored === undefined ? checkoutSession?.id : stored;
+    if (typeof stripeId !== 'string' || !/^cs_[A-Za-z0-9_]+$/.test(stripeId)) {
+      throw new Error(
+        `Checkout session ${id} has no stored Stripe checkout session id`
+      );
+    }
+    return stripeId;
+  }
+
   async expireCheckoutSession({ id }: IdDto): Promise<void> {
-    await this.stripeClient.checkout.sessions.expire(id);
+    await this.stripeClient.checkout.sessions.expire(
+      await this.stripeCheckoutSessionId(id)
+    );
     await this.baseCheckoutSessionService.expireCheckoutSession({ id });
   }
 
   async handleCheckoutSuccess({ id }: IdDto): Promise<void> {
-    await this.stripeClient.checkout.sessions.update(id, {
-      metadata: {
-        status: 'SUCCESS'
+    await this.stripeClient.checkout.sessions.update(
+      await this.stripeCheckoutSessionId(id),
+      {
+        metadata: {
+          status: 'SUCCESS'
+        }
       }
-    });
+    );
     await this.baseCheckoutSessionService.handleCheckoutSuccess({ id });
   }
 
   async handleCheckoutFailure({ id }: IdDto): Promise<void> {
-    await this.stripeClient.checkout.sessions.update(id, {
-      metadata: {
-        status: 'FAILED'
+    await this.stripeClient.checkout.sessions.update(
+      await this.stripeCheckoutSessionId(id),
+      {
+        metadata: {
+          status: 'FAILED'
+        }
       }
-    });
+    );
     await this.baseCheckoutSessionService.handleCheckoutFailure({ id });
   }
 }

package/lib/eject/services/paymentLink.service.ts

@@ -21,24 +21,44 @@ import {
 } from '../domain/types/stripe.dto.types';
 import { StripePaymentLinkEntities } from '../domain/types/stripe.entity.types';
 
+/** Match the required provider object/line-items structure without modeling the SDK. */
+function validatePaymentLinkCreateFields(value: unknown): void {
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    Array.isArray(value) ||
+    !Array.isArray((value as Record<string, unknown>).line_items) ||
+    !(value as { line_items: unknown[] }).line_items.every(
+      (item) =>
+        item !== null && typeof item === 'object' && !Array.isArray(item)
+    )
+  ) {
+    throw new Error(
+      'Payment link provider options require a line_items array of objects'
+    );
+  }
+}
+
 export class StripePaymentLinkService<
   SchemaValidator extends AnySchemaValidator,
   StatusEnum,
   Entities extends StripePaymentLinkEntities,
-  Dto extends StripePaymentLinkDtos<StatusEnum> =
-    StripePaymentLinkDtos<StatusEnum>
-> implements PaymentLinkService<
-  PaymentMethodEnum,
-  typeof CurrencyEnum,
-  StatusEnum,
-  {
-    CreatePaymentLinkDto: StripeCreatePaymentLinkDto<StatusEnum>;
-    UpdatePaymentLinkDto: StripeUpdatePaymentLinkDto<StatusEnum>;
-    PaymentLinkDto: StripePaymentLinkDto<StatusEnum>;
-    IdDto: IdDto;
-    IdsDto: IdsDto;
-  }
-> {
+  Dto extends
+    StripePaymentLinkDtos<StatusEnum> = StripePaymentLinkDtos<StatusEnum>
+> implements
+    PaymentLinkService<
+      PaymentMethodEnum,
+      typeof CurrencyEnum,
+      StatusEnum,
+      {
+        CreatePaymentLinkDto: StripeCreatePaymentLinkDto<StatusEnum>;
+        UpdatePaymentLinkDto: StripeUpdatePaymentLinkDto<StatusEnum>;
+        PaymentLinkDto: StripePaymentLinkDto<StatusEnum>;
+        IdDto: IdDto;
+        IdsDto: IdsDto;
+      }
+    >
+{
   basePaymentLinkService: BasePaymentLinkService<
     SchemaValidator,
     PaymentMethodEnum,
@@ -47,6 +67,7 @@ export class StripePaymentLinkService<
     Entities,
     Dto
   >;
+  private readonly maxConfiguredListRecords: number;
   protected readonly stripeClient: Stripe;
   protected readonly em: EntityManager;
   protected readonly cache: TtlCache;
@@ -67,9 +88,19 @@ export class StripePaymentLinkService<
     mappers: StripePaymentLinkMappers<StatusEnum, Entities, Dto>,
     readonly options?: {
       enableDatabaseBackup?: boolean;
+      /** Trusted configured-cache list limit; defaults to 100, maximum 1000. */
+      maxConfiguredListRecords?: number;
       telemetry?: TelemetryOptions;
     }
   ) {
+    const limit =
+      options?.maxConfiguredListRecords === undefined
+        ? 100
+        : options.maxConfiguredListRecords;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000) {
+      throw new Error('Invalid configured payment link list limit');
+    }
+    this.maxConfiguredListRecords = limit;
     this.stripeClient = stripeClient;
     this.em = em;
     this.cache = cache;
@@ -96,12 +127,19 @@ export class StripePaymentLinkService<
     paymentLinkDto: StripeCreatePaymentLinkDto<StatusEnum>,
     ...args: unknown[]
   ): Promise<Dto['PaymentLinkMapper']> {
+    await this.mappers.CreatePaymentLinkMapper.validateCreate?.(paymentLinkDto);
+
+    validatePaymentLinkCreateFields(paymentLinkDto.stripeFields);
     const session = await this.stripeClient.paymentLinks.create({
       ...paymentLinkDto.stripeFields,
       payment_method_types: paymentLinkDto.paymentMethods,
       currency: paymentLinkDto.currency as string
     });
 
+    await this.mappers.CreatePaymentLinkMapper.validateProviderCreate?.(
+      session
+    );
+
     const paymentLink = await this.basePaymentLinkService.createPaymentLink(
       {
         ...paymentLinkDto,
@@ -123,24 +161,68 @@ export class StripePaymentLinkService<
     return paymentLink;
   }
 
+  /**
+   * The Stripe id (`plink_...`) stored with a payment link when it was created.
+   * Public ids are local; Stripe only knows its own id. The stored provider
+   * object's id wins; a record without one is still usable when its own id is a
+   * Stripe id. Anything else fails here rather than sending Stripe a local id.
+   */
+  protected stripePaymentLinkId(
+    paymentLink: Dto['PaymentLinkMapper'],
+    id: string
+  ): string {
+    const stored = (paymentLink?.stripeFields as { id?: unknown } | undefined)
+      ?.id;
+    const stripeId = stored === undefined ? paymentLink?.id : stored;
+    if (
+      typeof stripeId !== 'string' ||
+      !/^plink_[A-Za-z0-9_]+$/.test(stripeId)
+    ) {
+      throw new Error(
+        `Payment link ${id} has no stored Stripe payment link id`
+      );
+    }
+    return stripeId;
+  }
+
   async updatePaymentLink(
     paymentLinkDto: StripeUpdatePaymentLinkDto<StatusEnum>,
     ...args: unknown[]
   ): Promise<Dto['PaymentLinkMapper']> {
-    const session = await this.stripeClient.paymentLinks.update(
-      paymentLinkDto.id,
-      {
-        ...paymentLinkDto.stripeFields,
-        payment_method_types: paymentLinkDto.paymentMethods
-      }
-    );
+    const existing = await this.basePaymentLinkService.getPaymentLink({
+      id: paymentLinkDto.id
+    });
+    if (this.mappers.UpdatePaymentLinkMapper.validateCachedUpdate) {
+      await this.mappers.UpdatePaymentLinkMapper.validateCachedUpdate(
+        paymentLinkDto,
+        existing
+      );
+    }
+    const stripeId = this.stripePaymentLinkId(existing, paymentLinkDto.id);
+    const session = await this.stripeClient.paymentLinks.update(stripeId, {
+      ...paymentLinkDto.stripeFields,
+      payment_method_types: paymentLinkDto.paymentMethods
+    });
+    if (session.id !== stripeId) {
+      throw new Error('Invalid Stripe billing response');
+    }
+
+    const toLocalUpdate = this.mappers.UpdatePaymentLinkMapper.toLocalUpdate;
+    if (toLocalUpdate) {
+      const patch = await toLocalUpdate(paymentLinkDto, session);
+      return this.basePaymentLinkService.updatePaymentLink(
+        patch,
+        this.em,
+        session,
+        ...args
+      );
+    }
 
     const paymentLink = await this.basePaymentLinkService.updatePaymentLink(
       await this.mappers.PaymentLinkMapper.toDto(
         await this.mappers.UpdatePaymentLinkMapper.toEntity(
           {
             ...paymentLinkDto,
-            id: session.id,
             amount:
               session.line_items?.data.reduce<number>(
                 (total, item) => total + item.amount_total,
@@ -160,6 +242,16 @@ export class StripePaymentLinkService<
   }
 
   async getPaymentLink({ id }: IdDto): Promise<Dto['PaymentLinkMapper']> {
+    const readCachedDto = this.mappers.PaymentLinkMapper.readCachedDto;
+    if (readCachedDto) {
+      const existing = await this.basePaymentLinkService.getPaymentLink({ id });
+      if (existing.id !== id) {
+        throw new Error('Cached payment link identity does not match');
+      }
+      return readCachedDto(existing, (providerId) =>
+        this.stripeClient.paymentLinks.retrieve(providerId)
+      );
+    }
     const stripePaymentLink = await this.stripeClient.paymentLinks.retrieve(id);
 
     const databasePaymentLink =
@@ -171,7 +263,11 @@ export class StripePaymentLinkService<
   }
 
   async expirePaymentLink({ id }: IdDto): Promise<void> {
-    await this.stripeClient.paymentLinks.update(id, {
+    const stripeId = this.stripePaymentLinkId(
+      await this.basePaymentLinkService.getPaymentLink({ id }),
+      id
+    );
+    await this.stripeClient.paymentLinks.update(stripeId, {
       metadata: {
         status: 'EXPIRED'
       }
@@ -180,7 +276,11 @@ export class StripePaymentLinkService<
   }
 
   async handlePaymentSuccess({ id }: IdDto): Promise<void> {
-    await this.stripeClient.paymentLinks.update(id, {
+    const stripeId = this.stripePaymentLinkId(
+      await this.basePaymentLinkService.getPaymentLink({ id }),
+      id
+    );
+    await this.stripeClient.paymentLinks.update(stripeId, {
       metadata: {
         status: 'COMPLETED'
       }
@@ -189,7 +289,11 @@ export class StripePaymentLinkService<
   }
 
   async handlePaymentFailure({ id }: IdDto): Promise<void> {
-    await this.stripeClient.paymentLinks.update(id, {
+    const stripeId = this.stripePaymentLinkId(
+      await this.basePaymentLinkService.getPaymentLink({ id }),
+      id
+    );
+    await this.stripeClient.paymentLinks.update(stripeId, {
       metadata: {
         status: 'FAILED'
       }
@@ -199,6 +303,26 @@ export class StripePaymentLinkService<
 
   async listPaymentLinks(idsDto?: IdsDto): Promise<Dto['PaymentLinkMapper'][]> {
     this.openTelemetryCollector.log('info', idsDto ?? 'idsDto is undefined');
+    const { readCachedDto, validateCachedRead } =
+      this.mappers.PaymentLinkMapper;
+    if (readCachedDto && validateCachedRead) {
+      const cached = await this.basePaymentLinkService.listPaymentLinks(
+        idsDto,
+        this.maxConfiguredListRecords
+      );
+      for (const value of cached) validateCachedRead(value);
+      const active: Dto['PaymentLinkMapper'][] = [];
+      for (const value of cached) {
+        const fresh = await readCachedDto(value, (providerId) =>
+          this.stripeClient.paymentLinks.retrieve(providerId)
+        );
+        if (typeof fresh.stripeFields.active !== 'boolean') {
+          throw new Error('Invalid payment link active state');
+        }
+        if (fresh.stripeFields.active) active.push(fresh);
+      }
+      return active;
+    }
     const stripePaymentLinks = await this.stripeClient.paymentLinks.list({
       active: true
     });