@wildo-ai/saas-models 1.1.5 → 1.1.6

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

@@ -20,6 +20,8 @@
 import { z } from 'zod';
 import { ResourcePrimaryScope } from '../resources/resources.shared.schemas';
 import { ProductType, PricingModel, BillingInterval, UsageAggregationType, TaxDisplayMode } from './billing-enums.shared.schemas';
+import { ProductPriceDisclosure, ProductAvailability } from './public-pricing-catalog.shared.atoms';
+import { type ProductBehaviorPolicyInput } from './product-behavior-policy.shared.schemas';
 /**
  * Inline price definition for product catalog configuration.
  * Maps to a separate Price DB record when synced.
@@ -50,7 +52,7 @@ export declare const ProductDefinitionSchema: z.ZodObject<{
     targetScopes: z.ZodArray<z.ZodEnum<typeof ResourcePrimaryScope>>;
     grantedFeatures: z.ZodOptional<z.ZodArray<z.ZodString>>;
     grantedLimits: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-        value: z.ZodNumber;
+        value: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodNumber>;
         mode: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").LimitGrantMode>>;
     }, z.core.$strip>>>;
     prices: z.ZodArray<z.ZodObject<{
@@ -106,6 +108,32 @@ export declare const ProductDefinitionSchema: z.ZodObject<{
     }, z.core.$strip>>;
     sortOrder: z.ZodOptional<z.ZodNumber>;
     isPublic: z.ZodOptional<z.ZodBoolean>;
+    isRecommended: z.ZodOptional<z.ZodBoolean>;
+    priceDisclosure: z.ZodOptional<z.ZodEnum<typeof ProductPriceDisclosure>>;
+    availability: z.ZodOptional<z.ZodEnum<typeof ProductAvailability>>;
 }, z.core.$strip>;
-export type ProductDefinition = z.infer<typeof ProductDefinitionSchema>;
+/**
+ * A product as an application authors it. Its `behaviorPolicy` is the policy's INPUT type, so a field the policy
+ * defaults may be omitted; the catalog sync parses it onto the persisted `Product`, where the defaults materialize.
+ * An interface rather than an intersection alias, so declaration emit keeps the name.
+ */
+export interface ProductDefinition extends Omit<z.infer<typeof ProductDefinitionSchema>, 'behaviorPolicy'> {
+    behaviorPolicy?: ProductBehaviorPolicyInput;
+}
+/** The three pricing-surface facts of a product, with every omission resolved. */
+export interface ProductPricingSurfaceFacts {
+    readonly isRecommended: boolean;
+    readonly priceDisclosure: ProductPriceDisclosure;
+    readonly availability: ProductAvailability;
+}
+/**
+ * Resolve a definition's pricing-surface facts, applying the defaults the persisted `Product`
+ * resource declares.
+ *
+ * ONE place for the fallbacks, because two readers need them and must agree: the catalogue sync,
+ * which must WRITE the default rather than leave a field out (an update ignores an absent field, so
+ * a definition that stops recommending a plan would otherwise leave it recommended forever), and a
+ * website build, which reads the definitions directly and never sees a persisted row.
+ */
+export declare function resolveProductPricingSurfaceFacts(definition: Pick<ProductDefinition, 'isRecommended' | 'priceDisclosure' | 'availability'>): ProductPricingSurfaceFacts;
 //# sourceMappingURL=product-definition.shared.schemas.d.ts.map

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;AACxC,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AACpG,OAAO,EAAiD,KAAK,0BAA0B,EAAE,MAAM,0CAA0C,CAAC;AAK1I;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+FlC,CAAC;AAEH;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,EAAE,gBAAgB,CAAC;IACxG,cAAc,CAAC,EAAE,0BAA0B,CAAC;CAC7C;AAED,kFAAkF;AAClF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,sBAAsB,CAAC;IACjD,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,iCAAiC,CAAC,UAAU,EAAE,IAAI,CAAC,iBAAiB,EAAE,eAAe,GAAG,iBAAiB,GAAG,cAAc,CAAC,GAAG,0BAA0B,CAMvK"}

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

@@ -21,6 +21,7 @@ import { z } from 'zod';
 import { z_money, CurrencyAllowed } from '@wildo-ai/zod-decorators';
 import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
 import { ProductType, PricingModel, BillingInterval, UsageAggregationType, TaxDisplayMode, } from './billing-enums.shared.schemas.js';
+import { ProductPriceDisclosure, ProductAvailability } from './public-pricing-catalog.shared.atoms.js';
 import { LimitGrantSchema, ProductBehaviorPolicySchema } from './product-behavior-policy.shared.schemas.js';
 import { PriceTierSchema } from './price.shared.schemas.js';
 // ── Price Definition (inline in product config) ────────────────────
@@ -123,5 +124,39 @@ export const ProductDefinitionSchema = z.object({
      * straight off a `ProductDefinition` must apply the same fallback the resource does.
      */
     isPublic: z.boolean().optional(),
+    // ── Pricing-surface facts ──
+    //
+    // What a pricing page needs beyond the price itself, stated here so every surface that lists the
+    // catalogue — the application's own pricing table and its public website — reads one answer
+    // instead of keeping its own list (#1835). All three are optional for the reason `isPublic`
+    // gives: the persisted `Product` resource carries the defaults.
+    /**
+     * The plan this application recommends to the audience it is designed for, emphasised on a
+     * pricing surface. Omitted = not recommended.
+     *
+     * A RECOMMENDATION, not a popularity claim: nothing here measures what customers chose, so no
+     * surface may word it as "most popular". Recommend at most one plan per scope a surface lists.
+     */
+    isRecommended: z.boolean().optional(),
+    /** How much of this product's price a pricing surface may state. Omitted = `LISTED`. */
+    priceDisclosure: z.enum(ProductPriceDisclosure).optional(),
+    /** Whether this product can be bought today. Omitted = `AVAILABLE`. */
+    availability: z.enum(ProductAvailability).optional(),
 });
