@wildo-ai/saas-models 1.1.4 → 1.1.5

package/dist/esm/billing/product-behavior-policy.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"product-behavior-policy.shared.schemas.js","sourceRoot":"","sources":["../../../src/billing/product-behavior-policy.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Product Behavior Policy & Limit Grant Schemas (Shared)\n *\n * Declarative configuration for how the billing provider and the engine\n * should handle product lifecycle (trial, proration, cancellation, metering).\n *\n * Also defines the LimitGrant schema that controls how product limits compose.\n *\n * @see billing-and-features-system.md §6.1 (LimitGrant), §6.1 (ProductBehaviorPolicy)\n */\n\nimport { z } from 'zod';\nimport {\n  LimitGrantMode,\n  ProrationBehavior,\n  BillingTiming,\n  MeteringAggregationWindow,\n} from './billing-enums.shared.schemas';\n\n// ── Limit Grant ────────────────────────────────────────────────────\n\n/**\n * A limit grant from a product.\n *\n * - SET mode: absolute value (replaces, used for PLAN base limits).\n *   Example: \"Professional plan gives you 50 projects.\"\n * - ADD mode: additive (stacks on top, used for ADDON bonus limits).\n *   Example: \"+10 extra projects.\"\n *\n * Aggregation algorithm in BillingFeatureSyncBackendService:\n *   1. Start with active PLAN's SET limits (only one active plan per billing account)\n *   2. For each active ADDON with ADD mode: sum onto current limit\n *   3. For each active ADDON with SET mode: take max(current, addon value)\n *   4. FEATURES_UNLIMITED always wins in any comparison\n */\nexport const LimitGrantSchema = z.object({\n  /** The limit value (count or -1 for FEATURES_UNLIMITED) */\n  value: z.number(),\n  /** How this grant composes with others */\n  mode: z.enum(LimitGrantMode).default(LimitGrantMode.SET),\n});\nexport type LimitGrant = z.infer<typeof LimitGrantSchema>;\n\n// ── Product Behavior Policy ────────────────────────────────────────\n\n/**\n * Declarative configuration for how the billing provider and the engine\n * should handle this product's lifecycle.\n *\n * This is the \"billing policy\" layer — NOT reimplementing provider logic,\n * but CONFIGURING the parameters that get passed to the provider's API.\n */\nexport const ProductBehaviorPolicySchema = z.object({\n  /** Trial configuration (overrides global BillingConfiguration.defaultTrialDays) */\n  trial: z.object({\n    /** Number of trial days (0 = no trial) */\n    days: z.number().min(0).default(0),\n    /**\n     * Require a payment method before the trial starts. READ since 2026-09-08 (#408).\n     *\n     * It reached no provider call before that, so a trial declared as requiring a card behaved\n     * identically to one that did not — Wonder Todos' enterprise plan (`true`) and professional\n     * plan (`false`) were indistinguishable at the provider.\n     *\n     * Only meaningful WITH a trial: a product declaring it alongside `days: 0` demands nothing,\n     * because asking for a card up front on a purchase with no trial is a different decision and\n     * nobody authored it.\n     */\n    requirePaymentMethod: z.boolean().default(false),\n  }).optional(),\n\n  /** Upgrade behavior (when switching TO this plan from a lower tier) */\n  upgrade: z.object({\n    /** Proration passed to provider: create_prorations, none, always_invoice */\n    proration: z.enum(ProrationBehavior).default(ProrationBehavior.CREATE_PRORATIONS),\n    /** Apply immediately or at end of current period */\n    timing: z.enum(BillingTiming).default(BillingTiming.IMMEDIATE),\n  }).optional(),\n\n  /** Downgrade behavior (when switching FROM this plan to a lower tier) */\n  downgrade: z.object({\n    proration: z.enum(ProrationBehavior).default(ProrationBehavior.NONE),\n    timing: z.enum(BillingTiming).default(BillingTiming.AT_PERIOD_END),\n  }).optional(),\n\n  /** Cancellation behavior for subscriptions on this product */\n  cancellation: z.object({\n    /** Allow immediate cancellation (vs only at period end) */\n    allowImmediate: z.boolean().default(false),\n    /** Default cancellation timing when user cancels */\n    defaultBehavior: z.enum(BillingTiming).default(BillingTiming.AT_PERIOD_END),\n  }).optional(),\n\n  /**\n   * Authored metering policy (for METERED products only), READ by\n   * `UsageMeteringBackendService` since 2026-09-08 (#415).\n   *\n   * Every field here was declared, defaulted, documented and read by NOTHING until then: the flush\n   * merged every pending row by billing account and product whatever the product said, so\n   * `preFlushAggregation: false` was unrepresentable and `aggregationWindow`'s two members selected\n   * between behaviours that were the same behaviour. The note that stood here said exactly that and\n   * asked that the gap stay visible rather than become \"a false runtime guarantee\"; this replaces it\n   * because the guarantee is now real, and says which reader makes each field true.\n   */\n  metering: z.object({\n    /**\n     * How often to flush aggregated usage to the billing provider (minutes).\n     *\n     * Read by the engine's usage-flush batch, which picks the SHORTEST interval any metered product\n     * authors — a schedule is one thing and the products sharing it are many, so the fastest promise\n     * is the one that has to be kept. A product asking for less frequent reporting than its neighbour\n     * still gets reported at the neighbour's cadence, which costs nothing: reporting sooner than\n     * authored is never wrong, reporting later than authored is.\n     */\n    flushIntervalMinutes: z.number().min(1).default(60),\n    /**\n     * Whether one meter event may span a billing-period boundary.\n     *\n     * This is not a preference, it is a correctness choice about MONEY. A merged group carries ONE\n     * timestamp and the provider assigns the event to the period that timestamp falls in, so\n     * `PER_FLUSH` merging across a boundary bills the earlier period's usage into the later one.\n     * `PER_BILLING_PERIOD` splits at the boundary, derived from the subscription's own\n     * `currentPeriodStart` / `currentPeriodEnd`. Leave it `PER_FLUSH` when the product's periods do\n     * not change what it costs.\n     */\n    aggregationWindow: z.enum(MeteringAggregationWindow).default(MeteringAggregationWindow.PER_FLUSH),\n    /**\n     * Aggregate locally before sending (sum same-key records into one meter event).\n     *\n     * `false` sends one event per recorded row, each with its own instant. Choose it when the provider\n     * must see every event — because its aggregation is not a sum, or because the individual instants\n     * matter. Local merging destroys both irreversibly, before the provider ever sees them.\n     */\n    preFlushAggregation: z.boolean().default(true),\n    /**\n     * Retry policy when a provider report fails.\n     *\n     * Safe only because every meter event carries a derived idempotency identifier: a retry after a\n     * response lost in transit re-sends the same identifier and the provider discards it. Retrying\n     * without that is how a timeout becomes a double charge, which is why the two shipped together.\n     */\n    retryPolicy: z.object({\n      maxRetries: z.number().default(3),\n      backoffMultiplier: z.number().default(2),\n    }).default({ maxRetries: 3, backoffMultiplier: 2 }),\n  }).optional(),\n});\nexport type ProductBehaviorPolicy = z.infer<typeof ProductBehaviorPolicySchema>;\n"]}
+{"version":3,"file":"product-behavior-policy.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/product-behavior-policy.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Product Behavior Policy & Limit Grant Schemas (Shared)\n *\n * Declarative configuration for how the billing provider and the engine\n * should handle product lifecycle (trial, proration, cancellation, metering).\n *\n * Also defines the LimitGrant schema that controls how product limits compose.\n *\n * @see billing-and-features-system.md §6.1 (LimitGrant), §6.1 (ProductBehaviorPolicy)\n */\n\nimport { z } from 'zod';\nimport {\n  LimitGrantMode,\n  ProrationBehavior,\n  BillingTiming,\n  MeteringAggregationWindow,\n} from './billing-enums.shared.schemas';\n\n// ── Limit Grant ────────────────────────────────────────────────────\n\n/**\n * A limit grant from a product.\n *\n * - SET mode: absolute value (replaces, used for PLAN base limits).\n *   Example: \"Professional plan gives you 50 projects.\"\n * - ADD mode: additive (stacks on top, used for ADDON bonus limits).\n *   Example: \"+10 extra projects.\"\n *\n * Aggregation algorithm in BillingFeatureSyncBackendService:\n *   1. Start with active PLAN's SET limits (only one active plan per billing account)\n *   2. For each active ADDON with ADD mode: sum onto current limit\n *   3. For each active ADDON with SET mode: take max(current, addon value)\n *   4. FEATURES_UNLIMITED always wins in any comparison\n */\nexport const LimitGrantSchema = z.object({\n  /** The limit value (count or -1 for FEATURES_UNLIMITED) */\n  value: z.number(),\n  /** How this grant composes with others */\n  mode: z.enum(LimitGrantMode).default(LimitGrantMode.SET),\n});\nexport type LimitGrant = z.infer<typeof LimitGrantSchema>;\n\n// ── Product Behavior Policy ────────────────────────────────────────\n\n/**\n * Declarative configuration for how the billing provider and the engine\n * should handle this product's lifecycle.\n *\n * This is the \"billing policy\" layer — NOT reimplementing provider logic,\n * but CONFIGURING the parameters that get passed to the provider's API.\n */\nexport const ProductBehaviorPolicySchema = z.object({\n  /** Trial configuration (overrides global BillingConfiguration.defaultTrialDays) */\n  trial: z.object({\n    /** Number of trial days (0 = no trial) */\n    days: z.number().min(0).default(0),\n    /**\n     * Require a payment method before the trial starts. READ since 2026-09-08 (#408).\n     *\n     * It reached no provider call before that, so a trial declared as requiring a card behaved\n     * identically to one that did not — Wonder Todos' enterprise plan (`true`) and professional\n     * plan (`false`) were indistinguishable at the provider.\n     *\n     * Only meaningful WITH a trial: a product declaring it alongside `days: 0` demands nothing,\n     * because asking for a card up front on a purchase with no trial is a different decision and\n     * nobody authored it.\n     */\n    requirePaymentMethod: z.boolean().default(false),\n  }).optional(),\n\n  /** Upgrade behavior (when switching TO this plan from a lower tier) */\n  upgrade: z.object({\n    /** Proration passed to provider: create_prorations, none, always_invoice */\n    proration: z.enum(ProrationBehavior).default(ProrationBehavior.CREATE_PRORATIONS),\n    /** Apply immediately or at end of current period */\n    timing: z.enum(BillingTiming).default(BillingTiming.IMMEDIATE),\n  }).optional(),\n\n  /** Downgrade behavior (when switching FROM this plan to a lower tier) */\n  downgrade: z.object({\n    proration: z.enum(ProrationBehavior).default(ProrationBehavior.NONE),\n    timing: z.enum(BillingTiming).default(BillingTiming.AT_PERIOD_END),\n  }).optional(),\n\n  /** Cancellation behavior for subscriptions on this product */\n  cancellation: z.object({\n    /** Allow immediate cancellation (vs only at period end) */\n    allowImmediate: z.boolean().default(false),\n    /** Default cancellation timing when user cancels */\n    defaultBehavior: z.enum(BillingTiming).default(BillingTiming.AT_PERIOD_END),\n  }).refine(\n    (policy) => policy.allowImmediate || policy.defaultBehavior !== BillingTiming.IMMEDIATE,\n    { message: 'Immediate cancellation cannot be the default when immediate cancellation is forbidden.', path: ['defaultBehavior'] },\n  ).optional(),\n\n  /**\n   * Authored metering policy (for METERED products only), READ by\n   * `UsageMeteringBackendService` since 2026-09-08 (#415).\n   *\n   * Every field here was declared, defaulted, documented and read by NOTHING until then: the flush\n   * merged every pending row by billing account and product whatever the product said, so\n   * `preFlushAggregation: false` was unrepresentable and `aggregationWindow`'s two members selected\n   * between behaviours that were the same behaviour. The note that stood here said exactly that and\n   * asked that the gap stay visible rather than become \"a false runtime guarantee\"; this replaces it\n   * because the guarantee is now real, and says which reader makes each field true.\n   */\n  metering: z.object({\n    /**\n     * How often to flush aggregated usage to the billing provider (minutes).\n     *\n     * Read by the engine's usage-flush batch, which picks the SHORTEST interval any metered product\n     * authors — a schedule is one thing and the products sharing it are many, so the fastest promise\n     * is the one that has to be kept. A product asking for less frequent reporting than its neighbour\n     * still gets reported at the neighbour's cadence, which costs nothing: reporting sooner than\n     * authored is never wrong, reporting later than authored is.\n     */\n    flushIntervalMinutes: z.number().min(1).default(60),\n    /**\n     * Whether one meter event may span a billing-period boundary.\n     *\n     * This is not a preference, it is a correctness choice about MONEY. A merged group carries ONE\n     * timestamp and the provider assigns the event to the period that timestamp falls in, so\n     * `PER_FLUSH` merging across a boundary bills the earlier period's usage into the later one.\n     * `PER_BILLING_PERIOD` splits at the boundary, derived from the subscription's own\n     * `currentPeriodStart` / `currentPeriodEnd`. Leave it `PER_FLUSH` when the product's periods do\n     * not change what it costs.\n     */\n    aggregationWindow: z.enum(MeteringAggregationWindow).default(MeteringAggregationWindow.PER_FLUSH),\n    /**\n     * Aggregate locally before sending (sum same-key records into one meter event).\n     *\n     * `false` sends one event per recorded row, each with its own instant. Choose it when the provider\n     * must see every event — because its aggregation is not a sum, or because the individual instants\n     * matter. Local merging destroys both irreversibly, before the provider ever sees them.\n     */\n    preFlushAggregation: z.boolean().default(true),\n    /**\n     * Retry policy when a provider report fails.\n     *\n     * Safe only because every meter event carries a derived idempotency identifier: a retry after a\n     * response lost in transit re-sends the same identifier and the provider discards it. Retrying\n     * without that is how a timeout becomes a double charge, which is why the two shipped together.\n     */\n    retryPolicy: z.object({\n      maxRetries: z.number().default(3),\n      backoffMultiplier: z.number().default(2),\n    }).default({ maxRetries: 3, backoffMultiplier: 2 }),\n  }).optional(),\n});\nexport type ProductBehaviorPolicy = z.infer<typeof ProductBehaviorPolicySchema>;\n"]}

