npm - @wildo-ai/saas-models - Versions diffs - 1.1.5 → 1.1.7 - Mend

@wildo-ai/saas-models 1.1.5 → 1.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1295) hide show

package/dist/esm/billing/subscription.shared.resources-config.schemas.d.ts CHANGED Viewed

@@ -9,6 +9,7 @@
  */
 import { z } from 'zod';
 import { CoreResourceOperation } from '../resources/resources.shared.core.definitions';
+import { BillingTiming } from './billing-enums.shared.schemas';
 export declare enum BillingSubscription_Operations {
     /** Cancel the subscription (at period end or immediately) */
     CANCEL = "cancel",
@@ -21,7 +22,12 @@ export declare enum BillingSubscription_Operations {
     /** Add an addon product to the subscription */
     ADD_ADDON = "add_addon",
     /** Remove an addon product from the subscription */
-    REMOVE_ADDON = "remove_addon"
+    REMOVE_ADDON = "remove_addon",
+    /**
+     * Withdraw a plan change that was confirmed to take effect at the end of the current period (#1868): the provider's schedule
+     * is released and the subscription's `pendingPlanChange` cleared, so the subscription renews on its current plan.
+     */
+    CANCEL_PLAN_CHANGE = "cancel_plan_change"
 }
 /** Request DTO for CANCEL operation — shared between resource config and custom impl */
 export declare const BillingSubscription_CancelRequestDto: z.ZodObject<{
@@ -50,6 +56,8 @@ export declare const BillingSubscription_PlanChangePreviewResponseDto: z.ZodObje
     }, z.core.$strip>>;
     periodStart: z.ZodCoercedDate<unknown>;
     periodEnd: z.ZodCoercedDate<unknown>;
+    timing: z.ZodEnum<typeof BillingTiming>;
+    effectiveAt: z.ZodCoercedDate<unknown>;
     prorationDate: z.ZodNumber;
     previewToken: z.ZodString;
 }, z.core.$strip>;

package/dist/esm/billing/subscription.shared.resources-config.schemas.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"subscription.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["~~../../../../~~src/billing/subscription.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAoB,MAAM,gDAAgD,CAAC;~~AAezG~~,oBAAY,8BAA8B;IACxC,6DAA6D;IAC7D,MAAM,WAAW;IACjB,wDAAwD;IACxD,MAAM,WAAW;IACjB,qDAAqD;IACrD,WAAW,gBAAgB;IAC3B,+EAA+E;IAC/E,mBAAmB,wBAAwB;IAC3C,+CAA+C;IAC/C,SAAS,cAAc;IACvB,oDAAoD;IACpD,YAAY,iBAAiB;~~CAC9B~~;AAID,wFAAwF;AACxF,eAAO,MAAM,oCAAoC;;;iBAiB/C,CAAC;AAEH,sFAAsF;AACtF,eAAO,MAAM,+CAA+C;;;iBAG1D,CAAC;AAEH,uFAAuF;AACvF,eAAO,MAAM,wCAAwC;;;;iBAEnD,CAAC;AAEH,6GAA6G;AAC7G,eAAO,MAAM,gDAAgD~~;;;;;;;;;;;;iBAS3D~~,CAAC;AAEH,2FAA2F;AAC3F,eAAO,MAAM,sCAAsC;;;iBAGjD,CAAC;AAEH,8FAA8F;AAC9F,eAAO,MAAM,yCAAyC;;iBAEpD,CAAC;AAMH;;;;;;;;GAQG;AACH,eAAO,MAAM,wCAAwC,~~iRAwNpD~~,CAAC"}
1	+ {"version":3,"file":"subscription.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/subscription.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAoB,MAAM,gDAAgD,CAAC;AAYzG,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAI/D,oBAAY,8BAA8B;IACxC,6DAA6D;IAC7D,MAAM,WAAW;IACjB,wDAAwD;IACxD,MAAM,WAAW;IACjB,qDAAqD;IACrD,WAAW,gBAAgB;IAC3B,+EAA+E;IAC/E,mBAAmB,wBAAwB;IAC3C,+CAA+C;IAC/C,SAAS,cAAc;IACvB,oDAAoD;IACpD,YAAY,iBAAiB;IAC7B;;;OAGG;IACH,kBAAkB,uBAAuB;CAC1C;AAID,wFAAwF;AACxF,eAAO,MAAM,oCAAoC;;;iBAiB/C,CAAC;AAEH,sFAAsF;AACtF,eAAO,MAAM,+CAA+C;;;iBAG1D,CAAC;AAEH,uFAAuF;AACvF,eAAO,MAAM,wCAAwC;;;;iBAEnD,CAAC;AAEH,6GAA6G;AAC7G,eAAO,MAAM,gDAAgD;;;;;;;;;;;;;;iBAmB3D,CAAC;AAEH,2FAA2F;AAC3F,eAAO,MAAM,sCAAsC;;;iBAGjD,CAAC;AAEH,8FAA8F;AAC9F,eAAO,MAAM,yCAAyC;;iBAEpD,CAAC;AAMH;;;;;;;;GAQG;AACH,eAAO,MAAM,wCAAwC,iRAyOpD,CAAC"}

package/dist/esm/billing/subscription.shared.resources-config.schemas.js CHANGED Viewed

@@ -17,6 +17,7 @@ import { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles
 import { billingSubscriptionsPolymorphicDeclaration } from './subscription.shared.schemas.js';
 import { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas.js';
 import { ResourceOperationIdempotencyKeyRequirement } from '../requests/idempotency-key.shared.js';
+import { BillingTiming } from './billing-enums.shared.schemas.js';
 // ── Custom Operations ────────────────────────────────────────────────
 export var BillingSubscription_Operations;
 (function (BillingSubscription_Operations) {
@@ -32,6 +33,11 @@ export var BillingSubscription_Operations;
     BillingSubscription_Operations["ADD_ADDON"] = "add_addon";
     /** Remove an addon product from the subscription */
     BillingSubscription_Operations["REMOVE_ADDON"] = "remove_addon";
+    /**
+     * Withdraw a plan change that was confirmed to take effect at the end of the current period (#1868): the provider's schedule
+     * is released and the subscription's `pendingPlanChange` cleared, so the subscription renews on its current plan.
+     */
+    BillingSubscription_Operations["CANCEL_PLAN_CHANGE"] = "cancel_plan_change";
 })(BillingSubscription_Operations || (BillingSubscription_Operations = {}));
 // ── Request DTOs ─────────────────────────────────────────────────────
 /** Request DTO for CANCEL operation — shared between resource config and custom impl */
@@ -50,37 +56,47 @@ export const BillingSubscription_CancelRequestDto = z.object({
      * for a product that authors no policy, so nothing changes for an existing caller — what changes
      * is that a product declaring IMMEDIATE now gets it.
      */
-    cancelImmediately: z.boolean().optional(),
-    reason: z.string().max(500).optional(),
+    cancelImmediately: z.boolean().optional().describe("`true` ends the subscription now, `false` at the end of the current billing period. When omitted, the plan's default cancellation timing applies, then the application's, then period end. An immediate cancellation is refused when the plan does not allow it."),
+    reason: z.string().max(500).optional().describe("Why the subscription is being cancelled, kept on the subscription and in the audit trail. At most 500 characters."),
 });
 /** Selection sent for a provider-computed preview; it does not authorize a change. */
 export const BillingSubscription_PreviewPlanChangeRequestDto = z.object({
-    newProductKey: z.string().min(1),
-    newPriceId: z.string().min(1),
+    newProductKey: z.string().min(1).describe("The key of the plan to move the subscription onto. It must be a plan that is available for purchase."),
+    newPriceId: z.string().min(1).describe("The id of the price to bill the new plan at. It must be a price of that plan."),
 });
 /** Confirmation must carry the server-issued preview bound to this exact selection. */
 export const BillingSubscription_ChangePlanRequestDto = BillingSubscription_PreviewPlanChangeRequestDto.extend({
-    previewToken: z.string().min(1).max(65_536),
+    previewToken: z.string().min(1).max(65_536).describe("The `previewToken` from a plan-change preview for the same subscription, plan and price. It is valid for 10 minutes, and is refused when the subscription has changed since the preview."),
 });
 /** Provider invoice estimate plus a short-lived confirmation binding; normal authorization still applies. */
 export const BillingSubscription_PlanChangePreviewResponseDto = z.object({
-    amount: z.number().int(),
-    currency: z.string().min(1),
-    lineItems: z.array(z.object({ description: z.string(), amount: z.number().int(), quantity: z.number() })),
-    periodStart: z.coerce.date(),
-    periodEnd: z.coerce.date(),
+    amount: z.number().int().describe("The amount due on the previewed invoice, in the currency's smallest unit (such as cents). An estimate, not necessarily an immediate charge."),
+    currency: z.string().min(1).describe("The currency of the amounts, as the billing provider reports it, such as `usd`."),
+    lineItems: z.array(z.object({
+        description: z.string().describe("The billing provider's description of the line."),
+        amount: z.number().int().describe("The line's amount, in the currency's smallest unit. Negative for a credit, such as unused time on the current plan."),
+        quantity: z.number().describe("The quantity billed on the line."),
+    })).describe("The lines of the previewed invoice, including any proration for the change."),
+    periodStart: z.coerce.date().describe("Start of the period the previewed invoice covers."),
+    periodEnd: z.coerce.date().describe("End of the period the previewed invoice covers."),
+    /**
+     * When the change would take effect, decided by the new plan's `behaviorPolicy` (#1868). For `at_period_end` the previewed
+     * invoice is the one at renewal, on the new plan, with no proration: nothing is charged on confirmation.
+     */
+    timing: z.enum(BillingTiming).describe("When the change takes effect if confirmed: `immediate` (now, and the previewed invoice includes any proration) or `at_period_end` (at renewal; the previewed invoice is the renewal invoice on the new plan, and nothing is charged on confirmation)."),
+    effectiveAt: z.coerce.date().describe("When the change takes effect if confirmed: now for an immediate change, the end of the current billing period for a change at period end."),
     /** Server-generated calculation instant, in Unix seconds. */
-    prorationDate: z.number().int().nonnegative(),
-    previewToken: z.string().min(1).max(65_536),
+    prorationDate: z.number().int().nonnegative().describe("When the estimate was calculated, in Unix seconds. A prorated change is charged as of this instant when it is confirmed."),
+    previewToken: z.string().min(1).max(65_536).describe("Send this back as `previewToken` to confirm the change. Valid for 10 minutes."),
 });
 /** Request DTO for ADD_ADDON operation — shared between resource config and custom impl */
 export const BillingSubscription_AddAddonRequestDto = z.object({
-    addonProductKey: z.string().min(1),
-    priceId: z.string().min(1),
+    addonProductKey: z.string().min(1).describe("The key of the add-on product to add. It must be an add-on available for purchase, and allowed on the subscription's plan."),
+    priceId: z.string().min(1).describe("The id of the price to bill the add-on at. It must be a price of that add-on."),
 });
 /** Request DTO for REMOVE_ADDON operation — shared between resource config and custom impl */
 export const BillingSubscription_RemoveAddonRequestDto = z.object({
-    addonProductKey: z.string().min(1),
+    addonProductKey: z.string().min(1).describe("The key of the add-on product to remove. The subscription must include it."),
 });
 // =============================================================================
 // POLYMORPHIC FACTORY — 2 variants (org, user)
@@ -175,8 +191,8 @@ export const billingSubscriptionsPolymorphicFactories = createPolymorphicResourc
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
                     polymorphicRole: {
-                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],
-                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],
                     },
                     riskLevel: ResourceOperationRiskLevel.LOW,
                 }],
