@wildo-ai/saas-models 1.1.5 → 1.1.6

package/dist/esm/billing/referral.shared.resources-config.schemas.js

@@ -3,17 +3,39 @@
  *
  * Operational: referral tracking between billing accounts.
  */
+import { z } from 'zod';
 import { createResourceConfiguration_Initialization } from '../resources/resources-config.shared.factory.js';
 import { CoreResourceOperation, CoreResourceType, coreResourceShared_FieldIdentifier } from '../resources/resources.shared.core.definitions.js';
 import { ResourceOperationRiskLevel, ResourceOperationVariantType, } from '../resources/resources.shared.schemas.js';
 import { CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas.js';
+import { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas.js';
 import { ReferralSchema } from './referral.shared.schemas.js';
+/**
+ * The referral program's own verbs (#1802). The lifecycle's other steps have no route: a code is redeemed
+ * from the REDEEMING account (`BillingAccount_Operations.REDEEM_REFERRAL`), and conversion happens when that
+ * account pays its first invoice.
+ */
+export var Referral_Operations;
+(function (Referral_Operations) {
+    /** Issue a single-use referral code for the organization's billing account. */
+    Referral_Operations["ISSUE"] = "issue";
+    /** Withdraw a referral that has not converted. */
+    Referral_Operations["CANCEL"] = "cancel";
+})(Referral_Operations || (Referral_Operations = {}));
+/** ISSUE takes nothing: the referrer is the organization's own billing account, and the rewards are server policy. */
+export const Referral_IssueRequestDto = z.strictObject({});
+/** CANCEL takes nothing: the referral in the path is the one withdrawn. */
+export const Referral_CancelRequestDto = z.strictObject({});
 export const referralsResourceConfiguration_InitializationFactory = (resourcesRelationships) => createResourceConfiguration_Initialization({
     mainSchema: ReferralSchema,
     resourceIdentifier: CoreResourceType.REFERRALS,
     resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.REFERRALS],
     resourceRelationships: resourcesRelationships,
     isSystemResource: true,
+    // The referral program (#1802) writes the row it issues as the system: the owner asked for a code, and the row's
+    // rewards, code and status are server-set. Its scope FK is the routed organization, carried on the data.
+    systemAccessPolicy: { create: ResourceSystemAccessMode.ALLOWED },
+    customOperation: Referral_Operations,
     coreOperations: [
         CoreResourceOperation.READ,
         CoreResourceOperation.LIST,
@@ -47,8 +69,13 @@ export const referralsResourceConfiguration_InitializationFactory = (resourcesRe
                      * entry existed and every request 404'd at the ROUTER.
                      *
                      * `ORG_OWNER` matches that destination's own `requiredRoles` exactly. The resource is
-                     * ORGANIZATIONS-scoped, so the contextual filter confines the answer to the caller's own
-                     * tenant — this door shows an owner their own referrals and nobody else's.
+                     * ORGANIZATIONS-scoped and routed under the organization (`/organizations/{organizationId}/referrals`),
+                     * so the contextual filter confines the answer to the caller's own tenant — this door shows an
+                     * owner their own referrals and nobody else's.
+                     *
+                     * The route only exists since 2026-09-28. Adding this variant fixed the 404 but not the page: the
+                     * ORGANIZATIONS edge was then a STANDALONE anchor, so the route mounted at `/api/v1/referrals`,
+                     * carried no organization, and every request answered 403. See the edge in the core registry.
                      */
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
@@ -73,6 +100,33 @@ export const referralsResourceConfiguration_InitializationFactory = (resourcesRe
                     riskLevel: ResourceOperationRiskLevel.LOW,
                 }],
         },
+        /*
+         * #1802 — an organization owner issues a code for the organization's billing account. The rewards it
+         * carries are copied from `billing.referrals` and never taken from the request, which is why the request
+         * DTO is empty and strict. MEDIUM: a code promises the application's money (credits, discounts) to
+         * whoever redeems it.
+         */
+        [Referral_Operations.ISSUE]: {
+            variants: [{
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [CORE_ORG_ROLES.ORG_OWNER],
+                    riskLevel: ResourceOperationRiskLevel.MEDIUM,
+                    resourceOperationLike: CoreResourceOperation.CREATE,
+                    requestDto: Referral_IssueRequestDto,
+                }],
+        },
+        /** #1802 — the owner withdraws a PENDING or ACCEPTED referral; a converted one has been paid out and stays. */
+        [Referral_Operations.CANCEL]: {
+            variants: [{
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [CORE_ORG_ROLES.ORG_OWNER],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                    resourceOperationLike: CoreResourceOperation.UPDATE,
+                    requestDto: Referral_CancelRequestDto,
+                }],
+        },
     },
 });
 //# sourceMappingURL=referral.shared.resources-config.schemas.js.map

