@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/billing/services/custom-impl/subscription.mutations.custom-impl.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscription.mutations.custom-impl.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/billing/services/custom-impl/subscription.mutations.custom-impl.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAiBH,OAAO,EAEL,KAAK,0CAA0C,EAChD,MAAM,4GAA4G,CAAC;AAuBpH,wBAAgB,iCAAiC,IAAI,0CAA0C,EAAE,CAqChG;AAMD;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,IAAI,0CAA0C,EAAE,CAwChG;AAMD;;;;;;;;GAQG;AACH,wBAAgB,qCAAqC,IAAI,0CAA0C,EAAE,CAiHpG;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mCAAmC,IAAI,0CAA0C,EAAE,CAuFlG;AAMD;;;;;;;;GAQG;AACH,wBAAgB,sCAAsC,IAAI,0CAA0C,EAAE,CA8CrG"}
+{"version":3,"file":"subscription.mutations.custom-impl.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/billing/services/custom-impl/subscription.mutations.custom-impl.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAiBH,OAAO,EAEL,KAAK,0CAA0C,EAChD,MAAM,4GAA4G,CAAC;AA8CpH,wBAAgB,iCAAiC,IAAI,0CAA0C,EAAE,CA0FhG;AAMD;;;;;;;GAOG;AACH,wBAAgB,iCAAiC,IAAI,0CAA0C,EAAE,CAwChG;AAMD;;;;;;;;GAQG;AACH,wBAAgB,qCAAqC,IAAI,0CAA0C,EAAE,CA0HpG;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mCAAmC,IAAI,0CAA0C,EAAE,CAoFlG;AAMD;;;;;;;;GAQG;AACH,wBAAgB,sCAAsC,IAAI,0CAA0C,EAAE,CAmDrG"}

package/dist/esm/billing/services/custom-impl/subscription.mutations.custom-impl.backend.service.js

@@ -17,12 +17,29 @@
 import { CoreResourceType, ResourceOperationVariantType, SubscriptionStatus, ErrorType, ErrorCustomMessageReference, ProductType, ProrationBehavior, BillingTiming, BillingSubscription_Operations, BillingSubscription_CancelRequestDto, BillingSubscription_ChangePlanRequestDto, BillingSubscription_AddAddonRequestDto, BillingSubscription_RemoveAddonRequestDto, } from '@wildo-ai/saas-models';
 import { createResourceCustomServiceImplementation, } from '../../../base-classes/services/services/resource-operation-custom-implementation.factory.backend.js';
 import { getBillingProvider, getBillingConfig } from '../../../billing/services/custom-impl/billing-custom-implementations.backend.js';
-import { readProductByKey, readProductById, readPriceById, readPriceForProduct, validateProviderSubscription, resolveProviderItems, } from '../../../billing/services/custom-impl/billing-custom-impl-utils.backend.js';
+import { BillingCatalogReadIntent, readProductByKey, readProductById, readPriceById, readPriceForProduct, validateProviderSubscription, resolveProviderItems, } from '../../../billing/services/custom-impl/billing-custom-impl-utils.backend.js';
 // ── Subscription polymorphic variant types ───────────────────────────
 const SUBSCRIPTION_VARIANT_TYPES = [
     CoreResourceType.ORGANIZATION_SUBSCRIPTIONS,
     CoreResourceType.USER_SUBSCRIPTIONS,
 ];
+/**
+ * The subscription item carrying the PLAN, or `null` when a subscription holds only addons.
+ *
+ * A subscription's items are a plan plus any addons, and three places in this file needed to find
+ * the plan among them — the change-plan path, the addon plan-tier gate, and now the cancellation
+ * policy (#408). Each had its own inline loop. One helper because "which item is the plan" is a
+ * single question with a single answer, and three copies is how the fourth one comes to differ.
+ */
+async function resolvePlanItem(subscription, executionContext, utils) {
+    for (const item of subscription.items) {
+        const itemProduct = await readProductById(item.productId, executionContext, utils);
+        if (itemProduct.type === ProductType.PLAN) {
+            return item;
+        }
+    }
+    return null;
+}
 // ════════════════════════════════════════════════════════════════════
 // CANCEL
 // ════════════════════════════════════════════════════════════════════