@@ -186,8 +202,8 @@ export const billingSubscriptionsPolymorphicFactories = createPolymorphicResourc
                     variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
                     polymorphicRole: {
-                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],
-                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],
                     },
                     riskLevel: ResourceOperationRiskLevel.MEDIUM,
                 }],
@@ -197,8 +213,8 @@ export const billingSubscriptionsPolymorphicFactories = createPolymorphicResourc
                     variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
                     polymorphicRole: {
-                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],
-                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],
                     },
                     riskLevel: ResourceOperationRiskLevel.MEDIUM,
                 }],
@@ -234,7 +250,7 @@ export const billingSubscriptionsPolymorphicFactories = createPolymorphicResourc
                     // takes no caller input. Its implementation already ignores the payload, but the
                     // dispatcher MERGES a prefix's return onto the caller payload rather than replacing
                     // it, so an unnarrowed contract is still writable. Omitting `requestDto` would
-                    // auto-derive the FULL subscription update DTO (`status`, `items`, `discount`,
+                    // auto-derive the FULL subscription update DTO (`status`, `items`, `discounts`,
                     // `currentPeriodEnd`, `cancelledAt`, …), letting a subscriber rewrite their own
                     // billing state through "resume".
                     requestDto: z.object({}),
@@ -303,6 +319,23 @@ export const billingSubscriptionsPolymorphicFactories = createPolymorphicResourc
                     idempotencyKey: ResourceOperationIdempotencyKeyRequirement.REQUIRED,
                 }],
         },
+        [BillingSubscription_Operations.CANCEL_PLAN_CHANGE]: {
+            variants: [{
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    polymorphicRole: {
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
+                    },
+                    riskLevel: ResourceOperationRiskLevel.MEDIUM,
+                    resourceOperationLike: CoreResourceOperation.UPDATE,
+                    // No caller input, for RESUME's reason: an omitted `requestDto` derives the full subscription update DTO.
+                    requestDto: z.object({}),
+                    // ACCEPTED, as RESUME: a repeat with the key replays the committed withdrawal, and a repeat without one converges at
+                    // the provider (a released schedule stays released).
+                    idempotencyKey: ResourceOperationIdempotencyKeyRequirement.ACCEPTED,
+                }],
+        },
     },
 });
 //# sourceMappingURL=subscription.shared.resources-config.schemas.js.map

