@wildo-ai/saas-models 1.1.5 → 1.1.7

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

@@ -0,0 +1,92 @@
+/**
+ * Referral rewards (#1802) — what each side of a referral receives, and the fields each kind reads.
+ *
+ * One object per side, with a `type` and the fields that type needs. A refinement requires exactly
+ * those fields and refuses the others, so a reward cannot carry a `featureKey` it will never use, and
+ * what each field means is stated here rather than in a comment beside a generic `value`.
+ *
+ * Rewards are SERVER policy: the application declares them in `billing.referrals`, and a referral
+ * copies them when it is issued. A caller never supplies them, because a caller who could would
+ * grant itself anything.
+ */
+import { z } from 'zod';
+// Side-effect import: this module calls `.systemEnum()` at load, so the decorators must be installed first (#966).
+import '@wildo-ai/zod-decorators';
+import { PromotionDuration, ReferredRewardType, ReferrerRewardType } from './billing-enums.shared.schemas.js';
+/**
+ * The referred kind each referrer kind is delivered as. The two vocabularies stay distinct — they are
+ * different sides' promises — but a referrer's credit, discount or feature is read and granted exactly
+ * as the referred side's is. A `Record` over the referrer enum, so a new referrer kind cannot ship
+ * without saying which delivery it shares.
+ */
+export const REFERRER_REWARD_DELIVERED_AS = {
+    [ReferrerRewardType.CREDIT]: ReferredRewardType.CREDIT,
+    [ReferrerRewardType.DISCOUNT]: ReferredRewardType.DISCOUNT,
+    [ReferrerRewardType.FEATURE]: ReferredRewardType.FEATURE,
+};
+/** The fields each reward kind reads, keyed by the delivery kind. */
+const REWARD_FIELDS_BY_TYPE = {
+    [ReferredRewardType.CREDIT]: ['credits', 'creditPoolKey'],
+    [ReferredRewardType.FEATURE]: ['featureKey', 'durationDays'],
+    [ReferredRewardType.DISCOUNT]: ['percentOff', 'discountDuration', 'discountDurationInMonths'],
+    [ReferredRewardType.TRIAL_EXTENSION]: ['trialExtensionDays'],
+};
+/** Fields a kind MUST carry (a subset of {@link REWARD_FIELDS_BY_TYPE}). */
+const REQUIRED_REWARD_FIELDS_BY_TYPE = {
+    [ReferredRewardType.CREDIT]: ['credits', 'creditPoolKey'],
+    [ReferredRewardType.FEATURE]: ['featureKey'],
+    [ReferredRewardType.DISCOUNT]: ['percentOff', 'discountDuration'],
+    [ReferredRewardType.TRIAL_EXTENSION]: ['trialExtensionDays'],
+};
+/** The delivery kind of either side's reward type. */
+export function referralRewardDeliveryKind(type) {
+    return Object.hasOwn(REFERRER_REWARD_DELIVERED_AS, type)
+        ? REFERRER_REWARD_DELIVERED_AS[type]
+        : type;
+}
+const ALL_REWARD_FIELDS = ['credits', 'creditPoolKey', 'featureKey', 'durationDays', 'percentOff', 'discountDuration', 'discountDurationInMonths', 'trialExtensionDays'];
+const rewardFields = {
+    credits: z.number().int().min(1).optional().describe('For a `credit` reward: how many credits are added to the pool.'),
+    creditPoolKey: z.string().min(1).optional().describe('For a `credit` reward: the key of the credit pool the credits are added to. The pool is created if the account has none.'),
+    featureKey: z.string().min(1).optional().describe('For a `feature` reward: the boolean feature the account is granted.'),
+    durationDays: z.number().int().min(1).optional().describe('For a `feature` reward: how many days after conversion the feature lasts. Absent means it does not expire.'),
+    percentOff: z.number().min(1).max(100).optional().describe('For a `discount` reward: the percentage taken off the subscription\'s invoices.'),
+    discountDuration: z.enum(PromotionDuration).optional().describe('For a `discount` reward: how long it applies — `once` (the next invoice), `repeating` (for `discountDurationInMonths`) or `forever`.'),
+    discountDurationInMonths: z.number().int().min(1).optional().describe('For a `repeating` discount: how many months it applies.'),
+};
+/** Refuses a reward missing a field its kind needs, or carrying one its kind never reads. */
+function refineRewardShape(reward, context) {
+    const type = reward.type;
+    const kind = referralRewardDeliveryKind(type);
+    const allowed = REWARD_FIELDS_BY_TYPE[kind] ?? [];
+    for (const field of REQUIRED_REWARD_FIELDS_BY_TYPE[kind] ?? []) {
+        if (reward[field] === undefined)
+            context.addIssue({ code: 'custom', path: [field], message: `A '${type}' reward needs '${field}'.` });
+    }
+    for (const field of ALL_REWARD_FIELDS) {
+        if (reward[field] !== undefined && !allowed.includes(field)) {
+            context.addIssue({ code: 'custom', path: [field], message: `A '${type}' reward does not read '${field}'.` });
+        }
+    }
+    const repeating = reward.discountDuration === PromotionDuration.REPEATING;
+    if (kind === ReferredRewardType.DISCOUNT && repeating !== (reward.discountDurationInMonths !== undefined)) {
+        context.addIssue({
+            code: 'custom', path: ['discountDurationInMonths'],
+            message: 'A repeating discount needs discountDurationInMonths, and only a repeating discount takes it.',
+        });
+    }
+}
+/** @wildo_source:part:start saas.models.billing.referral-program facet:layer:shared facet:audience:app-developer */
+/** What the referrer receives when the referral converts. */
+export const ReferrerRewardSchema = z.object({
+    type: z.enum(ReferrerRewardType).systemEnum('ReferrerRewardType').describe('What the referrer receives: `credit`, `discount` or `feature`.'),
+    ...rewardFields,
+}).superRefine(refineRewardShape);
+/** What the referred account receives. */
+export const ReferredRewardSchema = z.object({
+    type: z.enum(ReferredRewardType).systemEnum('ReferredRewardType').describe('What the referred account receives: `credit`, `discount`, `feature` or `trial_extension`.'),
+    ...rewardFields,
+    trialExtensionDays: z.number().int().min(1).optional().describe('For a `trial_extension` reward: the days added to the trial of a subscription checkout the referred account opens while the referral is accepted.'),
+}).superRefine(refineRewardShape);
+/** @wildo_source:part:end saas.models.billing.referral-program */
+//# sourceMappingURL=referral-reward.shared.schemas.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"referral-reward.shared.schemas.js","sourceRoot":"","sources":["../../../src/billing/referral-reward.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Referral rewards (#1802) — what each side of a referral receives, and the fields each kind reads.\n *\n * One object per side, with a `type` and the fields that type needs. A refinement requires exactly\n * those fields and refuses the others, so a reward cannot carry a `featureKey` it will never use, and\n * what each field means is stated here rather than in a comment beside a generic `value`.\n *\n * Rewards are SERVER policy: the application declares them in `billing.referrals`, and a referral\n * copies them when it is issued. A caller never supplies them, because a caller who could would\n * grant itself anything.\n */\n\nimport { z } from 'zod';\n// Side-effect import: this module calls `.systemEnum()` at load, so the decorators must be installed first (#966).\nimport '@wildo-ai/zod-decorators';\nimport { PromotionDuration, ReferredRewardType, ReferrerRewardType } from './billing-enums.shared.schemas';\n\n/**\n * The referred kind each referrer kind is delivered as. The two vocabularies stay distinct — they are\n * different sides' promises — but a referrer's credit, discount or feature is read and granted exactly\n * as the referred side's is. A `Record` over the referrer enum, so a new referrer kind cannot ship\n * without saying which delivery it shares.\n */\nexport const REFERRER_REWARD_DELIVERED_AS: Readonly<Record<ReferrerRewardType, ReferredRewardType>> = {\n  [ReferrerRewardType.CREDIT]: ReferredRewardType.CREDIT,\n  [ReferrerRewardType.DISCOUNT]: ReferredRewardType.DISCOUNT,\n  [ReferrerRewardType.FEATURE]: ReferredRewardType.FEATURE,\n};\n\n/** The fields each reward kind reads, keyed by the delivery kind. */\nconst REWARD_FIELDS_BY_TYPE: Readonly<Record<ReferredRewardType, readonly string[]>> = {\n  [ReferredRewardType.CREDIT]: ['credits', 'creditPoolKey'],\n  [ReferredRewardType.FEATURE]: ['featureKey', 'durationDays'],\n  [ReferredRewardType.DISCOUNT]: ['percentOff', 'discountDuration', 'discountDurationInMonths'],\n  [ReferredRewardType.TRIAL_EXTENSION]: ['trialExtensionDays'],\n};\n\n/** Fields a kind MUST carry (a subset of {@link REWARD_FIELDS_BY_TYPE}). */\nconst REQUIRED_REWARD_FIELDS_BY_TYPE: Readonly<Record<ReferredRewardType, readonly string[]>> = {\n  [ReferredRewardType.CREDIT]: ['credits', 'creditPoolKey'],\n  [ReferredRewardType.FEATURE]: ['featureKey'],\n  [ReferredRewardType.DISCOUNT]: ['percentOff', 'discountDuration'],\n  [ReferredRewardType.TRIAL_EXTENSION]: ['trialExtensionDays'],\n};\n\n/** The delivery kind of either side's reward type. */\nexport function referralRewardDeliveryKind(type: ReferrerRewardType | ReferredRewardType): ReferredRewardType {\n  return Object.hasOwn(REFERRER_REWARD_DELIVERED_AS, type)\n    ? REFERRER_REWARD_DELIVERED_AS[type as ReferrerRewardType]\n    : type as ReferredRewardType;\n}\n\nconst ALL_REWARD_FIELDS = ['credits', 'creditPoolKey', 'featureKey', 'durationDays', 'percentOff', 'discountDuration', 'discountDurationInMonths', 'trialExtensionDays'] as const;\n\nconst rewardFields = {\n  credits: z.number().int().min(1).optional().describe('For a `credit` reward: how many credits are added to the pool.'),\n  creditPoolKey: z.string().min(1).optional().describe('For a `credit` reward: the key of the credit pool the credits are added to. The pool is created if the account has none.'),\n  featureKey: z.string().min(1).optional().describe('For a `feature` reward: the boolean feature the account is granted.'),\n  durationDays: z.number().int().min(1).optional().describe('For a `feature` reward: how many days after conversion the feature lasts. Absent means it does not expire.'),\n  percentOff: z.number().min(1).max(100).optional().describe('For a `discount` reward: the percentage taken off the subscription\\'s invoices.'),\n  discountDuration: z.enum(PromotionDuration).optional().describe('For a `discount` reward: how long it applies — `once` (the next invoice), `repeating` (for `discountDurationInMonths`) or `forever`.'),\n  discountDurationInMonths: z.number().int().min(1).optional().describe('For a `repeating` discount: how many months it applies.'),\n};\n\n/** Refuses a reward missing a field its kind needs, or carrying one its kind never reads. */\nfunction refineRewardShape(reward: Record<string, unknown> & { type: string }, context: z.RefinementCtx): void {\n  const type = reward.type as ReferrerRewardType | ReferredRewardType;\n  const kind = referralRewardDeliveryKind(type);\n  const allowed = REWARD_FIELDS_BY_TYPE[kind] ?? [];\n  for (const field of REQUIRED_REWARD_FIELDS_BY_TYPE[kind] ?? []) {\n    if (reward[field] === undefined) context.addIssue({ code: 'custom', path: [field], message: `A '${type}' reward needs '${field}'.` });\n  }\n  for (const field of ALL_REWARD_FIELDS) {\n    if (reward[field] !== undefined && !allowed.includes(field)) {\n      context.addIssue({ code: 'custom', path: [field], message: `A '${type}' reward does not read '${field}'.` });\n    }\n  }\n  const repeating = reward.discountDuration === PromotionDuration.REPEATING;\n  if (kind === ReferredRewardType.DISCOUNT && repeating !== (reward.discountDurationInMonths !== undefined)) {\n    context.addIssue({\n      code: 'custom', path: ['discountDurationInMonths'],\n      message: 'A repeating discount needs discountDurationInMonths, and only a repeating discount takes it.',\n    });\n  }\n}\n\n/** @wildo_source:part:start saas.models.billing.referral-program facet:layer:shared facet:audience:app-developer */\n/** What the referrer receives when the referral converts. */\nexport const ReferrerRewardSchema = z.object({\n  type: z.enum(ReferrerRewardType).systemEnum('ReferrerRewardType').describe('What the referrer receives: `credit`, `discount` or `feature`.'),\n  ...rewardFields,\n}).superRefine(refineRewardShape);\nexport type ReferrerReward = z.infer<typeof ReferrerRewardSchema>;\n\n/** What the referred account receives. */\nexport const ReferredRewardSchema = z.object({\n  type: z.enum(ReferredRewardType).systemEnum('ReferredRewardType').describe('What the referred account receives: `credit`, `discount`, `feature` or `trial_extension`.'),\n  ...rewardFields,\n  trialExtensionDays: z.number().int().min(1).optional().describe('For a `trial_extension` reward: the days added to the trial of a subscription checkout the referred account opens while the referral is accepted.'),\n}).superRefine(refineRewardShape);\nexport type ReferredReward = z.infer<typeof ReferredRewardSchema>;\n/** @wildo_source:part:end saas.models.billing.referral-program */\n"]}

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