package/dist/esm/billing/referral.shared.resources-config.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"referral.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/referral.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,0CAA0C,EAAE,MAAM,8CAA8C,CAAC;AAC1G,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,kCAAkC,EAAE,MAAM,gDAAgD,CAAC;AAC7I,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,GAE7B,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,iDAAiD,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAQ3D,MAAM,CAAC,MAAM,oDAAoD,GAAG,CAClE,sBAA8C,EAC9C,EAAE,CAAC,0CAA0C,CAI7C;IACA,UAAU,EAAE,cAAc;IAC1B,kBAAkB,EAAE,gBAAgB,CAAC,SAAS;IAC9C,uBAAuB,EAAE,kCAAkC,CAAC,gBAAgB,CAAC,SAAS,CAAC;IACvF,qBAAqB,EAAE,sBAAsB;IAC7C,gBAAgB,EAAE,IAAI;IACtB,cAAc,EAAE;QACd,qBAAqB,CAAC,IAAI;QAC1B,qBAAqB,CAAC,IAAI;QAC1B,qBAAqB,CAAC,MAAM;QAC5B,qBAAqB,CAAC,MAAM;KAC7B;IACD,uBAAuB,EAAE;QACvB,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE;YAC5B,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,aAAa;oBACvD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;oBACjC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C,CAAC;SACH;QACD,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE;YAC5B,QAAQ,EAAE;gBACV;oBACE,WAAW,EAAE,4BAA4B,CAAC,aAAa;oBACvD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;oBACjC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C;gBACD;oBACE;;;;;;;;;;;uBAWG;oBACH,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;oBACjC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C;aACA;SACF;QACD,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE;YAC9B,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,aAAa;oBACvD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;oBACjC,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,KAAK,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;oBACjC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C,CAAC;SACH;KACF;CACF,CAAC,CAAC","sourcesContent":["/**\n * Referral Resource Configuration\n *\n * Operational: referral tracking between billing accounts.\n */\n\nimport { createResourceConfiguration_Initialization } from '../resources/resources-config.shared.factory';\nimport { CoreResourceOperation, CoreResourceType, coreResourceShared_FieldIdentifier } from '../resources/resources.shared.core.definitions';\nimport {\n  ResourceOperationRiskLevel,\n  ResourceOperationVariantType,\n  ResourceRelationship,\n} from '../resources/resources.shared.schemas';\nimport { CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { ReferralSchema } from './referral.shared.schemas';\n\ntype ReferralsCoreOps =\n  | CoreResourceOperation.READ\n  | CoreResourceOperation.LIST\n  | CoreResourceOperation.CREATE\n  | CoreResourceOperation.UPDATE;\n\nexport const referralsResourceConfiguration_InitializationFactory = (\n  resourcesRelationships: ResourceRelationship[]\n) => createResourceConfiguration_Initialization<\n  undefined,\n  ReferralsCoreOps,\n  typeof ReferralSchema\n>({\n  mainSchema: ReferralSchema,\n  resourceIdentifier: CoreResourceType.REFERRALS,\n  resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.REFERRALS],\n  resourceRelationships: resourcesRelationships,\n  isSystemResource: true,\n  coreOperations: [\n    CoreResourceOperation.READ,\n    CoreResourceOperation.LIST,\n    CoreResourceOperation.CREATE,\n    CoreResourceOperation.UPDATE,\n  ],\n  operationsConfiguration: {\n    [CoreResourceOperation.READ]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      }],\n    },\n    [CoreResourceOperation.LIST]: {\n      variants: [\n      {\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      },\n      {\n        /*\n         * The TENANT's door onto its own referrals — added 2026-09-18 for issue #1295.\n         *\n         * The `INTERNAL_CALL` variant above is route-less and stays the DEFAULT, so the billing\n         * back-office's service-pipeline reads are untouched. The `organization-referrals` settings\n         * destination targets this operation and could never load: no route was mounted, so the rail\n         * entry existed and every request 404'd at the ROUTER.\n         *\n         * `ORG_OWNER` matches that destination's own `requiredRoles` exactly. The resource is\n         * ORGANIZATIONS-scoped, so the contextual filter confines the answer to the caller's own\n         * tenant — this door shows an owner their own referrals and nobody else's.\n         */\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      },\n      ],\n    },\n    [CoreResourceOperation.CREATE]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      }],\n    },\n    [CoreResourceOperation.UPDATE]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      }],\n    },\n  },\n});\n"]}
+{"version":3,"file":"referral.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/referral.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Referral Resource Configuration\n *\n * Operational: referral tracking between billing accounts.\n */\n\nimport { z } from 'zod';\nimport { createResourceConfiguration_Initialization } from '../resources/resources-config.shared.factory';\nimport { CoreResourceOperation, CoreResourceType, coreResourceShared_FieldIdentifier } from '../resources/resources.shared.core.definitions';\nimport {\n  ResourceOperationRiskLevel,\n  ResourceOperationVariantType,\n  ResourceRelationship,\n} from '../resources/resources.shared.schemas';\nimport { CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { ReferralSchema } from './referral.shared.schemas';\n\n/**\n * The referral program's own verbs (#1802). The lifecycle's other steps have no route: a code is redeemed\n * from the REDEEMING account (`BillingAccount_Operations.REDEEM_REFERRAL`), and conversion happens when that\n * account pays its first invoice.\n */\nexport enum Referral_Operations {\n  /** Issue a single-use referral code for the organization's billing account. */\n  ISSUE = 'issue',\n  /** Withdraw a referral that has not converted. */\n  CANCEL = 'cancel',\n}\n\n/** ISSUE takes nothing: the referrer is the organization's own billing account, and the rewards are server policy. */\nexport const Referral_IssueRequestDto = z.strictObject({});\n\n/** CANCEL takes nothing: the referral in the path is the one withdrawn. */\nexport const Referral_CancelRequestDto = z.strictObject({});\n\ntype ReferralsCoreOps =\n  | CoreResourceOperation.READ\n  | CoreResourceOperation.LIST\n  | CoreResourceOperation.CREATE\n  | CoreResourceOperation.UPDATE;\n\nexport const referralsResourceConfiguration_InitializationFactory = (\n  resourcesRelationships: ResourceRelationship[]\n) => createResourceConfiguration_Initialization<\n  typeof Referral_Operations,\n  ReferralsCoreOps,\n  typeof ReferralSchema\n>({\n  mainSchema: ReferralSchema,\n  resourceIdentifier: CoreResourceType.REFERRALS,\n  resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.REFERRALS],\n  resourceRelationships: resourcesRelationships,\n  isSystemResource: true,\n  // The referral program (#1802) writes the row it issues as the system: the owner asked for a code, and the row's\n  // rewards, code and status are server-set. Its scope FK is the routed organization, carried on the data.\n  systemAccessPolicy: { create: ResourceSystemAccessMode.ALLOWED },\n  customOperation: Referral_Operations,\n  coreOperations: [\n    CoreResourceOperation.READ,\n    CoreResourceOperation.LIST,\n    CoreResourceOperation.CREATE,\n    CoreResourceOperation.UPDATE,\n  ],\n  operationsConfiguration: {\n    [CoreResourceOperation.READ]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      }],\n    },\n    [CoreResourceOperation.LIST]: {\n      variants: [\n      {\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      },\n      {\n        /*\n         * The TENANT's door onto its own referrals — added 2026-09-18 for issue #1295.\n         *\n         * The `INTERNAL_CALL` variant above is route-less and stays the DEFAULT, so the billing\n         * back-office's service-pipeline reads are untouched. The `organization-referrals` settings\n         * destination targets this operation and could never load: no route was mounted, so the rail\n         * entry existed and every request 404'd at the ROUTER.\n         *\n         * `ORG_OWNER` matches that destination's own `requiredRoles` exactly. The resource is\n         * ORGANIZATIONS-scoped and routed under the organization (`/organizations/{organizationId}/referrals`),\n         * so the contextual filter confines the answer to the caller's own tenant — this door shows an\n         * owner their own referrals and nobody else's.\n         *\n         * The route only exists since 2026-09-28. Adding this variant fixed the 404 but not the page: the\n         * ORGANIZATIONS edge was then a STANDALONE anchor, so the route mounted at `/api/v1/referrals`,\n         * carried no organization, and every request answered 403. See the edge in the core registry.\n         */\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      },\n      ],\n    },\n    [CoreResourceOperation.CREATE]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      }],\n    },\n    [CoreResourceOperation.UPDATE]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      }],\n    },\n    /*\n     * #1802 — an organization owner issues a code for the organization's billing account. The rewards it\n     * carries are copied from `billing.referrals` and never taken from the request, which is why the request\n     * DTO is empty and strict. MEDIUM: a code promises the application's money (credits, discounts) to\n     * whoever redeems it.\n     */\n    [Referral_Operations.ISSUE]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.MEDIUM,\n        resourceOperationLike: CoreResourceOperation.CREATE,\n        requestDto: Referral_IssueRequestDto,\n      }],\n    },\n    /** #1802 — the owner withdraws a PENDING or ACCEPTED referral; a converted one has been paid out and stays. */\n    [Referral_Operations.CANCEL]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n        resourceOperationLike: CoreResourceOperation.UPDATE,\n        requestDto: Referral_CancelRequestDto,\n      }],\n    },\n  },\n});\n"]}