package/dist/esm/billing/subscription.shared.resources-config.schemas.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"subscription.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/subscription.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n Subscription Resource Configuration — Polymorphic\n \n Produces 3 factory functions (one per scope variant) via the polymorphic factory.\n * Spread into the registry factory map:\n * ...billingSubscriptionsPolymorphicFactories\n \n @see polymorphic-scope-approach-A-expansion.md — Phase 3\n /\n\nimport { z } from 'zod';\nimport { CoreResourceOperation, CoreResourceType } from '../resources/resources.shared.core.definitions';\nimport {\n ResourceOperationRiskLevel,\n ResourceOperationVariantType,\n} from '../resources/resources.shared.schemas';\nimport { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';\nimport { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory';\nimport { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { billingSubscriptionsPolymorphicDeclaration } from './subscription.shared.schemas';\nimport { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas';\nimport { ResourceOperationIdempotencyKeyRequirement } from '../requests/idempotency-key.shared';\n\n// ── Custom Operations ────────────────────────────────────────────────\n\nexport enum BillingSubscription_Operations {\n /* Cancel the subscription (at period end or immediately) /\n CANCEL = 'cancel',\n /* Resume a cancelled subscription before period end /\n RESUME = 'resume',\n /* Change to a different plan (upgrade/downgrade) /\n CHANGE_PLAN = 'change_plan',\n /* Calculate a provider invoice estimate without changing the subscription. /\n PREVIEW_PLAN_CHANGE = 'preview_plan_change',\n /* Add an addon product to the subscription /\n ADD_ADDON = 'add_addon',\n /* Remove an addon product from the subscription /\n REMOVE_ADDON = 'remove_addon',\n}\n\n// ── Request DTOs ─────────────────────────────────────────────────────\n\n/* Request DTO for CANCEL operation — shared between resource config and custom impl /\nexport const BillingSubscription_CancelRequestDto = z.object({\n /\n OPTIONAL, with no default — and the absence of a default is the point (#408, 2026-09-08).\n \n It carried `.default(false)` until then, which materialized `false` at parse and made \"the\n * caller expressed no preference\" a state the handler could never observe. That erased the only\n * input `ProductBehaviorPolicy.cancellation.defaultBehavior` exists to answer, so an authored\n * product default was unimplementable rather than merely unimplemented — a field one layer up\n * had already decided for it.\n \n The resolution order is now: the caller's explicit choice, then the plan product's\n * `defaultBehavior`, then period-end as the framework floor. Omitting it still ends in period-end\n * for a product that authors no policy, so nothing changes for an existing caller — what changes\n * is that a product declaring IMMEDIATE now gets it.\n /\n cancelImmediately: z.boolean().optional(),\n reason: z.string().max(500).optional(),\n});\n\n/* Selection sent for a provider-computed preview; it does not authorize a change. /\nexport const BillingSubscription_PreviewPlanChangeRequestDto = z.object({\n newProductKey: z.string().min(1),\n newPriceId: z.string().min(1),\n});\n\n/* Confirmation must carry the server-issued preview bound to this exact selection. /\nexport const BillingSubscription_ChangePlanRequestDto = BillingSubscription_PreviewPlanChangeRequestDto.extend({\n previewToken: z.string().min(1).max(65_536),\n});\n\n/* Provider invoice estimate plus a short-lived confirmation binding; normal authorization still applies. /\nexport const BillingSubscription_PlanChangePreviewResponseDto = z.object({\n amount: z.number().int(),\n currency: z.string().min(1),\n lineItems: z.array(z.object({ description: z.string(), amount: z.number().int(), quantity: z.number() })),\n periodStart: z.coerce.date(),\n periodEnd: z.coerce.date(),\n /* Server-generated calculation instant, in Unix seconds. /\n prorationDate: z.number().int().nonnegative(),\n previewToken: z.string().min(1).max(65_536),\n});\n\n/* Request DTO for ADD_ADDON operation — shared between resource config and custom impl /\nexport const BillingSubscription_AddAddonRequestDto = z.object({\n addonProductKey: z.string().min(1),\n priceId: z.string().min(1),\n});\n\n/* Request DTO for REMOVE_ADDON operation — shared between resource config and custom impl /\nexport const BillingSubscription_RemoveAddonRequestDto = z.object({\n addonProductKey: z.string().min(1),\n});\n\n// =============================================================================\n// POLYMORPHIC FACTORY — 2 variants (org, user)\n// =============================================================================\n\n/\n Polymorphic factory map for subscriptions.\n * Spread into `coreShared_ResourcesConfigurations_FactoryMap`:\n * ...billingSubscriptionsPolymorphicFactories\n \n Produces entries for:\n * - organizationSubscriptions\n * - userSubscriptions\n /\nexport const billingSubscriptionsPolymorphicFactories = createPolymorphicResourceConfigurations(\n billingSubscriptionsPolymorphicDeclaration,\n {\n isSystemResource: true,\n // System-context LIST opt-in (fail-closed default is FORBIDDEN). Subject erasure enumerates the\n // erased person's live subscriptions so it can cancel them at the provider immediately — an\n // erased subject must stop being billed. There is no request context on that path (the subject\n // is being erased), so it reads through `SystemAccessBackendService.listAsSystem`, which refuses\n // any resource that has not opted in here. LIST's default variant is API_CALL and therefore\n // resolves through `getServiceOperationPathDefault`; a REPOSITORY_ONLY-only LIST would satisfy\n // this grant and still fail to resolve at erasure time.\n systemAccessPolicy: {\n // Subject-export disclosure. The subject's own subscriptions. Secrets and backend-only values are withheld by the export's security floor regardless of this grant. On a polymorphic resource this grant applies to EVERY generated variant, which is the documented intent of the shared config.\n exportSubject: ResourceSystemAccessMode.ALLOWED,\n list: ResourceSystemAccessMode.ALLOWED,\n },\n portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.OBSERVED },\n\n /\n Subject erasure RETAINS this row and scrubs nothing, because there is nothing here to scrub.\n \n `RETAIN_ONLY` is a positive ASSERTION that this resource holds no personal data of its own. The row is\n * subscription terms — plan and price references, status and period boundaries — amounts and contract terms about the ACCOUNT. They\n * describe nobody once the linked USER row is scrubbed, and they must survive erasure for the tax/audit\n * obligation this family exists to serve, so they can be neither scrubbed nor honestly declared as\n * personal data the row holds. The person is the scope foreign key, which the never-scrub floor protects.\n \n The assertion is CHECKED in both directions: the factory refuses `RETAIN_ONLY` if any field declares an\n * impersonalize treatment, and (since 2026-08-31) if any non-floor field declares `.dataCategories()`.\n /\n retentionPolicy: {\n mode: ErasureRetentionMode.RETAIN_ONLY,\n },\n\n /\n Erasing one of these rows revokes NO session. The row is not a person — its owner FK names the ACTOR the\n * record belongs to — and the enum prescribes `NO_PRINCIPAL` for exactly that shape. The subject's own\n * session ends through the `USERS` row, which is `SELF_PRINCIPAL`.\n /\n dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },\n customOperation: BillingSubscription_Operations,\n coreOperations: [\n CoreResourceOperation.READ,\n CoreResourceOperation.LIST,\n CoreResourceOperation.CREATE,\n CoreResourceOperation.UPDATE,\n // Route-less; `retentionPolicy` requires READ + LIST + UPDATE_MANY.\n CoreResourceOperation.UPDATE_MANY,\n ],\n operationsConfiguration: {\n /\n * Route-less retention plumbing — INTERNAL_CALL registers no route, so no API surface is added, and it\n * must not be REPOSITORY_ONLY: the retention primitives resolve through `getServiceOperationPathDefault`,\n * which matches only INTERNAL_CALL / API_CALL. LIST is LOW (a read-shaped op may not claim the\n * HIGH/CRITICAL band, which carries an audit-emission obligation); UPDATE_MANY is CRITICAL — it is the\n * verb the impersonalize writer uses to stamp the retention markers.\n */\n [CoreResourceOperation.UPDATE_MANY]: {\n variants: [{\n variantType: ResourceOperationVariantType.INTERNAL_CALL,\n isDefault: true,\n roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n riskLevel: ResourceOperationRiskLevel.CRITICAL,\n }],\n },\n\n [CoreResourceOperation.READ]: {\n variants: [{\n // API_CALL: subscriptions are a user-facing collection (Settings Hub → Billing →\n // Subscriptions, and the resource presets' LIST/READ views). REPOSITORY_ONLY would\n // strip the op from the frontend registry and register no HTTP route. Writes\n // (checkout + webhook sync) are INTERNAL_CALL (service-pipeline) / custom API_CALL ops.\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.LOW,\n }],\n },\n [CoreResourceOperation.LIST]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.LOW,\n }],\n },\n [CoreResourceOperation.CREATE]: {\n variants: [{\n variantType: ResourceOperationVariantType.INTERNAL_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.MEDIUM,\n }],\n },\n [CoreResourceOperation.UPDATE]: {\n variants: [{\n variantType: ResourceOperationVariantType.INTERNAL_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.MEDIUM,\n }],\n },\n [BillingSubscription_Operations.CANCEL]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.CRITICAL,\n auditableEvent: { reasonField: 'reason' },\n resourceOperationLike: CoreResourceOperation.UPDATE,\n requestDto: BillingSubscription_CancelRequestDto,\n // A caller may send an Idempotency-Key: a repeat with it replays the committed cancellation, and the same key with a\n // different request is refused (#535 S5a). Optional, because a repeat without one still converges at the provider.\n idempotencyKey: ResourceOperationIdempotencyKeyRequirement.ACCEPTED,\n }],\n },\n [BillingSubscription_Operations.RESUME]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.MEDIUM,\n resourceOperationLike: CoreResourceOperation.UPDATE,\n // RESUME clears a pending cancellation at the provider and mirrors the result — it\n // takes no caller input. Its implementation already ignores the payload, but the\n // dispatcher MERGES a prefix's return onto the caller payload rather than replacing\n // it, so an unnarrowed contract is still writable. Omitting `requestDto` would\n // auto-derive the FULL subscription update DTO (`status`, `items`, `discount`,\n // `currentPeriodEnd`, `cancelledAt`, …), letting a subscriber rewrite their own\n // billing state through \"resume\".\n requestDto: z.object({}),\n // A caller may send an Idempotency-Key: a repeat with it replays the committed resume, and the same key with a\n // different request is refused (#535 S5a).\n idempotencyKey: ResourceOperationIdempotencyKeyRequirement.ACCEPTED,\n }],\n },\n [BillingSubscription_Operations.PREVIEW_PLAN_CHANGE]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.LOW,\n resourceOperationLike: CoreResourceOperation.READ,\n requestDto: BillingSubscription_PreviewPlanChangeRequestDto,\n customResponseDto: BillingSubscription_PlanChangePreviewResponseDto,\n }],\n },\n [BillingSubscription_Operations.CHANGE_PLAN]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.HIGH,\n resourceOperationLike: CoreResourceOperation.UPDATE,\n requestDto: BillingSubscription_ChangePlanRequestDto,\n }],\n },\n [BillingSubscription_Operations.ADD_ADDON]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.HIGH,\n resourceOperationLike: CoreResourceOperation.UPDATE,\n requestDto: BillingSubscription_AddAddonRequestDto,\n // REQUIRED, not ACCEPTED (#535 S5b): repeating an addition is a second line and a second charge, so a retry after a lost\n // response must be recognizable as the same request. Every external caller sends the key and a repeat with it replays the\n // committed addition. Kept off MCP, whose tool calls carry no key (boot refuses REQUIRED on an exposed tool).\n idempotencyKey: ResourceOperationIdempotencyKeyRequirement.REQUIRED,\n }],\n },\n [BillingSubscription_Operations.REMOVE_ADDON]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.HIGH,\n resourceOperationLike: CoreResourceOperation.UPDATE,\n requestDto: BillingSubscription_RemoveAddonRequestDto,\n // REQUIRED (#535 S5b): a repeat after the removal committed no longer finds the add-on, so without a key a retry after a\n // lost response cannot learn that its removal succeeded. A repeat with the key replays the committed removal. Kept off MCP.\n idempotencyKey: ResourceOperationIdempotencyKeyRequirement.REQUIRED,\n }],\n },\n },\n },\n);\n"]}
1	+ {"version":3,"file":"subscription.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../src/billing/subscription.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AACzG,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,8CAA8C,CAAC;AACxF,OAAO,EAAE,yBAAyB,EAAE,MAAM,qDAAqD,CAAC;AAChG,OAAO,EAAE,uCAAuC,EAAE,MAAM,kDAAkD,CAAC;AAC3G,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iDAAiD,CAAC;AACjG,OAAO,EAAE,0CAA0C,EAAE,MAAM,+BAA+B,CAAC;AAC3F,OAAO,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,wDAAwD,CAAC;AACvH,OAAO,EAAE,0CAA0C,EAAE,MAAM,oCAAoC,CAAC;AAChG,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAE/D,wEAAwE;AAExE,MAAM,CAAN,IAAY,8BAkBX;AAlBD,WAAY,8BAA8B;IACxC,6DAA6D;IAC7D,mDAAiB,CAAA;IACjB,wDAAwD;IACxD,mDAAiB,CAAA;IACjB,qDAAqD;IACrD,6DAA2B,CAAA;IAC3B,+EAA+E;IAC/E,6EAA2C,CAAA;IAC3C,+CAA+C;IAC/C,yDAAuB,CAAA;IACvB,oDAAoD;IACpD,+DAA6B,CAAA;IAC7B;;;OAGG;IACH,2EAAyC,CAAA;AAC3C,CAAC,EAlBW,8BAA8B,KAA9B,8BAA8B,QAkBzC;AAED,wEAAwE;AAExE,wFAAwF;AACxF,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3D;;;;;;;;;;;;;OAaG;IACH,iBAAiB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kQAAkQ,CAAC;IACtT,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mHAAmH,CAAC;CACrK,CAAC,CAAC;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,+CAA+C,GAAG,CAAC,CAAC,MAAM,CAAC;IACtE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,sGAAsG,CAAC;IACjJ,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,+EAA+E,CAAC;CACxH,CAAC,CAAC;AAEH,uFAAuF;AACvF,MAAM,CAAC,MAAM,wCAAwC,GAAG,+CAA+C,CAAC,MAAM,CAAC;IAC7G,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,0LAA0L,CAAC;CACjP,CAAC,CAAC;AAEH,6GAA6G;AAC7G,MAAM,CAAC,MAAM,gDAAgD,GAAG,CAAC,CAAC,MAAM,CAAC;IACvE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,6IAA6I,CAAC;IAChL,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,iFAAiF,CAAC;IACvH,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;QAC1B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;QACnF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,qHAAqH,CAAC;QACxJ,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;KAClE,CAAC,CAAC,CAAC,QAAQ,CAAC,6EAA6E,CAAC;IAC3F,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;IAC1F,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,iDAAiD,CAAC;IACtF;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,QAAQ,CAAC,uPAAuP,CAAC;IAC/R,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,2IAA2I,CAAC;IAClL,6DAA6D;IAC7D,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,0HAA0H,CAAC;IAClL,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,+EAA+E,CAAC;CACtI,CAAC,CAAC;AAEH,2FAA2F;AAC3F,MAAM,CAAC,MAAM,sCAAsC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7D,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,4HAA4H,CAAC;IACzK,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,+EAA+E,CAAC;CACrH,CAAC,CAAC;AAEH,8FAA8F;AAC9F,MAAM,CAAC,MAAM,yCAAyC,GAAG,CAAC,CAAC,MAAM,CAAC;IAChE,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,4EAA4E,CAAC;CAC1H,CAAC,CAAC;AAEH,gFAAgF;AAChF,+CAA+C;AAC/C,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAAG,uCAAuC,CAC7F,0CAA0C,EAC1C;IACE,gBAAgB,EAAE,IAAI;IACtB,gGAAgG;IAChG,4FAA4F;IAC5F,+FAA+F;IAC/F,iGAAiG;IACjG,4FAA4F;IAC5F,+FAA+F;IAC/F,wDAAwD;IACxD,kBAAkB,EAAE;QAClB,kSAAkS;QAClS,aAAa,EAAE,wBAAwB,CAAC,OAAO;QAC/C,IAAI,EAAE,wBAAwB,CAAC,OAAO;KACvC;IACD,iBAAiB,EAAE,EAAE,iBAAiB,EAAE,yBAAyB,CAAC,QAAQ,EAAE;IAE5E;;;;;;;;;;;OAWG;IACH,eAAe,EAAE;QACf,IAAI,EAAE,oBAAoB,CAAC,WAAW;KACvC;IAED;;;;OAIG;IACH,iBAAiB,EAAE,EAAE,IAAI,EAAE,uBAAuB,CAAC,YAAY,EAAE;IACjE,eAAe,EAAE,8BAA8B;IAC/C,cAAc,EAAE;QACd,qBAAqB,CAAC,IAAI;QAC1B,qBAAqB,CAAC,IAAI;QAC1B,qBAAqB,CAAC,MAAM;QAC5B,qBAAqB,CAAC,MAAM;QAC5B,oEAAoE;QACpE,qBAAqB,CAAC,WAAW;KAClC;IACD,uBAAuB,EAAE;QACvB;;;;;;WAMG;QACH,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE;YACnC,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,aAAa;oBACvD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,qBAAqB,CAAC;oBAC7C,SAAS,EAAE,0BAA0B,CAAC,QAAQ;iBAC/C,CAAC;SACH;QAED,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE;YAC5B,QAAQ,EAAE,CAAC;oBACT,iFAAiF;oBACjF,mFAAmF;oBACnF,6EAA6E;oBAC7E,wFAAwF;oBACxF,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC;wBACtF,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC;qBACpD;oBACD,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C,CAAC;SACH;QACD,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE;YAC5B,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,2BAA2B,CAAC;wBAClI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,EAAE,cAAc,CAAC,2BAA2B,CAAC;qBAChG;oBACD,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C,CAAC;SACH;QACD,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE;YAC9B,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,aAAa;oBACvD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,2BAA2B,CAAC;wBAClI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,EAAE,cAAc,CAAC,2BAA2B,CAAC;qBAChG;oBACD,SAAS,EAAE,0BAA0B,CAAC,MAAM;iBAC7C,CAAC;SACH;QACD,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE;YAC9B,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,aAAa;oBACvD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,2BAA2B,CAAC;wBAClI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,EAAE,cAAc,CAAC,2BAA2B,CAAC;qBAChG;oBACD,SAAS,EAAE,0BAA0B,CAAC,MAAM;iBAC7C,CAAC;SACH;QACD,CAAC,8BAA8B,CAAC,MAAM,CAAC,EAAE;YACvC,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC;wBACtF,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC;qBACpD;oBACD,SAAS,EAAE,0BAA0B,CAAC,QAAQ;oBAC9C,cAAc,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE;oBACzC,qBAAqB,EAAE,qBAAqB,CAAC,MAAM;oBACnD,UAAU,EAAE,oCAAoC;oBAChD,qHAAqH;oBACrH,mHAAmH;oBACnH,cAAc,EAAE,0CAA0C,CAAC,QAAQ;iBACpE,CAAC;SACH;QACD,CAAC,8BAA8B,CAAC,MAAM,CAAC,EAAE;YACvC,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC;wBACtF,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC;qBACpD;oBACD,SAAS,EAAE,0BAA0B,CAAC,MAAM;oBAC5C,qBAAqB,EAAE,qBAAqB,CAAC,MAAM;oBACnD,mFAAmF;oBACnF,iFAAiF;oBACjF,oFAAoF;oBACpF,+EAA+E;oBAC/E,gFAAgF;oBAChF,gFAAgF;oBAChF,kCAAkC;oBAClC,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;oBACxB,+GAA+G;oBAC/G,2CAA2C;oBAC3C,cAAc,EAAE,0CAA0C,CAAC,QAAQ;iBACpE,CAAC;SACH;QACD,CAAC,8BAA8B,CAAC,mBAAmB,CAAC,EAAE;YACpD,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC;wBACtF,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC;qBACpD;oBACD,SAAS,EAAE,0BAA0B,CAAC,GAAG;oBACzC,qBAAqB,EAAE,qBAAqB,CAAC,IAAI;oBACjD,UAAU,EAAE,+CAA+C;oBAC3D,iBAAiB,EAAE,gDAAgD;iBACpE,CAAC;SACH;QACD,CAAC,8BAA8B,CAAC,WAAW,CAAC,EAAE;YAC5C,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC;wBACtF,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC;qBACpD;oBACD,SAAS,EAAE,0BAA0B,CAAC,IAAI;oBAC1C,qBAAqB,EAAE,qBAAqB,CAAC,MAAM;oBACnD,UAAU,EAAE,wCAAwC;iBACrD,CAAC;SACH;QACD,CAAC,8BAA8B,CAAC,SAAS,CAAC,EAAE;YAC1C,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC;wBACtF,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC;qBACpD;oBACD,SAAS,EAAE,0BAA0B,CAAC,IAAI;oBAC1C,qBAAqB,EAAE,qBAAqB,CAAC,MAAM;oBACnD,UAAU,EAAE,sCAAsC;oBAClD,yHAAyH;oBACzH,0HAA0H;oBAC1H,8GAA8G;oBAC9G,cAAc,EAAE,0CAA0C,CAAC,QAAQ;iBACpE,CAAC;SACH;QACD,CAAC,8BAA8B,CAAC,YAAY,CAAC,EAAE;YAC7C,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC;wBACtF,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC;qBACpD;oBACD,SAAS,EAAE,0BAA0B,CAAC,IAAI;oBAC1C,qBAAqB,EAAE,qBAAqB,CAAC,MAAM;oBACnD,UAAU,EAAE,yCAAyC;oBACrD,yHAAyH;oBACzH,4HAA4H;oBAC5H,cAAc,EAAE,0CAA0C,CAAC,QAAQ;iBACpE,CAAC;SACH;QACD,CAAC,8BAA8B,CAAC,kBAAkB,CAAC,EAAE;YACnD,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,SAAS,EAAE,IAAI;oBACf,eAAe,EAAE;wBACf,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC;wBACtF,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC;qBACpD;oBACD,SAAS,EAAE,0BAA0B,CAAC,MAAM;oBAC5C,qBAAqB,EAAE,qBAAqB,CAAC,MAAM;oBACnD,0GAA0G;oBAC1G,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;oBACxB,qHAAqH;oBACrH,qDAAqD;oBACrD,cAAc,EAAE,0CAA0C,CAAC,QAAQ;iBACpE,CAAC;SACH;KACF;CACF,CACF,CAAC","sourcesContent":["/*\n Subscription Resource Configuration — Polymorphic\n \n Produces 3 factory functions (one per scope variant) via the polymorphic factory.\n * Spread into the registry factory map:\n * ...billingSubscriptionsPolymorphicFactories\n \n @see polymorphic-scope-approach-A-expansion.md — Phase 3\n /\n\nimport { z } from 'zod';\nimport { CoreResourceOperation, CoreResourceType } from '../resources/resources.shared.core.definitions';\nimport {\n ResourceOperationRiskLevel,\n ResourceOperationVariantType,\n} from '../resources/resources.shared.schemas';\nimport { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';\nimport { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory';\nimport { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { billingSubscriptionsPolymorphicDeclaration } from './subscription.shared.schemas';\nimport { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas';\nimport { ResourceOperationIdempotencyKeyRequirement } from '../requests/idempotency-key.shared';\nimport { BillingTiming } from './billing-enums.shared.schemas';\n\n// ── Custom Operations ────────────────────────────────────────────────\n\nexport enum BillingSubscription_Operations {\n /* Cancel the subscription (at period end or immediately) /\n CANCEL = 'cancel',\n /* Resume a cancelled subscription before period end /\n RESUME = 'resume',\n /* Change to a different plan (upgrade/downgrade) /\n CHANGE_PLAN = 'change_plan',\n /* Calculate a provider invoice estimate without changing the subscription. /\n PREVIEW_PLAN_CHANGE = 'preview_plan_change',\n /* Add an addon product to the subscription /\n ADD_ADDON = 'add_addon',\n /* Remove an addon product from the subscription /\n REMOVE_ADDON = 'remove_addon',\n /\n Withdraw a plan change that was confirmed to take effect at the end of the current period (#1868): the provider's schedule\n * is released and the subscription's `pendingPlanChange` cleared, so the subscription renews on its current plan.\n /\n CANCEL_PLAN_CHANGE = 'cancel_plan_change',\n}\n\n// ── Request DTOs ─────────────────────────────────────────────────────\n\n/* Request DTO for CANCEL operation — shared between resource config and custom impl /\nexport const BillingSubscription_CancelRequestDto = z.object({\n /\n OPTIONAL, with no default — and the absence of a default is the point (#408, 2026-09-08).\n \n It carried `.default(false)` until then, which materialized `false` at parse and made \"the\n * caller expressed no preference\" a state the handler could never observe. That erased the only\n * input `ProductBehaviorPolicy.cancellation.defaultBehavior` exists to answer, so an authored\n * product default was unimplementable rather than merely unimplemented — a field one layer up\n * had already decided for it.\n \n The resolution order is now: the caller's explicit choice, then the plan product's\n * `defaultBehavior`, then period-end as the framework floor. Omitting it still ends in period-end\n * for a product that authors no policy, so nothing changes for an existing caller — what changes\n * is that a product declaring IMMEDIATE now gets it.\n /\n cancelImmediately: z.boolean().optional().describe(\"`true` ends the subscription now, `false` at the end of the current billing period. When omitted, the plan's default cancellation timing applies, then the application's, then period end. An immediate cancellation is refused when the plan does not allow it.\"),\n reason: z.string().max(500).optional().describe(\"Why the subscription is being cancelled, kept on the subscription and in the audit trail. At most 500 characters.\"),\n});\n\n/* Selection sent for a provider-computed preview; it does not authorize a change. /\nexport const BillingSubscription_PreviewPlanChangeRequestDto = z.object({\n newProductKey: z.string().min(1).describe(\"The key of the plan to move the subscription onto. It must be a plan that is available for purchase.\"),\n newPriceId: z.string().min(1).describe(\"The id of the price to bill the new plan at. It must be a price of that plan.\"),\n});\n\n/* Confirmation must carry the server-issued preview bound to this exact selection. /\nexport const BillingSubscription_ChangePlanRequestDto = BillingSubscription_PreviewPlanChangeRequestDto.extend({\n previewToken: z.string().min(1).max(65_536).describe(\"The `previewToken` from a plan-change preview for the same subscription, plan and price. It is valid for 10 minutes, and is refused when the subscription has changed since the preview.\"),\n});\n\n/* Provider invoice estimate plus a short-lived confirmation binding; normal authorization still applies. /\nexport const BillingSubscription_PlanChangePreviewResponseDto = z.object({\n amount: z.number().int().describe(\"The amount due on the previewed invoice, in the currency's smallest unit (such as cents). An estimate, not necessarily an immediate charge.\"),\n currency: z.string().min(1).describe(\"The currency of the amounts, as the billing provider reports it, such as `usd`.\"),\n lineItems: z.array(z.object({\n description: z.string().describe(\"The billing provider's description of the line.\"),\n amount: z.number().int().describe(\"The line's amount, in the currency's smallest unit. Negative for a credit, such as unused time on the current plan.\"),\n quantity: z.number().describe(\"The quantity billed on the line.\"),\n })).describe(\"The lines of the previewed invoice, including any proration for the change.\"),\n periodStart: z.coerce.date().describe(\"Start of the period the previewed invoice covers.\"),\n periodEnd: z.coerce.date().describe(\"End of the period the previewed invoice covers.\"),\n /\n When the change would take effect, decided by the new plan's `behaviorPolicy` (#1868). For `at_period_end` the previewed\n * invoice is the one at renewal, on the new plan, with no proration: nothing is charged on confirmation.\n /\n timing: z.enum(BillingTiming).describe(\"When the change takes effect if confirmed: `immediate` (now, and the previewed invoice includes any proration) or `at_period_end` (at renewal; the previewed invoice is the renewal invoice on the new plan, and nothing is charged on confirmation).\"),\n effectiveAt: z.coerce.date().describe(\"When the change takes effect if confirmed: now for an immediate change, the end of the current billing period for a change at period end.\"),\n /* Server-generated calculation instant, in Unix seconds. /\n prorationDate: z.number().int().nonnegative().describe(\"When the estimate was calculated, in Unix seconds. A prorated change is charged as of this instant when it is confirmed.\"),\n previewToken: z.string().min(1).max(65_536).describe(\"Send this back as `previewToken` to confirm the change. Valid for 10 minutes.\"),\n});\n\n/* Request DTO for ADD_ADDON operation — shared between resource config and custom impl /\nexport const BillingSubscription_AddAddonRequestDto = z.object({\n addonProductKey: z.string().min(1).describe(\"The key of the add-on product to add. It must be an add-on available for purchase, and allowed on the subscription's plan.\"),\n priceId: z.string().min(1).describe(\"The id of the price to bill the add-on at. It must be a price of that add-on.\"),\n});\n\n/* Request DTO for REMOVE_ADDON operation — shared between resource config and custom impl /\nexport const BillingSubscription_RemoveAddonRequestDto = z.object({\n addonProductKey: z.string().min(1).describe(\"The key of the add-on product to remove. The subscription must include it.\"),\n});\n\n// =============================================================================\n// POLYMORPHIC FACTORY — 2 variants (org, user)\n// =============================================================================\n\n/\n Polymorphic factory map for subscriptions.\n * Spread into `coreShared_ResourcesConfigurations_FactoryMap`:\n * ...billingSubscriptionsPolymorphicFactories\n \n Produces entries for:\n * - organizationSubscriptions\n * - userSubscriptions\n /\nexport const billingSubscriptionsPolymorphicFactories = createPolymorphicResourceConfigurations(\n billingSubscriptionsPolymorphicDeclaration,\n {\n isSystemResource: true,\n // System-context LIST opt-in (fail-closed default is FORBIDDEN). Subject erasure enumerates the\n // erased person's live subscriptions so it can cancel them at the provider immediately — an\n // erased subject must stop being billed. There is no request context on that path (the subject\n // is being erased), so it reads through `SystemAccessBackendService.listAsSystem`, which refuses\n // any resource that has not opted in here. LIST's default variant is API_CALL and therefore\n // resolves through `getServiceOperationPathDefault`; a REPOSITORY_ONLY-only LIST would satisfy\n // this grant and still fail to resolve at erasure time.\n systemAccessPolicy: {\n // Subject-export disclosure. The subject's own subscriptions. Secrets and backend-only values are withheld by the export's security floor regardless of this grant. On a polymorphic resource this grant applies to EVERY generated variant, which is the documented intent of the shared config.\n exportSubject: ResourceSystemAccessMode.ALLOWED,\n list: ResourceSystemAccessMode.ALLOWED,\n },\n portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.OBSERVED },\n\n /\n Subject erasure RETAINS this row and scrubs nothing, because there is nothing here to scrub.\n \n `RETAIN_ONLY` is a positive ASSERTION that this resource holds no personal data of its own. The row is\n * subscription terms — plan and price references, status and period boundaries — amounts and contract terms about the ACCOUNT. They\n * describe nobody once the linked USER row is scrubbed, and they must survive erasure for the tax/audit\n * obligation this family exists to serve, so they can be neither scrubbed nor honestly declared as\n * personal data the row holds. The person is the scope foreign key, which the never-scrub floor protects.\n \n The assertion is CHECKED in both directions: the factory refuses `RETAIN_ONLY` if any field declares an\n * impersonalize treatment, and (since 2026-08-31) if any non-floor field declares `.dataCategories()`.\n /\n retentionPolicy: {\n mode: ErasureRetentionMode.RETAIN_ONLY,\n },\n\n /\n Erasing one of these rows revokes NO session. The row is not a person — its owner FK names the ACTOR the\n * record belongs to — and the enum prescribes `NO_PRINCIPAL` for exactly that shape. The subject's own\n * session ends through the `USERS` row, which is `SELF_PRINCIPAL`.\n /\n dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },\n customOperation: BillingSubscription_Operations,\n coreOperations: [\n CoreResourceOperation.READ,\n CoreResourceOperation.LIST,\n CoreResourceOperation.CREATE,\n CoreResourceOperation.UPDATE,\n // Route-less; `retentionPolicy` requires READ + LIST + UPDATE_MANY.\n CoreResourceOperation.UPDATE_MANY,\n ],\n operationsConfiguration: {\n /\n * Route-less retention plumbing — INTERNAL_CALL registers no route, so no API surface is added, and it\n * must not be REPOSITORY_ONLY: the retention primitives resolve through `getServiceOperationPathDefault`,\n * which matches only INTERNAL_CALL / API_CALL. LIST is LOW (a read-shaped op may not claim the\n * HIGH/CRITICAL band, which carries an audit-emission obligation); UPDATE_MANY is CRITICAL — it is the\n * verb the impersonalize writer uses to stamp the retention markers.\n */\n [CoreResourceOperation.UPDATE_MANY]: {\n variants: [{\n variantType: ResourceOperationVariantType.INTERNAL_CALL,\n isDefault: true,\n roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n riskLevel: ResourceOperationRiskLevel.CRITICAL,\n }],\n },\n\n [CoreResourceOperation.READ]: {\n variants: [{\n // API_CALL: subscriptions are a user-facing collection (Settings Hub → Billing →\n // Subscriptions, and the resource presets' LIST/READ views). REPOSITORY_ONLY would\n // strip the op from the frontend registry and register no HTTP route. Writes\n // (checkout + webhook sync) are INTERNAL_CALL (service-pipeline) / custom API_CALL ops.\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.LOW,\n }],\n },\n [CoreResourceOperation.LIST]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],\n },\n riskLevel: ResourceOperationRiskLevel.LOW,\n }],\n },\n [CoreResourceOperation.CREATE]: {\n variants: [{\n variantType: ResourceOperationVariantType.INTERNAL_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],\n },\n riskLevel: ResourceOperationRiskLevel.MEDIUM,\n }],\n },\n [CoreResourceOperation.UPDATE]: {\n variants: [{\n variantType: ResourceOperationVariantType.INTERNAL_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],\n },\n riskLevel: ResourceOperationRiskLevel.MEDIUM,\n }],\n },\n [BillingSubscription_Operations.CANCEL]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.CRITICAL,\n auditableEvent: { reasonField: 'reason' },\n resourceOperationLike: CoreResourceOperation.UPDATE,\n requestDto: BillingSubscription_CancelRequestDto,\n // A caller may send an Idempotency-Key: a repeat with it replays the committed cancellation, and the same key with a\n // different request is refused (#535 S5a). Optional, because a repeat without one still converges at the provider.\n idempotencyKey: ResourceOperationIdempotencyKeyRequirement.ACCEPTED,\n }],\n },\n [BillingSubscription_Operations.RESUME]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.MEDIUM,\n resourceOperationLike: CoreResourceOperation.UPDATE,\n // RESUME clears a pending cancellation at the provider and mirrors the result — it\n // takes no caller input. Its implementation already ignores the payload, but the\n // dispatcher MERGES a prefix's return onto the caller payload rather than replacing\n // it, so an unnarrowed contract is still writable. Omitting `requestDto` would\n // auto-derive the FULL subscription update DTO (`status`, `items`, `discounts`,\n // `currentPeriodEnd`, `cancelledAt`, …), letting a subscriber rewrite their own\n // billing state through \"resume\".\n requestDto: z.object({}),\n // A caller may send an Idempotency-Key: a repeat with it replays the committed resume, and the same key with a\n // different request is refused (#535 S5a).\n idempotencyKey: ResourceOperationIdempotencyKeyRequirement.ACCEPTED,\n }],\n },\n [BillingSubscription_Operations.PREVIEW_PLAN_CHANGE]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.LOW,\n resourceOperationLike: CoreResourceOperation.READ,\n requestDto: BillingSubscription_PreviewPlanChangeRequestDto,\n customResponseDto: BillingSubscription_PlanChangePreviewResponseDto,\n }],\n },\n [BillingSubscription_Operations.CHANGE_PLAN]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.HIGH,\n resourceOperationLike: CoreResourceOperation.UPDATE,\n requestDto: BillingSubscription_ChangePlanRequestDto,\n }],\n },\n [BillingSubscription_Operations.ADD_ADDON]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.HIGH,\n resourceOperationLike: CoreResourceOperation.UPDATE,\n requestDto: BillingSubscription_AddAddonRequestDto,\n // REQUIRED, not ACCEPTED (#535 S5b): repeating an addition is a second line and a second charge, so a retry after a lost\n // response must be recognizable as the same request. Every external caller sends the key and a repeat with it replays the\n // committed addition. Kept off MCP, whose tool calls carry no key (boot refuses REQUIRED on an exposed tool).\n idempotencyKey: ResourceOperationIdempotencyKeyRequirement.REQUIRED,\n }],\n },\n [BillingSubscription_Operations.REMOVE_ADDON]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.HIGH,\n resourceOperationLike: CoreResourceOperation.UPDATE,\n requestDto: BillingSubscription_RemoveAddonRequestDto,\n // REQUIRED (#535 S5b): a repeat after the removal committed no longer finds the add-on, so without a key a retry after a\n // lost response cannot learn that its removal succeeded. A repeat with the key replays the committed removal. Kept off MCP.\n idempotencyKey: ResourceOperationIdempotencyKeyRequirement.REQUIRED,\n }],\n },\n [BillingSubscription_Operations.CANCEL_PLAN_CHANGE]: {\n variants: [{\n variantType: ResourceOperationVariantType.API_CALL,\n isDefault: true,\n polymorphicRole: {\n [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n },\n riskLevel: ResourceOperationRiskLevel.MEDIUM,\n resourceOperationLike: CoreResourceOperation.UPDATE,\n // No caller input, for RESUME's reason: an omitted `requestDto` derives the full subscription update DTO.\n requestDto: z.object({}),\n // ACCEPTED, as RESUME: a repeat with the key replays the committed withdrawal, and a repeat without one converges at\n // the provider (a released schedule stays released).\n idempotencyKey: ResourceOperationIdempotencyKeyRequirement.ACCEPTED,\n }],\n },\n },\n },\n);\n"]}