@@ -41,7 +58,58 @@ export function createSubscriptionCancelFactories() {
                     prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {
                         const subscription = utils.currentObject;
                         validateProviderSubscription(subscription, _id, executionContext, utils);
-                        const cancelImmediately = input.cancelImmediately;
+                        /*
+                         * `ProductBehaviorPolicy.cancellation` now governs this operation (#408, decided
+                         * 2026-09-08). Until then it was read by NOTHING: timing came solely from the caller's
+                         * `cancelImmediately` flag, so a product declaring that immediate cancellation is not
+                         * allowed could not refuse one — and Wonder Todos authors `allowImmediate: false` on
+                         * BOTH plans, unenforced.
+                         *
+                         * Two distinct things come from the policy, and conflating them was the trap:
+                         *   - `allowImmediate` is a REFUSAL. A caller who asks for immediate cancellation
+                         *     against a product that forbids it gets a 409, not a silent downgrade to
+                         *     period-end. Silently honouring the safer timing would tell the caller their
+                         *     subscription had ended when it has not, which is worse than refusing.
+                         *   - `defaultBehavior` decides the timing when the caller expresses NO preference.
+                         *     `cancelImmediately` is optional on the request DTO, so "absent" is a real state
+                         *     and is where an authored default belongs.
+                         *
+                         * The policy is read from the subscription's PLAN product, resolved the same way the
+                         * change-plan path above resolves it. An addon does not carry the cancellation policy
+                         * of the subscription it rides on.
+                         */
+                        const planItem = await resolvePlanItem(subscription, executionContext, utils);
+                        const planProduct = planItem
+                            ? await readProductById(planItem.productId, executionContext, utils)
+                            : null;
+                        const cancellationPolicy = planProduct?.behaviorPolicy?.cancellation;
+                        const requestedImmediate = input.cancelImmediately;
+                        if (requestedImmediate === true && cancellationPolicy?.allowImmediate === false) {
+                            throw utils.errorBuilder.buildError(ErrorType.CONFLICT, executionContext, {
+                                customMessageReference: ErrorCustomMessageReference.CONFLICT,
+                                context: {
+                                    reason: 'billing_product_forbids_immediate_cancellation',
+                                    message: 'This plan does not allow immediate cancellation; it can only be cancelled at the end of the current period.',
+                                    productKey: planProduct?.key,
+                                },
+                            });
+                        }
+                        /*
+                         * Absent preference resolves down a chain, most specific first: the caller, the plan
+                         * product's own default, the application's `defaultCancellation`, then period-end.
+                         *
+                         * The application-level step is what makes `billing.defaultBehaviorPolicy.defaultCancellation`
+                         * mean something. It was dead alongside its neighbours, and it is BOUND rather than
+                         * relabelled because — unlike grace periods and retry counts, which are dunning settings
+                         * living at the provider — cancellation timing is resolved locally. The only thing
+                         * standing between that key and an effect was a reader.
+                         *
+                         * Period-end is the floor because it never ends access a customer has already paid for.
+                         */
+                        const resolvedTiming = cancellationPolicy?.defaultBehavior
+                            ?? getBillingConfig().defaultBehaviorPolicy?.defaultCancellation;
+                        const cancelImmediately = requestedImmediate
+                            ?? (resolvedTiming === BillingTiming.IMMEDIATE);
                         const atPeriodEnd = !cancelImmediately;
                         const provider = getBillingProvider();
                         await provider.cancelSubscription(subscription.providerSubscriptionId, { atPeriodEnd });
@@ -133,7 +201,8 @@ export function createSubscriptionChangePlanFactories() {
                     prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {
                         const subscription = utils.currentObject;
                         validateProviderSubscription(subscription, _id, executionContext, utils);
-                        const newProduct = await readProductByKey(input.newProductKey, executionContext, utils);
+                        // ACQUIRE: the subscription is being moved ONTO this product.
+                        const newProduct = await readProductByKey(input.newProductKey, BillingCatalogReadIntent.ACQUIRE, executionContext, utils);
                         // The price MUST belong to the product being switched to. These were resolved
                         // independently, so pairing a premium `newProductKey` with a cheap `newPriceId` billed the
                         // provider the cheap price while the local item — and every entitlement derived from
@@ -146,14 +215,8 @@ export function createSubscriptionChangePlanFactories() {
                             });
                         }
                         // Find the current plan item (type === PLAN) and determine upgrade/downgrade
-                        let planItemIndex = -1;
-                        for (let i = 0; i < subscription.items.length; i++) {
-                            const itemProduct = await readProductById(subscription.items[i].productId, executionContext, utils);
-                            if (itemProduct.type === ProductType.PLAN) {
-                                planItemIndex = i;
-                                break;
-                            }
-                        }
+                        const currentPlanItem = await resolvePlanItem(subscription, executionContext, utils);
+                        const planItemIndex = currentPlanItem ? subscription.items.indexOf(currentPlanItem) : -1;
                         // Build provider items: replace plan item, preserve addons
                         const providerItems = [];
                         const localItems = [];
@@ -205,11 +268,25 @@ export function createSubscriptionChangePlanFactories() {
                         const provider = getBillingProvider();
                         await provider.updateSubscription(subscription.providerSubscriptionId, {
                             items: providerItems,
+                            /*
+                             * The resolved proration, as a REQUEST FIELD (#516).
+                             *
+                             * It was `metadata.prorationBehavior` until 2026-09-08 — a free-form key/value bag the
+                             * provider stores and never reads — so this policy was correctly resolved from the target
+                             * product's `upgrade`/`downgrade` block and then discarded at the boundary. A product
+                             * declaring `ProrationBehavior.NONE` for a downgrade was prorated anyway, by the
+                             * provider's account default. Wonder Todos authors exactly that.
+                             */
+                            prorationBehavior: policy.proration,
                             metadata: {
-                                prorationBehavior: policy.proration,
-                                // Timing is captured for provider connectors that support deferred changes
-                                // (e.g., Stripe subscription schedules). Connectors that don't support it
-                                // will ignore the field and apply the change immediately.
+                                /*
+                                 * TIMING remains metadata, and that is honest rather than an oversight: a provider's
+                                 * proration parameter says HOW a change settles, not WHEN it applies. Deferring a
+                                 * change to the period end needs a subscription schedule, which is a different call and
+                                 * a different mechanism — so `prorationTiming` is still carried for a connector that
+                                 * grows one, and still changes nothing today. Do not read this field's presence as the
+                                 * timing being honoured.
+                                 */
                                 prorationTiming: policy.timing,
                             },
                         });
@@ -250,7 +327,8 @@ export function createSubscriptionAddAddonFactories() {
                         const subscription = utils.currentObject;
                         validateProviderSubscription(subscription, _id, executionContext, utils);
                         // Resolve addon product and validate
-                        const addonProduct = await readProductByKey(input.addonProductKey, executionContext, utils);
+                        // ACQUIRE: an add-on is being bought.
+                        const addonProduct = await readProductByKey(input.addonProductKey, BillingCatalogReadIntent.ACQUIRE, executionContext, utils);
                         if (addonProduct.type !== ProductType.ADDON) {
                             throw utils.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
                                 customMessageReference: ErrorCustomMessageReference.BILLING_INVALID_PRODUCT_TYPE,
@@ -259,14 +337,10 @@ export function createSubscriptionAddAddonFactories() {
                         }
                         // Validate requiredPlanTiers
                         if (addonProduct.requiredPlanTiers && addonProduct.requiredPlanTiers.length > 0) {
-                            let currentPlanTier;
-                            for (const item of subscription.items) {
-                                const itemProduct = await readProductById(item.productId, executionContext, utils);
-                                if (itemProduct.type === ProductType.PLAN) {
-                                    currentPlanTier = itemProduct.planTier;
-                                    break;
-                                }
-                            }
+                            const planItemForTier = await resolvePlanItem(subscription, executionContext, utils);
+                            const currentPlanTier = planItemForTier
+                                ? (await readProductById(planItemForTier.productId, executionContext, utils)).planTier
+                                : undefined;
                             if (!currentPlanTier || !addonProduct.requiredPlanTiers.includes(currentPlanTier)) {
                                 throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
                                     customMessageReference: ErrorCustomMessageReference.BILLING_PLAN_TIER_REQUIRED,
@@ -341,7 +415,12 @@ export function createSubscriptionRemoveAddonFactories() {
                         const subscription = utils.currentObject;
                         validateProviderSubscription(subscription, _id, executionContext, utils);
                         // Resolve addon product
-                        const addonProduct = await readProductByKey(input.addonProductKey, executionContext, utils);
+                        /*
+                         * REFERENCE, deliberately — the ONE site of the four that must not refuse a retired
+                         * product. This resolves the add-on the subscription ALREADY carries in order to drop
+                         * it, so gating it would trap a customer on the very add-on the catalogue withdrew.
+                         */
+                        const addonProduct = await readProductByKey(input.addonProductKey, BillingCatalogReadIntent.REFERENCE, executionContext, utils);
                         // Find and remove the addon item
                         const remainingItems = subscription.items.filter((item) => item.productId !== addonProduct._id);
                         if (remainingItems.length === subscription.items.length) {

package/dist/esm/billing/services/custom-impl/subscription.mutations.custom-impl.backend.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"subscription.mutations.custom-impl.backend.service.js","sourceRoot":"","sources":["../../../../../../src/billing/services/custom-impl/subscription.mutations.custom-impl.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Subscription Mutations Custom Implementations\n *\n * Implements CANCEL, RESUME, CHANGE_PLAN, ADD_ADDON, REMOVE_ADDON operations\n * on subscription polymorphic variants.\n *\n * Pattern: PREFIX_CORE_OPERATIONS\n *   PREFIX  → validate, call billing provider (Stripe), return update payload\n *   CORE    → standard UPDATE (engine handles DB write)\n *   Feature sync is handled automatically by the post-operation hook infrastructure.\n *\n * One factory per polymorphic variant (org, user) per operation.\n * All variants share the same handler logic.\n *\n * @see billing-polymorphic-full-implementation.md §4.2 + §4.3\n */\n\nimport {\n  CoreResourceType,\n  ResourceOperationVariantType,\n  SubscriptionStatus,\n  ErrorType,\n  ErrorCustomMessageReference,\n  ProductType,\n  ProrationBehavior,\n  BillingTiming,\n  BillingSubscription_Operations,\n  BillingSubscription_CancelRequestDto,\n  BillingSubscription_ChangePlanRequestDto,\n  BillingSubscription_AddAddonRequestDto,\n  BillingSubscription_RemoveAddonRequestDto,\n} from '@wildo-ai/saas-models';\nimport {\n  createResourceCustomServiceImplementation,\n  type ResourceCustomServiceImplementationFactory,\n} from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation.factory.backend';\nimport type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';\nimport { getBillingProvider, getBillingConfig } from '~wildo-backend-lib/billing/services/custom-impl/billing-custom-implementations.backend';\nimport {\n  readProductByKey,\n  readProductById,\n  readPriceById,\n  readPriceForProduct,\n  validateProviderSubscription,\n  resolveProviderItems,\n} from '~wildo-backend-lib/billing/services/custom-impl/billing-custom-impl-utils.backend';\n\n// ── Subscription polymorphic variant types ───────────────────────────\n\nconst SUBSCRIPTION_VARIANT_TYPES = [\n  CoreResourceType.ORGANIZATION_SUBSCRIPTIONS,\n  CoreResourceType.USER_SUBSCRIPTIONS,\n] as const;\n\n// ════════════════════════════════════════════════════════════════════\n// CANCEL\n// ════════════════════════════════════════════════════════════════════\n\nexport function createSubscriptionCancelFactories(): ResourceCustomServiceImplementationFactory[] {\n  return SUBSCRIPTION_VARIANT_TYPES.map((variantResourceType) => {\n    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {\n      return createResourceCustomServiceImplementation({\n        operationPath: {\n          resourceIdentifier: variantResourceType,\n          operationIdentifier: BillingSubscription_Operations.CANCEL,\n          variantType: ResourceOperationVariantType.API_CALL,\n          isOperationDefault: true,\n        },\n        requestDtoSchema: BillingSubscription_CancelRequestDto,\n        handlers: {\n          prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n            const subscription = utils.currentObject;\n            validateProviderSubscription(subscription, _id!, executionContext, utils);\n\n            const cancelImmediately = input.cancelImmediately;\n            const atPeriodEnd = !cancelImmediately;\n\n            const provider = getBillingProvider();\n            await provider.cancelSubscription(subscription.providerSubscriptionId, { atPeriodEnd });\n\n            return {\n              cancelAtPeriodEnd: atPeriodEnd,\n              cancelledAt: new Date(),\n              ...(!atPeriodEnd && { status: SubscriptionStatus.CANCELLED }),\n              ...(input.reason && { cancellationReason: input.reason }),\n            };\n          },\n\n          // Feature sync is handled automatically by the post-operation hook infrastructure\n        },\n      });\n    };\n\n    return factory as unknown as ResourceCustomServiceImplementationFactory;\n  });\n}\n\n// ════════════════════════════════════════════════════════════════════\n// RESUME\n// ════════════════════════════════════════════════════════════════════\n\n/**\n * Create RESUME custom impl factories for all subscription variants.\n *\n * RESUME un-cancels a subscription that has cancelAtPeriodEnd = true.\n *   PREFIX:  validates subscription is pending cancellation, calls provider resumeSubscription()\n *   CORE:    standard UPDATE clears cancellation fields\n *   (Feature sync handled by post-operation hook)\n */\nexport function createSubscriptionResumeFactories(): ResourceCustomServiceImplementationFactory[] {\n  return SUBSCRIPTION_VARIANT_TYPES.map((variantResourceType) => {\n    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {\n      return createResourceCustomServiceImplementation({\n        operationPath: {\n          resourceIdentifier: variantResourceType,\n          operationIdentifier: BillingSubscription_Operations.RESUME,\n          variantType: ResourceOperationVariantType.API_CALL,\n          isOperationDefault: true,\n        },\n        handlers: {\n          prefixCoreOperations: async (_id, _input, executionContext, _operationPath, utils) => {\n            const subscription = utils.currentObject;\n            validateProviderSubscription(subscription, _id!, executionContext, utils);\n\n            if (!subscription.cancelAtPeriodEnd) {\n              throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {\n                customMessageReference: ErrorCustomMessageReference.BILLING_NO_ACTIVE_SUBSCRIPTION,\n                context: { subscriptionId: _id, reason: 'Subscription is not pending cancellation' },\n              });\n            }\n\n            const provider = getBillingProvider();\n            await provider.resumeSubscription(subscription.providerSubscriptionId);\n\n            return {\n              cancelAtPeriodEnd: false,\n              cancelledAt: null,\n              cancellationReason: null,\n              status: SubscriptionStatus.ACTIVE,\n            };\n          },\n\n          // Feature sync is handled automatically by the post-operation hook infrastructure\n        },\n      });\n    };\n\n    return factory as unknown as ResourceCustomServiceImplementationFactory;\n  });\n}\n\n// ════════════════════════════════════════════════════════════════════\n// CHANGE_PLAN\n// ════════════════════════════════════════════════════════════════════\n\n/**\n * Create CHANGE_PLAN custom impl factories for all subscription variants.\n *\n * CHANGE_PLAN upgrades or downgrades the subscription plan.\n *   PREFIX:  resolves new product/price, determines proration, builds provider items,\n *            calls provider updateSubscription(), returns update payload with new items\n *   CORE:    standard UPDATE writes new items to DB\n *   (Feature sync handled by post-operation hook)\n */\nexport function createSubscriptionChangePlanFactories(): ResourceCustomServiceImplementationFactory[] {\n  return SUBSCRIPTION_VARIANT_TYPES.map((variantResourceType) => {\n    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {\n      return createResourceCustomServiceImplementation({\n        operationPath: {\n          resourceIdentifier: variantResourceType,\n          operationIdentifier: BillingSubscription_Operations.CHANGE_PLAN,\n          variantType: ResourceOperationVariantType.API_CALL,\n          isOperationDefault: true,\n        },\n        requestDtoSchema: BillingSubscription_ChangePlanRequestDto,\n        handlers: {\n          prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n            const subscription = utils.currentObject;\n            validateProviderSubscription(subscription, _id!, executionContext, utils);\n\n            const newProduct = await readProductByKey(input.newProductKey, executionContext, utils);\n            // The price MUST belong to the product being switched to. These were resolved\n            // independently, so pairing a premium `newProductKey` with a cheap `newPriceId` billed the\n            // provider the cheap price while the local item — and every entitlement derived from\n            // `item.productId` — recorded the premium product.\n            const newPrice = await readPriceForProduct(input.newPriceId, newProduct, executionContext, utils);\n\n            if (!newPrice.providerPriceId) {\n              throw utils.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {\n                customMessageReference: ErrorCustomMessageReference.BILLING_NO_PROVIDER_PRICE,\n                context: { priceId: input.newPriceId, productKey: input.newProductKey },\n              });\n            }\n\n            // Find the current plan item (type === PLAN) and determine upgrade/downgrade\n            let planItemIndex = -1;\n            for (let i = 0; i < subscription.items.length; i++) {\n              const itemProduct = await readProductById(subscription.items[i].productId, executionContext, utils);\n              if (itemProduct.type === ProductType.PLAN) {\n                planItemIndex = i;\n                break;\n              }\n            }\n\n            // Build provider items: replace plan item, preserve addons\n            const providerItems: Array<{ providerSubscriptionItemId?: string; providerPriceId: string; quantity: number }> = [];\n            const localItems: Array<any> = [];\n\n            for (let i = 0; i < subscription.items.length; i++) {\n              if (i === planItemIndex) {\n                providerItems.push({\n                  providerSubscriptionItemId: subscription.items[i].providerSubscriptionItemId,\n                  providerPriceId: newPrice.providerPriceId,\n                  quantity: 1,\n                });\n                localItems.push({\n                  _id: subscription.items[i]._id,\n                  productId: newProduct._id,\n                  priceId: newPrice._id,\n                  quantity: 1,\n                });\n              } else {\n                const price = await readPriceById(subscription.items[i].priceId, executionContext, utils);\n                providerItems.push({\n                  providerSubscriptionItemId: subscription.items[i].providerSubscriptionItemId,\n                  providerPriceId: price.providerPriceId || subscription.items[i].priceId,\n                  quantity: subscription.items[i].quantity,\n                });\n                localItems.push(subscription.items[i]);\n              }\n            }\n\n            // If no plan item found, prepend the new plan\n            if (planItemIndex === -1) {\n              providerItems.unshift({ providerPriceId: newPrice.providerPriceId, quantity: 1 });\n              localItems.unshift({\n                _id: `${subscription.providerSubscriptionId}_item_plan`,\n                productId: newProduct._id,\n                priceId: newPrice._id,\n                quantity: 1,\n              });\n            }\n\n            // Determine proration from product behavior policy\n            const currentProduct = planItemIndex >= 0\n              ? await readProductById(subscription.items[planItemIndex].productId, executionContext, utils)\n              : null;\n            const isUpgrade = currentProduct\n              ? (newProduct.planTierOrder ?? 0) > (currentProduct.planTierOrder ?? 0)\n              : true;\n            const config = getBillingConfig();\n            const policy = isUpgrade\n              ? (newProduct.behaviorPolicy?.upgrade ?? { proration: config.defaultBehaviorPolicy.defaultProration, timing: BillingTiming.IMMEDIATE })\n              : (newProduct.behaviorPolicy?.downgrade ?? { proration: ProrationBehavior.NONE, timing: BillingTiming.AT_PERIOD_END });\n\n            const provider = getBillingProvider();\n            await provider.updateSubscription(subscription.providerSubscriptionId, {\n              items: providerItems,\n              metadata: {\n                prorationBehavior: policy.proration,\n                // Timing is captured for provider connectors that support deferred changes\n                // (e.g., Stripe subscription schedules). Connectors that don't support it\n                // will ignore the field and apply the change immediately.\n                prorationTiming: policy.timing,\n              },\n            });\n\n            return { items: localItems };\n          },\n\n          // Feature sync is handled automatically by the post-operation hook infrastructure\n        },\n      });\n    };\n\n    return factory as unknown as ResourceCustomServiceImplementationFactory;\n  });\n}\n\n// ════════════════════════════════════════════════════════════════════\n// ADD_ADDON\n// ════════════════════════════════════════════════════════════════════\n\n/**\n * Create ADD_ADDON custom impl factories for all subscription variants.\n *\n * ADD_ADDON adds an addon product to the existing subscription.\n *   PREFIX:  validates addon product (type, requiredPlanTiers), builds provider items,\n *            calls provider updateSubscription(), returns update payload with expanded items\n *   CORE:    standard UPDATE writes new items to DB\n *   (Feature sync handled by post-operation hook)\n */\nexport function createSubscriptionAddAddonFactories(): ResourceCustomServiceImplementationFactory[] {\n  return SUBSCRIPTION_VARIANT_TYPES.map((variantResourceType) => {\n    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {\n      return createResourceCustomServiceImplementation({\n        operationPath: {\n          resourceIdentifier: variantResourceType,\n          operationIdentifier: BillingSubscription_Operations.ADD_ADDON,\n          variantType: ResourceOperationVariantType.API_CALL,\n          isOperationDefault: true,\n        },\n        requestDtoSchema: BillingSubscription_AddAddonRequestDto,\n        handlers: {\n          prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n            const subscription = utils.currentObject;\n            validateProviderSubscription(subscription, _id!, executionContext, utils);\n\n            // Resolve addon product and validate\n            const addonProduct = await readProductByKey(input.addonProductKey, executionContext, utils);\n            if (addonProduct.type !== ProductType.ADDON) {\n              throw utils.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {\n                customMessageReference: ErrorCustomMessageReference.BILLING_INVALID_PRODUCT_TYPE,\n                context: { productKey: input.addonProductKey, expectedType: ProductType.ADDON, actualType: addonProduct.type },\n              });\n            }\n\n            // Validate requiredPlanTiers\n            if (addonProduct.requiredPlanTiers && addonProduct.requiredPlanTiers.length > 0) {\n              let currentPlanTier: string | undefined;\n              for (const item of subscription.items) {\n                const itemProduct = await readProductById(item.productId, executionContext, utils);\n                if (itemProduct.type === ProductType.PLAN) {\n                  currentPlanTier = itemProduct.planTier;\n                  break;\n                }\n              }\n              if (!currentPlanTier || !addonProduct.requiredPlanTiers.includes(currentPlanTier)) {\n                throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {\n                  customMessageReference: ErrorCustomMessageReference.BILLING_PLAN_TIER_REQUIRED,\n                  context: { addonProductKey: input.addonProductKey, requiredTiers: addonProduct.requiredPlanTiers, currentTier: currentPlanTier ?? null },\n                });\n              }\n            }\n\n            // Resolve addon price — and prove it belongs to the addon product. Same defect shape as\n            // CHANGE_PLAN: the addon's entitlements come from `addonProduct._id` on the local item\n            // while the provider is billed `addonPrice.providerPriceId`.\n            const addonPrice = await readPriceForProduct(input.priceId, addonProduct, executionContext, utils);\n            if (!addonPrice.providerPriceId) {\n              throw utils.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {\n                customMessageReference: ErrorCustomMessageReference.BILLING_NO_PROVIDER_PRICE,\n                context: { priceId: input.priceId, productKey: input.addonProductKey },\n              });\n            }\n\n            // Build provider items: existing items + new addon\n            const existingProviderItems = await resolveProviderItems(subscription.items, executionContext, utils);\n            existingProviderItems.push({\n              providerPriceId: addonPrice.providerPriceId,\n              quantity: 1,\n            });\n\n            const provider = getBillingProvider();\n            await provider.updateSubscription(subscription.providerSubscriptionId, {\n              items: existingProviderItems,\n            });\n\n            // Build local items with the new addon appended\n            const newItems = [\n              ...subscription.items,\n              {\n                _id: `${subscription.providerSubscriptionId}_item_${subscription.items.length}`,\n                productId: addonProduct._id,\n                priceId: addonPrice._id,\n                quantity: 1,\n              },\n            ];\n\n            return { items: newItems };\n          },\n\n          // Feature sync is handled automatically by the post-operation hook infrastructure\n        },\n      });\n    };\n\n    return factory as unknown as ResourceCustomServiceImplementationFactory;\n  });\n}\n\n// ════════════════════════════════════════════════════════════════════\n// REMOVE_ADDON\n// ════════════════════════════════════════════════════════════════════\n\n/**\n * Create REMOVE_ADDON custom impl factories for all subscription variants.\n *\n * REMOVE_ADDON removes an addon product from the subscription.\n *   PREFIX:  finds addon item, builds remaining items, calls provider updateSubscription(),\n *            returns update payload with remaining items\n *   CORE:    standard UPDATE writes remaining items to DB\n *   (Feature sync handled by post-operation hook)\n */\nexport function createSubscriptionRemoveAddonFactories(): ResourceCustomServiceImplementationFactory[] {\n  return SUBSCRIPTION_VARIANT_TYPES.map((variantResourceType) => {\n    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {\n      return createResourceCustomServiceImplementation({\n        operationPath: {\n          resourceIdentifier: variantResourceType,\n          operationIdentifier: BillingSubscription_Operations.REMOVE_ADDON,\n          variantType: ResourceOperationVariantType.API_CALL,\n          isOperationDefault: true,\n        },\n        requestDtoSchema: BillingSubscription_RemoveAddonRequestDto,\n        handlers: {\n          prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n            const subscription = utils.currentObject;\n            validateProviderSubscription(subscription, _id!, executionContext, utils);\n\n            // Resolve addon product\n            const addonProduct = await readProductByKey(input.addonProductKey, executionContext, utils);\n\n            // Find and remove the addon item\n            const remainingItems = subscription.items.filter((item: any) => item.productId !== addonProduct._id);\n            if (remainingItems.length === subscription.items.length) {\n              throw utils.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {\n                customMessageReference: ErrorCustomMessageReference.BILLING_ADDON_NOT_ON_SUBSCRIPTION,\n                context: { addonProductKey: input.addonProductKey, subscriptionId: _id },\n              });\n            }\n\n            // Build provider items from remaining items\n            const providerItems = await resolveProviderItems(remainingItems, executionContext, utils);\n\n            const provider = getBillingProvider();\n            await provider.updateSubscription(subscription.providerSubscriptionId, {\n              items: providerItems,\n            });\n\n            return { items: remainingItems };\n          },\n\n          // Feature sync is handled automatically by the post-operation hook infrastructure\n        },\n      });\n    };\n\n    return factory as unknown as ResourceCustomServiceImplementationFactory;\n  });\n}\n"]}
+{"version":3,"file":"subscription.mutations.custom-impl.backend.service.js","sourceRoot":"","sources":["../../../../../../src/billing/services/custom-impl/subscription.mutations.custom-impl.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,gBAAgB,EAChB,4BAA4B,EAC5B,kBAAkB,EAClB,SAAS,EACT,2BAA2B,EAC3B,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,8BAA8B,EAC9B,oCAAoC,EACpC,wCAAwC,EACxC,sCAAsC,EACtC,yCAAyC,GAC1C,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,yCAAyC,GAE1C,MAAM,4GAA4G,CAAC;AAEpH,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,wFAAwF,CAAC;AAC9I,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,4BAA4B,EAC5B,oBAAoB,GACrB,MAAM,mFAAmF,CAAC;AAE3F,wEAAwE;AAExE,MAAM,0BAA0B,GAAG;IACjC,gBAAgB,CAAC,0BAA0B;IAC3C,gBAAgB,CAAC,kBAAkB;CAC3B,CAAC;AAEX;;;;;;;GAOG;AACH,KAAK,UAAU,eAAe,CAC5B,YAAqD,EACrD,gBAAuD,EACvD,KAA4C;IAE5C,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,KAAK,EAAE,CAAC;QACtC,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,SAAS,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;QACnF,IAAI,WAAW,CAAC,IAAI,KAAK,WAAW,CAAC,IAAI,EAAE,CAAC;YAC1C,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,uEAAuE;AACvE,SAAS;AACT,uEAAuE;AAEvE,MAAM,UAAU,iCAAiC;IAC/C,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC,mBAAmB,EAAE,EAAE;QAC5D,MAAM,OAAO,GAAG,CAAC,yBAA0D,EAAE,EAAE;YAC7E,OAAO,yCAAyC,CAAC;gBAC/C,aAAa,EAAE;oBACb,kBAAkB,EAAE,mBAAmB;oBACvC,mBAAmB,EAAE,8BAA8B,CAAC,MAAM;oBAC1D,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,kBAAkB,EAAE,IAAI;iBACzB;gBACD,gBAAgB,EAAE,oCAAoC;gBACtD,QAAQ,EAAE;oBACR,oBAAoB,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE;wBAClF,MAAM,YAAY,GAAG,KAAK,CAAC,aAAa,CAAC;wBACzC,4BAA4B,CAAC,YAAY,EAAE,GAAI,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBAE1E;;;;;;;;;;;;;;;;;;;2BAmBG;wBACH,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,YAAY,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBAC9E,MAAM,WAAW,GAAG,QAAQ;4BAC1B,CAAC,CAAC,MAAM,eAAe,CAAC,QAAQ,CAAC,SAAS,EAAE,gBAAgB,EAAE,KAAK,CAAC;4BACpE,CAAC,CAAC,IAAI,CAAC;wBACT,MAAM,kBAAkB,GAAG,WAAW,EAAE,cAAc,EAAE,YAAY,CAAC;wBAErE,MAAM,kBAAkB,GAAG,KAAK,CAAC,iBAAiB,CAAC;wBACnD,IAAI,kBAAkB,KAAK,IAAI,IAAI,kBAAkB,EAAE,cAAc,KAAK,KAAK,EAAE,CAAC;4BAChF,MAAM,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,QAAQ,EAAE,gBAAgB,EAAE;gCACxE,sBAAsB,EAAE,2BAA2B,CAAC,QAAQ;gCAC5D,OAAO,EAAE;oCACP,MAAM,EAAE,gDAAgD;oCACxD,OAAO,EAAE,6GAA6G;oCACtH,UAAU,EAAE,WAAW,EAAE,GAAG;iCAC7B;6BACF,CAAC,CAAC;wBACL,CAAC;wBAED;;;;;;;;;;;2BAWG;wBACH,MAAM,cAAc,GAAG,kBAAkB,EAAE,eAAe;+BACrD,gBAAgB,EAAE,CAAC,qBAAqB,EAAE,mBAAmB,CAAC;wBACnE,MAAM,iBAAiB,GAAG,kBAAkB;+BACvC,CAAC,cAAc,KAAK,aAAa,CAAC,SAAS,CAAC,CAAC;wBAClD,MAAM,WAAW,GAAG,CAAC,iBAAiB,CAAC;wBAEvC,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAC;wBACtC,MAAM,QAAQ,CAAC,kBAAkB,CAAC,YAAY,CAAC,sBAAsB,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;wBAExF,OAAO;4BACL,iBAAiB,EAAE,WAAW;4BAC9B,WAAW,EAAE,IAAI,IAAI,EAAE;4BACvB,GAAG,CAAC,CAAC,WAAW,IAAI,EAAE,MAAM,EAAE,kBAAkB,CAAC,SAAS,EAAE,CAAC;4BAC7D,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,kBAAkB,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;yBAC1D,CAAC;oBACJ,CAAC;oBAED,kFAAkF;iBACnF;aACF,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,OAAO,OAAgE,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC;AAED,uEAAuE;AACvE,SAAS;AACT,uEAAuE;AAEvE;;;;;;;GAOG;AACH,MAAM,UAAU,iCAAiC;IAC/C,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC,mBAAmB,EAAE,EAAE;QAC5D,MAAM,OAAO,GAAG,CAAC,yBAA0D,EAAE,EAAE;YAC7E,OAAO,yCAAyC,CAAC;gBAC/C,aAAa,EAAE;oBACb,kBAAkB,EAAE,mBAAmB;oBACvC,mBAAmB,EAAE,8BAA8B,CAAC,MAAM;oBAC1D,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,kBAAkB,EAAE,IAAI;iBACzB;gBACD,QAAQ,EAAE;oBACR,oBAAoB,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE;wBACnF,MAAM,YAAY,GAAG,KAAK,CAAC,aAAa,CAAC;wBACzC,4BAA4B,CAAC,YAAY,EAAE,GAAI,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBAE1E,IAAI,CAAC,YAAY,CAAC,iBAAiB,EAAE,CAAC;4BACpC,MAAM,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,aAAa,EAAE,gBAAgB,EAAE;gCAC7E,sBAAsB,EAAE,2BAA2B,CAAC,8BAA8B;gCAClF,OAAO,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,0CAA0C,EAAE;6BACrF,CAAC,CAAC;wBACL,CAAC;wBAED,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAC;wBACtC,MAAM,QAAQ,CAAC,kBAAkB,CAAC,YAAY,CAAC,sBAAsB,CAAC,CAAC;wBAEvE,OAAO;4BACL,iBAAiB,EAAE,KAAK;4BACxB,WAAW,EAAE,IAAI;4BACjB,kBAAkB,EAAE,IAAI;4BACxB,MAAM,EAAE,kBAAkB,CAAC,MAAM;yBAClC,CAAC;oBACJ,CAAC;oBAED,kFAAkF;iBACnF;aACF,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,OAAO,OAAgE,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC;AAED,uEAAuE;AACvE,cAAc;AACd,uEAAuE;AAEvE;;;;;;;;GAQG;AACH,MAAM,UAAU,qCAAqC;IACnD,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC,mBAAmB,EAAE,EAAE;QAC5D,MAAM,OAAO,GAAG,CAAC,yBAA0D,EAAE,EAAE;YAC7E,OAAO,yCAAyC,CAAC;gBAC/C,aAAa,EAAE;oBACb,kBAAkB,EAAE,mBAAmB;oBACvC,mBAAmB,EAAE,8BAA8B,CAAC,WAAW;oBAC/D,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,kBAAkB,EAAE,IAAI;iBACzB;gBACD,gBAAgB,EAAE,wCAAwC;gBAC1D,QAAQ,EAAE;oBACR,oBAAoB,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE;wBAClF,MAAM,YAAY,GAAG,KAAK,CAAC,aAAa,CAAC;wBACzC,4BAA4B,CAAC,YAAY,EAAE,GAAI,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBAE1E,8DAA8D;wBAC9D,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,aAAa,EAAE,wBAAwB,CAAC,OAAO,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBAC1H,8EAA8E;wBAC9E,2FAA2F;wBAC3F,qFAAqF;wBACrF,mDAAmD;wBACnD,MAAM,QAAQ,GAAG,MAAM,mBAAmB,CAAC,KAAK,CAAC,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBAElG,IAAI,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC;4BAC9B,MAAM,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,aAAa,EAAE,gBAAgB,EAAE;gCAC7E,sBAAsB,EAAE,2BAA2B,CAAC,yBAAyB;gCAC7E,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,UAAU,EAAE,UAAU,EAAE,KAAK,CAAC,aAAa,EAAE;6BACxE,CAAC,CAAC;wBACL,CAAC;wBAED,6EAA6E;wBAC7E,MAAM,eAAe,GAAG,MAAM,eAAe,CAAC,YAAY,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBACrF,MAAM,aAAa,GAAG,eAAe,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,eAAoD,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;wBAE9H,2DAA2D;wBAC3D,MAAM,aAAa,GAA8F,EAAE,CAAC;wBACpH,MAAM,UAAU,GAAe,EAAE,CAAC;wBAElC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;4BACnD,IAAI,CAAC,KAAK,aAAa,EAAE,CAAC;gCACxB,aAAa,CAAC,IAAI,CAAC;oCACjB,0BAA0B,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,0BAA0B;oCAC5E,eAAe,EAAE,QAAQ,CAAC,eAAe;oCACzC,QAAQ,EAAE,CAAC;iCACZ,CAAC,CAAC;gCACH,UAAU,CAAC,IAAI,CAAC;oCACd,GAAG,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG;oCAC9B,SAAS,EAAE,UAAU,CAAC,GAAG;oCACzB,OAAO,EAAE,QAAQ,CAAC,GAAG;oCACrB,QAAQ,EAAE,CAAC;iCACZ,CAAC,CAAC;4BACL,CAAC;iCAAM,CAAC;gCACN,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;gCAC1F,aAAa,CAAC,IAAI,CAAC;oCACjB,0BAA0B,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,0BAA0B;oCAC5E,eAAe,EAAE,KAAK,CAAC,eAAe,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO;oCACvE,QAAQ,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ;iCACzC,CAAC,CAAC;gCACH,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;4BACzC,CAAC;wBACH,CAAC;wBAED,8CAA8C;wBAC9C,IAAI,aAAa,KAAK,CAAC,CAAC,EAAE,CAAC;4BACzB,aAAa,CAAC,OAAO,CAAC,EAAE,eAAe,EAAE,QAAQ,CAAC,eAAe,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;4BAClF,UAAU,CAAC,OAAO,CAAC;gCACjB,GAAG,EAAE,GAAG,YAAY,CAAC,sBAAsB,YAAY;gCACvD,SAAS,EAAE,UAAU,CAAC,GAAG;gCACzB,OAAO,EAAE,QAAQ,CAAC,GAAG;gCACrB,QAAQ,EAAE,CAAC;6BACZ,CAAC,CAAC;wBACL,CAAC;wBAED,mDAAmD;wBACnD,MAAM,cAAc,GAAG,aAAa,IAAI,CAAC;4BACvC,CAAC,CAAC,MAAM,eAAe,CAAC,YAAY,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,SAAS,EAAE,gBAAgB,EAAE,KAAK,CAAC;4BAC7F,CAAC,CAAC,IAAI,CAAC;wBACT,MAAM,SAAS,GAAG,cAAc;4BAC9B,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,IAAI,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,aAAa,IAAI,CAAC,CAAC;4BACvE,CAAC,CAAC,IAAI,CAAC;wBACT,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC;wBAClC,MAAM,MAAM,GAAG,SAAS;4BACtB,CAAC,CAAC,CAAC,UAAU,CAAC,cAAc,EAAE,OAAO,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,EAAE,aAAa,CAAC,SAAS,EAAE,CAAC;4BACvI,CAAC,CAAC,CAAC,UAAU,CAAC,cAAc,EAAE,SAAS,IAAI,EAAE,SAAS,EAAE,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,CAAC,aAAa,EAAE,CAAC,CAAC;wBAEzH,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAC;wBACtC,MAAM,QAAQ,CAAC,kBAAkB,CAAC,YAAY,CAAC,sBAAsB,EAAE;4BACrE,KAAK,EAAE,aAAa;4BACpB;;;;;;;;+BAQG;4BACH,iBAAiB,EAAE,MAAM,CAAC,SAAS;4BACnC,QAAQ,EAAE;gCACR;;;;;;;mCAOG;gCACH,eAAe,EAAE,MAAM,CAAC,MAAM;6BAC/B;yBACF,CAAC,CAAC;wBAEH,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;oBAC/B,CAAC;oBAED,kFAAkF;iBACnF;aACF,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,OAAO,OAAgE,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC;AAED,uEAAuE;AACvE,YAAY;AACZ,uEAAuE;AAEvE;;;;;;;;GAQG;AACH,MAAM,UAAU,mCAAmC;IACjD,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC,mBAAmB,EAAE,EAAE;QAC5D,MAAM,OAAO,GAAG,CAAC,yBAA0D,EAAE,EAAE;YAC7E,OAAO,yCAAyC,CAAC;gBAC/C,aAAa,EAAE;oBACb,kBAAkB,EAAE,mBAAmB;oBACvC,mBAAmB,EAAE,8BAA8B,CAAC,SAAS;oBAC7D,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,kBAAkB,EAAE,IAAI;iBACzB;gBACD,gBAAgB,EAAE,sCAAsC;gBACxD,QAAQ,EAAE;oBACR,oBAAoB,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE;wBAClF,MAAM,YAAY,GAAG,KAAK,CAAC,aAAa,CAAC;wBACzC,4BAA4B,CAAC,YAAY,EAAE,GAAI,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBAE1E,qCAAqC;wBACrC,sCAAsC;wBACtC,MAAM,YAAY,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,eAAe,EAAE,wBAAwB,CAAC,OAAO,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBAC9H,IAAI,YAAY,CAAC,IAAI,KAAK,WAAW,CAAC,KAAK,EAAE,CAAC;4BAC5C,MAAM,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,UAAU,EAAE,gBAAgB,EAAE;gCAC1E,sBAAsB,EAAE,2BAA2B,CAAC,4BAA4B;gCAChF,OAAO,EAAE,EAAE,UAAU,EAAE,KAAK,CAAC,eAAe,EAAE,YAAY,EAAE,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,YAAY,CAAC,IAAI,EAAE;6BAC/G,CAAC,CAAC;wBACL,CAAC;wBAED,6BAA6B;wBAC7B,IAAI,YAAY,CAAC,iBAAiB,IAAI,YAAY,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;4BAChF,MAAM,eAAe,GAAG,MAAM,eAAe,CAAC,YAAY,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;4BACrF,MAAM,eAAe,GAAG,eAAe;gCACrC,CAAC,CAAC,CAAC,MAAM,eAAe,CAAC,eAAe,CAAC,SAAS,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ;gCACtF,CAAC,CAAC,SAAS,CAAC;4BACd,IAAI,CAAC,eAAe,IAAI,CAAC,YAAY,CAAC,iBAAiB,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;gCAClF,MAAM,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,aAAa,EAAE,gBAAgB,EAAE;oCAC7E,sBAAsB,EAAE,2BAA2B,CAAC,0BAA0B;oCAC9E,OAAO,EAAE,EAAE,eAAe,EAAE,KAAK,CAAC,eAAe,EAAE,aAAa,EAAE,YAAY,CAAC,iBAAiB,EAAE,WAAW,EAAE,eAAe,IAAI,IAAI,EAAE;iCACzI,CAAC,CAAC;4BACL,CAAC;wBACH,CAAC;wBAED,wFAAwF;wBACxF,uFAAuF;wBACvF,6DAA6D;wBAC7D,MAAM,UAAU,GAAG,MAAM,mBAAmB,CAAC,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBACnG,IAAI,CAAC,UAAU,CAAC,eAAe,EAAE,CAAC;4BAChC,MAAM,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,aAAa,EAAE,gBAAgB,EAAE;gCAC7E,sBAAsB,EAAE,2BAA2B,CAAC,yBAAyB;gCAC7E,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,CAAC,eAAe,EAAE;6BACvE,CAAC,CAAC;wBACL,CAAC;wBAED,mDAAmD;wBACnD,MAAM,qBAAqB,GAAG,MAAM,oBAAoB,CAAC,YAAY,CAAC,KAAK,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBACtG,qBAAqB,CAAC,IAAI,CAAC;4BACzB,eAAe,EAAE,UAAU,CAAC,eAAe;4BAC3C,QAAQ,EAAE,CAAC;yBACZ,CAAC,CAAC;wBAEH,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAC;wBACtC,MAAM,QAAQ,CAAC,kBAAkB,CAAC,YAAY,CAAC,sBAAsB,EAAE;4BACrE,KAAK,EAAE,qBAAqB;yBAC7B,CAAC,CAAC;wBAEH,gDAAgD;wBAChD,MAAM,QAAQ,GAAG;4BACf,GAAG,YAAY,CAAC,KAAK;4BACrB;gCACE,GAAG,EAAE,GAAG,YAAY,CAAC,sBAAsB,SAAS,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE;gCAC/E,SAAS,EAAE,YAAY,CAAC,GAAG;gCAC3B,OAAO,EAAE,UAAU,CAAC,GAAG;gCACvB,QAAQ,EAAE,CAAC;6BACZ;yBACF,CAAC;wBAEF,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;oBAC7B,CAAC;oBAED,kFAAkF;iBACnF;aACF,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,OAAO,OAAgE,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC;AAED,uEAAuE;AACvE,eAAe;AACf,uEAAuE;AAEvE;;;;;;;;GAQG;AACH,MAAM,UAAU,sCAAsC;IACpD,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC,mBAAmB,EAAE,EAAE;QAC5D,MAAM,OAAO,GAAG,CAAC,yBAA0D,EAAE,EAAE;YAC7E,OAAO,yCAAyC,CAAC;gBAC/C,aAAa,EAAE;oBACb,kBAAkB,EAAE,mBAAmB;oBACvC,mBAAmB,EAAE,8BAA8B,CAAC,YAAY;oBAChE,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,kBAAkB,EAAE,IAAI;iBACzB;gBACD,gBAAgB,EAAE,yCAAyC;gBAC3D,QAAQ,EAAE;oBACR,oBAAoB,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE;wBAClF,MAAM,YAAY,GAAG,KAAK,CAAC,aAAa,CAAC;wBACzC,4BAA4B,CAAC,YAAY,EAAE,GAAI,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBAE1E,wBAAwB;wBACxB;;;;2BAIG;wBACH,MAAM,YAAY,GAAG,MAAM,gBAAgB,CAAC,KAAK,CAAC,eAAe,EAAE,wBAAwB,CAAC,SAAS,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBAEhI,iCAAiC;wBACjC,MAAM,cAAc,GAAG,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAS,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,YAAY,CAAC,GAAG,CAAC,CAAC;wBACrG,IAAI,cAAc,CAAC,MAAM,KAAK,YAAY,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;4BACxD,MAAM,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,SAAS,EAAE,gBAAgB,EAAE;gCACzE,sBAAsB,EAAE,2BAA2B,CAAC,iCAAiC;gCACrF,OAAO,EAAE,EAAE,eAAe,EAAE,KAAK,CAAC,eAAe,EAAE,cAAc,EAAE,GAAG,EAAE;6BACzE,CAAC,CAAC;wBACL,CAAC;wBAED,4CAA4C;wBAC5C,MAAM,aAAa,GAAG,MAAM,oBAAoB,CAAC,cAAc,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;wBAE1F,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAC;wBACtC,MAAM,QAAQ,CAAC,kBAAkB,CAAC,YAAY,CAAC,sBAAsB,EAAE;4BACrE,KAAK,EAAE,aAAa;yBACrB,CAAC,CAAC;wBAEH,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC;oBACnC,CAAC;oBAED,kFAAkF;iBACnF;aACF,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,OAAO,OAAgE,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["/**\n * Subscription Mutations Custom Implementations\n *\n * Implements CANCEL, RESUME, CHANGE_PLAN, ADD_ADDON, REMOVE_ADDON operations\n * on subscription polymorphic variants.\n *\n * Pattern: PREFIX_CORE_OPERATIONS\n *   PREFIX  → validate, call billing provider (Stripe), return update payload\n *   CORE    → standard UPDATE (engine handles DB write)\n *   Feature sync is handled automatically by the post-operation hook infrastructure.\n *\n * One factory per polymorphic variant (org, user) per operation.\n * All variants share the same handler logic.\n *\n * @see billing-polymorphic-full-implementation.md §4.2 + §4.3\n */\n\nimport {\n  CoreResourceType,\n  ResourceOperationVariantType,\n  SubscriptionStatus,\n  ErrorType,\n  ErrorCustomMessageReference,\n  ProductType,\n  ProrationBehavior,\n  BillingTiming,\n  BillingSubscription_Operations,\n  BillingSubscription_CancelRequestDto,\n  BillingSubscription_ChangePlanRequestDto,\n  BillingSubscription_AddAddonRequestDto,\n  BillingSubscription_RemoveAddonRequestDto,\n} from '@wildo-ai/saas-models';\nimport {\n  createResourceCustomServiceImplementation,\n  type ResourceCustomServiceImplementationFactory,\n} from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation.factory.backend';\nimport type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';\nimport { getBillingProvider, getBillingConfig } from '~wildo-backend-lib/billing/services/custom-impl/billing-custom-implementations.backend';\nimport {\n  BillingCatalogReadIntent,\n  readProductByKey,\n  readProductById,\n  readPriceById,\n  readPriceForProduct,\n  validateProviderSubscription,\n  resolveProviderItems,\n} from '~wildo-backend-lib/billing/services/custom-impl/billing-custom-impl-utils.backend';\n\n// ── Subscription polymorphic variant types ───────────────────────────\n\nconst SUBSCRIPTION_VARIANT_TYPES = [\n  CoreResourceType.ORGANIZATION_SUBSCRIPTIONS,\n  CoreResourceType.USER_SUBSCRIPTIONS,\n] as const;\n\n/**\n * The subscription item carrying the PLAN, or `null` when a subscription holds only addons.\n *\n * A subscription's items are a plan plus any addons, and three places in this file needed to find\n * the plan among them — the change-plan path, the addon plan-tier gate, and now the cancellation\n * policy (#408). Each had its own inline loop. One helper because \"which item is the plan\" is a\n * single question with a single answer, and three copies is how the fourth one comes to differ.\n */\nasync function resolvePlanItem(\n  subscription: { items: Array<{ productId: string }> },\n  executionContext: Parameters<typeof readProductById>[1],\n  utils: Parameters<typeof readProductById>[2],\n): Promise<{ productId: string } | null> {\n  for (const item of subscription.items) {\n    const itemProduct = await readProductById(item.productId, executionContext, utils);\n    if (itemProduct.type === ProductType.PLAN) {\n      return item;\n    }\n  }\n  return null;\n}\n\n// ════════════════════════════════════════════════════════════════════\n// CANCEL\n// ════════════════════════════════════════════════════════════════════\n\nexport function createSubscriptionCancelFactories(): ResourceCustomServiceImplementationFactory[] {\n  return SUBSCRIPTION_VARIANT_TYPES.map((variantResourceType) => {\n    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {\n      return createResourceCustomServiceImplementation({\n        operationPath: {\n          resourceIdentifier: variantResourceType,\n          operationIdentifier: BillingSubscription_Operations.CANCEL,\n          variantType: ResourceOperationVariantType.API_CALL,\n          isOperationDefault: true,\n        },\n        requestDtoSchema: BillingSubscription_CancelRequestDto,\n        handlers: {\n          prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n            const subscription = utils.currentObject;\n            validateProviderSubscription(subscription, _id!, executionContext, utils);\n\n            /*\n             * `ProductBehaviorPolicy.cancellation` now governs this operation (#408, decided\n             * 2026-09-08). Until then it was read by NOTHING: timing came solely from the caller's\n             * `cancelImmediately` flag, so a product declaring that immediate cancellation is not\n             * allowed could not refuse one — and Wonder Todos authors `allowImmediate: false` on\n             * BOTH plans, unenforced.\n             *\n             * Two distinct things come from the policy, and conflating them was the trap:\n             *   - `allowImmediate` is a REFUSAL. A caller who asks for immediate cancellation\n             *     against a product that forbids it gets a 409, not a silent downgrade to\n             *     period-end. Silently honouring the safer timing would tell the caller their\n             *     subscription had ended when it has not, which is worse than refusing.\n             *   - `defaultBehavior` decides the timing when the caller expresses NO preference.\n             *     `cancelImmediately` is optional on the request DTO, so \"absent\" is a real state\n             *     and is where an authored default belongs.\n             *\n             * The policy is read from the subscription's PLAN product, resolved the same way the\n             * change-plan path above resolves it. An addon does not carry the cancellation policy\n             * of the subscription it rides on.\n             */\n            const planItem = await resolvePlanItem(subscription, executionContext, utils);\n            const planProduct = planItem\n              ? await readProductById(planItem.productId, executionContext, utils)\n              : null;\n            const cancellationPolicy = planProduct?.behaviorPolicy?.cancellation;\n\n            const requestedImmediate = input.cancelImmediately;\n            if (requestedImmediate === true && cancellationPolicy?.allowImmediate === false) {\n              throw utils.errorBuilder.buildError(ErrorType.CONFLICT, executionContext, {\n                customMessageReference: ErrorCustomMessageReference.CONFLICT,\n                context: {\n                  reason: 'billing_product_forbids_immediate_cancellation',\n                  message: 'This plan does not allow immediate cancellation; it can only be cancelled at the end of the current period.',\n                  productKey: planProduct?.key,\n                },\n              });\n            }\n\n            /*\n             * Absent preference resolves down a chain, most specific first: the caller, the plan\n             * product's own default, the application's `defaultCancellation`, then period-end.\n             *\n             * The application-level step is what makes `billing.defaultBehaviorPolicy.defaultCancellation`\n             * mean something. It was dead alongside its neighbours, and it is BOUND rather than\n             * relabelled because — unlike grace periods and retry counts, which are dunning settings\n             * living at the provider — cancellation timing is resolved locally. The only thing\n             * standing between that key and an effect was a reader.\n             *\n             * Period-end is the floor because it never ends access a customer has already paid for.\n             */\n            const resolvedTiming = cancellationPolicy?.defaultBehavior\n              ?? getBillingConfig().defaultBehaviorPolicy?.defaultCancellation;\n            const cancelImmediately = requestedImmediate\n              ?? (resolvedTiming === BillingTiming.IMMEDIATE);\n            const atPeriodEnd = !cancelImmediately;\n\n            const provider = getBillingProvider();\n            await provider.cancelSubscription(subscription.providerSubscriptionId, { atPeriodEnd });\n\n            return {\n              cancelAtPeriodEnd: atPeriodEnd,\n              cancelledAt: new Date(),\n              ...(!atPeriodEnd && { status: SubscriptionStatus.CANCELLED }),\n              ...(input.reason && { cancellationReason: input.reason }),\n            };\n          },\n\n          // Feature sync is handled automatically by the post-operation hook infrastructure\n        },\n      });\n    };\n\n    return factory as unknown as ResourceCustomServiceImplementationFactory;\n  });\n}\n\n// ════════════════════════════════════════════════════════════════════\n// RESUME\n// ════════════════════════════════════════════════════════════════════\n\n/**\n * Create RESUME custom impl factories for all subscription variants.\n *\n * RESUME un-cancels a subscription that has cancelAtPeriodEnd = true.\n *   PREFIX:  validates subscription is pending cancellation, calls provider resumeSubscription()\n *   CORE:    standard UPDATE clears cancellation fields\n *   (Feature sync handled by post-operation hook)\n */\nexport function createSubscriptionResumeFactories(): ResourceCustomServiceImplementationFactory[] {\n  return SUBSCRIPTION_VARIANT_TYPES.map((variantResourceType) => {\n    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {\n      return createResourceCustomServiceImplementation({\n        operationPath: {\n          resourceIdentifier: variantResourceType,\n          operationIdentifier: BillingSubscription_Operations.RESUME,\n          variantType: ResourceOperationVariantType.API_CALL,\n          isOperationDefault: true,\n        },\n        handlers: {\n          prefixCoreOperations: async (_id, _input, executionContext, _operationPath, utils) => {\n            const subscription = utils.currentObject;\n            validateProviderSubscription(subscription, _id!, executionContext, utils);\n\n            if (!subscription.cancelAtPeriodEnd) {\n              throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {\n                customMessageReference: ErrorCustomMessageReference.BILLING_NO_ACTIVE_SUBSCRIPTION,\n                context: { subscriptionId: _id, reason: 'Subscription is not pending cancellation' },\n              });\n            }\n\n            const provider = getBillingProvider();\n            await provider.resumeSubscription(subscription.providerSubscriptionId);\n\n            return {\n              cancelAtPeriodEnd: false,\n              cancelledAt: null,\n              cancellationReason: null,\n              status: SubscriptionStatus.ACTIVE,\n            };\n          },\n\n          // Feature sync is handled automatically by the post-operation hook infrastructure\n        },\n      });\n    };\n\n    return factory as unknown as ResourceCustomServiceImplementationFactory;\n  });\n}\n\n// ════════════════════════════════════════════════════════════════════\n// CHANGE_PLAN\n// ════════════════════════════════════════════════════════════════════\n\n/**\n * Create CHANGE_PLAN custom impl factories for all subscription variants.\n *\n * CHANGE_PLAN upgrades or downgrades the subscription plan.\n *   PREFIX:  resolves new product/price, determines proration, builds provider items,\n *            calls provider updateSubscription(), returns update payload with new items\n *   CORE:    standard UPDATE writes new items to DB\n *   (Feature sync handled by post-operation hook)\n */\nexport function createSubscriptionChangePlanFactories(): ResourceCustomServiceImplementationFactory[] {\n  return SUBSCRIPTION_VARIANT_TYPES.map((variantResourceType) => {\n    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {\n      return createResourceCustomServiceImplementation({\n        operationPath: {\n          resourceIdentifier: variantResourceType,\n          operationIdentifier: BillingSubscription_Operations.CHANGE_PLAN,\n          variantType: ResourceOperationVariantType.API_CALL,\n          isOperationDefault: true,\n        },\n        requestDtoSchema: BillingSubscription_ChangePlanRequestDto,\n        handlers: {\n          prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n            const subscription = utils.currentObject;\n            validateProviderSubscription(subscription, _id!, executionContext, utils);\n\n            // ACQUIRE: the subscription is being moved ONTO this product.\n            const newProduct = await readProductByKey(input.newProductKey, BillingCatalogReadIntent.ACQUIRE, executionContext, utils);\n            // The price MUST belong to the product being switched to. These were resolved\n            // independently, so pairing a premium `newProductKey` with a cheap `newPriceId` billed the\n            // provider the cheap price while the local item — and every entitlement derived from\n            // `item.productId` — recorded the premium product.\n            const newPrice = await readPriceForProduct(input.newPriceId, newProduct, executionContext, utils);\n\n            if (!newPrice.providerPriceId) {\n              throw utils.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {\n                customMessageReference: ErrorCustomMessageReference.BILLING_NO_PROVIDER_PRICE,\n                context: { priceId: input.newPriceId, productKey: input.newProductKey },\n              });\n            }\n\n            // Find the current plan item (type === PLAN) and determine upgrade/downgrade\n            const currentPlanItem = await resolvePlanItem(subscription, executionContext, utils);\n            const planItemIndex = currentPlanItem ? subscription.items.indexOf(currentPlanItem as typeof subscription.items[number]) : -1;\n\n            // Build provider items: replace plan item, preserve addons\n            const providerItems: Array<{ providerSubscriptionItemId?: string; providerPriceId: string; quantity: number }> = [];\n            const localItems: Array<any> = [];\n\n            for (let i = 0; i < subscription.items.length; i++) {\n              if (i === planItemIndex) {\n                providerItems.push({\n                  providerSubscriptionItemId: subscription.items[i].providerSubscriptionItemId,\n                  providerPriceId: newPrice.providerPriceId,\n                  quantity: 1,\n                });\n                localItems.push({\n                  _id: subscription.items[i]._id,\n                  productId: newProduct._id,\n                  priceId: newPrice._id,\n                  quantity: 1,\n                });\n              } else {\n                const price = await readPriceById(subscription.items[i].priceId, executionContext, utils);\n                providerItems.push({\n                  providerSubscriptionItemId: subscription.items[i].providerSubscriptionItemId,\n                  providerPriceId: price.providerPriceId || subscription.items[i].priceId,\n                  quantity: subscription.items[i].quantity,\n                });\n                localItems.push(subscription.items[i]);\n              }\n            }\n\n            // If no plan item found, prepend the new plan\n            if (planItemIndex === -1) {\n              providerItems.unshift({ providerPriceId: newPrice.providerPriceId, quantity: 1 });\n              localItems.unshift({\n                _id: `${subscription.providerSubscriptionId}_item_plan`,\n                productId: newProduct._id,\n                priceId: newPrice._id,\n                quantity: 1,\n              });\n            }\n\n            // Determine proration from product behavior policy\n            const currentProduct = planItemIndex >= 0\n              ? await readProductById(subscription.items[planItemIndex].productId, executionContext, utils)\n              : null;\n            const isUpgrade = currentProduct\n              ? (newProduct.planTierOrder ?? 0) > (currentProduct.planTierOrder ?? 0)\n              : true;\n            const config = getBillingConfig();\n            const policy = isUpgrade\n              ? (newProduct.behaviorPolicy?.upgrade ?? { proration: config.defaultBehaviorPolicy.defaultProration, timing: BillingTiming.IMMEDIATE })\n              : (newProduct.behaviorPolicy?.downgrade ?? { proration: ProrationBehavior.NONE, timing: BillingTiming.AT_PERIOD_END });\n\n            const provider = getBillingProvider();\n            await provider.updateSubscription(subscription.providerSubscriptionId, {\n              items: providerItems,\n              /*\n               * The resolved proration, as a REQUEST FIELD (#516).\n               *\n               * It was `metadata.prorationBehavior` until 2026-09-08 — a free-form key/value bag the\n               * provider stores and never reads — so this policy was correctly resolved from the target\n               * product's `upgrade`/`downgrade` block and then discarded at the boundary. A product\n               * declaring `ProrationBehavior.NONE` for a downgrade was prorated anyway, by the\n               * provider's account default. Wonder Todos authors exactly that.\n               */\n              prorationBehavior: policy.proration,\n              metadata: {\n                /*\n                 * TIMING remains metadata, and that is honest rather than an oversight: a provider's\n                 * proration parameter says HOW a change settles, not WHEN it applies. Deferring a\n                 * change to the period end needs a subscription schedule, which is a different call and\n                 * a different mechanism — so `prorationTiming` is still carried for a connector that\n                 * grows one, and still changes nothing today. Do not read this field's presence as the\n                 * timing being honoured.\n                 */\n                prorationTiming: policy.timing,\n              },\n            });\n\n            return { items: localItems };\n          },\n\n          // Feature sync is handled automatically by the post-operation hook infrastructure\n        },\n      });\n    };\n\n    return factory as unknown as ResourceCustomServiceImplementationFactory;\n  });\n}\n\n// ════════════════════════════════════════════════════════════════════\n// ADD_ADDON\n// ════════════════════════════════════════════════════════════════════\n\n/**\n * Create ADD_ADDON custom impl factories for all subscription variants.\n *\n * ADD_ADDON adds an addon product to the existing subscription.\n *   PREFIX:  validates addon product (type, requiredPlanTiers), builds provider items,\n *            calls provider updateSubscription(), returns update payload with expanded items\n *   CORE:    standard UPDATE writes new items to DB\n *   (Feature sync handled by post-operation hook)\n */\nexport function createSubscriptionAddAddonFactories(): ResourceCustomServiceImplementationFactory[] {\n  return SUBSCRIPTION_VARIANT_TYPES.map((variantResourceType) => {\n    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {\n      return createResourceCustomServiceImplementation({\n        operationPath: {\n          resourceIdentifier: variantResourceType,\n          operationIdentifier: BillingSubscription_Operations.ADD_ADDON,\n          variantType: ResourceOperationVariantType.API_CALL,\n          isOperationDefault: true,\n        },\n        requestDtoSchema: BillingSubscription_AddAddonRequestDto,\n        handlers: {\n          prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n            const subscription = utils.currentObject;\n            validateProviderSubscription(subscription, _id!, executionContext, utils);\n\n            // Resolve addon product and validate\n            // ACQUIRE: an add-on is being bought.\n            const addonProduct = await readProductByKey(input.addonProductKey, BillingCatalogReadIntent.ACQUIRE, executionContext, utils);\n            if (addonProduct.type !== ProductType.ADDON) {\n              throw utils.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {\n                customMessageReference: ErrorCustomMessageReference.BILLING_INVALID_PRODUCT_TYPE,\n                context: { productKey: input.addonProductKey, expectedType: ProductType.ADDON, actualType: addonProduct.type },\n              });\n            }\n\n            // Validate requiredPlanTiers\n            if (addonProduct.requiredPlanTiers && addonProduct.requiredPlanTiers.length > 0) {\n              const planItemForTier = await resolvePlanItem(subscription, executionContext, utils);\n              const currentPlanTier = planItemForTier\n                ? (await readProductById(planItemForTier.productId, executionContext, utils)).planTier\n                : undefined;\n              if (!currentPlanTier || !addonProduct.requiredPlanTiers.includes(currentPlanTier)) {\n                throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {\n                  customMessageReference: ErrorCustomMessageReference.BILLING_PLAN_TIER_REQUIRED,\n                  context: { addonProductKey: input.addonProductKey, requiredTiers: addonProduct.requiredPlanTiers, currentTier: currentPlanTier ?? null },\n                });\n              }\n            }\n\n            // Resolve addon price — and prove it belongs to the addon product. Same defect shape as\n            // CHANGE_PLAN: the addon's entitlements come from `addonProduct._id` on the local item\n            // while the provider is billed `addonPrice.providerPriceId`.\n            const addonPrice = await readPriceForProduct(input.priceId, addonProduct, executionContext, utils);\n            if (!addonPrice.providerPriceId) {\n              throw utils.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {\n                customMessageReference: ErrorCustomMessageReference.BILLING_NO_PROVIDER_PRICE,\n                context: { priceId: input.priceId, productKey: input.addonProductKey },\n              });\n            }\n\n            // Build provider items: existing items + new addon\n            const existingProviderItems = await resolveProviderItems(subscription.items, executionContext, utils);\n            existingProviderItems.push({\n              providerPriceId: addonPrice.providerPriceId,\n              quantity: 1,\n            });\n\n            const provider = getBillingProvider();\n            await provider.updateSubscription(subscription.providerSubscriptionId, {\n              items: existingProviderItems,\n            });\n\n            // Build local items with the new addon appended\n            const newItems = [\n              ...subscription.items,\n              {\n                _id: `${subscription.providerSubscriptionId}_item_${subscription.items.length}`,\n                productId: addonProduct._id,\n                priceId: addonPrice._id,\n                quantity: 1,\n              },\n            ];\n\n            return { items: newItems };\n          },\n\n          // Feature sync is handled automatically by the post-operation hook infrastructure\n        },\n      });\n    };\n\n    return factory as unknown as ResourceCustomServiceImplementationFactory;\n  });\n}\n\n// ════════════════════════════════════════════════════════════════════\n// REMOVE_ADDON\n// ════════════════════════════════════════════════════════════════════\n\n/**\n * Create REMOVE_ADDON custom impl factories for all subscription variants.\n *\n * REMOVE_ADDON removes an addon product from the subscription.\n *   PREFIX:  finds addon item, builds remaining items, calls provider updateSubscription(),\n *            returns update payload with remaining items\n *   CORE:    standard UPDATE writes remaining items to DB\n *   (Feature sync handled by post-operation hook)\n */\nexport function createSubscriptionRemoveAddonFactories(): ResourceCustomServiceImplementationFactory[] {\n  return SUBSCRIPTION_VARIANT_TYPES.map((variantResourceType) => {\n    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {\n      return createResourceCustomServiceImplementation({\n        operationPath: {\n          resourceIdentifier: variantResourceType,\n          operationIdentifier: BillingSubscription_Operations.REMOVE_ADDON,\n          variantType: ResourceOperationVariantType.API_CALL,\n          isOperationDefault: true,\n        },\n        requestDtoSchema: BillingSubscription_RemoveAddonRequestDto,\n        handlers: {\n          prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n            const subscription = utils.currentObject;\n            validateProviderSubscription(subscription, _id!, executionContext, utils);\n\n            // Resolve addon product\n            /*\n             * REFERENCE, deliberately — the ONE site of the four that must not refuse a retired\n             * product. This resolves the add-on the subscription ALREADY carries in order to drop\n             * it, so gating it would trap a customer on the very add-on the catalogue withdrew.\n             */\n            const addonProduct = await readProductByKey(input.addonProductKey, BillingCatalogReadIntent.REFERENCE, executionContext, utils);\n\n            // Find and remove the addon item\n            const remainingItems = subscription.items.filter((item: any) => item.productId !== addonProduct._id);\n            if (remainingItems.length === subscription.items.length) {\n              throw utils.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {\n                customMessageReference: ErrorCustomMessageReference.BILLING_ADDON_NOT_ON_SUBSCRIPTION,\n                context: { addonProductKey: input.addonProductKey, subscriptionId: _id },\n              });\n            }\n\n            // Build provider items from remaining items\n            const providerItems = await resolveProviderItems(remainingItems, executionContext, utils);\n\n            const provider = getBillingProvider();\n            await provider.updateSubscription(subscription.providerSubscriptionId, {\n              items: providerItems,\n            });\n\n            return { items: remainingItems };\n          },\n\n          // Feature sync is handled automatically by the post-operation hook infrastructure\n        },\n      });\n    };\n\n    return factory as unknown as ResourceCustomServiceImplementationFactory;\n  });\n}\n"]}

package/dist/esm/billing/services/stripe-standard-billing-provider.backend.service.d.ts

@@ -1,4 +1,4 @@
-import { type StandardBilling_Interface, type StandardBilling_CreateCustomerRequest, type StandardBilling_CreateCustomerResponse, type StandardBilling_UpdateCustomerRequest, type StandardBilling_PaymentMethodSummary, type StandardBilling_SyncProductRequest, type StandardBilling_SyncProductResponse, type StandardBilling_SyncPriceRequest, type StandardBilling_SyncPriceResponse, type StandardBilling_CreateSubscriptionRequest, type StandardBilling_CreateSubscriptionResponse, type StandardBilling_UpdateSubscriptionRequest, type StandardBilling_CancelSubscriptionOptions, type StandardBilling_SubscriptionData, type StandardBilling_InvoicePreview, type StandardBilling_CreateCheckoutSessionRequest, type StandardBilling_CreateCheckoutSessionResponse, type StandardBilling_CreateCustomerPortalSessionResponse, type StandardBilling_ReportUsageRequest, type StandardBilling_WebhookEvent, type StandardBilling_CreateCouponRequest, type StandardBilling_CreateCouponResponse, type StandardBilling_CreatePromotionCodeResponse } from '@wildo-ai/external-connectors-models';
+import { type StandardBilling_Interface, type StandardBilling_CreateCustomerRequest, type StandardBilling_CreateCustomerResponse, type StandardBilling_UpdateCustomerRequest, type StandardBilling_PaymentMethodSummary, type StandardBilling_SyncProductRequest, type StandardBilling_SyncProductResponse, type StandardBilling_SyncPriceRequest, type StandardBilling_SyncPriceResponse, type StandardBilling_CreateSubscriptionRequest, type StandardBilling_CreateSubscriptionResponse, type StandardBilling_UpdateSubscriptionRequest, type StandardBilling_CancelSubscriptionOptions, type StandardBilling_SubscriptionData, type StandardBilling_InvoicePreview, type StandardBilling_InvoiceData, type StandardBilling_CreateCheckoutSessionRequest, type StandardBilling_CreateCheckoutSessionResponse, type StandardBilling_CreateCustomerPortalSessionResponse, type StandardBilling_ReportUsageRequest, type StandardBilling_WebhookEvent, type StandardBilling_CreateCouponRequest, type StandardBilling_CreateCouponResponse, type StandardBilling_CreatePromotionCodeResponse } from '@wildo-ai/external-connectors-models';
 export declare class StripeStandardBillingProvider implements StandardBilling_Interface {
     private readonly secretKey;
     private readonly apiVersion;
@@ -37,6 +37,23 @@ export declare class StripeStandardBillingProvider implements StandardBilling_In
     resumeSubscription(providerSubscriptionId: string): Promise<void>;
     retrieveSubscription(providerSubscriptionId: string): Promise<StandardBilling_SubscriptionData>;
     retrieveUpcomingInvoice(providerSubscriptionId: string, newPriceId?: string): Promise<StandardBilling_InvoicePreview>;
+    /**
+     * One page of the customer's invoices, newest first.
+     *
+     * `total` rather than `amount_paid`, deliberately, and it disagrees with what the webhook router
+     * records for the same invoice. The router reads `amount_paid ?? total`, which is `0` for every
+     * invoice that is finalized-but-unpaid — so an OPEN invoice lands locally at zero. That reading is
+     * not corrected here (it is a separate finding on a separate write path); what this file
+     * guarantees is that the two never fight, because the reconciliation sweep only ever INSERTS a
+     * total and never updates one.
+     *
+     * An invoice whose Stripe status is not in {@link STRIPE_INVOICE_STATUS_MAP} is SKIPPED rather
+     * than defaulted. A defaulted status is a wrong fact about money written into a durable row; an
+     * omitted invoice stays missing and is found again on the next tick, once the mapping is fixed.
+     */
+    listInvoices(providerCustomerId: string, options?: {
+        limit?: number;
+    }): Promise<StandardBilling_InvoiceData[]>;
     createCheckoutSession(request: StandardBilling_CreateCheckoutSessionRequest): Promise<StandardBilling_CreateCheckoutSessionResponse>;
     createCustomerPortalSession(providerCustomerId: string, returnUrl: string): Promise<StandardBilling_CreateCustomerPortalSessionResponse>;
     reportUsage(request: StandardBilling_ReportUsageRequest): Promise<void>;

package/dist/esm/billing/services/stripe-standard-billing-provider.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stripe-standard-billing-provider.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/billing/services/stripe-standard-billing-provider.backend.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"stripe-standard-billing-provider.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/billing/services/stripe-standard-billing-provider.backend.service.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,yBAAyB,EAC9B,KAAK,qCAAqC,EAC1C,KAAK,sCAAsC,EAC3C,KAAK,qCAAqC,EAC1C,KAAK,oCAAoC,EACzC,KAAK,kCAAkC,EACvC,KAAK,mCAAmC,EACxC,KAAK,gCAAgC,EACrC,KAAK,iCAAiC,EACtC,KAAK,yCAAyC,EAC9C,KAAK,0CAA0C,EAC/C,KAAK,yCAAyC,EAC9C,KAAK,yCAAyC,EAC9C,KAAK,gCAAgC,EACrC,KAAK,8BAA8B,EACnC,KAAK,2BAA2B,EAChC,KAAK,4CAA4C,EACjD,KAAK,6CAA6C,EAClD,KAAK,mDAAmD,EACxD,KAAK,kCAAkC,EACvC,KAAK,4BAA4B,EACjC,KAAK,mCAAmC,EACxC,KAAK,oCAAoC,EACzC,KAAK,2CAA2C,EAIjD,MAAM,sCAAsC,CAAC;AAwD9C,qBAAa,6BAA8B,YAAW,yBAAyB;IAK3E,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAL7B,QAAQ,CAAC,0BAA0B,sBAAsB;IACzD,OAAO,CAAC,MAAM,CAAoB;gBAGf,SAAS,EAAE,MAAM,EACjB,UAAU,SAAsB;IAGnD,OAAO,CAAC,SAAS;IAYX,cAAc,CAAC,OAAO,EAAE,qCAAqC,GAAG,OAAO,CAAC,sCAAsC,CAAC;IAS/G,cAAc,CAAC,kBAAkB,EAAE,MAAM,EAAE,OAAO,EAAE,qCAAqC,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBzG,cAAc,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD,kBAAkB,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,oCAAoC,EAAE,CAAC;IAc/F,mBAAmB,CAAC,uBAAuB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE,WAAW,CAAC,OAAO,EAAE,kCAAkC,GAAG,OAAO,CAAC,mCAAmC,CAAC;IA4B5G;;;;;;;OAOG;YACW,6BAA6B;IAiBrC,SAAS,CAAC,OAAO,EAAE,gCAAgC,GAAG,OAAO,CAAC,iCAAiC,CAAC;IA8CtG;;;;;;OAMG;YACW,uBAAuB;IAmB/B,kBAAkB,CAAC,OAAO,EAAE,yCAAyC,GAAG,OAAO,CAAC,0CAA0C,CAAC;IAyB3H,kBAAkB,CAAC,sBAAsB,EAAE,MAAM,EAAE,OAAO,EAAE,yCAAyC,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BrH,kBAAkB,CAAC,sBAAsB,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,yCAAyC,GAAG,OAAO,CAAC,IAAI,CAAC;IAQtH,iBAAiB,CAAC,sBAAsB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE,kBAAkB,CAAC,sBAAsB,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE,oBAAoB,CAAC,sBAAsB,EAAE,MAAM,GAAG,OAAO,CAAC,gCAAgC,CAAC;IAoB/F,uBAAuB,CAAC,sBAAsB,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,8BAA8B,CAAC;IAwB3H;;;;;;;;;;;;;OAaG;IACG,YAAY,CAAC,kBAAkB,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,2BAA2B,EAAE,CAAC;IAwB9G,qBAAqB,CAAC,OAAO,EAAE,4CAA4C,GAAG,OAAO,CAAC,6CAA6C,CAAC;IAqCpI,2BAA2B,CAAC,kBAAkB,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mDAAmD,CAAC;IAKxI,WAAW,CAAC,OAAO,EAAE,kCAAkC,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7E,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAUhG,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,4BAA4B,GAAG,IAAI;IAY9E,YAAY,CAAC,OAAO,EAAE,mCAAmC,GAAG,OAAO,CAAC,oCAAoC,CAAC;IAYzG,mBAAmB,CAAC,gBAAgB,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,2CAA2C,CAAC;CAOxH"}

package/dist/esm/billing/services/stripe-standard-billing-provider.backend.service.js

@@ -1,5 +1,5 @@
 import { createRequire } from 'node:module';
-import { PricingModel, TaxDisplayMode, StandardBilling_EventType, } from '@wildo-ai/external-connectors-models';
+import { PricingModel, TaxDisplayMode, InvoiceStatus, StandardBilling_EventType, } from '@wildo-ai/external-connectors-models';
 const require = createRequire(import.meta.url);
 const STRIPE_STATUS_MAP = {
     active: 'active',
@@ -11,6 +11,24 @@ const STRIPE_STATUS_MAP = {
     trialing: 'trialing',
     paused: 'paused',
 };
+/**
+ * Stripe invoice status → the canonical vocabulary.
+ *
+ * Every member of both enums is spelled identically today, so this map looks redundant. It is not:
+ * without it an unrecognised Stripe status would be cast through as a canonical one, and the sweep
+ * that compares statuses would then WRITE a value the local schema's `z.enum` refuses — a repair
+ * that fails validation on a row it was trying to correct. An unknown status is a mapping gap, and
+ * `listInvoices` treats it as one rather than guessing.
+ */
+const STRIPE_INVOICE_STATUS_MAP = {
+    draft: InvoiceStatus.DRAFT,
+    open: InvoiceStatus.OPEN,
+    paid: InvoiceStatus.PAID,
+    void: InvoiceStatus.VOID,
+    uncollectible: InvoiceStatus.UNCOLLECTIBLE,
+};
+/** Upper bound Stripe itself enforces on `invoices.list`. Asking for more is an API error, not a bigger page. */
+const STRIPE_INVOICE_LIST_MAX_LIMIT = 100;
 const STRIPE_EVENT_TYPE_MAP = {
     'customer.updated': StandardBilling_EventType.CUSTOMER_UPDATED,
     'customer.deleted': StandardBilling_EventType.CUSTOMER_DELETED,
@@ -230,12 +248,39 @@ export class StripeStandardBillingProvider {
             metadata: request.metadata,
             ...(request.trialPeriodDays && { trial_period_days: request.trialPeriodDays }),
             ...(request.providerPromotionCodeId && { promotion_code: request.providerPromotionCodeId }),
+            // #408: tax is COMPUTED only when the application asks for it. Until 2026-09-08 nothing here
+            // enabled it, so `calculationMode: PROVIDER_MANAGED` changed nothing and the Stripe account's
+            // own configuration silently decided.
+            ...(request.automaticTax && { automatic_tax: { enabled: true } }),
+            /*
+             * #408: a trial that REQUIRES a payment method says so to Stripe in the only place it can —
+             * what happens when the trial ends and none was collected. `cancel` is the reading that
+             * matches the declaration: a trial declared as requiring a card must not roll into an unpaid
+             * subscription. `createSubscription` has no production caller today (checkout is the live
+             * purchase route), so this is the contract kept coherent rather than a live path.
+             */
+            ...(request.requirePaymentMethodForTrial && request.trialPeriodDays
+                ? { trial_settings: { end_behavior: { missing_payment_method: 'cancel' } } }
+                : {}),
         });
         return { providerSubscriptionId: subscription.id, status: subscription.status };
     }
     async updateSubscription(providerSubscriptionId, request) {
         await this.getStripe().subscriptions.update(providerSubscriptionId, {
             metadata: request.metadata,
+            /*
+             * The authored proration finally reaches the provider (#516).
+             *
+             * No mapping table, deliberately: `ProrationBehavior`'s three values ARE Stripe's
+             * `proration_behavior` values — `create_prorations`, `none`, `always_invoice` — which is why the
+             * vocabulary moved to the protocol module rather than being translated here. If a second provider
+             * ever spells them differently, THAT adapter maps; this one has nothing to map.
+             *
+             * Omitted when the caller sends none, so Stripe applies its account default — exactly what every
+             * update did before this field existed. Sending an explicit value unconditionally would change
+             * behaviour for callers that never authored a policy.
+             */
+            ...(request.prorationBehavior && { proration_behavior: request.prorationBehavior }),
             ...(request.providerPromotionCodeId && { promotion_code: request.providerPromotionCodeId }),
             ...(request.items && {
                 items: request.items.map((item) => ({
@@ -303,6 +348,43 @@ export class StripeStandardBillingProvider {
             periodEnd: new Date(invoice.period_end * 1000),
         };
     }
+    /**
+     * One page of the customer's invoices, newest first.
+     *
+     * `total` rather than `amount_paid`, deliberately, and it disagrees with what the webhook router
+     * records for the same invoice. The router reads `amount_paid ?? total`, which is `0` for every
+     * invoice that is finalized-but-unpaid — so an OPEN invoice lands locally at zero. That reading is
+     * not corrected here (it is a separate finding on a separate write path); what this file
+     * guarantees is that the two never fight, because the reconciliation sweep only ever INSERTS a
+     * total and never updates one.
+     *
+     * An invoice whose Stripe status is not in {@link STRIPE_INVOICE_STATUS_MAP} is SKIPPED rather
+     * than defaulted. A defaulted status is a wrong fact about money written into a durable row; an
+     * omitted invoice stays missing and is found again on the next tick, once the mapping is fixed.
+     */
+    async listInvoices(providerCustomerId, options) {
+        const page = await this.getStripe().invoices.list({
+            customer: providerCustomerId,
+            limit: Math.min(options?.limit ?? 20, STRIPE_INVOICE_LIST_MAX_LIMIT),
+        });
+        const invoices = [];
+        for (const invoice of (page.data ?? [])) {
+            const status = STRIPE_INVOICE_STATUS_MAP[invoice.status];
+            if (!status || !invoice.id)
+                continue;
+            invoices.push({
+                providerInvoiceId: invoice.id,
+                providerCustomerId,
+                status,
+                total: invoice.total ?? 0,
+                currency: invoice.currency,
+                hostedInvoiceUrl: invoice.hosted_invoice_url ?? undefined,
+                invoicePdfUrl: invoice.invoice_pdf ?? undefined,
+                createdAt: new Date(invoice.created * 1000),
+            });
+        }
+        return invoices;
+    }
     async createCheckoutSession(request) {
         const session = await this.getStripe().checkout.sessions.create({
             customer: request.providerCustomerId,
@@ -313,7 +395,29 @@ export class StripeStandardBillingProvider {
             metadata: request.metadata,
             ...(request.allowPromotionCodes && { allow_promotion_codes: true }),
             ...(request.providerPromotionCodeId && { discounts: [{ promotion_code: request.providerPromotionCodeId }] }),
-            ...(request.trialPeriodDays && { subscription_data: { trial_period_days: request.trialPeriodDays } }),
+            // #408 — see `createSubscription` above for why each of these exists.
+            ...(request.automaticTax && { automatic_tax: { enabled: true } }),
+            /*
+             * `payment_method_collection` is the checkout-side half of the trial declaration: `always`
+             * collects a card even when the session's immediate amount is zero, which is exactly the
+             * free-trial case. Stripe's default is `if_required`, so without this a "requires a payment
+             * method" trial collected nothing.
+             *
+             * Built as ONE `subscription_data` object rather than two spreads: a second spread of the same
+             * key REPLACES the first, so composing trial days and trial settings separately would silently
+             * drop whichever came first. That is the shape this file already had for trial days alone.
+             */
+            ...(request.requirePaymentMethodForTrial && { payment_method_collection: 'always' }),
+            ...(request.trialPeriodDays
+                ? {
+                    subscription_data: {
+                        trial_period_days: request.trialPeriodDays,
+                        ...(request.requirePaymentMethodForTrial
+                            ? { trial_settings: { end_behavior: { missing_payment_method: 'cancel' } } }
+                            : {}),
+                    },
+                }
+                : {}),
         });
         return { url: session.url, sessionId: session.id };
     }