package/dist/esm/billing/referral.shared.schemas.d.ts

@@ -1,39 +1,19 @@
 /**
- * Referral Schema (Shared)
+ * Referral Schema (Shared) — one single-use referral code, from one referrer to one referred account (#1802).
  *
- * Scope-agnostic referral tracking. Links a referrer billing account
- * to a referred billing account, with reward configuration.
- *
- * Referral flow:
- * 1. Referrer shares a referral link (contains referralCode)
- * 2. Referred user signs up and creates a billing account
- * 3. ReferralSchema is created with status: PENDING
- * 4. On referred user's first subscription: status → CONVERTED
- * 5. Rewards are applied to both parties
- *
- * @see billing-and-features-system.md §10 (Referrals)
+ * The lifecycle, and who moves it:
+ * 1. PENDING — an organization's billing account issues the code (`ISSUE`). The rewards are
+ *    copied from the application's `billing.referrals` policy at that moment, never taken from the caller.
+ * 2. ACCEPTED — another billing account redeems the code (`REDEEM_REFERRAL`) before `expiresAt`. It must
+ *    be a new customer: never subscribed, not already referred, and not the referrer.
+ * 3. CONVERTED — the referred account's first paid invoice. Both sides' rewards are granted once each,
+ *    and `referrerRewardApplied` / `referredRewardApplied` record the delivery.
+ * EXPIRED — a code redeemed after `expiresAt` is refused and marked so. CANCELLED — the referrer
+ * withdrew a PENDING or ACCEPTED referral.
  */
 import { z } from 'zod';
 import '@wildo-ai/zod-decorators';