package/dist/esm/billing/subscription.shared.schemas.d.ts CHANGED Viewed

@@ -15,7 +15,7 @@
  */
 import { z } from 'zod';
 import '@wildo-ai/zod-decorators';
-import { SubscriptionStatus } from './billing-enums.shared.schemas';
+import { PromotionDuration, SubscriptionStatus } from './billing-enums.shared.schemas';
 /**
  * A line item within a subscription (one product/price pair).
  */
@@ -27,6 +27,55 @@ export declare const SubscriptionItemSchema: z.ZodObject<{
     providerSubscriptionItemId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>;
 export type SubscriptionItem = z.infer<typeof SubscriptionItemSchema>;
+/**
+ * One line of the items a pending plan change will give the subscription (#1868). Unlike a {@link SubscriptionItemSchema}
+ * line it carries the provider price: at renewal the provider's lines are matched to these by price and quantity, and a
+ * changed line has no provider item id until the provider creates it.
+ */
+export declare const PendingPlanChangeItemSchema: z.ZodObject<{
+    _id: z.ZodString;
+    productId: z.ZodString;
+    priceId: z.ZodString;
+    quantity: z.ZodNumber;
+    providerPriceId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+}, z.core.$strip>;
+export type PendingPlanChangeItem = z.infer<typeof PendingPlanChangeItemSchema>;
+/**
+ * A plan change confirmed to take effect at the end of the current period (#1868): the plan the subscription moves to,
+ * when, and the lines it will then carry. Present from the confirmation until renewal applies it — then the subscription's
+ * `items` become these lines and this is cleared — or until the change is cancelled.
+ */
+export declare const PendingPlanChangeSchema: z.ZodObject<{
+    productId: z.ZodString;
+    priceId: z.ZodString;
+    effectiveAt: z.ZodDate;
+    items: z.ZodArray<z.ZodObject<{
+        _id: z.ZodString;
+        productId: z.ZodString;
+        priceId: z.ZodString;
+        quantity: z.ZodNumber;
+        providerPriceId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+    }, z.core.$strip>>;
+    providerScheduleId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
+}, z.core.$strip>;
+export type PendingPlanChange = z.infer<typeof PendingPlanChangeSchema>;
+/**
+ * How long before a pending plan change's `effectiveAt` it stops being withdrawable (#1868).
+ *
+ * The provider moves the subscription onto the new lines at renewal, and releasing its schedule after that keeps them: a withdrawal then
+ * would clear the pending change while the provider bills the new plan. The provider refuses a release once the next phase has begun,
+ * but reading the phase and releasing are two calls. Refusing a few minutes early covers that window and any clock skew between the
+ * engine and the provider, and it covers the time between renewal and the local realization, when the change is still recorded as
+ * pending but has already happened. One value: the operation refuses by it, and a frontend withholds the action by it.
+ */
+export declare const PLAN_CHANGE_WITHDRAWAL_CUTOFF_MS: number;
+/**
+ * Whether a pending plan change's renewal is still far enough off for it to be withdrawn at `now`. Time only: the backend also refuses a
+ * change recorded with no schedule, which a client cannot see (`providerScheduleId` is backend-only).
+ */
+export declare function isPendingPlanChangeWithdrawable(pending: {
+    effectiveAt: Date | string;
+}, now?: Date): boolean;
 /**
  * Subscription base schema — NO identity scope fields.
  * The polymorphic declaration injects the parent scope FK automatically per variant.
@@ -50,14 +99,27 @@ export declare const BillingSubscriptionBaseSchema: z.ZodObject<{
     cancelAtPeriodEnd: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>;
     cancelledAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>;
     cancellationReason: z.ZodOptional<z.ZodString>;
-    discount: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodObject<{
+    discounts: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodArray<z.ZodObject<{
         providerCouponId: z.ZodOptional<z.ZodString>;
         percentOff: z.ZodOptional<z.ZodNumber>;
         amountOff: z.ZodOptional<z.ZodNumber>;
         currency: z.ZodOptional<z.ZodString>;
-        duration: z.ZodOptional<z.ZodString>;
+        duration: z.ZodOptional<z.ZodEnum<typeof PromotionDuration>>;
         durationInMonths: z.ZodOptional<z.ZodNumber>;
         end: z.ZodOptional<z.ZodDate>;
+    }, z.core.$strip>>>>;
+    pendingPlanChange: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodObject<{
+        productId: z.ZodString;
+        priceId: z.ZodString;
+        effectiveAt: z.ZodDate;
+        items: z.ZodArray<z.ZodObject<{
+            _id: z.ZodString;
+            productId: z.ZodString;
+            priceId: z.ZodString;
+            quantity: z.ZodNumber;
+            providerPriceId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+        }, z.core.$strip>>;
+        providerScheduleId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
     }, z.core.$strip>>>;
     providerSubscriptionId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -93,14 +155,27 @@ export declare const billingSubscriptionsPolymorphicDeclaration: import("..").Po
     cancelAtPeriodEnd: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>;
     cancelledAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>;
     cancellationReason: z.ZodOptional<z.ZodString>;
-    discount: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodObject<{
+    discounts: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodArray<z.ZodObject<{
         providerCouponId: z.ZodOptional<z.ZodString>;
         percentOff: z.ZodOptional<z.ZodNumber>;
         amountOff: z.ZodOptional<z.ZodNumber>;
         currency: z.ZodOptional<z.ZodString>;
-        duration: z.ZodOptional<z.ZodString>;
+        duration: z.ZodOptional<z.ZodEnum<typeof PromotionDuration>>;
         durationInMonths: z.ZodOptional<z.ZodNumber>;
         end: z.ZodOptional<z.ZodDate>;
+    }, z.core.$strip>>>>;
+    pendingPlanChange: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodObject<{
+        productId: z.ZodString;
+        priceId: z.ZodString;
+        effectiveAt: z.ZodDate;
+        items: z.ZodArray<z.ZodObject<{
+            _id: z.ZodString;
+            productId: z.ZodString;
+            priceId: z.ZodString;
+            quantity: z.ZodNumber;
+            providerPriceId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>;
+        }, z.core.$strip>>;
+        providerScheduleId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
     }, z.core.$strip>>>;
     providerSubscriptionId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;

package/dist/esm/billing/subscription.shared.schemas.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"subscription.shared.schemas.d.ts","sourceRoot":"","sources":["~~../../../../~~src/billing/subscription.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,0BAA0B,CAAC;AAGlC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;~~AAIpE~~;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;;iBAUjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;~~AAItE~~;;;;GAIG;AACH,eAAO,MAAM,6BAA6B~~;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0ExC~~,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAIpF;;;;;;;;;GASG;AACH,eAAO,MAAM,0CAA0C~~;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;~~kBAQrD,CAAC"}
1	+ {"version":3,"file":"subscription.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/subscription.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,0BAA0B,CAAC;AAGlC,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAIvF;;GAEG;AACH,eAAO,MAAM,sBAAsB;;;;;;iBAUjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;iBAMtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;iBAMlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,QAAgB,CAAC;AAE9D;;;GAGG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE;IAAE,WAAW,EAAE,IAAI,GAAG,MAAM,CAAA;CAAE,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAExH;AAID;;;;GAIG;AACH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8FxC,CAAC;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAIpF;;;;;;;;;GASG;AACH,eAAO,MAAM,0CAA0C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAQrD,CAAC"}

package/dist/esm/billing/subscription.shared.schemas.js CHANGED Viewed

@@ -19,7 +19,7 @@ import { z } from 'zod';
 import '@wildo-ai/zod-decorators';
 import { declarePolymorphicSchemas, optOutPolymorphicAutoBusinessKey } from '../resources/utils/resource-polymorphism.schemas.js';
 import { BILLING_SCOPE_VARIANTS, BILLING_SCOPE_FK_VARIANTS } from './billing-account.shared.schemas.js';
-import { SubscriptionStatus } from './billing-enums.shared.schemas.js';
+import { PromotionDuration, SubscriptionStatus } from './billing-enums.shared.schemas.js';
 // ── Subscription Item ──────────────────────────────────────────────
 /**
  * A line item within a subscription (one product/price pair).
@@ -27,14 +27,55 @@ import { SubscriptionStatus } from './billing-enums.shared.schemas.js';
 export const SubscriptionItemSchema = z.object({
     _id: z.string().min(1).isPrimaryKey(),
     /** Reference to the product */
-    productId: z.string().min(1).isForeignKey().isSummaryField({ populate: true }),
+    productId: z.string().min(1).isForeignKey().isSummaryField({ populate: true }).describe("The id of the product this line bills for: the plan, or an add-on."),
     /** Reference to the specific price */
-    priceId: z.string().min(1).isForeignKey().isSummaryField({ populate: true }),
+    priceId: z.string().min(1).isForeignKey().isSummaryField({ populate: true }).describe("The id of the price this line is billed at. It belongs to the line's product."),
     /** Quantity (e.g., number of seats) */
-    quantity: z.number().min(1).default(1).isSummaryField(),
+    quantity: z.number().min(1).default(1).isSummaryField().describe("How many units of the price are billed, such as seats. Defaults to 1."),
     /** Provider sync */
     providerSubscriptionItemId: z.string().optional().isBackendOnly(),
 });