+/**
+ * Resolve a definition's pricing-surface facts, applying the defaults the persisted `Product`
+ * resource declares.
+ *
+ * ONE place for the fallbacks, because two readers need them and must agree: the catalogue sync,
+ * which must WRITE the default rather than leave a field out (an update ignores an absent field, so
+ * a definition that stops recommending a plan would otherwise leave it recommended forever), and a
+ * website build, which reads the definitions directly and never sees a persisted row.
+ */
+export function resolveProductPricingSurfaceFacts(definition) {
+    return {
+        isRecommended: definition.isRecommended ?? false,
+        priceDisclosure: definition.priceDisclosure ?? ProductPriceDisclosure.LISTED,
+        availability: definition.availability ?? ProductAvailability.AVAILABLE,
+    };
+}
 //# sourceMappingURL=product-definition.shared.schemas.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"product-definition.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/product-definition.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Product Definition Schema (Shared)\n *\n * The bridge between what developers write in the product catalog config\n * and the DB-level Product + Price schemas.\n *\n * Unlike ProductSchema (the DB record), ProductDefinition:\n * - Has prices INLINE (not separate records)\n * - Has no _id, providerProductId, or DB timestamps\n * - Uses `key` as the unique identifier (maps to Product.key in DB)\n *\n * ProductCatalogSyncBackendService.ensureProductSynced(key):\n *   1. Look up ProductDefinition from catalog config by key\n *   2. Upsert Product DB record (key → _id mapping)\n *   3. Upsert Price DB records for each inline price\n *   4. On first provider use: sync to billing provider (fill providerProductId/providerPriceId)\n *\n * @see billing-and-features-system.md §6.2b (Product Definition)\n */\n\nimport { z } from 'zod';\nimport { z_money, CurrencyAllowed } from '@wildo-ai/zod-decorators';\nimport { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\nimport {\n  ProductType,\n  PricingModel,\n  BillingInterval,\n  UsageAggregationType,\n  TaxDisplayMode,\n} from './billing-enums.shared.schemas';\nimport { LimitGrantSchema, ProductBehaviorPolicySchema } from './product-behavior-policy.shared.schemas';\nimport { PriceTierSchema } from './price.shared.schemas';\n\n// ── Price Definition (inline in product config) ────────────────────\n\n/**\n * Inline price definition for product catalog configuration.\n * Maps to a separate Price DB record when synced.\n */\nexport const PriceDefinitionSchema = z.object({\n  /** Pricing model (flat, per_unit, tiered, graduated, package) */\n  model: z.enum(PricingModel),\n  /**\n   * Unit price for FLAT/PER_UNIT models.\n   * Uses z_money for consistent monetary representation across the billing system.\n   * Undefined for TIERED/GRADUATED models (use `tiers` instead).\n   */\n  unitPrice: z_money({ currenciesAllowed: [CurrencyAllowed.FIAT], minAmount: 0n }),\n  /** Billing interval (undefined = one-time) */\n  interval: z.enum(BillingInterval).optional(),\n  /** Interval count (e.g., 3 for quarterly = interval:'month', intervalCount:3) */\n  intervalCount: z.number().min(1).default(1),\n  /** Tiers for TIERED/GRADUATED pricing models */\n  tiers: z.array(PriceTierSchema).optional(),\n  /** Package size for PACKAGE pricing model */\n  packageSize: z.number().min(1).optional(),\n  /** Usage aggregation for metered prices */\n  usageAggregation: z.enum(UsageAggregationType).optional(),\n  /** Per-price tax behavior override */\n  taxBehavior: z.enum(TaxDisplayMode).optional(),\n  /** Whether this is the default price */\n  isDefault: z.boolean().default(true),\n});\n\nexport type PriceDefinition = z.infer<typeof PriceDefinitionSchema>;\n\n// ── Product Definition (what developers write) ─────────────────────\n\n/**\n * ProductDefinition: what custom app developers write in their product catalog config.\n * This is the declarative product definition that lives in shared-lib code.\n */\nexport const ProductDefinitionSchema = z.object({\n  /** Unique product key (matches Product.key in DB) */\n  key: z.string().min(1),\n  type: z.enum(ProductType),\n\n  /** Which scopes can subscribe/purchase this product */\n  targetScopes: z.array(z.enum(ResourcePrimaryScope)).min(1),\n\n  /**\n   * Features this product grants (boolean features: present = enabled).\n   * Optional — omit to grant none. See the defaults note on `isPublic`.\n   */\n  grantedFeatures: z.array(z.string()).optional(),\n  /**\n   * Limits this product grants, with mode (SET for plans, ADD for addons).\n   * Optional — omit to grant none. See the defaults note on `isPublic`.\n   */\n  grantedLimits: z.record(z.string(), LimitGrantSchema).optional(),\n\n  /** Inline price definitions (transformed into separate Price records on sync) */\n  prices: z.array(PriceDefinitionSchema).min(1),\n\n  /** Behavior policy (trial, proration, cancellation, metering) */\n  behaviorPolicy: ProductBehaviorPolicySchema.optional(),\n\n  // ── PLAN-specific ──\n  /** Tier identifier for mutual exclusion (e.g., 'free', 'professional', 'enterprise') */\n  planTier: z.string().optional(),\n  /** Tier sort order (higher = higher tier, for upgrade/downgrade direction) */\n  planTierOrder: z.number().optional(),\n\n  // ── ADDON-specific ──\n  /** Required plan tiers to subscribe (empty/undefined = no restriction) */\n  requiredPlanTiers: z.array(z.string()).optional(),\n\n  // ── Tax ──\n  /** Per-product tax display override */\n  taxDisplayMode: z.enum(TaxDisplayMode).optional(),\n\n  // ── Non-subscription specific ──\n  /** Purchase config for ONE_TIME/CREDIT_PACK/ITEM products */\n  purchaseConfig: z.object({\n    maxQuantityPerPurchase: z.number().min(1).optional(),\n    creditsPerUnit: z.number().min(1).optional(),\n    creditPoolKey: z.string().optional(),\n  }).optional(),\n\n  /**\n   * Sort order in pricing tables. Optional — see the defaults note on `isPublic`.\n   */\n  sortOrder: z.number().optional(),\n  /**\n   * Show in public pricing pages. Optional — omitting it yields a PUBLIC product,\n   * because the persisted resource defaults it to `true`.\n   *\n   * WHY `.optional()` AND NOT `.default(...)`\n   * This schema is a declarative authoring surface: an application hand-writes\n   * `const PLAN: ProductDefinition = { ... }` and nothing ever calls\n   * `ProductDefinitionSchema.parse()` on it. A `.default(...)` here would be dead\n   * code that never runs, while `z.infer` would still type the field as REQUIRED —\n   * so every app author was forced to hand-write `isPublic: true`, `grantedLimits: {}`\n   * and friends purely to satisfy the compiler.\n   *\n   * The real defaults live one layer down, on the PERSISTED `Product` resource\n   * (`product.shared.schemas.ts`), which mirrors all four of these fields with\n   * identical default values and IS parsed on write. `ProductCatalogSyncBackendService`\n   * maps this definition into a `Partial<Product>`, so an omitted field arrives as\n   * `undefined` and the resource default materializes it — `grantedFeatures: []`,\n   * `grantedLimits: {}`, `sortOrder: 0`, `isPublic: true`.\n   *\n   * Do NOT \"restore\" `.default(...)` here to make the type look tidier: that would\n   * re-assert a guarantee nothing enforces at this layer. Any consumer reading these\n   * straight off a `ProductDefinition` must apply the same fallback the resource does.\n   */\n  isPublic: z.boolean().optional(),\n});\n\nexport type ProductDefinition = z.infer<typeof ProductDefinitionSchema>;\n"]}