-import { BillingScopeType, ReferralStatus, ReferrerRewardType, ReferredRewardType } from './billing-enums.shared.schemas';
-export declare const ReferrerRewardSchema: z.ZodObject<{
-    type: z.ZodEnum<typeof ReferrerRewardType>;
-    value: z.ZodNumber;
-    creditPoolKey: z.ZodOptional<z.ZodString>;
-    featureKey: z.ZodOptional<z.ZodString>;
-    durationDays: z.ZodOptional<z.ZodNumber>;
-    commissionPercentage: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-export type ReferrerReward = z.infer<typeof ReferrerRewardSchema>;
-export declare const ReferredRewardSchema: z.ZodObject<{
-    type: z.ZodEnum<typeof ReferredRewardType>;
-    value: z.ZodNumber;
-    creditPoolKey: z.ZodOptional<z.ZodString>;
-    featureKey: z.ZodOptional<z.ZodString>;
-    durationDays: z.ZodOptional<z.ZodNumber>;
-    trialExtensionDays: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>;
-export type ReferredReward = z.infer<typeof ReferredRewardSchema>;
+import { BillingScopeType, ReferralStatus } from './billing-enums.shared.schemas';
 export declare const ReferralSchema: z.ZodObject<{
     _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     referrerBillingAccountId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
@@ -43,20 +23,25 @@ export declare const ReferralSchema: z.ZodObject<{
     referralCode: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;
     status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodEnum<typeof ReferralStatus>>>>;
     referrerReward: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodObject<{
-        type: z.ZodEnum<typeof ReferrerRewardType>;
-        value: z.ZodNumber;
+        credits: z.ZodOptional<z.ZodNumber>;
         creditPoolKey: z.ZodOptional<z.ZodString>;
         featureKey: z.ZodOptional<z.ZodString>;
         durationDays: z.ZodOptional<z.ZodNumber>;
-        commissionPercentage: z.ZodOptional<z.ZodNumber>;
+        percentOff: z.ZodOptional<z.ZodNumber>;
+        discountDuration: z.ZodOptional<z.ZodEnum<typeof import("./billing-enums.shared.schemas").PromotionDuration>>;
+        discountDurationInMonths: z.ZodOptional<z.ZodNumber>;
+        type: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodEnum<typeof import("./billing-enums.shared.schemas").ReferrerRewardType>>;
     }, z.core.$strip>>>;
     referredReward: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodObject<{
-        type: z.ZodEnum<typeof ReferredRewardType>;
-        value: z.ZodNumber;
+        trialExtensionDays: z.ZodOptional<z.ZodNumber>;
+        credits: z.ZodOptional<z.ZodNumber>;
         creditPoolKey: z.ZodOptional<z.ZodString>;
         featureKey: z.ZodOptional<z.ZodString>;
         durationDays: z.ZodOptional<z.ZodNumber>;
-        trialExtensionDays: z.ZodOptional<z.ZodNumber>;
+        percentOff: z.ZodOptional<z.ZodNumber>;
+        discountDuration: z.ZodOptional<z.ZodEnum<typeof import("./billing-enums.shared.schemas").PromotionDuration>>;
+        discountDurationInMonths: z.ZodOptional<z.ZodNumber>;
+        type: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodEnum<typeof import("./billing-enums.shared.schemas").ReferredRewardType>>;
     }, z.core.$strip>>>;
     referrerRewardApplied: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>;
     referredRewardApplied: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>;

package/dist/esm/billing/referral.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"referral.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/referral.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,0BAA0B,CAAC;AAElC,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,gCAAgC,CAAC;AAKxC,eAAO,MAAM,oBAAoB;;;;;;;iBAY/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,oBAAoB;;;;;;;iBAQ/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAIlE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoEzB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}
+{"version":3,"file":"referral.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/referral.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,0BAA0B,CAAC;AAElC,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAMlF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAwEzB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/esm/billing/referral.shared.schemas.js

@@ -1,48 +1,24 @@
 /**
- * Referral Schema (Shared)
+ * Referral Schema (Shared) — one single-use referral code, from one referrer to one referred account (#1802).
  *
- * Scope-agnostic referral tracking. Links a referrer billing account
- * to a referred billing account, with reward configuration.
- *
- * Referral flow:
- * 1. Referrer shares a referral link (contains referralCode)
- * 2. Referred user signs up and creates a billing account
- * 3. ReferralSchema is created with status: PENDING
- * 4. On referred user's first subscription: status → CONVERTED
- * 5. Rewards are applied to both parties
- *
- * @see billing-and-features-system.md §10 (Referrals)
+ * The lifecycle, and who moves it:
+ * 1. PENDING — an organization's billing account issues the code (`ISSUE`). The rewards are
+ *    copied from the application's `billing.referrals` policy at that moment, never taken from the caller.
+ * 2. ACCEPTED — another billing account redeems the code (`REDEEM_REFERRAL`) before `expiresAt`. It must
+ *    be a new customer: never subscribed, not already referred, and not the referrer.
+ * 3. CONVERTED — the referred account's first paid invoice. Both sides' rewards are granted once each,
+ *    and `referrerRewardApplied` / `referredRewardApplied` record the delivery.
+ * EXPIRED — a code redeemed after `expiresAt` is refused and marked so. CANCELLED — the referrer
+ * withdrew a PENDING or ACCEPTED referral.
  */
 import { z } from 'zod';
 // Side-effect import: this module calls `.systemEnum()` at load, so the decorators must be installed first —
 // never by the importer's luck (#966). A named import used only as a type would be elided and install nothing.
 import '@wildo-ai/zod-decorators';
 import { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas.js';
-import { BillingScopeType, ReferralStatus, ReferrerRewardType, ReferredRewardType, } from './billing-enums.shared.schemas.js';
+import { BillingScopeType, ReferralStatus } from './billing-enums.shared.schemas.js';
+import { ReferredRewardSchema, ReferrerRewardSchema } from './referral-reward.shared.schemas.js';
 import { BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS } from './billing-account.shared.schemas.js';
-// ── Reward Definitions ──────────────────────────────────────────
-export const ReferrerRewardSchema = z.object({
-    type: z.enum(ReferrerRewardType),
-    /** Credit amount (for CREDIT type), discount percentage (for DISCOUNT), etc. */
-    value: z.number().min(0),
-    /** Credit pool key (for CREDIT type) */
-    creditPoolKey: z.string().optional(),
-    /** Feature key (for FEATURE type) */
-    featureKey: z.string().optional(),
-    /** Duration in days (for temporary rewards) */
-    durationDays: z.number().min(1).optional(),
-    /** Commission percentage (for COMMISSION type) */
-    commissionPercentage: z.number().min(0).max(100).optional(),
-});
-export const ReferredRewardSchema = z.object({
-    type: z.enum(ReferredRewardType),
-    value: z.number().min(0),
-    creditPoolKey: z.string().optional(),
-    featureKey: z.string().optional(),
-    durationDays: z.number().min(1).optional(),
-    /** Trial extension in days (for TRIAL_EXTENSION type) */
-    trialExtensionDays: z.number().min(1).optional(),
-});
 // ── Referral ────────────────────────────────────────────────────
 export const ReferralSchema = z.object({
     _id: z.string().min(1).isPrimaryKey().isSummaryField(),
@@ -85,17 +61,21 @@ export const ReferralSchema = z.object({
     /** Current status */
     status: z.enum(ReferralStatus).isDBIndexed().isSummaryField().systemEnum('ReferralStatus'),
     // ── Rewards ──
-    /** What the referrer gets when referral converts */
-    referrerReward: ReferrerRewardSchema.optional().isNotEditable(),
-    /** What the referred user gets */
-    referredReward: ReferredRewardSchema.optional().isNotEditable(),
-    /** Whether rewards have been applied */
-    referrerRewardApplied: z.boolean().default(false).isNotEditable(),
-    referredRewardApplied: z.boolean().default(false).isNotEditable(),
+    /** What the referrer receives on conversion — copied from `billing.referrals` when the code is issued. */
+    referrerReward: ReferrerRewardSchema.optional().isNotEditable().describe('What the referrer receives when the referral converts, copied from the application\'s referral policy when the code was issued. Absent when the policy gives the referrer nothing.'),
+    /** What the referred account receives — copied the same way. */
+    referredReward: ReferredRewardSchema.optional().isNotEditable().describe('What the referred account receives, copied from the application\'s referral policy when the code was issued. Absent when the policy gives it nothing.'),
+    /**
+     * Whether each side's reward was delivered. Set once the grant has landed: a credit top-up, a
+     * discount on the account's subscription, or a feature grant starting. A discount waiting for the
+     * account to have an active subscription leaves it `false` until then.
+     */
+    referrerRewardApplied: z.boolean().default(false).isNotEditable().describe('Whether the referrer\'s reward has been delivered.'),
+    referredRewardApplied: z.boolean().default(false).isNotEditable().describe('Whether the referred account\'s reward has been delivered.'),
     // ── Dates ──
     /** When the referred user accepted the referral */
     acceptedAt: z.date().optional().isNotEditable(),
-    /** When the referred user converted (first subscription) */
+    /** When the referral converted: the referred account's first paid invoice with money on it. */
     convertedAt: z.date().optional().isSummaryField().isNotEditable(),
     /** When the referral expires */
     expiresAt: z.date().optional().isDBIndexed().isSummaryField(),

package/dist/esm/billing/referral.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"referral.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/referral.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Referral Schema (Shared)\n *\n * Scope-agnostic referral tracking. Links a referrer billing account\n * to a referred billing account, with reward configuration.\n *\n * Referral flow:\n * 1. Referrer shares a referral link (contains referralCode)\n * 2. Referred user signs up and creates a billing account\n * 3. ReferralSchema is created with status: PENDING\n * 4. On referred user's first subscription: status → CONVERTED\n * 5. Rewards are applied to both parties\n *\n * @see billing-and-features-system.md §10 (Referrals)\n */\n\nimport { z } from 'zod';\n// Side-effect import: this module calls `.systemEnum()` at load, so the decorators must be installed first —\n// never by the importer's luck (#966). A named import used only as a type would be elided and install nothing.\nimport '@wildo-ai/zod-decorators';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport {\n  BillingScopeType,\n  ReferralStatus,\n  ReferrerRewardType,\n  ReferredRewardType,\n} from './billing-enums.shared.schemas';\nimport { BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS } from './billing-account.shared.schemas';\n\n// ── Reward Definitions ──────────────────────────────────────────\n\nexport const ReferrerRewardSchema = z.object({\n  type: z.enum(ReferrerRewardType),\n  /** Credit amount (for CREDIT type), discount percentage (for DISCOUNT), etc. */\n  value: z.number().min(0),\n  /** Credit pool key (for CREDIT type) */\n  creditPoolKey: z.string().optional(),\n  /** Feature key (for FEATURE type) */\n  featureKey: z.string().optional(),\n  /** Duration in days (for temporary rewards) */\n  durationDays: z.number().min(1).optional(),\n  /** Commission percentage (for COMMISSION type) */\n  commissionPercentage: z.number().min(0).max(100).optional(),\n});\nexport type ReferrerReward = z.infer<typeof ReferrerRewardSchema>;\n\nexport const ReferredRewardSchema = z.object({\n  type: z.enum(ReferredRewardType),\n  value: z.number().min(0),\n  creditPoolKey: z.string().optional(),\n  featureKey: z.string().optional(),\n  durationDays: z.number().min(1).optional(),\n  /** Trial extension in days (for TRIAL_EXTENSION type) */\n  trialExtensionDays: z.number().min(1).optional(),\n});\nexport type ReferredReward = z.infer<typeof ReferredRewardSchema>;\n\n// ── Referral ────────────────────────────────────────────────────\n\nexport const ReferralSchema = z.object({\n\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /**\n   * The billing account that created the referral.\n   *\n   * Per-record DISCRIMINATED polymorphic FK: it references EITHER a\n   * `userBillingAccounts` or an `organizationBillingAccounts` record, chosen per\n   * record by the sibling `referrerScopeType`. Resolution/display/links consult\n   * the discriminator (via {@link BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS}); the\n   * single-valued registry FK→type map only holds a NON-AUTHORITATIVE\n   * representative for this field.\n   */\n  referrerBillingAccountId: z.string().min(1).isForeignKey({\n    polymorphicVariants: BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS,\n    polymorphicDiscriminatorField: 'referrerScopeType',\n  }).isDBIndexed().isSummaryField(),\n  /** Scope type of the referrer's billing account — the discriminator that selects the polymorphic billing-account branch for `referrerBillingAccountId`. */\n  referrerScopeType: z.enum(BillingScopeType).isDBIndexed(),\n  /**\n   * The billing account that was referred (set when they sign up).\n   *\n   * Per-record DISCRIMINATED polymorphic FK like `referrerBillingAccountId`,\n   * with the branch chosen by the sibling `referredScopeType`.\n   */\n  referredBillingAccountId: z.string().optional().isForeignKey({\n    polymorphicVariants: BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS,\n    polymorphicDiscriminatorField: 'referredScopeType',\n  }).isDBIndexed(),\n  /** Scope type of the referred billing account (set together with referredBillingAccountId) — the discriminator that selects the branch for `referredBillingAccountId`. */\n  referredScopeType: z.enum(BillingScopeType).optional().isDBIndexed(),\n\n  /** Unique referral code (shared by referrer) */\n  // USAGE — a referral records that one account introduced another, and when both are USER-scoped\n  // billing accounts that is a social link between two people. The code itself is the identifier the\n  // link is made through. Declared even though the resource is scope-polymorphic, for the same\n  // reason as the billing family: an org variant at worst over-reports, a missing declaration\n  // silently under-reports.\n  referralCode: z.string().min(1).isUnique({ scope: 'global' }).isDBIndexed().isSummaryField()\n    .dataCategories(PersonalDataCategory.USAGE),\n\n  /** Current status */\n  status: z.enum(ReferralStatus).isDBIndexed().isSummaryField().systemEnum('ReferralStatus'),\n\n  // ── Rewards ──\n\n  /** What the referrer gets when referral converts */\n  referrerReward: ReferrerRewardSchema.optional().isNotEditable(),\n  /** What the referred user gets */\n  referredReward: ReferredRewardSchema.optional().isNotEditable(),\n\n  /** Whether rewards have been applied */\n  referrerRewardApplied: z.boolean().default(false).isNotEditable(),\n  referredRewardApplied: z.boolean().default(false).isNotEditable(),\n\n  // ── Dates ──\n\n  /** When the referred user accepted the referral */\n  acceptedAt: z.date().optional().isNotEditable(),\n  /** When the referred user converted (first subscription) */\n  convertedAt: z.date().optional().isSummaryField().isNotEditable(),\n  /** When the referral expires */\n  expiresAt: z.date().optional().isDBIndexed().isSummaryField(),\n\n  metadata: z.record(z.string(), z.string()).optional(),\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type Referral = z.infer<typeof ReferralSchema>;\n"]}
+{"version":3,"file":"referral.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/referral.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Referral Schema (Shared) — one single-use referral code, from one referrer to one referred account (#1802).\n *\n * The lifecycle, and who moves it:\n * 1. PENDING — an organization's billing account issues the code (`ISSUE`). The rewards are\n *    copied from the application's `billing.referrals` policy at that moment, never taken from the caller.\n * 2. ACCEPTED — another billing account redeems the code (`REDEEM_REFERRAL`) before `expiresAt`. It must\n *    be a new customer: never subscribed, not already referred, and not the referrer.\n * 3. CONVERTED — the referred account's first paid invoice. Both sides' rewards are granted once each,\n *    and `referrerRewardApplied` / `referredRewardApplied` record the delivery.\n * EXPIRED — a code redeemed after `expiresAt` is refused and marked so. CANCELLED — the referrer\n * withdrew a PENDING or ACCEPTED referral.\n */\n\nimport { z } from 'zod';\n// Side-effect import: this module calls `.systemEnum()` at load, so the decorators must be installed first —\n// never by the importer's luck (#966). A named import used only as a type would be elided and install nothing.\nimport '@wildo-ai/zod-decorators';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { BillingScopeType, ReferralStatus } from './billing-enums.shared.schemas';\nimport { ReferredRewardSchema, ReferrerRewardSchema } from './referral-reward.shared.schemas';\nimport { BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS } from './billing-account.shared.schemas';\n\n// ── Referral ────────────────────────────────────────────────────\n\nexport const ReferralSchema = z.object({\n\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /**\n   * The billing account that created the referral.\n   *\n   * Per-record DISCRIMINATED polymorphic FK: it references EITHER a\n   * `userBillingAccounts` or an `organizationBillingAccounts` record, chosen per\n   * record by the sibling `referrerScopeType`. Resolution/display/links consult\n   * the discriminator (via {@link BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS}); the\n   * single-valued registry FK→type map only holds a NON-AUTHORITATIVE\n   * representative for this field.\n   */\n  referrerBillingAccountId: z.string().min(1).isForeignKey({\n    polymorphicVariants: BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS,\n    polymorphicDiscriminatorField: 'referrerScopeType',\n  }).isDBIndexed().isSummaryField(),\n  /** Scope type of the referrer's billing account — the discriminator that selects the polymorphic billing-account branch for `referrerBillingAccountId`. */\n  referrerScopeType: z.enum(BillingScopeType).isDBIndexed(),\n  /**\n   * The billing account that was referred (set when they sign up).\n   *\n   * Per-record DISCRIMINATED polymorphic FK like `referrerBillingAccountId`,\n   * with the branch chosen by the sibling `referredScopeType`.\n   */\n  referredBillingAccountId: z.string().optional().isForeignKey({\n    polymorphicVariants: BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS,\n    polymorphicDiscriminatorField: 'referredScopeType',\n  }).isDBIndexed(),\n  /** Scope type of the referred billing account (set together with referredBillingAccountId) — the discriminator that selects the branch for `referredBillingAccountId`. */\n  referredScopeType: z.enum(BillingScopeType).optional().isDBIndexed(),\n\n  /** Unique referral code (shared by referrer) */\n  // USAGE — a referral records that one account introduced another, and when both are USER-scoped\n  // billing accounts that is a social link between two people. The code itself is the identifier the\n  // link is made through. Declared even though the resource is scope-polymorphic, for the same\n  // reason as the billing family: an org variant at worst over-reports, a missing declaration\n  // silently under-reports.\n  referralCode: z.string().min(1).isUnique({ scope: 'global' }).isDBIndexed().isSummaryField()\n    .dataCategories(PersonalDataCategory.USAGE),\n\n  /** Current status */\n  status: z.enum(ReferralStatus).isDBIndexed().isSummaryField().systemEnum('ReferralStatus'),\n\n  // ── Rewards ──\n\n  /** What the referrer receives on conversion — copied from `billing.referrals` when the code is issued. */\n  referrerReward: ReferrerRewardSchema.optional().isNotEditable().describe('What the referrer receives when the referral converts, copied from the application\\'s referral policy when the code was issued. Absent when the policy gives the referrer nothing.'),\n  /** What the referred account receives — copied the same way. */\n  referredReward: ReferredRewardSchema.optional().isNotEditable().describe('What the referred account receives, copied from the application\\'s referral policy when the code was issued. Absent when the policy gives it nothing.'),\n\n  /**\n   * Whether each side's reward was delivered. Set once the grant has landed: a credit top-up, a\n   * discount on the account's subscription, or a feature grant starting. A discount waiting for the\n   * account to have an active subscription leaves it `false` until then.\n   */\n  referrerRewardApplied: z.boolean().default(false).isNotEditable().describe('Whether the referrer\\'s reward has been delivered.'),\n  referredRewardApplied: z.boolean().default(false).isNotEditable().describe('Whether the referred account\\'s reward has been delivered.'),\n\n  // ── Dates ──\n\n  /** When the referred user accepted the referral */\n  acceptedAt: z.date().optional().isNotEditable(),\n  /** When the referral converted: the referred account's first paid invoice with money on it. */\n  convertedAt: z.date().optional().isSummaryField().isNotEditable(),\n  /** When the referral expires */\n  expiresAt: z.date().optional().isDBIndexed().isSummaryField(),\n\n  metadata: z.record(z.string(), z.string()).optional(),\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type Referral = z.infer<typeof ReferralSchema>;\n"]}

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

@@ -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

@@ -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"}
+{"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

@@ -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