+/**
+ * One line of the items a pending plan change will give the subscription (#1868). Unlike a {@link SubscriptionItemSchema}
+ * line it carries the provider price: at renewal the provider's lines are matched to these by price and quantity, and a
+ * changed line has no provider item id until the provider creates it.
+ */
+export const PendingPlanChangeItemSchema = z.object({
+    _id: z.string().min(1).describe("The line's id: the current line's id when the line carries over, a new id when the change adds it."),
+    productId: z.string().min(1).describe("The id of the product this line will bill for."),
+    priceId: z.string().min(1).describe("The id of the price this line will be billed at."),
+    quantity: z.number().min(1).describe("How many units of the price will be billed."),
+    providerPriceId: z.string().min(1).isBackendOnly(),
+});
+/**
+ * A plan change confirmed to take effect at the end of the current period (#1868): the plan the subscription moves to,
+ * when, and the lines it will then carry. Present from the confirmation until renewal applies it — then the subscription's
+ * `items` become these lines and this is cleared — or until the change is cancelled.
+ */
+export const PendingPlanChangeSchema = z.object({
+    productId: z.string().min(1).describe("The id of the plan the subscription moves to."),
+    priceId: z.string().min(1).describe("The id of the price the subscription moves to."),
+    effectiveAt: z.date().describe("When the change takes effect: the end of the billing period in which it was confirmed."),
+    items: z.array(PendingPlanChangeItemSchema).min(1).describe("The lines the subscription will carry once the change takes effect: the new plan and the add-ons that carry over."),
+    providerScheduleId: z.string().optional().isBackendOnly(),
+});
+/**
+ * How long before a pending plan change's `effectiveAt` it stops being withdrawable (#1868).
+ *
+ * The provider moves the subscription onto the new lines at renewal, and releasing its schedule after that keeps them: a withdrawal then
+ * would clear the pending change while the provider bills the new plan. The provider refuses a release once the next phase has begun,
+ * but reading the phase and releasing are two calls. Refusing a few minutes early covers that window and any clock skew between the
+ * engine and the provider, and it covers the time between renewal and the local realization, when the change is still recorded as
+ * pending but has already happened. One value: the operation refuses by it, and a frontend withholds the action by it.
+ */
+export const PLAN_CHANGE_WITHDRAWAL_CUTOFF_MS = 5 * 60 * 1000;
+/**
+ * Whether a pending plan change's renewal is still far enough off for it to be withdrawn at `now`. Time only: the backend also refuses a
+ * change recorded with no schedule, which a client cannot see (`providerScheduleId` is backend-only).
+ */
+export function isPendingPlanChangeWithdrawable(pending, now = new Date()) {
+    return now.getTime() < new Date(pending.effectiveAt).getTime() - PLAN_CHANGE_WITHDRAWAL_CUTOFF_MS;
+}
 // ── Subscription Base Schema ───────────────────────────────────────
 /**
  * Subscription base schema — NO identity scope fields.
@@ -44,7 +85,7 @@ export const SubscriptionItemSchema = z.object({
 export const BillingSubscriptionBaseSchema = z.object({
     _id: z.string().min(1).isPrimaryKey().isSummaryField(),
     /** References the parent billing account (polymorphic FK — renamed per variant) */