@@ -3,41 +3,62 @@
  *
  * Operational: referral tracking between billing accounts.
  */
+import { z } from 'zod';
 import { CoreResourceOperation } from '../resources/resources.shared.core.definitions';
 import { ResourceRelationship } from '../resources/resources.shared.schemas';
+/**
+ * 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 declare enum Referral_Operations {
+    /** Issue a single-use referral code for the organization's billing account. */
+    ISSUE = "issue",
+    /** Withdraw a referral that has not converted. */
+    CANCEL = "cancel"
+}
+/** ISSUE takes nothing: the referrer is the organization's own billing account, and the rewards are server policy. */
+export declare const Referral_IssueRequestDto: z.ZodObject<{}, z.core.$strict>;
+/** CANCEL takes nothing: the referral in the path is the one withdrawn. */
+export declare const Referral_CancelRequestDto: z.ZodObject<{}, z.core.$strict>;
 type ReferralsCoreOps = CoreResourceOperation.READ | CoreResourceOperation.LIST | CoreResourceOperation.CREATE | CoreResourceOperation.UPDATE;
-export declare const referralsResourceConfiguration_InitializationFactory: (resourcesRelationships: ResourceRelationship[]) => import("..").ResourceConfiguration<undefined, ReferralsCoreOps, import("zod").ZodObject<{
-    _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodString>>;
-    referrerBillingAccountId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodString>>>;
-    referrerScopeType: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodEnum<typeof import("./billing-enums.shared.schemas").BillingScopeType>>;
-    referredBillingAccountId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodOptional<import("zod").ZodString>>>;
-    referredScopeType: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodOptional<import("zod").ZodEnum<typeof import("./billing-enums.shared.schemas").BillingScopeType>>>;
-    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<import("zod").ZodString>>>>;
-    status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodEnum<typeof import("./billing-enums.shared.schemas").ReferralStatus>>>>;
-    referrerReward: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodOptional<import("zod").ZodObject<{
-        type: import("zod").ZodEnum<typeof import("./billing-enums.shared.schemas").ReferrerRewardType>;
-        value: import("zod").ZodNumber;
-        creditPoolKey: import("zod").ZodOptional<import("zod").ZodString>;
-        featureKey: import("zod").ZodOptional<import("zod").ZodString>;
-        durationDays: import("zod").ZodOptional<import("zod").ZodNumber>;
-        commissionPercentage: import("zod").ZodOptional<import("zod").ZodNumber>;
-    }, import("zod/v4/core").$strip>>>;
-    referredReward: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodOptional<import("zod").ZodObject<{
-        type: import("zod").ZodEnum<typeof import("./billing-enums.shared.schemas").ReferredRewardType>;
-        value: import("zod").ZodNumber;
-        creditPoolKey: import("zod").ZodOptional<import("zod").ZodString>;
-        featureKey: import("zod").ZodOptional<import("zod").ZodString>;
-        durationDays: import("zod").ZodOptional<import("zod").ZodNumber>;
-        trialExtensionDays: import("zod").ZodOptional<import("zod").ZodNumber>;
-    }, import("zod/v4/core").$strip>>>;
-    referrerRewardApplied: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodBoolean>>;
-    referredRewardApplied: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodBoolean>>;
-    acceptedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodOptional<import("zod").ZodDate>>;
-    convertedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodOptional<import("zod").ZodDate>>>;
-    expiresAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodOptional<import("zod").ZodDate>>>;
-    metadata: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
-    createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodDate>>>;
-    updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodDate>>>;
-}, import("zod/v4/core").$strip>>;
+export declare const referralsResourceConfiguration_InitializationFactory: (resourcesRelationships: ResourceRelationship[]) => import("..").ResourceConfiguration<typeof Referral_Operations, ReferralsCoreOps, 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>>>;
+    referrerScopeType: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodEnum<typeof import("./billing-enums.shared.schemas").BillingScopeType>>;
+    referredBillingAccountId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>;
+    referredScopeType: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodEnum<typeof import("./billing-enums.shared.schemas").BillingScopeType>>>;
+    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 import("./billing-enums.shared.schemas").ReferralStatus>>>>;
+    referrerReward: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodObject<{
+        credits: z.ZodOptional<z.ZodNumber>;
+        creditPoolKey: z.ZodOptional<z.ZodString>;
+        featureKey: z.ZodOptional<z.ZodString>;
+        durationDays: 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<{
+        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>;
+        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>>;
+    acceptedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>;
+    convertedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
+    expiresAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>;
+    updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>;
+}, z.core.$strip>>;
 export {};
 //# sourceMappingURL=referral.shared.resources-config.schemas.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"referral.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/referral.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,qBAAqB,EAAwD,MAAM,gDAAgD,CAAC;AAC7I,OAAO,EAGL,oBAAoB,EACrB,MAAM,uCAAuC,CAAC;AAI/C,KAAK,gBAAgB,GACjB,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,oDAAoD,GAC/D,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAuE9C,CAAC"}
+{"version":3,"file":"referral.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/referral.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,qBAAqB,EAAwD,MAAM,gDAAgD,CAAC;AAC7I,OAAO,EAGL,oBAAoB,EACrB,MAAM,uCAAuC,CAAC;AAK/C;;;;GAIG;AACH,oBAAY,mBAAmB;IAC7B,+EAA+E;IAC/E,KAAK,UAAU;IACf,kDAAkD;IAClD,MAAM,WAAW;CAClB;AAED,sHAAsH;AACtH,eAAO,MAAM,wBAAwB,iCAAqB,CAAC;AAE3D,2EAA2E;AAC3E,eAAO,MAAM,yBAAyB,iCAAqB,CAAC;AAE5D,KAAK,gBAAgB,GACjB,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,oDAAoD,GAC/D,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA2G9C,CAAC"}

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":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,6GAA6G;AAC7G,+GAA+G;AAC/G,OAAO,0BAA0B,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,6DAA6D,CAAC;AACnG,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,uCAAuC,EAAE,MAAM,kCAAkC,CAAC;AAE3F,mEAAmE;AAEnE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC;IAChC,gFAAgF;IAChF,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,wCAAwC;IACxC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,qCAAqC;IACrC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,+CAA+C;IAC/C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC1C,kDAAkD;IAClD,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;CAC5D,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC;IAChC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACjC,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC1C,yDAAyD;IACzD,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACjD,CAAC,CAAC;AAGH,mEAAmE;AAEnE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAErC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE;IAEtD;;;;;;;;;OASG;IACH,wBAAwB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;QACvD,mBAAmB,EAAE,uCAAuC;QAC5D,6BAA6B,EAAE,mBAAmB;KACnD,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE;IACjC,2JAA2J;IAC3J,iBAAiB,EAAE,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,WAAW,EAAE;IACzD;;;;;OAKG;IACH,wBAAwB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,YAAY,CAAC;QAC3D,mBAAmB,EAAE,uCAAuC;QAC5D,6BAA6B,EAAE,mBAAmB;KACnD,CAAC,CAAC,WAAW,EAAE;IAChB,0KAA0K;IAC1K,iBAAiB,EAAE,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE;IAEpE,gDAAgD;IAChD,gGAAgG;IAChG,mGAAmG;IACnG,6FAA6F;IAC7F,4FAA4F;IAC5F,0BAA0B;IAC1B,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE;SACzF,cAAc,CAAC,oBAAoB,CAAC,KAAK,CAAC;IAE7C,qBAAqB;IACrB,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,UAAU,CAAC,gBAAgB,CAAC;IAE1F,gBAAgB;IAEhB,oDAAoD;IACpD,cAAc,EAAE,oBAAoB,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE;IAC/D,kCAAkC;IAClC,cAAc,EAAE,oBAAoB,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE;IAE/D,wCAAwC;IACxC,qBAAqB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,aAAa,EAAE;IACjE,qBAAqB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,aAAa,EAAE;IAEjE,cAAc;IAEd,mDAAmD;IACnD,UAAU,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE;IAC/C,4DAA4D;IAC5D,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE;IACjE,gCAAgC;IAChC,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE;IAE7D,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACrD,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IACrF,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;CACtF,CAAC,CAAC","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"]}