+{"version":3,"file":"product-definition.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/product-definition.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Product Definition Schema (Shared)\n *\n * The bridge between what developers write in the product catalog config\n * and the DB-level Product + Price schemas.\n *\n * Unlike ProductSchema (the DB record), ProductDefinition:\n * - Has prices INLINE (not separate records)\n * - Has no _id, providerProductId, or DB timestamps\n * - Uses `key` as the unique identifier (maps to Product.key in DB)\n *\n * ProductCatalogSyncBackendService.ensureProductSynced(key):\n *   1. Look up ProductDefinition from catalog config by key\n *   2. Upsert Product DB record (key → _id mapping)\n *   3. Upsert Price DB records for each inline price\n *   4. On first provider use: sync to billing provider (fill providerProductId/providerPriceId)\n *\n * @see billing-and-features-system.md §6.2b (Product Definition)\n */\n\nimport { z } from 'zod';\nimport { z_money, CurrencyAllowed } from '@wildo-ai/zod-decorators';\nimport { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\nimport {\n  ProductType,\n  PricingModel,\n  BillingInterval,\n  UsageAggregationType,\n  TaxDisplayMode,\n} from './billing-enums.shared.schemas';\nimport { ProductPriceDisclosure, ProductAvailability } from './public-pricing-catalog.shared.atoms';\nimport { LimitGrantSchema, ProductBehaviorPolicySchema, type ProductBehaviorPolicyInput } from './product-behavior-policy.shared.schemas';\nimport { PriceTierSchema } from './price.shared.schemas';\n\n// ── Price Definition (inline in product config) ────────────────────\n\n/**\n * Inline price definition for product catalog configuration.\n * Maps to a separate Price DB record when synced.\n */\nexport const PriceDefinitionSchema = z.object({\n  /** Pricing model (flat, per_unit, tiered, graduated, package) */\n  model: z.enum(PricingModel),\n  /**\n   * Unit price for FLAT/PER_UNIT models.\n   * Uses z_money for consistent monetary representation across the billing system.\n   * Undefined for TIERED/GRADUATED models (use `tiers` instead).\n   */\n  unitPrice: z_money({ currenciesAllowed: [CurrencyAllowed.FIAT], minAmount: 0n }),\n  /** Billing interval (undefined = one-time) */\n  interval: z.enum(BillingInterval).optional(),\n  /** Interval count (e.g., 3 for quarterly = interval:'month', intervalCount:3) */\n  intervalCount: z.number().min(1).default(1),\n  /** Tiers for TIERED/GRADUATED pricing models */\n  tiers: z.array(PriceTierSchema).optional(),\n  /** Package size for PACKAGE pricing model */\n  packageSize: z.number().min(1).optional(),\n  /** Usage aggregation for metered prices */\n  usageAggregation: z.enum(UsageAggregationType).optional(),\n  /** Per-price tax behavior override */\n  taxBehavior: z.enum(TaxDisplayMode).optional(),\n  /** Whether this is the default price */\n  isDefault: z.boolean().default(true),\n});\n\nexport type PriceDefinition = z.infer<typeof PriceDefinitionSchema>;\n\n// ── Product Definition (what developers write) ─────────────────────\n\n/**\n * ProductDefinition: what custom app developers write in their product catalog config.\n * This is the declarative product definition that lives in shared-lib code.\n */\nexport const ProductDefinitionSchema = z.object({\n  /** Unique product key (matches Product.key in DB) */\n  key: z.string().min(1),\n  type: z.enum(ProductType),\n\n  /** Which scopes can subscribe/purchase this product */\n  targetScopes: z.array(z.enum(ResourcePrimaryScope)).min(1),\n\n  /**\n   * Features this product grants (boolean features: present = enabled).\n   * Optional — omit to grant none. See the defaults note on `isPublic`.\n   */\n  grantedFeatures: z.array(z.string()).optional(),\n  /**\n   * Limits this product grants, with mode (SET for plans, ADD for addons).\n   * Optional — omit to grant none. See the defaults note on `isPublic`.\n   */\n  grantedLimits: z.record(z.string(), LimitGrantSchema).optional(),\n\n  /** Inline price definitions (transformed into separate Price records on sync) */\n  prices: z.array(PriceDefinitionSchema).min(1),\n\n  /** Behavior policy (trial, proration, cancellation, metering) */\n  behaviorPolicy: ProductBehaviorPolicySchema.optional(),\n\n  // ── PLAN-specific ──\n  /** Tier identifier for mutual exclusion (e.g., 'free', 'professional', 'enterprise') */\n  planTier: z.string().optional(),\n  /** Tier sort order (higher = higher tier, for upgrade/downgrade direction) */\n  planTierOrder: z.number().optional(),\n\n  // ── ADDON-specific ──\n  /** Required plan tiers to subscribe (empty/undefined = no restriction) */\n  requiredPlanTiers: z.array(z.string()).optional(),\n\n  // ── Tax ──\n  /** Per-product tax display override */\n  taxDisplayMode: z.enum(TaxDisplayMode).optional(),\n\n  // ── Non-subscription specific ──\n  /** Purchase config for ONE_TIME/CREDIT_PACK/ITEM products */\n  purchaseConfig: z.object({\n    maxQuantityPerPurchase: z.number().min(1).optional(),\n    creditsPerUnit: z.number().min(1).optional(),\n    creditPoolKey: z.string().optional(),\n  }).optional(),\n\n  /**\n   * Sort order in pricing tables. Optional — see the defaults note on `isPublic`.\n   */\n  sortOrder: z.number().optional(),\n  /**\n   * Show in public pricing pages. Optional — omitting it yields a PUBLIC product,\n   * because the persisted resource defaults it to `true`.\n   *\n   * WHY `.optional()` AND NOT `.default(...)`\n   * This schema is a declarative authoring surface: an application hand-writes\n   * `const PLAN: ProductDefinition = { ... }` and nothing ever calls\n   * `ProductDefinitionSchema.parse()` on it. A `.default(...)` here would be dead\n   * code that never runs, while `z.infer` would still type the field as REQUIRED —\n   * so every app author was forced to hand-write `isPublic: true`, `grantedLimits: {}`\n   * and friends purely to satisfy the compiler.\n   *\n   * The real defaults live one layer down, on the PERSISTED `Product` resource\n   * (`product.shared.schemas.ts`), which mirrors all four of these fields with\n   * identical default values and IS parsed on write. `ProductCatalogSyncBackendService`\n   * maps this definition into a `Partial<Product>`, so an omitted field arrives as\n   * `undefined` and the resource default materializes it — `grantedFeatures: []`,\n   * `grantedLimits: {}`, `sortOrder: 0`, `isPublic: true`.\n   *\n   * Do NOT \"restore\" `.default(...)` here to make the type look tidier: that would\n   * re-assert a guarantee nothing enforces at this layer. Any consumer reading these\n   * straight off a `ProductDefinition` must apply the same fallback the resource does.\n   */\n  isPublic: z.boolean().optional(),\n\n  // ── Pricing-surface facts ──\n  //\n  // What a pricing page needs beyond the price itself, stated here so every surface that lists the\n  // catalogue — the application's own pricing table and its public website — reads one answer\n  // instead of keeping its own list (#1835). All three are optional for the reason `isPublic`\n  // gives: the persisted `Product` resource carries the defaults.\n\n  /**\n   * The plan this application recommends to the audience it is designed for, emphasised on a\n   * pricing surface. Omitted = not recommended.\n   *\n   * A RECOMMENDATION, not a popularity claim: nothing here measures what customers chose, so no\n   * surface may word it as \"most popular\". Recommend at most one plan per scope a surface lists.\n   */\n  isRecommended: z.boolean().optional(),\n  /** How much of this product's price a pricing surface may state. Omitted = `LISTED`. */\n  priceDisclosure: z.enum(ProductPriceDisclosure).optional(),\n  /** Whether this product can be bought today. Omitted = `AVAILABLE`. */\n  availability: z.enum(ProductAvailability).optional(),\n});\n\n/**\n * A product as an application authors it. Its `behaviorPolicy` is the policy's INPUT type, so a field the policy\n * defaults may be omitted; the catalog sync parses it onto the persisted `Product`, where the defaults materialize.\n * An interface rather than an intersection alias, so declaration emit keeps the name.\n */\nexport interface ProductDefinition extends Omit<z.infer<typeof ProductDefinitionSchema>, 'behaviorPolicy'> {\n  behaviorPolicy?: ProductBehaviorPolicyInput;\n}\n\n/** The three pricing-surface facts of a product, with every omission resolved. */\nexport interface ProductPricingSurfaceFacts {\n  readonly isRecommended: boolean;\n  readonly priceDisclosure: ProductPriceDisclosure;\n  readonly availability: ProductAvailability;\n}\n\n/**\n * Resolve a definition's pricing-surface facts, applying the defaults the persisted `Product`\n * resource declares.\n *\n * ONE place for the fallbacks, because two readers need them and must agree: the catalogue sync,\n * which must WRITE the default rather than leave a field out (an update ignores an absent field, so\n * a definition that stops recommending a plan would otherwise leave it recommended forever), and a\n * website build, which reads the definitions directly and never sees a persisted row.\n */\nexport function resolveProductPricingSurfaceFacts(definition: Pick<ProductDefinition, 'isRecommended' | 'priceDisclosure' | 'availability'>): ProductPricingSurfaceFacts {\n  return {\n    isRecommended: definition.isRecommended ?? false,\n    priceDisclosure: definition.priceDisclosure ?? ProductPriceDisclosure.LISTED,\n    availability: definition.availability ?? ProductAvailability.AVAILABLE,\n  };\n}\n"]}

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