-    billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed().isSummaryField(),
+    billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed().isSummaryField().describe("The id of the billing account this subscription belongs to."),
     // `.isAuditEvidence()` — subscription status is the ENTITLEMENT gate: the feature resolver
     // derives a scope's capabilities from it, so a transition to/from ACTIVE silently widens or
     // narrows what the tenant may do. Recording the before/after states makes an entitlement
@@ -62,27 +103,46 @@ export const BillingSubscriptionBaseSchema = z.object({
     // value must survive erasure for the tax/audit obligation this family exists to serve — so it can be
     // neither scrubbed nor honestly declared as personal data the row holds. See `retentionPolicy` on the
     // resource config (#138).
-    items: z.array(SubscriptionItemSchema).min(1),
+    items: z.array(SubscriptionItemSchema).min(1).describe("What the subscription bills for: one line for the plan and one for each add-on."),
     /** Period */
-    currentPeriodStart: z.date().isDBIndexed().isNotEditable(),
-    currentPeriodEnd: z.date().isDBIndexed().isSummaryField().isNotEditable(),
-    /** Trial */
-    trialStart: z.date().optional().isNotEditable(),
-    trialEnd: z.date().optional().isSummaryField().isNotEditable(),
+    currentPeriodStart: z.date().isDBIndexed().isNotEditable().describe("When the current billing period started, as the billing provider reports it."),
+    currentPeriodEnd: z.date().isDBIndexed().isSummaryField().isNotEditable().describe("When the current billing period ends, as the billing provider reports it. The subscription renews then, or ends if `cancelAtPeriodEnd` is set."),
+    /**
+     * Trial — copied from the billing provider (#1798). Nothing wrote either before, so every subscription
+     * reported no trial whatever the provider held. Both are kept after the trial is over: they describe
+     * the subscription's trial, and `status` says whether it is trialing now.
+     */
+    trialStart: z.date().optional().isNotEditable().describe("When the subscription's trial began, as the billing provider reports it. Absent when the subscription never had a trial."),
+    trialEnd: z.date().optional().isSummaryField().isNotEditable().describe("When the subscription's trial ends, or ended, as the billing provider reports it. Kept after the trial is over; `status` says whether the subscription is trialing now."),
     /** Cancellation */
-    cancelAtPeriodEnd: z.boolean().default(false).isSummaryField(),
-    cancelledAt: z.date().optional().isNotEditable(),
-    cancellationReason: z.string().optional(),
-    /** Active discount from a coupon/promotion applied to this subscription (populated from provider) */
-    discount: z.object({
-        providerCouponId: z.string().optional(),
-        percentOff: z.number().optional(),
-        amountOff: z.number().optional(),
-        currency: z.string().optional(),
-        duration: z.string().optional(),
-        durationInMonths: z.number().optional(),
-        end: z.date().optional(),
-    }).optional().isNotEditable(),
+    cancelAtPeriodEnd: z.boolean().default(false).isSummaryField().describe("Whether the subscription is set to end when the current billing period ends. Set by a cancellation at period end, cleared by resuming, and kept in step with the billing provider."),
+    cancelledAt: z.date().optional().isNotEditable().describe("When the subscription was cancelled through the cancel operation, whether it ended immediately or at period end. Cleared when a scheduled cancellation is resumed."),
+    cancellationReason: z.string().optional().describe("The reason given when the subscription was cancelled, if one was given. Cleared when a scheduled cancellation is resumed."),
+    /**
+     * The discounts the billing provider applies to this subscription, in the order it applies them (#1798, #1948).
+     * Copied from the provider by every provider event and the reconciliation sweep; absent when none applies, including
+     * after the last one ends.
+     *
+     * A LIST, because a subscription can carry several at once: a referral reward is added BESIDE a promotion code the
+     * checkout applied (#1802), and the provider charges both. This was one `discount`, which showed the first and hid the
+     * rest, so a customer was told about one discount and billed for two. Order is kept because it is the order the
+     * provider applies them in, and a percentage taken after a fixed amount is a different price from the reverse.
+     */
+    discounts: z.array(z.object({
+        providerCouponId: z.string().optional().describe("The billing provider's id for the coupon behind the discount."),
+        percentOff: z.number().optional().describe("The percentage taken off, for a percentage discount."),
+        amountOff: z.number().optional().describe("The amount taken off each invoice, in minor units of `currency`, for a fixed-amount discount."),
+        currency: z.string().optional().describe("The ISO 4217 currency of `amountOff`, upper-case."),
+        duration: z.enum(PromotionDuration).optional().describe("How long the discount applies: `once` (the first invoice), `repeating` (for `durationInMonths`) or `forever`."),
+        durationInMonths: z.number().optional().describe("For a `repeating` discount, how many months it applies."),
+        end: z.date().optional().describe("When the discount stops applying, if it ends."),
+    })).optional().isNotEditable().describe("The discounts the billing provider applies to this subscription, in the order it applies them. Absent when none applies, including after the last one ends."),
+    /**
+     * A plan change that takes effect at the end of the current period (#1868): written by a CHANGE_PLAN confirmation whose
+     * plan's policy says `at_period_end`, cleared when renewal applies it (the provider projection then writes `items`) or when
+     * CANCEL_PLAN_CHANGE withdraws it. While it is present the subscription's other changes are refused until it is withdrawn.
+     */
+    pendingPlanChange: PendingPlanChangeSchema.optional().isNotEditable().describe("A plan change confirmed to take effect at the end of the current period, with the plan, the date and the lines it will then carry. Absent when no change is pending."),
     /** Provider sync (payment methods are managed entirely by provider) */
     providerSubscriptionId: z.string().optional().isBackendOnly(),
     /**
@@ -104,7 +164,7 @@ export const BillingSubscriptionBaseSchema = z.object({
      * hide/freeze to become separable from scrub — a real capability change with no current consumer.
      * Revisit only if an app is found using the bag this way.
      */
-    metadata: z.record(z.string(), z.string()).optional(),
+    metadata: z.record(z.string(), z.string()).optional().describe("String tags the application's own code may attach to the subscription. Do not store personal data here: this record is kept when its owner is erased."),
     createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
     updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
 });