package/dist/esm/billing/product-definition.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"product-definition.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/product-definition.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EACL,WAAW,EACX,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,cAAc,EACf,MAAM,gCAAgC,CAAC;AAMxC;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;iBAuBhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAIpE;;;GAGG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2ElC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}
+{"version":3,"file":"product-definition.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/product-definition.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EACL,WAAW,EACX,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,cAAc,EACf,MAAM,gCAAgC,CAAC;AAMxC;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;iBAuBhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAIpE;;;GAGG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2ElC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"product.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/product.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,eAAe,GAChB,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,mDAAmD,GAC9D,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAkE9C,CAAC"}
+{"version":3,"file":"product.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/product.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,eAAe,GAChB,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,mDAAmD,GAC9D,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAgG9C,CAAC"}

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

@@ -31,12 +31,42 @@ export const productsResourceConfiguration_InitializationFactory = (resourcesRel
                 }],
         },
         [CoreResourceOperation.LIST]: {
-            variants: [{
+            variants: [
+                {
                     variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
                     roles: [CORE_APP_ROLES.APP_USER],
                     riskLevel: ResourceOperationRiskLevel.LOW,
-                }],
+                },
+                {
+                    /*
+                     * The OPERATOR's door onto the catalogue — added 2026-09-18 for issue #1295.
+                     *
+                     * The `INTERNAL_CALL` variant above is route-less by design: the billing back-office drives
+                     * this resource through the service pipeline, and states that these catalog reads have "NO
+                     * HTTP surface". That stays true and stays the DEFAULT, so `createForInternalServiceOperation`
+                     * keeps resolving it and no internal seam moves.
+                     *
+                     * What was missing is the surface an application ADMINISTRATOR needs. The `billing-catalog`
+                     * settings destination targets `products.list` and could never load — the rail entry, the tab and the
+                     * heading all rendered, and every request 404'd at the ROUTER, because no route was ever
+                     * mounted. An operator cannot price what they cannot see.
+                     *
+                     * Gated on `APP_ADMIN_SUPER_ADMIN`, exactly what that destination already requires. Not a
+                     * widening: the aggregated billing state already ships products, prices and active promotions
+                     * to EVERY authenticated client, so an admin-only list is strictly narrower than what the
+                     * application discloses today.
+                     *
+                     * Two `isDefault: true` variants is the shape `organizations.CREATE` already uses — default is
+                     * per variant TYPE, so the internal door and the HTTP door each stay the default of their own
+                     * transport and the HTTP one needs no `variantKey` in its URL.
+                     */
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                },
+            ],
         },
         [CoreResourceOperation.SEARCH]: {
             variants: [{

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

@@ -1 +1 @@
-{"version":3,"file":"product.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/product.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,cAAc,EAAE,MAAM,iDAAiD,CAAC;AACjG,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AASzD,MAAM,CAAC,MAAM,mDAAmD,GAAG,CACjE,sBAA8C,EAC9C,EAAE,CAAC,0CAA0C,CAI7C;IACA,UAAU,EAAE,aAAa;IACzB,kBAAkB,EAAE,gBAAgB,CAAC,QAAQ;IAC7C,uBAAuB,EAAE,kCAAkC,CAAC,gBAAgB,CAAC,QAAQ,CAAC;IACtF,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;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,QAAQ,CAAC;oBAChC,SAAS,EAAE,0BAA0B,CAAC,GAAG;iBAC1C,CAAC;SACH;QACD,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,QAAQ,CAAC;oBAChC,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,QAAQ,CAAC;oBAChC,SAAS,EAAE,0BAA0B,CAAC,GAAG;oBACzC,YAAY,EAAE,IAAI;oBAClB,gBAAgB,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC;oBACjC,iBAAiB,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE;oBACjE,YAAY,EAAE,EAAE;oBAChB,UAAU,EAAE,EAAE;oBACd,8BAA8B,EAAE,EAAE;iBACnC,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,MAAM;iBAC7C,CAAC;SACH;QACD,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE;YAC9B,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,aAAa;oBACvD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;oBACjC,SAAS,EAAE,0BAA0B,CAAC,MAAM;iBAC7C,CAAC;SACH;KACF;CACF,CAAC,CAAC","sourcesContent":["/**\n * Product Resource Configuration\n *\n * Admin-managed: APPLICATION-scoped catalog (read-only in UI, code-driven).\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_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { ProductSchema } from './product.shared.schemas';\n\ntype ProductsCoreOps =\n  | CoreResourceOperation.READ\n  | CoreResourceOperation.LIST\n  | CoreResourceOperation.SEARCH\n  | CoreResourceOperation.CREATE\n  | CoreResourceOperation.UPDATE;\n\nexport const productsResourceConfiguration_InitializationFactory = (\n  resourcesRelationships: ResourceRelationship[]\n) => createResourceConfiguration_Initialization<\n  undefined,\n  ProductsCoreOps,\n  typeof ProductSchema\n>({\n  mainSchema: ProductSchema,\n  resourceIdentifier: CoreResourceType.PRODUCTS,\n  resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.PRODUCTS],\n  resourceRelationships: resourcesRelationships,\n  isSystemResource: true,\n  coreOperations: [\n    CoreResourceOperation.READ,\n    CoreResourceOperation.LIST,\n    CoreResourceOperation.SEARCH,\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_APP_ROLES.APP_USER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      }],\n    },\n    [CoreResourceOperation.LIST]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_APP_ROLES.APP_USER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      }],\n    },\n    [CoreResourceOperation.SEARCH]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_APP_ROLES.APP_USER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n        isSearchable: true,\n        searchableFields: ['key', 'type'],\n        searchableOptions: { caseSensitive: false, fullMatchOnly: false },\n        filterFields: {},\n        sortFields: [],\n        maxPaginatedResultPerPageLimit: 50,\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.MEDIUM,\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.MEDIUM,\n      }],\n    },\n  },\n});\n"]}
+{"version":3,"file":"product.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/product.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Product Resource Configuration\n *\n * Admin-managed: APPLICATION-scoped catalog (read-only in UI, code-driven).\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_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { ProductSchema } from './product.shared.schemas';\n\ntype ProductsCoreOps =\n  | CoreResourceOperation.READ\n  | CoreResourceOperation.LIST\n  | CoreResourceOperation.SEARCH\n  | CoreResourceOperation.CREATE\n  | CoreResourceOperation.UPDATE;\n\nexport const productsResourceConfiguration_InitializationFactory = (\n  resourcesRelationships: ResourceRelationship[]\n) => createResourceConfiguration_Initialization<\n  undefined,\n  ProductsCoreOps,\n  typeof ProductSchema\n>({\n  mainSchema: ProductSchema,\n  resourceIdentifier: CoreResourceType.PRODUCTS,\n  resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.PRODUCTS],\n  resourceRelationships: resourcesRelationships,\n  isSystemResource: true,\n  coreOperations: [\n    CoreResourceOperation.READ,\n    CoreResourceOperation.LIST,\n    CoreResourceOperation.SEARCH,\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_APP_ROLES.APP_USER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      }],\n    },\n    [CoreResourceOperation.LIST]: {\n      variants: [\n      {\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_APP_ROLES.APP_USER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      },\n      {\n        /*\n         * The OPERATOR's door onto the catalogue — added 2026-09-18 for issue #1295.\n         *\n         * The `INTERNAL_CALL` variant above is route-less by design: the billing back-office drives\n         * this resource through the service pipeline, and states that these catalog reads have \"NO\n         * HTTP surface\". That stays true and stays the DEFAULT, so `createForInternalServiceOperation`\n         * keeps resolving it and no internal seam moves.\n         *\n         * What was missing is the surface an application ADMINISTRATOR needs. The `billing-catalog`\n         * settings destination targets `products.list` and could never load — the rail entry, the tab and the\n         * heading all rendered, and every request 404'd at the ROUTER, because no route was ever\n         * mounted. An operator cannot price what they cannot see.\n         *\n         * Gated on `APP_ADMIN_SUPER_ADMIN`, exactly what that destination already requires. Not a\n         * widening: the aggregated billing state already ships products, prices and active promotions\n         * to EVERY authenticated client, so an admin-only list is strictly narrower than what the\n         * application discloses today.\n         *\n         * Two `isDefault: true` variants is the shape `organizations.CREATE` already uses — default is\n         * per variant TYPE, so the internal door and the HTTP door each stay the default of their own\n         * transport and the HTTP one needs no `variantKey` in its URL.\n         */\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      },\n      ],\n    },\n    [CoreResourceOperation.SEARCH]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_APP_ROLES.APP_USER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n        isSearchable: true,\n        searchableFields: ['key', 'type'],\n        searchableOptions: { caseSensitive: false, fullMatchOnly: false },\n        filterFields: {},\n        sortFields: [],\n        maxPaginatedResultPerPageLimit: 50,\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.MEDIUM,\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.MEDIUM,\n      }],\n    },\n  },\n});\n"]}

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

@@ -17,6 +17,7 @@
  * @see billing-and-features-system.md §6.2 (Product & Price Catalog)
  */
 import { z } from 'zod';
+import '@wildo-ai/zod-decorators';
 import { ResourcePrimaryScope } from '../resources/resources.shared.schemas';
 import { ProductType, TaxDisplayMode } from './billing-enums.shared.schemas';
 export declare const ProductSchema: z.ZodObject<{

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

@@ -1 +1 @@
-{"version":3,"file":"product.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/product.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EACL,WAAW,EACX,cAAc,EACf,MAAM,gCAAgC,CAAC;AAIxC,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8ExB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}
+{"version":3,"file":"product.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/product.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,0BAA0B,CAAC;AAClC,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EACL,WAAW,EACX,cAAc,EACf,MAAM,gCAAgC,CAAC;AAIxC,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8ExB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

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

@@ -17,6 +17,9 @@
  * @see billing-and-features-system.md §6.2 (Product & Price Catalog)
  */
 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 { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
 import { ProductType, TaxDisplayMode, } from './billing-enums.shared.schemas.js';
 import { LimitGrantSchema } from './product-behavior-policy.shared.schemas.js';

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

@@ -1 +1 @@
-{"version":3,"file":"product.shared.schemas.js","sourceRoot":"","sources":["../../../src/billing/product.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Product Schema (Shared)\n *\n * Products define what you sell. They live in the DB as APPLICATION-scoped records,\n * populated lazily from the code-defined ProductDefinition catalog.\n *\n * Config-driven, lazy-populated:\n * 1. Config is the source of truth: Product definitions live in code (shared lib)\n * 2. Populate on demand: DB records created on first checkout/admin view\n * 3. Provider sync on demand: providerProductId filled when first used in provider ops\n * 4. Bulk sync available: Admin action to pre-populate all products\n * 5. Startup is lightweight: No blocking provider calls at boot\n *\n * The admin UI shows products as read-only resources (view + \"Sync to Provider\" action),\n * NOT as CRUD-editable. Changes require code deployment.\n *\n * @see billing-and-features-system.md §6.2 (Product & Price Catalog)\n */\n\nimport { z } from 'zod';\nimport { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\nimport {\n  ProductType,\n  TaxDisplayMode,\n} from './billing-enums.shared.schemas';\nimport { LimitGrantSchema } from './product-behavior-policy.shared.schemas';\nimport { ProductBehaviorPolicySchema } from './product-behavior-policy.shared.schemas';\n\nexport const ProductSchema = z.object({\n\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  type: z.enum(ProductType).isDBIndexed().isSummaryField().isNotEditable().systemEnum('ProductType'),\n  /** Unique product key (maps to ProductDefinition.key in code catalog) */\n  key: z.string().min(1).isUnique({ scope: 'global' }).isSummaryField().isNotEditable(),\n\n  /** Which scopes can subscribe to this product (code-driven, not user-editable) */\n  targetScopes: z.array(z.enum(ResourcePrimaryScope)).min(1),\n\n  /** Features this product grants (boolean: present = enabled) */\n  grantedFeatures: z.array(z.string()).default([]).isNotEditable(),\n\n  /**\n   * Limits this product grants, with aggregation mode.\n   * - SET: absolute value (for PLAN products: \"Professional gives you 50 projects\")\n   * - ADD: additive to current limits (for ADDON products: \"+10 extra projects\")\n   *\n   * Aggregation algorithm in BillingFeatureSyncBackendService:\n   *   1. Start with active PLAN's SET limits (only one active plan per billing account)\n   *   2. For each active ADDON with ADD mode: sum onto current limit\n   *   3. For each active ADDON with SET mode: take max(current, addon value)\n   *   4. FEATURES_UNLIMITED always wins in any comparison\n   */\n  grantedLimits: z.record(z.string(), LimitGrantSchema).default({}).isNotEditable(),\n\n  /** For PLAN type: mutually exclusive tier ordering (higher number = higher tier) */\n  planTier: z.string().optional().isSummaryField(),\n  /** For PLAN type: tier sort order (used for upgrade/downgrade direction detection) */\n  planTierOrder: z.number().optional(),\n\n  /** For ADDON type: required plan tiers to subscribe to this addon (empty = no restriction) */\n  requiredPlanTiers: z.array(z.string()).optional(),\n\n  /**\n   * Tax display intent for this product, recorded on the product row.\n   * - 'exclusive': price amounts are HT (tax added at checkout)\n   * - 'inclusive': price amounts are TTC (tax embedded)\n   *\n   * It is DECLARATIVE ONLY and does not reach the billing provider. The catalog sync stores it on\n   * the product and then sends each price's own `taxBehavior` unchanged, so a price that declares\n   * none is created without `tax_behavior` regardless of what this field says. To make the\n   * intention effective, set `taxBehavior` on the prices as well.\n   *\n   * Common pattern: org products exclusive, user products inclusive.\n   */\n  taxDisplayMode: z.enum(TaxDisplayMode).optional(),\n\n  /**\n   * Purchase configuration for non-subscription products (ONE_TIME, CREDIT_PACK, ITEM).\n   * Ignored for subscription products (PLAN, ADDON, METERED).\n   */\n  purchaseConfig: z.object({\n    /** Maximum quantity per purchase (for CREDIT_PACK/ITEM). undefined = no limit */\n    maxQuantityPerPurchase: z.number().min(1).optional(),\n    /** For CREDIT_PACK: how many credits per pack unit */\n    creditsPerUnit: z.number().min(1).optional(),\n    /** For CREDIT_PACK: which \"credit pool\" this feeds (e.g., 'ai_tokens', 'sms_credits') */\n    creditPoolKey: z.string().optional(),\n  }).optional(),\n\n  /** Behavior policy: trial, proration, cancellation, metering */\n  behaviorPolicy: ProductBehaviorPolicySchema.optional(),\n\n  /** Provider sync (lazy: populated on first checkout or sync action, NOT at startup) */\n  providerProductId: z.string().optional().isBackendOnly(),\n\n  /** Display sort order in pricing tables */\n  sortOrder: z.number().default(0),\n  /** Whether this product is visible to end users */\n  isPublic: z.boolean().default(true).isSummaryField(),\n  /** Whether this product is available for purchase */\n  isActive: z.boolean().default(true).isDBIndexed().isSummaryField(),\n  metadata: z.record(z.string(), z.string()).optional(),\n\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type Product = z.infer<typeof ProductSchema>;\n"]}
+{"version":3,"file":"product.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/product.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Product Schema (Shared)\n *\n * Products define what you sell. They live in the DB as APPLICATION-scoped records,\n * populated lazily from the code-defined ProductDefinition catalog.\n *\n * Config-driven, lazy-populated:\n * 1. Config is the source of truth: Product definitions live in code (shared lib)\n * 2. Populate on demand: DB records created on first checkout/admin view\n * 3. Provider sync on demand: providerProductId filled when first used in provider ops\n * 4. Bulk sync available: Admin action to pre-populate all products\n * 5. Startup is lightweight: No blocking provider calls at boot\n *\n * The admin UI shows products as read-only resources (view + \"Sync to Provider\" action),\n * NOT as CRUD-editable. Changes require code deployment.\n *\n * @see billing-and-features-system.md §6.2 (Product & Price Catalog)\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 { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\nimport {\n  ProductType,\n  TaxDisplayMode,\n} from './billing-enums.shared.schemas';\nimport { LimitGrantSchema } from './product-behavior-policy.shared.schemas';\nimport { ProductBehaviorPolicySchema } from './product-behavior-policy.shared.schemas';\n\nexport const ProductSchema = z.object({\n\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  type: z.enum(ProductType).isDBIndexed().isSummaryField().isNotEditable().systemEnum('ProductType'),\n  /** Unique product key (maps to ProductDefinition.key in code catalog) */\n  key: z.string().min(1).isUnique({ scope: 'global' }).isSummaryField().isNotEditable(),\n\n  /** Which scopes can subscribe to this product (code-driven, not user-editable) */\n  targetScopes: z.array(z.enum(ResourcePrimaryScope)).min(1),\n\n  /** Features this product grants (boolean: present = enabled) */\n  grantedFeatures: z.array(z.string()).default([]).isNotEditable(),\n\n  /**\n   * Limits this product grants, with aggregation mode.\n   * - SET: absolute value (for PLAN products: \"Professional gives you 50 projects\")\n   * - ADD: additive to current limits (for ADDON products: \"+10 extra projects\")\n   *\n   * Aggregation algorithm in BillingFeatureSyncBackendService:\n   *   1. Start with active PLAN's SET limits (only one active plan per billing account)\n   *   2. For each active ADDON with ADD mode: sum onto current limit\n   *   3. For each active ADDON with SET mode: take max(current, addon value)\n   *   4. FEATURES_UNLIMITED always wins in any comparison\n   */\n  grantedLimits: z.record(z.string(), LimitGrantSchema).default({}).isNotEditable(),\n\n  /** For PLAN type: mutually exclusive tier ordering (higher number = higher tier) */\n  planTier: z.string().optional().isSummaryField(),\n  /** For PLAN type: tier sort order (used for upgrade/downgrade direction detection) */\n  planTierOrder: z.number().optional(),\n\n  /** For ADDON type: required plan tiers to subscribe to this addon (empty = no restriction) */\n  requiredPlanTiers: z.array(z.string()).optional(),\n\n  /**\n   * Tax display intent for this product, recorded on the product row.\n   * - 'exclusive': price amounts are HT (tax added at checkout)\n   * - 'inclusive': price amounts are TTC (tax embedded)\n   *\n   * It is DECLARATIVE ONLY and does not reach the billing provider. The catalog sync stores it on\n   * the product and then sends each price's own `taxBehavior` unchanged, so a price that declares\n   * none is created without `tax_behavior` regardless of what this field says. To make the\n   * intention effective, set `taxBehavior` on the prices as well.\n   *\n   * Common pattern: org products exclusive, user products inclusive.\n   */\n  taxDisplayMode: z.enum(TaxDisplayMode).optional(),\n\n  /**\n   * Purchase configuration for non-subscription products (ONE_TIME, CREDIT_PACK, ITEM).\n   * Ignored for subscription products (PLAN, ADDON, METERED).\n   */\n  purchaseConfig: z.object({\n    /** Maximum quantity per purchase (for CREDIT_PACK/ITEM). undefined = no limit */\n    maxQuantityPerPurchase: z.number().min(1).optional(),\n    /** For CREDIT_PACK: how many credits per pack unit */\n    creditsPerUnit: z.number().min(1).optional(),\n    /** For CREDIT_PACK: which \"credit pool\" this feeds (e.g., 'ai_tokens', 'sms_credits') */\n    creditPoolKey: z.string().optional(),\n  }).optional(),\n\n  /** Behavior policy: trial, proration, cancellation, metering */\n  behaviorPolicy: ProductBehaviorPolicySchema.optional(),\n\n  /** Provider sync (lazy: populated on first checkout or sync action, NOT at startup) */\n  providerProductId: z.string().optional().isBackendOnly(),\n\n  /** Display sort order in pricing tables */\n  sortOrder: z.number().default(0),\n  /** Whether this product is visible to end users */\n  isPublic: z.boolean().default(true).isSummaryField(),\n  /** Whether this product is available for purchase */\n  isActive: z.boolean().default(true).isDBIndexed().isSummaryField(),\n  metadata: z.record(z.string(), z.string()).optional(),\n\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type Product = z.infer<typeof ProductSchema>;\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"promotions.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/promotions.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;AAM/C,oBAAY,oBAAoB;IAC9B,2DAA2D;IAC3D,KAAK,UAAU;IACf,sDAAsD;IACtD,UAAU,eAAe;CAC1B;AAED,KAAK,iBAAiB,GAClB,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,qDAAqD,GAChE,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;;;;;;;;kBAqH9C,CAAC"}
+{"version":3,"file":"promotions.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/promotions.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;AAM/C,oBAAY,oBAAoB;IAC9B,2DAA2D;IAC3D,KAAK,UAAU;IACf,sDAAsD;IACtD,UAAU,eAAe;CAC1B;AAED,KAAK,iBAAiB,GAClB,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,IAAI,GAC1B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,GAC5B,qBAAqB,CAAC,MAAM,CAAC;AAEjC,eAAO,MAAM,qDAAqD,GAChE,wBAAwB,oBAAoB,EAAE;;;;;;;;;;;;;;;;;;;;;;kBAmJ9C,CAAC"}

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

@@ -7,7 +7,7 @@ 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 { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas.js';
 import { PromotionSchema } from './promotions.shared.schemas.js';
 // ── Custom Operations ────────────────────────────────────────────────
 export var Promotion_Operations;
@@ -41,12 +41,42 @@ export const promotionsResourceConfiguration_InitializationFactory = (resourcesR
                 }],
         },
         [CoreResourceOperation.LIST]: {
-            variants: [{
+            variants: [
+                {
                     variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
                     roles: [CORE_ORG_ROLES.ORG_OWNER],
                     riskLevel: ResourceOperationRiskLevel.LOW,
-                }],
+                },
+                {
+                    /*
+                     * The OPERATOR's door onto the catalogue — added 2026-09-18 for issue #1295.
+                     *
+                     * The `INTERNAL_CALL` variant above is route-less by design: the billing back-office drives
+                     * this resource through the service pipeline, and states that these catalog reads have "NO
+                     * HTTP surface". That stays true and stays the DEFAULT, so `createForInternalServiceOperation`
+                     * keeps resolving it and no internal seam moves.
+                     *
+                     * What was missing is the surface an application ADMINISTRATOR needs. The `billing-catalog`
+                     * settings destination targets `promotions.list` and could never load — the rail entry, the tab and the
+                     * heading all rendered, and every request 404'd at the ROUTER, because no route was ever
+                     * mounted. An operator cannot price what they cannot see.
+                     *
+                     * Gated on `APP_ADMIN_SUPER_ADMIN`, exactly what that destination already requires. Not a
+                     * widening: the aggregated billing state already ships products, prices and active promotions
+                     * to EVERY authenticated client, so an admin-only list is strictly narrower than what the
+                     * application discloses today.
+                     *
+                     * Two `isDefault: true` variants is the shape `organizations.CREATE` already uses — default is
+                     * per variant TYPE, so the internal door and the HTTP door each stay the default of their own
+                     * transport and the HTTP one needs no `variantKey` in its URL.
+                     */
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                },
+            ],
         },
         [CoreResourceOperation.SEARCH]: {
             variants: [{

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

@@ -1 +1 @@
-{"version":3,"file":"promotions.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/promotions.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Promotions Resource Configuration\n *\n * Admin-managed: discount mechanisms synced to provider.\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 { PromotionSchema } from './promotions.shared.schemas';\n\n// ── Custom Operations ────────────────────────────────────────────────\n\nexport enum Promotion_Operations {\n  /** Apply a promotion code (validates and records usage) */\n  APPLY = 'apply',\n  /** Deactivate a promotion (sets isActive to false) */\n  DEACTIVATE = 'deactivate',\n}\n\ntype PromotionsCoreOps =\n  | CoreResourceOperation.READ\n  | CoreResourceOperation.LIST\n  | CoreResourceOperation.SEARCH\n  | CoreResourceOperation.CREATE\n  | CoreResourceOperation.UPDATE;\n\nexport const promotionsResourceConfiguration_InitializationFactory = (\n  resourcesRelationships: ResourceRelationship[]\n) => createResourceConfiguration_Initialization<\n  typeof Promotion_Operations,\n  PromotionsCoreOps,\n  typeof PromotionSchema\n>({\n  mainSchema: PromotionSchema,\n  resourceIdentifier: CoreResourceType.PROMOTIONS,\n  resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.PROMOTIONS],\n  resourceRelationships: resourcesRelationships,\n  isSystemResource: true,\n  customOperation: Promotion_Operations,\n  coreOperations: [\n    CoreResourceOperation.READ,\n    CoreResourceOperation.LIST,\n    CoreResourceOperation.SEARCH,\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        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      }],\n    },\n    [CoreResourceOperation.SEARCH]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n        isSearchable: true,\n        searchableFields: ['name', 'code'],\n        searchableOptions: { caseSensitive: false, fullMatchOnly: false },\n        filterFields: {},\n        sortFields: [],\n        maxPaginatedResultPerPageLimit: 50,\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.MEDIUM,\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.MEDIUM,\n      }],\n    },\n    [Promotion_Operations.APPLY]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_MEMBER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n        resourceOperationLike: CoreResourceOperation.UPDATE,\n        requestDto: z.object({\n          code: z.string().min(1),\n        }),\n        // Borrows UPDATE for its route/verb but returns discount info for the caller,\n        // NOT the Promotion resource row. Without this the service output fails\n        // `transformOutput`'s `internalDto.parse` against the resource schema → 500.\n        customResponseDto: z.object({\n          valid: z.boolean(),\n          promotionId: z.string(),\n          providerCouponId: z.string().nullish(),\n          providerPromotionId: z.string().nullish(),\n          discount: z.object({\n            type: z.string(),\n            percentage: z.number().optional(),\n            // `amount` is a MoneyValue (z_money) — modelled permissively to avoid\n            // pulling the money factory into this response contract.\n            amount: z.unknown().optional(),\n          }),\n        }),\n      }],\n    },\n    [Promotion_Operations.DEACTIVATE]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.MEDIUM,\n        resourceOperationLike: CoreResourceOperation.UPDATE,\n        haveBulkOperation: true,\n        // DEACTIVATE forces `isActive: false` from its prefix implementation and takes no\n        // caller input. Omitting `requestDto` would auto-derive the FULL promotion update DTO\n        // — including `isActive` itself (so \"deactivate\" could re-activate), plus `code`,\n        // `discountPercentage` and `maxRedemptions`. The prefix's return is MERGED onto the\n        // caller payload rather than replacing it, so narrowing here is what actually\n        // constrains the write.\n        requestDto: z.object({}),\n        // Borrows UPDATE for its route/verb but returns a bare `{ isActive }` ack,\n        // NOT the Promotion resource row.\n        customResponseDto: z.object({\n          isActive: z.boolean(),\n        }),\n      }],\n    },\n  },\n});\n"]}
+{"version":3,"file":"promotions.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/promotions.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,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,cAAc,EAAE,MAAM,iDAAiD,CAAC;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,wEAAwE;AAExE,MAAM,CAAN,IAAY,oBAKX;AALD,WAAY,oBAAoB;IAC9B,2DAA2D;IAC3D,uCAAe,CAAA;IACf,sDAAsD;IACtD,iDAAyB,CAAA;AAC3B,CAAC,EALW,oBAAoB,KAApB,oBAAoB,QAK/B;AASD,MAAM,CAAC,MAAM,qDAAqD,GAAG,CACnE,sBAA8C,EAC9C,EAAE,CAAC,0CAA0C,CAI7C;IACA,UAAU,EAAE,eAAe;IAC3B,kBAAkB,EAAE,gBAAgB,CAAC,UAAU;IAC/C,uBAAuB,EAAE,kCAAkC,CAAC,gBAAgB,CAAC,UAAU,CAAC;IACxF,qBAAqB,EAAE,sBAAsB;IAC7C,gBAAgB,EAAE,IAAI;IACtB,eAAe,EAAE,oBAAoB;IACrC,cAAc,EAAE;QACd,qBAAqB,CAAC,IAAI;QAC1B,qBAAqB,CAAC,IAAI;QAC1B,qBAAqB,CAAC,MAAM;QAC5B,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;;;;;;;;;;;;;;;;;;;;;uBAqBG;oBACH,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,qBAAqB,CAAC;oBAC7C,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;oBACzC,YAAY,EAAE,IAAI;oBAClB,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;oBAClC,iBAAiB,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE;oBACjE,YAAY,EAAE,EAAE;oBAChB,UAAU,EAAE,EAAE;oBACd,8BAA8B,EAAE,EAAE;iBACnC,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,MAAM;iBAC7C,CAAC;SACH;QACD,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE;YAC9B,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,aAAa;oBACvD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;oBACjC,SAAS,EAAE,0BAA0B,CAAC,MAAM;iBAC7C,CAAC;SACH;QACD,CAAC,oBAAoB,CAAC,KAAK,CAAC,EAAE;YAC5B,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC;oBAC5D,SAAS,EAAE,0BAA0B,CAAC,GAAG;oBACzC,qBAAqB,EAAE,qBAAqB,CAAC,MAAM;oBACnD,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC;wBACnB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;qBACxB,CAAC;oBACF,8EAA8E;oBAC9E,wEAAwE;oBACxE,6EAA6E;oBAC7E,iBAAiB,EAAE,CAAC,CAAC,MAAM,CAAC;wBAC1B,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE;wBAClB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;wBACvB,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;wBACtC,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;wBACzC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;4BACjB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;4BAChB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;4BACjC,sEAAsE;4BACtE,yDAAyD;4BACzD,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;yBAC/B,CAAC;qBACH,CAAC;iBACH,CAAC;SACH;QACD,CAAC,oBAAoB,CAAC,UAAU,CAAC,EAAE;YACjC,QAAQ,EAAE,CAAC;oBACT,WAAW,EAAE,4BAA4B,CAAC,QAAQ;oBAClD,SAAS,EAAE,IAAI;oBACf,KAAK,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC;oBACjC,SAAS,EAAE,0BAA0B,CAAC,MAAM;oBAC5C,qBAAqB,EAAE,qBAAqB,CAAC,MAAM;oBACnD,iBAAiB,EAAE,IAAI;oBACvB,kFAAkF;oBAClF,sFAAsF;oBACtF,kFAAkF;oBAClF,oFAAoF;oBACpF,8EAA8E;oBAC9E,wBAAwB;oBACxB,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;oBACxB,2EAA2E;oBAC3E,kCAAkC;oBAClC,iBAAiB,EAAE,CAAC,CAAC,MAAM,CAAC;wBAC1B,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;qBACtB,CAAC;iBACH,CAAC;SACH;KACF;CACF,CAAC,CAAC","sourcesContent":["/**\n * Promotions Resource Configuration\n *\n * Admin-managed: discount mechanisms synced to provider.\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_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { PromotionSchema } from './promotions.shared.schemas';\n\n// ── Custom Operations ────────────────────────────────────────────────\n\nexport enum Promotion_Operations {\n  /** Apply a promotion code (validates and records usage) */\n  APPLY = 'apply',\n  /** Deactivate a promotion (sets isActive to false) */\n  DEACTIVATE = 'deactivate',\n}\n\ntype PromotionsCoreOps =\n  | CoreResourceOperation.READ\n  | CoreResourceOperation.LIST\n  | CoreResourceOperation.SEARCH\n  | CoreResourceOperation.CREATE\n  | CoreResourceOperation.UPDATE;\n\nexport const promotionsResourceConfiguration_InitializationFactory = (\n  resourcesRelationships: ResourceRelationship[]\n) => createResourceConfiguration_Initialization<\n  typeof Promotion_Operations,\n  PromotionsCoreOps,\n  typeof PromotionSchema\n>({\n  mainSchema: PromotionSchema,\n  resourceIdentifier: CoreResourceType.PROMOTIONS,\n  resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.PROMOTIONS],\n  resourceRelationships: resourcesRelationships,\n  isSystemResource: true,\n  customOperation: Promotion_Operations,\n  coreOperations: [\n    CoreResourceOperation.READ,\n    CoreResourceOperation.LIST,\n    CoreResourceOperation.SEARCH,\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 OPERATOR's door onto the catalogue — added 2026-09-18 for issue #1295.\n         *\n         * The `INTERNAL_CALL` variant above is route-less by design: the billing back-office drives\n         * this resource through the service pipeline, and states that these catalog reads have \"NO\n         * HTTP surface\". That stays true and stays the DEFAULT, so `createForInternalServiceOperation`\n         * keeps resolving it and no internal seam moves.\n         *\n         * What was missing is the surface an application ADMINISTRATOR needs. The `billing-catalog`\n         * settings destination targets `promotions.list` and could never load — the rail entry, the tab and the\n         * heading all rendered, and every request 404'd at the ROUTER, because no route was ever\n         * mounted. An operator cannot price what they cannot see.\n         *\n         * Gated on `APP_ADMIN_SUPER_ADMIN`, exactly what that destination already requires. Not a\n         * widening: the aggregated billing state already ships products, prices and active promotions\n         * to EVERY authenticated client, so an admin-only list is strictly narrower than what the\n         * application discloses today.\n         *\n         * Two `isDefault: true` variants is the shape `organizations.CREATE` already uses — default is\n         * per variant TYPE, so the internal door and the HTTP door each stay the default of their own\n         * transport and the HTTP one needs no `variantKey` in its URL.\n         */\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n      },\n      ],\n    },\n    [CoreResourceOperation.SEARCH]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n        isSearchable: true,\n        searchableFields: ['name', 'code'],\n        searchableOptions: { caseSensitive: false, fullMatchOnly: false },\n        filterFields: {},\n        sortFields: [],\n        maxPaginatedResultPerPageLimit: 50,\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.MEDIUM,\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.MEDIUM,\n      }],\n    },\n    [Promotion_Operations.APPLY]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_MEMBER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\n        resourceOperationLike: CoreResourceOperation.UPDATE,\n        requestDto: z.object({\n          code: z.string().min(1),\n        }),\n        // Borrows UPDATE for its route/verb but returns discount info for the caller,\n        // NOT the Promotion resource row. Without this the service output fails\n        // `transformOutput`'s `internalDto.parse` against the resource schema → 500.\n        customResponseDto: z.object({\n          valid: z.boolean(),\n          promotionId: z.string(),\n          providerCouponId: z.string().nullish(),\n          providerPromotionId: z.string().nullish(),\n          discount: z.object({\n            type: z.string(),\n            percentage: z.number().optional(),\n            // `amount` is a MoneyValue (z_money) — modelled permissively to avoid\n            // pulling the money factory into this response contract.\n            amount: z.unknown().optional(),\n          }),\n        }),\n      }],\n    },\n    [Promotion_Operations.DEACTIVATE]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.MEDIUM,\n        resourceOperationLike: CoreResourceOperation.UPDATE,\n        haveBulkOperation: true,\n        // DEACTIVATE forces `isActive: false` from its prefix implementation and takes no\n        // caller input. Omitting `requestDto` would auto-derive the FULL promotion update DTO\n        // — including `isActive` itself (so \"deactivate\" could re-activate), plus `code`,\n        // `discountPercentage` and `maxRedemptions`. The prefix's return is MERGED onto the\n        // caller payload rather than replacing it, so narrowing here is what actually\n        // constrains the write.\n        requestDto: z.object({}),\n        // Borrows UPDATE for its route/verb but returns a bare `{ isActive }` ack,\n        // NOT the Promotion resource row.\n        customResponseDto: z.object({\n          isActive: z.boolean(),\n        }),\n      }],\n    },\n  },\n});\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"promotions.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/promotions.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,aAAa,EACb,YAAY,EACZ,iBAAiB,EAClB,MAAM,gCAAgC,CAAC;AAExC,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;iBAkE1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}
+{"version":3,"file":"promotions.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/promotions.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,aAAa,EACb,YAAY,EACZ,iBAAiB,EAClB,MAAM,gCAAgC,CAAC;AAExC,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;iBAkE1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAmD9C,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;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"}

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

@@ -30,12 +30,32 @@ export const referralsResourceConfiguration_InitializationFactory = (resourcesRe
                 }],
         },
         [CoreResourceOperation.LIST]: {
-            variants: [{
+            variants: [
+                {
                     variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
                     roles: [CORE_ORG_ROLES.ORG_OWNER],
                     riskLevel: ResourceOperationRiskLevel.LOW,
-                }],
+                },
+                {
+                    /*
+                     * The TENANT's door onto its own referrals — added 2026-09-18 for issue #1295.
+                     *
+                     * The `INTERNAL_CALL` variant above is route-less and stays the DEFAULT, so the billing
+                     * back-office's service-pipeline reads are untouched. The `organization-referrals` settings
+                     * destination targets this operation and could never load: no route was mounted, so the rail
+                     * 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.
+                     */
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [CORE_ORG_ROLES.ORG_OWNER],
+                    riskLevel: ResourceOperationRiskLevel.LOW,
+                },
+            ],
         },
         [CoreResourceOperation.CREATE]: {
             variants: [{

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,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;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        variantType: ResourceOperationVariantType.INTERNAL_CALL,\n        isDefault: true,\n        roles: [CORE_ORG_ROLES.ORG_OWNER],\n        riskLevel: ResourceOperationRiskLevel.LOW,\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":"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"]}

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

@@ -14,6 +14,7 @@
  * @see billing-and-features-system.md §10 (Referrals)
  */
 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>;

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;AAExB,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;;;;;;;;;;;;;;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"}

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

@@ -14,6 +14,9 @@
  * @see billing-and-features-system.md §10 (Referrals)
  */
 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 { BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS } from './billing-account.shared.schemas.js';

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';\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)\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"]}

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

@@ -16,6 +16,8 @@ export declare enum BillingSubscription_Operations {
     RESUME = "resume",
     /** Change to a different plan (upgrade/downgrade) */
     CHANGE_PLAN = "change_plan",
+    /** Calculate a provider invoice estimate without changing the subscription. */
+    PREVIEW_PLAN_CHANGE = "preview_plan_change",
     /** Add an addon product to the subscription */
     ADD_ADDON = "add_addon",
     /** Remove an addon product from the subscription */
@@ -26,10 +28,30 @@ export declare const BillingSubscription_CancelRequestDto: z.ZodObject<{
     cancelImmediately: z.ZodOptional<z.ZodBoolean>;
     reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-/** Request DTO for CHANGE_PLAN operation — shared between resource config and custom impl */
+/** Selection sent for a provider-computed preview; it does not authorize a change. */
+export declare const BillingSubscription_PreviewPlanChangeRequestDto: z.ZodObject<{
+    newProductKey: z.ZodString;
+    newPriceId: z.ZodString;
+}, z.core.$strip>;
+/** Confirmation must carry the server-issued preview bound to this exact selection. */
 export declare const BillingSubscription_ChangePlanRequestDto: z.ZodObject<{
     newProductKey: z.ZodString;
     newPriceId: z.ZodString;
+    previewToken: z.ZodString;
+}, z.core.$strip>;
+/** Provider invoice estimate plus a short-lived confirmation binding; normal authorization still applies. */
+export declare const BillingSubscription_PlanChangePreviewResponseDto: z.ZodObject<{
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+    lineItems: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        amount: z.ZodNumber;
+        quantity: z.ZodNumber;
+    }, z.core.$strip>>;
+    periodStart: z.ZodCoercedDate<unknown>;
+    periodEnd: z.ZodCoercedDate<unknown>;
+    prorationDate: z.ZodNumber;
+    previewToken: z.ZodString;
 }, z.core.$strip>;
 /** Request DTO for ADD_ADDON operation — shared between resource config and custom impl */
 export declare const BillingSubscription_AddAddonRequestDto: z.ZodObject<{

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;AAczG,oBAAY,8BAA8B;IACxC,6DAA6D;IAC7D,MAAM,WAAW;IACjB,wDAAwD;IACxD,MAAM,WAAW;IACjB,qDAAqD;IACrD,WAAW,gBAAgB;IAC3B,+CAA+C;IAC/C,SAAS,cAAc;IACvB,oDAAoD;IACpD,YAAY,iBAAiB;CAC9B;AAID,wFAAwF;AACxF,eAAO,MAAM,oCAAoC;;;iBAiB/C,CAAC;AAEH,6FAA6F;AAC7F,eAAO,MAAM,wCAAwC;;;iBAGnD,CAAC;AAEH,2FAA2F;AAC3F,eAAO,MAAM,sCAAsC;;;iBAGjD,CAAC;AAEH,8FAA8F;AAC9F,eAAO,MAAM,yCAAyC;;iBAEpD,CAAC;AAMH;;;;;;;;GAQG;AACH,eAAO,MAAM,wCAAwC,iRA4LpD,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;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"}