@@ -11,9 +11,9 @@ export declare const productsResourceConfiguration_InitializationFactory: (resou
     type: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodEnum<typeof import("./billing-enums.shared.schemas").ProductType>>>>>;
     key: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodString>>>;
     targetScopes: import("zod").ZodArray<import("zod").ZodEnum<typeof import("..").ResourcePrimaryScope>>;
-    grantedFeatures: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodArray<import("zod").ZodString>>>;
-    grantedLimits: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodObject<{
-        value: import("zod").ZodNumber;
+    grantedFeatures: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodArray<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodString>>>>;
+    grantedLimits: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodRecord<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodString>, import("zod").ZodObject<{
+        value: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodNumber>;
         mode: import("zod").ZodDefault<import("zod").ZodEnum<typeof import("./billing-enums.shared.schemas").LimitGrantMode>>;
     }, import("zod/v4/core").$strip>>>>;
     planTier: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodOptional<import("zod").ZodString>>;
@@ -56,6 +56,9 @@ export declare const productsResourceConfiguration_InitializationFactory: (resou
     sortOrder: import("zod").ZodDefault<import("zod").ZodNumber>;
     isPublic: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodBoolean>>;
     isActive: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodBoolean>>>;
+    isRecommended: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodBoolean>>>;
+    priceDisclosure: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodEnum<typeof import("./public-pricing-catalog.shared.atoms").ProductPriceDisclosure>>>>;
+    availability: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodEnum<typeof import("./public-pricing-catalog.shared.atoms").ProductAvailability>>>>>;
     metadata: import("zod").ZodOptional<import("zod").ZodRecord<import("zod").ZodString, import("zod").ZodString>>;
     createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodDate>>>;
     updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("zod").ZodDefault<import("zod").ZodDate>>>;

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iCAgG9C,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.schemas.d.ts

@@ -20,14 +20,15 @@ import { z } from 'zod';
 import '@wildo-ai/zod-decorators';
 import { ResourcePrimaryScope } from '../resources/resources.shared.schemas';
 import { ProductType, TaxDisplayMode } from './billing-enums.shared.schemas';
+import { ProductPriceDisclosure, ProductAvailability } from './public-pricing-catalog.shared.atoms';
 export declare const ProductSchema: z.ZodObject<{
     _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
     type: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodEnum<typeof ProductType>>>>>;
     key: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>;
     targetScopes: z.ZodArray<z.ZodEnum<typeof ResourcePrimaryScope>>;
-    grantedFeatures: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodArray<z.ZodString>>>;
-    grantedLimits: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
-        value: z.ZodNumber;
+    grantedFeatures: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodArray<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;
+    grantedLimits: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodRecord<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>, z.ZodObject<{
+        value: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodNumber>;
         mode: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").LimitGrantMode>>;
     }, z.core.$strip>>>>;
     planTier: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
@@ -70,6 +71,9 @@ export declare const ProductSchema: z.ZodObject<{
     sortOrder: z.ZodDefault<z.ZodNumber>;
     isPublic: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>;
     isActive: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>>;
+    isRecommended: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>>;
+    priceDisclosure: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof ProductPriceDisclosure>>>>;
+    availability: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof ProductAvailability>>>>>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>;
     updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>;

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;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"}
+{"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;AAElC,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EACL,WAAW,EACX,cAAc,EACf,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAIpG,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4FxB,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

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

@@ -20,8 +20,10 @@ 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 { SectionedVocabulary } from '@wildo-ai/presets-components-models';
 import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
 import { ProductType, TaxDisplayMode, } from './billing-enums.shared.schemas.js';
+import { ProductPriceDisclosure, ProductAvailability } from './public-pricing-catalog.shared.atoms.js';
 import { LimitGrantSchema } from './product-behavior-policy.shared.schemas.js';
 import { ProductBehaviorPolicySchema } from './product-behavior-policy.shared.schemas.js';
 export const ProductSchema = z.object({
@@ -32,7 +34,7 @@ export const ProductSchema = z.object({
     /** Which scopes can subscribe to this product (code-driven, not user-editable) */
     targetScopes: z.array(z.enum(ResourcePrimaryScope)).min(1),
     /** Features this product grants (boolean: present = enabled) */
-    grantedFeatures: z.array(z.string()).default([]).isNotEditable(),
+    grantedFeatures: z.array(z.string().systemEnum(SectionedVocabulary.FEATURE)).default([]).isNotEditable(),
     /**
      * Limits this product grants, with aggregation mode.
      * - SET: absolute value (for PLAN products: "Professional gives you 50 projects")
@@ -44,7 +46,7 @@ export const ProductSchema = z.object({
      *   3. For each active ADDON with SET mode: take max(current, addon value)
      *   4. FEATURES_UNLIMITED always wins in any comparison
      */
-    grantedLimits: z.record(z.string(), LimitGrantSchema).default({}).isNotEditable(),
+    grantedLimits: z.record(z.string().systemEnum(SectionedVocabulary.LIMIT), LimitGrantSchema).default({}).isNotEditable(),
     /** For PLAN type: mutually exclusive tier ordering (higher number = higher tier) */
     planTier: z.string().optional().isSummaryField(),
     /** For PLAN type: tier sort order (used for upgrade/downgrade direction detection) */
@@ -69,12 +71,16 @@ export const ProductSchema = z.object({
      * Ignored for subscription products (PLAN, ADDON, METERED).
      */
     purchaseConfig: z.object({
-        /** Maximum quantity per purchase (for CREDIT_PACK/ITEM). undefined = no limit */
-        maxQuantityPerPurchase: z.number().min(1).optional(),
+        /**
+         * The most units one purchase may carry (for ONE_TIME/CREDIT_PACK/ITEM). Absent means no cap beyond the
+         * checkout's own bound. ENFORCED since #1798: opening a checkout for more is refused with
+         * `BILLING_PURCHASE_QUANTITY_EXCEEDS_LIMIT` (422). Nothing read it before.
+         */
+        maxQuantityPerPurchase: z.number().int().min(1).optional().describe("The most units one purchase of this product may carry. Opening a checkout for more is refused. Absent means no cap beyond the checkout's own bound. Ignored for subscription products."),
         /** For CREDIT_PACK: how many credits per pack unit */
-        creditsPerUnit: z.number().min(1).optional(),
+        creditsPerUnit: z.number().min(1).optional().describe("For a credit pack, how many credits each unit bought adds to the credit pool. Defaults to 1."),
         /** For CREDIT_PACK: which "credit pool" this feeds (e.g., 'ai_tokens', 'sms_credits') */
-        creditPoolKey: z.string().optional(),
+        creditPoolKey: z.string().optional().describe("For a credit pack, the key of the credit pool a completed purchase adds credits to. A credit pack without one grants no credits."),
     }).optional(),
     /** Behavior policy: trial, proration, cancellation, metering */
     behaviorPolicy: ProductBehaviorPolicySchema.optional(),
@@ -84,8 +90,17 @@ export const ProductSchema = z.object({
     sortOrder: z.number().default(0),
     /** Whether this product is visible to end users */
     isPublic: z.boolean().default(true).isSummaryField(),
-    /** Whether this product is available for purchase */
+    /**
+     * Whether this product is RETIRED (`false`): withdrawn from the code catalogue, no longer sold or
+     * offered. Not the same question as `availability`, which announces a product not yet on sale.
+     */
     isActive: z.boolean().default(true).isDBIndexed().isSummaryField(),
+    /** The plan this application recommends on pricing surfaces — a recommendation, never a popularity claim. */
+    isRecommended: z.boolean().default(false).isNotEditable().isSummaryField(),
+    /** How much of this product's price a pricing surface may state (display only; not an acquisition gate). */
+    priceDisclosure: z.enum(ProductPriceDisclosure).default(ProductPriceDisclosure.LISTED).isNotEditable().systemEnum('ProductPriceDisclosure'),
+    /** Whether this product can be bought today; `UPCOMING` is listed and refused at every acquisition door. */
+    availability: z.enum(ProductAvailability).default(ProductAvailability.AVAILABLE).isNotEditable().isSummaryField().systemEnum('ProductAvailability'),
     metadata: z.record(z.string(), z.string()).optional(),
     createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
     updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),

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';\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"]}
+{"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 { SectionedVocabulary } from '@wildo-ai/presets-components-models';\nimport { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\nimport {\n  ProductType,\n  TaxDisplayMode,\n} from './billing-enums.shared.schemas';\nimport { ProductPriceDisclosure, ProductAvailability } from './public-pricing-catalog.shared.atoms';\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().systemEnum(SectionedVocabulary.FEATURE)).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().systemEnum(SectionedVocabulary.LIMIT), 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    /**\n     * The most units one purchase may carry (for ONE_TIME/CREDIT_PACK/ITEM). Absent means no cap beyond the\n     * checkout's own bound. ENFORCED since #1798: opening a checkout for more is refused with\n     * `BILLING_PURCHASE_QUANTITY_EXCEEDS_LIMIT` (422). Nothing read it before.\n     */\n    maxQuantityPerPurchase: z.number().int().min(1).optional().describe(\"The most units one purchase of this product may carry. Opening a checkout for more is refused. Absent means no cap beyond the checkout's own bound. Ignored for subscription products.\"),\n    /** For CREDIT_PACK: how many credits per pack unit */\n    creditsPerUnit: z.number().min(1).optional().describe(\"For a credit pack, how many credits each unit bought adds to the credit pool. Defaults to 1.\"),\n    /** For CREDIT_PACK: which \"credit pool\" this feeds (e.g., 'ai_tokens', 'sms_credits') */\n    creditPoolKey: z.string().optional().describe(\"For a credit pack, the key of the credit pool a completed purchase adds credits to. A credit pack without one grants no credits.\"),\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  /**\n   * Whether this product is RETIRED (`false`): withdrawn from the code catalogue, no longer sold or\n   * offered. Not the same question as `availability`, which announces a product not yet on sale.\n   */\n  isActive: z.boolean().default(true).isDBIndexed().isSummaryField(),\n\n  /** The plan this application recommends on pricing surfaces — a recommendation, never a popularity claim. */\n  isRecommended: z.boolean().default(false).isNotEditable().isSummaryField(),\n  /** How much of this product's price a pricing surface may state (display only; not an acquisition gate). */\n  priceDisclosure: z.enum(ProductPriceDisclosure).default(ProductPriceDisclosure.LISTED).isNotEditable().systemEnum('ProductPriceDisclosure'),\n  /** Whether this product can be bought today; `UPCOMING` is listed and refused at every acquisition door. */\n  availability: z.enum(ProductAvailability).default(ProductAvailability.AVAILABLE).isNotEditable().isSummaryField().systemEnum('ProductAvailability'),\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.js

@@ -122,17 +122,17 @@ export const promotionsResourceConfiguration_InitializationFactory = (resourcesR
                     // NOT the Promotion resource row. Without this the service output fails
                     // `transformOutput`'s `internalDto.parse` against the resource schema → 500.
                     customResponseDto: z.object({
-                        valid: z.boolean(),
-                        promotionId: z.string(),
-                        providerCouponId: z.string().nullish(),
-                        providerPromotionId: z.string().nullish(),
+                        valid: z.boolean().describe("Always `true`. A promotion that cannot be used is refused with an error instead."),
+                        promotionId: z.string().describe("The id of the promotion that was checked."),
+                        providerCouponId: z.string().nullish().describe("The billing provider's id for the coupon behind the promotion. Absent when the promotion is not set up with the provider, in which case checkout refuses its code."),
+                        providerPromotionId: z.string().nullish().describe("The billing provider's id for the promotion code. Present only for a promotion with a code that is set up with the provider."),
                         discount: z.object({
-                            type: z.string(),
-                            percentage: z.number().optional(),
+                            type: z.string().describe("The kind of discount: `percentage` or `fixed_amount`."),
+                            percentage: z.number().optional().describe("For a `percentage` discount, the percentage taken off, from 0 to 100."),
                             // `amount` is a MoneyValue (z_money) — modelled permissively to avoid
                             // pulling the money factory into this response contract.
-                            amount: z.unknown().optional(),
-                        }),
+                            amount: z.unknown().optional().describe("For a `fixed_amount` discount, the amount taken off, as a money value with `amount`, `currency` and `decimals`."),
+                        }).describe("The discount the promotion gives. Checking a code does not redeem it: a redemption is counted when a checkout using the code completes."),
                     }),
                 }],
         },

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_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"]}
+{"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_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().describe(\"Always `true`. A promotion that cannot be used is refused with an error instead.\"),\n          promotionId: z.string().describe(\"The id of the promotion that was checked.\"),\n          providerCouponId: z.string().nullish().describe(\"The billing provider's id for the coupon behind the promotion. Absent when the promotion is not set up with the provider, in which case checkout refuses its code.\"),\n          providerPromotionId: z.string().nullish().describe(\"The billing provider's id for the promotion code. Present only for a promotion with a code that is set up with the provider.\"),\n          discount: z.object({\n            type: z.string().describe(\"The kind of discount: `percentage` or `fixed_amount`.\"),\n            percentage: z.number().optional().describe(\"For a `percentage` discount, the percentage taken off, from 0 to 100.\"),\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().describe(\"For a `fixed_amount` discount, the amount taken off, as a money value with `amount`, `currency` and `decimals`.\"),\n          }).describe(\"The discount the promotion gives. Checking a code does not redeem it: a redemption is counted when a checkout using the code completes.\"),\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/public-pricing-catalog.shared.atoms.d.ts

@@ -0,0 +1,135 @@
+/**
+ * The PUBLIC pricing catalogue: what a pricing surface outside the application (the public website)
+ * may know about the application's billing catalogue, as plain JSON-safe data (#1835).
+ *
+ * ## Why this file imports nothing
+ *
+ * It is an ATOM on the `@wildo-ai/saas-models/public-runtime` seam. The website's pricing section is a
+ * browser island, and the billing vocabulary it would otherwise need (`ProductType`, `BillingInterval`,
+ * `PricingModel`) lives behind the decorator-framework root barrel and the provider models, neither of
+ * which may reach a browser bundle. So the catalogue is DERIVED on the build side, where those
+ * vocabularies are available (`derivePublicPricingCatalog` in `./public-pricing-catalog.shared`), and
+ * crosses into the browser as the plain shape declared here.
+ *
+ * ## Why a price carries `amountMinor` as a STRING
+ *
+ * A `z_money` amount is a `bigint` in minor units. A bigint does not survive `JSON.stringify` (it
+ * throws), and the catalogue crosses Astro's island serialization boundary, so it travels as the
+ * decimal digits of that integer — lossless, where a `number` would not be for large amounts.
+ */
+/** @wildo_source:part:start saas.models.billing.catalog-vocabularies facet:layer:shared facet:audience:app-developer */
+/**
+ * How much of a product's price a pricing surface may state.
+ *
+ * The catalogue always carries typed prices — a product cannot sync to the billing provider
+ * without one — but a commercial offer is not always fully decided by them. A plan sold as "per
+ * member, plus a platform fee we quote" has a real unit price and an unsettled total; an
+ * enterprise plan sold by a sales conversation may carry a placeholder price nobody should read.
+ * Before this vocabulary existed, every pricing surface either printed that price as if it were
+ * the whole offer, or kept its own hand-written list of exceptions (#1835).
+ *
+ * This is a DISPLAY fact and deliberately NOT an acquisition gate: a customer handed a checkout
+ * link for an on-request plan by a salesperson must still be able to pay it, for the same reason a
+ * private-but-active plan stays purchasable. Whether the product can
+ * be bought today is {@link ProductAvailability}'s question.
+ */
+export declare enum ProductPriceDisclosure {
+    /** The listed prices ARE the offer: a pricing page states them, and structured data may publish them. */
+    LISTED = "listed",
+    /**
+     * The listed price is a FLOOR: part of the total is not settled (a quoted fee, a volume term).
+     * A pricing page states it as a starting price, and structured data must not publish it as the
+     * price, because a search engine would show it as the whole offer.
+     */
+    STARTING_AT = "starting_at",
+    /** No price is stated: the offer is quoted on request (a "contact sales" plan). */
+    ON_REQUEST = "on_request"
+}
+/**
+ * Whether a product can be bought today.
+ *
+ * Distinct from `Product.isActive`, which is RETIREMENT — a product the catalogue withdrew, no
+ * longer sold and no longer offered. An UPCOMING product is the opposite end of the same life: it is
+ * announced on pricing surfaces so a visitor can see where the product is going, and it cannot be
+ * bought yet. Folding it into `isActive: false` would hide it from the very pages that announce it.
+ */
+export declare enum ProductAvailability {
+    /** On sale: the acquisition doors accept it (subject to retirement). */
+    AVAILABLE = "available",
+    /** Announced, not yet on sale: listed on pricing surfaces, refused at every acquisition door. */
+    UPCOMING = "upcoming"
+}
+/** @wildo_source:part:end saas.models.billing.catalog-vocabularies */
+/**
+ * How a public price RECURS, as a pricing page states it.
+ *
+ * Not a copy of the provider's `BillingInterval`: that vocabulary has no member for a one-time price
+ * (an absent interval means one-time), and this one must name it, because "once" and "per month" are
+ * different sentences on a pricing page. Every `BillingInterval` member maps onto one of these in
+ * `derivePublicPricingCatalog`, through a table that is total over it.
+ */
+export declare enum PublicPricingRecurrenceUnit {
+    /** Paid once — no recurrence. */
+    ONE_TIME = "one_time",
+    /** Recurs every `count` months. */
+    MONTH = "month",
+    /** Recurs every `count` years. */
+    YEAR = "year"
+}
+/**
+ * What one public price amount MEANS.
+ *
+ * A single amount can state a flat price or a per-unit price. It cannot state a tiered, graduated or
+ * package price, whose total depends on quantity; for those the amount is indicative only, so no
+ * surface may present it — or publish it in structured data — as the price.
+ */
+export declare enum PublicPricingAmountBasis {
+    /** The amount is the whole price for the period. */
+    FLAT = "flat",
+    /** The amount is per unit (a seat, a member) for the period. */
+    PER_UNIT = "per_unit",
+    /** The total depends on quantity (tiered, graduated, package): the amount is indicative only. */
+    VARIABLE = "variable"
+}
+/** One public price of a plan. */
+export interface PublicPricingPrice {
+    /** The price amount in the currency's MINOR units, as decimal digits (see the file header). */
+    readonly amountMinor: string;
+    /** How many decimal places `amountMinor` carries: the value is `amountMinor / 10 ** decimals`. */
+    readonly decimals: number;
+    /** ISO 4217 currency code. */
+    readonly currency: string;
+    readonly recurrence: {
+        readonly unit: PublicPricingRecurrenceUnit;
+        readonly count: number;
+    };
+    readonly amountBasis: PublicPricingAmountBasis;
+    /** The price the catalogue marks as the plan's default. */
+    readonly isDefault: boolean;
+}
+/** One public plan: a product the catalogue lists publicly, with its pricing-surface facts resolved. */
+export interface PublicPricingPlan {
+    /** The catalogue key — also the label namespace a surface names the plan by. */
+    readonly key: string;
+    readonly planTier?: string;
+    /** Ascending order on a pricing surface. */
+    readonly sortOrder: number;
+    /** The scopes that may subscribe (wire values of `ResourcePrimaryScope`). */
+    readonly targetScopes: readonly string[];
+    readonly isRecommended: boolean;
+    readonly priceDisclosure: ProductPriceDisclosure;
+    readonly availability: ProductAvailability;
+    /** Free-trial length when the plan offers one. */
+    readonly trialDays?: number;
+    readonly prices: readonly PublicPricingPrice[];
+}
+/** The public pricing catalogue: every publicly listed plan, in display order. */
+export interface PublicPricingCatalog {
+    readonly plans: readonly PublicPricingPlan[];
+}
+/**
+ * The amount of a public price as a plain decimal string (`"4"`, `"29.9"`, `"0.0001"`), exact — no
+ * floating point. What structured data publishes as `price`, and what a surface formats for display.
+ */
+export declare function publicPricingAmountDecimal(price: Pick<PublicPricingPrice, 'amountMinor' | 'decimals'>): string;
+//# sourceMappingURL=public-pricing-catalog.shared.atoms.d.ts.map

package/dist/esm/billing/public-pricing-catalog.shared.atoms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-pricing-catalog.shared.atoms.d.ts","sourceRoot":"","sources":["../../../../src/billing/public-pricing-catalog.shared.atoms.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,wHAAwH;AACxH;;;;;;;;;;;;;;GAcG;AACH,oBAAY,sBAAsB;IAChC,yGAAyG;IACzG,MAAM,WAAW;IACjB;;;;OAIG;IACH,WAAW,gBAAgB;IAC3B,mFAAmF;IACnF,UAAU,eAAe;CAC1B;AAED;;;;;;;GAOG;AACH,oBAAY,mBAAmB;IAC7B,wEAAwE;IACxE,SAAS,cAAc;IACvB,iGAAiG;IACjG,QAAQ,aAAa;CACtB;AACD,sEAAsE;AAEtE;;;;;;;GAOG;AACH,oBAAY,2BAA2B;IACrC,iCAAiC;IACjC,QAAQ,aAAa;IACrB,mCAAmC;IACnC,KAAK,UAAU;IACf,kCAAkC;IAClC,IAAI,SAAS;CACd;AAED;;;;;;GAMG;AACH,oBAAY,wBAAwB;IAClC,oDAAoD;IACpD,IAAI,SAAS;IACb,gEAAgE;IAChE,QAAQ,aAAa;IACrB,iGAAiG;IACjG,QAAQ,aAAa;CACtB;AAED,kCAAkC;AAClC,MAAM,WAAW,kBAAkB;IACjC,+FAA+F;IAC/F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kGAAkG;IAClG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5F,QAAQ,CAAC,WAAW,EAAE,wBAAwB,CAAC;IAC/C,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,wGAAwG;AACxG,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,sBAAsB,CAAC;IACjD,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,kDAAkD;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAChD;AAED,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC9C;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,aAAa,GAAG,UAAU,CAAC,GAAG,MAAM,CAQ9G"}