@wildo-ai/saas-models 1.1.2 → 1.1.3

package/dist/esm/billing/billing-enums.shared.schemas.js

@@ -5,14 +5,28 @@
  * These supersede the legacy enums from billing.shared.schemas.ts.
  *
  * Enums shared with the standard billing interface (PricingModel, BillingInterval,
- * TaxDisplayMode, SubscriptionStatus) are defined in @wildo-ai/external-connectors-models
- * and re-exported here for convenience.
+ * TaxDisplayMode, SubscriptionStatus, InvoiceStatus, ProrationBehavior) are defined in
+ * @wildo-ai/external-connectors-models and re-exported here for convenience.
  *
  * @see billing-and-features-system.md §6 (Billing Schemas)
  */
-export { PricingModel, BillingInterval, TaxDisplayMode, SubscriptionStatus } from '@wildo-ai/external-connectors-models';
+export { PricingModel, BillingInterval, TaxDisplayMode, SubscriptionStatus, InvoiceStatus, ProrationBehavior } from '@wildo-ai/external-connectors-models';
 // ── Product & Pricing ──────────────────────────────────────────────
 /**
+ * @wildo_source:part:start saas.models.billing.catalog-vocabularies facet:layer:shared facet:audience:app-developer
+ *
+ * The vocabularies an application types into its own product catalogue — the `ProductDefinition[]`
+ * it exports from its shared library and hands to the engine with its module declarations.
+ *
+ * Imported from `@wildo-ai/saas-models`. `PricingModel`, `BillingInterval` and `ProrationBehavior`
+ * are re-exported from the connector models, because their values ARE the provider's wire values.
+ *
+ * ⚠️ **The catalogue is ONE-WAY.** Sync pushes only rows that have no provider link yet, so a product
+ * or price edited in the provider's own dashboard is never read back, never reconciled, and never
+ * reported. Removing a product from the array does not retire it at the provider and does not
+ * deactivate the existing row — nothing detects that a previously synced key has disappeared. Treat
+ * the array as the source of truth and make every change through it.
+ *
  * Product types available in the billing catalog.
  *
  * | Type        | Creates subscription? | Repeatable? | Grants features? | Usage tracked? |
@@ -53,12 +67,9 @@ export var LimitGrantMode;
 /**
  * Proration behavior for plan changes (upgrade/downgrade).
  */
-export var ProrationBehavior;
-(function (ProrationBehavior) {
-    ProrationBehavior["CREATE_PRORATIONS"] = "create_prorations";
-    ProrationBehavior["NONE"] = "none";
-    ProrationBehavior["ALWAYS_INVOICE"] = "always_invoice";
-})(ProrationBehavior || (ProrationBehavior = {}));
+// ProrationBehavior: re-exported from @wildo-ai/external-connectors-models (see top of file).
+// Moved there 2026-09-08 (#516) because its three values ARE the provider's wire values, so the
+// request contract has to be able to name the type — see TaxDisplayMode for the same reasoning.
 /**
  * Billing timing: when to apply plan changes.
  */
@@ -67,6 +78,7 @@ export var BillingTiming;
     BillingTiming["IMMEDIATE"] = "immediate";
     BillingTiming["AT_PERIOD_END"] = "at_period_end";
 })(BillingTiming || (BillingTiming = {}));
+/** @wildo_source:part:end saas.models.billing.catalog-vocabularies */
 // BillingInterval: re-exported from @wildo-ai/external-connectors-models (see top of file)
 // ── Metering & Usage ───────────────────────────────────────────────
 /**
@@ -95,6 +107,53 @@ export var UsageSourceType;
     UsageSourceType["RESOURCE_COUNT"] = "resource_count";
     UsageSourceType["CUSTOM"] = "custom";
 })(UsageSourceType || (UsageSourceType = {}));
+/**
+ * Where one metered usage row stands with respect to the provider flush.
+ *
+ * This was a BOOLEAN (`reportedToProvider`) until 2026-09-09, and the third state is the whole
+ * reason it is an enum now (#512). A boolean can say "not yet reported" and "reported", and the
+ * flush selects on the first — so a row that can NEVER be reported has nowhere to go. It stays
+ * pending, is re-selected by every run, fails identically, and grows an error backlog that no
+ * operator action can drain, on a five-minute schedule.
+ *
+ * The three states are genuinely distinct and must not be collapsed:
+ *
+ * - {@link PENDING} — the flush will try again. Every newly recorded row starts here.
+ * - {@link REPORTED} — the provider acknowledged the quantity. `reportedAt` says when. Terminal,
+ *   and money has moved: never move a row back out of this state.
+ * - {@link UNREPORTABLE} — the flush determined the row can never be reported, for a reason named
+ *   in `unreportableReason`. Terminal, and NO money moved. Marking such a row `REPORTED` instead
+ *   would drain the backlog just as well and would be a lie no later reader could detect, which is
+ *   exactly why the state exists rather than a shortcut.
+ */
+export var UsageRecordFlushState;
+(function (UsageRecordFlushState) {
+    UsageRecordFlushState["PENDING"] = "pending";
+    UsageRecordFlushState["REPORTED"] = "reported";
+    UsageRecordFlushState["UNREPORTABLE"] = "unreportable";
+})(UsageRecordFlushState || (UsageRecordFlushState = {}));
+/**
+ * Why a usage row was determined to be permanently unreportable.
+ *
+ * One member today, and it is a closed vocabulary rather than a free string because the operator
+ * reading a retained financial record needs to know which permanent condition applies — and because
+ * the distinction between a PERMANENT and a TRANSIENT failure is the judgement this whole state
+ * turns on. A billing account that merely has no `providerCustomerId` yet is transient: the account
+ * exists, provisioning may still complete, and such a row stays {@link UsageRecordFlushState.PENDING}.
+ * Only a condition that cannot resolve itself belongs here.
+ */
+export var UsageRecordUnreportableReason;
+(function (UsageRecordUnreportableReason) {
+    /**
+     * The billing account row no longer exists.
+     *
+     * Reachable by design: usage rows are RETAINED when their subject is erased (the tax/audit
+     * obligation on `usage-record.shared.schemas.ts`), so a deleted account legitimately leaves rows
+     * behind with no provider customer to report them to. Nothing can restore the mapping, so the
+     * quantity will never be billed and saying so on the row is the only honest outcome.
+     */
+    UsageRecordUnreportableReason["BILLING_ACCOUNT_DELETED"] = "billing_account_deleted";
+})(UsageRecordUnreportableReason || (UsageRecordUnreportableReason = {}));
 // ── Tax ────────────────────────────────────────────────────────────
 // TaxDisplayMode: re-exported from @wildo-ai/external-connectors-models (see top of file)
 /**
@@ -107,20 +166,9 @@ export var TaxCalculationMode;
 })(TaxCalculationMode || (TaxCalculationMode = {}));
 // ── Subscription & Invoice Status ──────────────────────────────────
 // SubscriptionStatus: re-exported from @wildo-ai/external-connectors-models (see top of file)
-/**
- * Invoice status values (maps to Stripe invoice statuses).
- *
- * Invoices are created and managed entirely by the billing provider.
- * We store a thin reference for status tracking and quick display.
- */
-export var InvoiceStatus;
-(function (InvoiceStatus) {
-    InvoiceStatus["DRAFT"] = "draft";
-    InvoiceStatus["OPEN"] = "open";
-    InvoiceStatus["PAID"] = "paid";
-    InvoiceStatus["VOID"] = "void";
-    InvoiceStatus["UNCOLLECTIBLE"] = "uncollectible";
-})(InvoiceStatus || (InvoiceStatus = {}));
+// InvoiceStatus: re-exported from @wildo-ai/external-connectors-models (see top of file).
+// It moved there on 2026-09-09 so `StandardBilling_InvoiceData` could name it; the specifier every
+// consumer imports is unchanged.
 // ── Billing Scope ──────────────────────────────────────────────────
 /**
  * Billing-compatible scope types.
@@ -252,6 +300,20 @@ export var BillingCheckoutMetadataKey;
     BillingCheckoutMetadataKey["BILLING_ACCOUNT_ID"] = "wildo_billingAccountId";
     /** The catalog product key purchased — selects the credit pool and credits-per-unit on top-up. */
     BillingCheckoutMetadataKey["PRODUCT_KEY"] = "wildo_productKey";
+    /**
+     * The PROMOTION row whose code the framework validated when it opened this checkout, so the
+     * redemption can be counted when the session COMPLETES (#518).
+     *
+     * Absent when the purchase used no code, which is the common case.
+     *
+     * Stamped rather than re-derived from the completed session, because the provider reports the
+     * DISCOUNT it applied and not the Wildo row that authorised it — and the row is what carries
+     * `maxRedemptions`. Like every key here it is written for the framework's own reconciliation and is
+     * never trusted as authority on its own: the redemption is counted with a compare-and-swap that
+     * refuses past the cap, so a tampered value can at worst count a redemption against a promotion
+     * that has room for one.
+     */
+    BillingCheckoutMetadataKey["PROMOTION_ID"] = "wildo_promotionId";
     /**
      * The purchased quantity, as a decimal integer string (provider metadata values are strings).
      * Strictly parsed and bounded by {@link BILLING_CHECKOUT_MAX_QUANTITY} on the way back in.

package/dist/esm/billing/billing-enums.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"billing-enums.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/billing-enums.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Billing Enums (Shared)\n *\n * All billing-system enums used across backend, frontend, and shared models.\n * These supersede the legacy enums from billing.shared.schemas.ts.\n *\n * Enums shared with the standard billing interface (PricingModel, BillingInterval,\n * TaxDisplayMode, SubscriptionStatus) are defined in @wildo-ai/external-connectors-models\n * and re-exported here for convenience.\n *\n * @see billing-and-features-system.md §6 (Billing Schemas)\n */\n\nexport { PricingModel, BillingInterval, TaxDisplayMode, SubscriptionStatus } from '@wildo-ai/external-connectors-models';\n\n// ── Product & Pricing ──────────────────────────────────────────────\n\n/**\n * Product types available in the billing catalog.\n *\n * | Type        | Creates subscription? | Repeatable? | Grants features? | Usage tracked? |\n * |-------------|----------------------|-------------|------------------|----------------|\n * | PLAN        | Yes (exclusive)      | No (switch) | Yes              | No             |\n * | ADDON       | Yes (stackable)      | No (toggle) | Yes              | No             |\n * | METERED     | Yes                  | No          | Optional         | Yes            |\n * | ONE_TIME    | No                   | No (once)   | Optional         | No             |\n * | CREDIT_PACK | No                   | Yes         | No (credits)     | Credits-based  |\n * | ITEM        | No                   | Yes         | Optional         | No             |\n */\nexport enum ProductType {\n  /** Subscription plan, mutually exclusive per billing account */\n  PLAN = 'plan',\n  /** Optional subscription add-on, stackable on top of plan */\n  ADDON = 'addon',\n  /** Usage-based subscription (consumption reported to provider) */\n  METERED = 'metered',\n  /** Single purchase, once per billing account (e.g., setup fee, migration) */\n  ONE_TIME = 'one_time',\n  /** Buy a pack of credits/tokens (repeatable, consumable over time) */\n  CREDIT_PACK = 'credit_pack',\n  /** Purchasable item, repeatable (e.g., report generation, data export) */\n  ITEM = 'item',\n}\n\n/**\n * Limit grant mode: how this product's limits compose with other products.\n * - SET: absolute value (replaces, used for PLAN base limits)\n * - ADD: additive (stacks on top, used for ADDON bonus limits)\n */\nexport enum LimitGrantMode {\n  SET = 'set',\n  ADD = 'add',\n}\n\n// ── Billing Lifecycle ──────────────────────────────────────────────\n\n/**\n * Proration behavior for plan changes (upgrade/downgrade).\n */\nexport enum ProrationBehavior {\n  CREATE_PRORATIONS = 'create_prorations',\n  NONE = 'none',\n  ALWAYS_INVOICE = 'always_invoice',\n}\n\n/**\n * Billing timing: when to apply plan changes.\n */\nexport enum BillingTiming {\n  IMMEDIATE = 'immediate',\n  AT_PERIOD_END = 'at_period_end',\n}\n\n// BillingInterval: re-exported from @wildo-ai/external-connectors-models (see top of file)\n\n// ── Metering & Usage ───────────────────────────────────────────────\n\n/**\n * Metering aggregation window for usage records.\n */\nexport enum MeteringAggregationWindow {\n  PER_FLUSH = 'per_flush',\n  PER_BILLING_PERIOD = 'per_billing_period',\n}\n\n/**\n * Usage aggregation type for metered prices.\n */\nexport enum UsageAggregationType {\n  SUM = 'sum',\n  MAX = 'max',\n  LAST = 'last',\n}\n\n/**\n * Usage record source type.\n */\nexport enum UsageSourceType {\n  OPERATION = 'operation',\n  RESOURCE_COUNT = 'resource_count',\n  CUSTOM = 'custom',\n}\n\n// ── Tax ────────────────────────────────────────────────────────────\n\n// TaxDisplayMode: re-exported from @wildo-ai/external-connectors-models (see top of file)\n\n/**\n * Tax calculation mode: provider-managed or disabled.\n */\nexport enum TaxCalculationMode {\n  PROVIDER_MANAGED = 'provider_managed',\n  DISABLED = 'disabled',\n}\n\n// ── Subscription & Invoice Status ──────────────────────────────────\n\n// SubscriptionStatus: re-exported from @wildo-ai/external-connectors-models (see top of file)\n\n/**\n * Invoice status values (maps to Stripe invoice statuses).\n *\n * Invoices are created and managed entirely by the billing provider.\n * We store a thin reference for status tracking and quick display.\n */\nexport enum InvoiceStatus {\n  DRAFT = 'draft',\n  OPEN = 'open',\n  PAID = 'paid',\n  VOID = 'void',\n  UNCOLLECTIBLE = 'uncollectible',\n}\n\n// ── Billing Scope ──────────────────────────────────────────────────\n\n/**\n * Billing-compatible scope types.\n * Subset of ResourcePrimaryScope — excludes APPLICATION which has no billing variants.\n * Used by scope-agnostic billing resources (e.g., Referrals) that reference\n * billing accounts across different polymorphic collections.\n */\nexport enum BillingScopeType {\n  ORGANIZATIONS = 'organizations',\n  USER_SELF = 'user_self',\n}\n\n// ── Promotions & Referrals ─────────────────────────────────────────\n\n/**\n * Promotion type.\n */\nexport enum PromotionType {\n  /** Direct discount */\n  COUPON = 'coupon',\n  /** Code-based discount */\n  PROMOTION_CODE = 'promotion_code',\n  /** Referral program */\n  REFERRAL = 'referral',\n  /** Special deal/offer */\n  DEAL = 'deal',\n}\n\n/**\n * Discount type for promotions.\n */\nexport enum DiscountType {\n  PERCENTAGE = 'percentage',\n  FIXED_AMOUNT = 'fixed_amount',\n}\n\n/**\n * Promotion duration (how long the discount applies).\n */\nexport enum PromotionDuration {\n  ONCE = 'once',\n  REPEATING = 'repeating',\n  FOREVER = 'forever',\n}\n\n/**\n * Referral status lifecycle.\n */\nexport enum ReferralStatus {\n  PENDING = 'pending',\n  ACCEPTED = 'accepted',\n  CONVERTED = 'converted',\n  EXPIRED = 'expired',\n  CANCELLED = 'cancelled',\n}\n\n/**\n * Reward type for the referrer (person who referred).\n */\nexport enum ReferrerRewardType {\n  CREDIT = 'credit',\n  DISCOUNT = 'discount',\n  FEATURE = 'feature',\n  COMMISSION = 'commission',\n}\n\n/**\n * Reward type for the referred (new customer).\n */\nexport enum ReferredRewardType {\n  CREDIT = 'credit',\n  DISCOUNT = 'discount',\n  FEATURE = 'feature',\n  TRIAL_EXTENSION = 'trial_extension',\n}\n\n// ── Provider checkout metadata: the framework/caller trust boundary ─────────────\n\n/**\n * Prefix that marks a provider-metadata key as FRAMEWORK-AUTHORITATIVE.\n *\n * ## Why a reserved namespace exists at all\n *\n * A provider checkout session carries ONE flat `metadata` map, and two parties want to write into\n * it: the framework (which needs to recognise the purchase when the provider echoes the session\n * back on `checkout.session.completed`) and the application's own caller (who legitimately wants\n * to tag the purchase for their analytics or reconciliation).\n *\n * Those two writers do not have the same authority. The framework's entries decide WHICH billing\n * account is credited and HOW MUCH — the provider replays them verbatim inside a genuinely SIGNED\n * webhook, so a signature proves the provider sent them, never that the framework wrote them. The\n * caller's entries decide nothing.\n *\n * Sharing one un-partitioned namespace between those two authorities is what turned a caller-supplied\n * map into a credit-minting primitive: the producer spread caller metadata LAST, so `billingAccountId`\n * / `productKey` / `quantity` were simply overwritable, and the webhook consumer read the result back\n * as trusted framework state. Ordering alone is not the fix — swapping the spread leaves an\n * unmarked namespace in which the NEXT authoritative key is one careless line from being overridable\n * again. The prefix makes the trust boundary a property of the KEY, so it survives refactors.\n *\n * The boundary is enforced in three places, deliberately overlapping:\n * 1. the OPEN_CHECKOUT request DTO REFUSES any caller key carrying this prefix (loud, at the edge);\n * 2. the metadata builder writes the reserved entries LAST (structural, cannot be forgotten);\n * 3. the webhook consumer reads ONLY reserved keys, and re-derives the billing account from\n *    provider-authoritative data rather than trusting the echoed value.\n *\n * @see BillingCheckoutMetadataKey for the reserved key vocabulary itself.\n */\nexport const BILLING_RESERVED_METADATA_KEY_PREFIX = 'wildo_';\n\n/**\n * The closed vocabulary of framework-authoritative provider-metadata keys.\n *\n * Every member MUST start with {@link BILLING_RESERVED_METADATA_KEY_PREFIX} — that is what makes the\n * DTO's caller-key refusal and the consumer's read-only-reserved rule line up. A member added\n * without the prefix would be silently overridable by a caller, which is the whole defect this\n * vocabulary exists to prevent, so a pinned test asserts the prefix across every member.\n *\n * Named rather than inlined because each member carries a different obligation on the consumer side\n * (one is cross-checked against provider truth, one selects the product, one is bounded and\n * strictly parsed) and a bare string literal has nowhere to record that.\n */\nexport enum BillingCheckoutMetadataKey {\n  /**\n   * The billing account the checkout was opened FOR.\n   *\n   * Written for traceability and cross-checking only. The webhook consumer re-derives the account\n   * from the provider-authoritative customer id on the event and REFUSES the event if the echoed\n   * value disagrees — it is never used as the account to credit.\n   */\n  BILLING_ACCOUNT_ID = 'wildo_billingAccountId',\n  /** The catalog product key purchased — selects the credit pool and credits-per-unit on top-up. */\n  PRODUCT_KEY = 'wildo_productKey',\n  /**\n   * The purchased quantity, as a decimal integer string (provider metadata values are strings).\n   * Strictly parsed and bounded by {@link BILLING_CHECKOUT_MAX_QUANTITY} on the way back in.\n   */\n  QUANTITY = 'wildo_quantity',\n}\n\n/**\n * Upper bound on a single checkout's line-item quantity, applied on BOTH sides of the provider\n * round trip: the OPEN_CHECKOUT request DTO refuses more, and the webhook consumer refuses to\n * honour more.\n *\n * One shared constant rather than two, because a consumer bound lower than the producer bound would\n * silently refuse legitimate large purchases the framework itself allowed to be billed — the\n * failure mode where the customer is charged and the credits never arrive.\n *\n * The value is a framework policy ceiling, not a provider-derived one: it is deliberately far above\n * any plausible self-serve purchase and far below the range where an unbounded quantity becomes a\n * credit-minting primitive. An application whose catalog genuinely sells in larger units should\n * raise it here, where both sides read it, rather than at either end.\n */\nexport const BILLING_CHECKOUT_MAX_QUANTITY = 999_999;\n"]}
+{"version":3,"file":"billing-enums.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/billing-enums.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Billing Enums (Shared)\n *\n * All billing-system enums used across backend, frontend, and shared models.\n * These supersede the legacy enums from billing.shared.schemas.ts.\n *\n * Enums shared with the standard billing interface (PricingModel, BillingInterval,\n * TaxDisplayMode, SubscriptionStatus, InvoiceStatus, ProrationBehavior) are defined in\n * @wildo-ai/external-connectors-models and re-exported here for convenience.\n *\n * @see billing-and-features-system.md §6 (Billing Schemas)\n */\n\nexport { PricingModel, BillingInterval, TaxDisplayMode, SubscriptionStatus, InvoiceStatus, ProrationBehavior } from '@wildo-ai/external-connectors-models';\n\n// ── Product & Pricing ──────────────────────────────────────────────\n\n/**\n * @wildo_source:part:start saas.models.billing.catalog-vocabularies facet:layer:shared facet:audience:app-developer\n *\n * The vocabularies an application types into its own product catalogue — the `ProductDefinition[]`\n * it exports from its shared library and hands to the engine with its module declarations.\n *\n * Imported from `@wildo-ai/saas-models`. `PricingModel`, `BillingInterval` and `ProrationBehavior`\n * are re-exported from the connector models, because their values ARE the provider's wire values.\n *\n * ⚠️ **The catalogue is ONE-WAY.** Sync pushes only rows that have no provider link yet, so a product\n * or price edited in the provider's own dashboard is never read back, never reconciled, and never\n * reported. Removing a product from the array does not retire it at the provider and does not\n * deactivate the existing row — nothing detects that a previously synced key has disappeared. Treat\n * the array as the source of truth and make every change through it.\n *\n * Product types available in the billing catalog.\n *\n * | Type        | Creates subscription? | Repeatable? | Grants features? | Usage tracked? |\n * |-------------|----------------------|-------------|------------------|----------------|\n * | PLAN        | Yes (exclusive)      | No (switch) | Yes              | No             |\n * | ADDON       | Yes (stackable)      | No (toggle) | Yes              | No             |\n * | METERED     | Yes                  | No          | Optional         | Yes            |\n * | ONE_TIME    | No                   | No (once)   | Optional         | No             |\n * | CREDIT_PACK | No                   | Yes         | No (credits)     | Credits-based  |\n * | ITEM        | No                   | Yes         | Optional         | No             |\n */\nexport enum ProductType {\n  /** Subscription plan, mutually exclusive per billing account */\n  PLAN = 'plan',\n  /** Optional subscription add-on, stackable on top of plan */\n  ADDON = 'addon',\n  /** Usage-based subscription (consumption reported to provider) */\n  METERED = 'metered',\n  /** Single purchase, once per billing account (e.g., setup fee, migration) */\n  ONE_TIME = 'one_time',\n  /** Buy a pack of credits/tokens (repeatable, consumable over time) */\n  CREDIT_PACK = 'credit_pack',\n  /** Purchasable item, repeatable (e.g., report generation, data export) */\n  ITEM = 'item',\n}\n\n/**\n * Limit grant mode: how this product's limits compose with other products.\n * - SET: absolute value (replaces, used for PLAN base limits)\n * - ADD: additive (stacks on top, used for ADDON bonus limits)\n */\nexport enum LimitGrantMode {\n  SET = 'set',\n  ADD = 'add',\n}\n\n// ── Billing Lifecycle ──────────────────────────────────────────────\n\n/**\n * Proration behavior for plan changes (upgrade/downgrade).\n */\n// ProrationBehavior: re-exported from @wildo-ai/external-connectors-models (see top of file).\n// Moved there 2026-09-08 (#516) because its three values ARE the provider's wire values, so the\n// request contract has to be able to name the type — see TaxDisplayMode for the same reasoning.\n\n/**\n * Billing timing: when to apply plan changes.\n */\nexport enum BillingTiming {\n  IMMEDIATE = 'immediate',\n  AT_PERIOD_END = 'at_period_end',\n}\n/** @wildo_source:part:end saas.models.billing.catalog-vocabularies */\n\n// BillingInterval: re-exported from @wildo-ai/external-connectors-models (see top of file)\n\n// ── Metering & Usage ───────────────────────────────────────────────\n\n/**\n * Metering aggregation window for usage records.\n */\nexport enum MeteringAggregationWindow {\n  PER_FLUSH = 'per_flush',\n  PER_BILLING_PERIOD = 'per_billing_period',\n}\n\n/**\n * Usage aggregation type for metered prices.\n */\nexport enum UsageAggregationType {\n  SUM = 'sum',\n  MAX = 'max',\n  LAST = 'last',\n}\n\n/**\n * Usage record source type.\n */\nexport enum UsageSourceType {\n  OPERATION = 'operation',\n  RESOURCE_COUNT = 'resource_count',\n  CUSTOM = 'custom',\n}\n\n/**\n * Where one metered usage row stands with respect to the provider flush.\n *\n * This was a BOOLEAN (`reportedToProvider`) until 2026-09-09, and the third state is the whole\n * reason it is an enum now (#512). A boolean can say \"not yet reported\" and \"reported\", and the\n * flush selects on the first — so a row that can NEVER be reported has nowhere to go. It stays\n * pending, is re-selected by every run, fails identically, and grows an error backlog that no\n * operator action can drain, on a five-minute schedule.\n *\n * The three states are genuinely distinct and must not be collapsed:\n *\n * - {@link PENDING} — the flush will try again. Every newly recorded row starts here.\n * - {@link REPORTED} — the provider acknowledged the quantity. `reportedAt` says when. Terminal,\n *   and money has moved: never move a row back out of this state.\n * - {@link UNREPORTABLE} — the flush determined the row can never be reported, for a reason named\n *   in `unreportableReason`. Terminal, and NO money moved. Marking such a row `REPORTED` instead\n *   would drain the backlog just as well and would be a lie no later reader could detect, which is\n *   exactly why the state exists rather than a shortcut.\n */\nexport enum UsageRecordFlushState {\n  PENDING = 'pending',\n  REPORTED = 'reported',\n  UNREPORTABLE = 'unreportable',\n}\n\n/**\n * Why a usage row was determined to be permanently unreportable.\n *\n * One member today, and it is a closed vocabulary rather than a free string because the operator\n * reading a retained financial record needs to know which permanent condition applies — and because\n * the distinction between a PERMANENT and a TRANSIENT failure is the judgement this whole state\n * turns on. A billing account that merely has no `providerCustomerId` yet is transient: the account\n * exists, provisioning may still complete, and such a row stays {@link UsageRecordFlushState.PENDING}.\n * Only a condition that cannot resolve itself belongs here.\n */\nexport enum UsageRecordUnreportableReason {\n  /**\n   * The billing account row no longer exists.\n   *\n   * Reachable by design: usage rows are RETAINED when their subject is erased (the tax/audit\n   * obligation on `usage-record.shared.schemas.ts`), so a deleted account legitimately leaves rows\n   * behind with no provider customer to report them to. Nothing can restore the mapping, so the\n   * quantity will never be billed and saying so on the row is the only honest outcome.\n   */\n  BILLING_ACCOUNT_DELETED = 'billing_account_deleted',\n}\n\n// ── Tax ────────────────────────────────────────────────────────────\n\n// TaxDisplayMode: re-exported from @wildo-ai/external-connectors-models (see top of file)\n\n/**\n * Tax calculation mode: provider-managed or disabled.\n */\nexport enum TaxCalculationMode {\n  PROVIDER_MANAGED = 'provider_managed',\n  DISABLED = 'disabled',\n}\n\n// ── Subscription & Invoice Status ──────────────────────────────────\n\n// SubscriptionStatus: re-exported from @wildo-ai/external-connectors-models (see top of file)\n\n// InvoiceStatus: re-exported from @wildo-ai/external-connectors-models (see top of file).\n// It moved there on 2026-09-09 so `StandardBilling_InvoiceData` could name it; the specifier every\n// consumer imports is unchanged.\n\n// ── Billing Scope ──────────────────────────────────────────────────\n\n/**\n * Billing-compatible scope types.\n * Subset of ResourcePrimaryScope — excludes APPLICATION which has no billing variants.\n * Used by scope-agnostic billing resources (e.g., Referrals) that reference\n * billing accounts across different polymorphic collections.\n */\nexport enum BillingScopeType {\n  ORGANIZATIONS = 'organizations',\n  USER_SELF = 'user_self',\n}\n\n// ── Promotions & Referrals ─────────────────────────────────────────\n\n/**\n * Promotion type.\n */\nexport enum PromotionType {\n  /** Direct discount */\n  COUPON = 'coupon',\n  /** Code-based discount */\n  PROMOTION_CODE = 'promotion_code',\n  /** Referral program */\n  REFERRAL = 'referral',\n  /** Special deal/offer */\n  DEAL = 'deal',\n}\n\n/**\n * Discount type for promotions.\n */\nexport enum DiscountType {\n  PERCENTAGE = 'percentage',\n  FIXED_AMOUNT = 'fixed_amount',\n}\n\n/**\n * Promotion duration (how long the discount applies).\n */\nexport enum PromotionDuration {\n  ONCE = 'once',\n  REPEATING = 'repeating',\n  FOREVER = 'forever',\n}\n\n/**\n * Referral status lifecycle.\n */\nexport enum ReferralStatus {\n  PENDING = 'pending',\n  ACCEPTED = 'accepted',\n  CONVERTED = 'converted',\n  EXPIRED = 'expired',\n  CANCELLED = 'cancelled',\n}\n\n/**\n * Reward type for the referrer (person who referred).\n */\nexport enum ReferrerRewardType {\n  CREDIT = 'credit',\n  DISCOUNT = 'discount',\n  FEATURE = 'feature',\n  COMMISSION = 'commission',\n}\n\n/**\n * Reward type for the referred (new customer).\n */\nexport enum ReferredRewardType {\n  CREDIT = 'credit',\n  DISCOUNT = 'discount',\n  FEATURE = 'feature',\n  TRIAL_EXTENSION = 'trial_extension',\n}\n\n// ── Provider checkout metadata: the framework/caller trust boundary ─────────────\n\n/**\n * Prefix that marks a provider-metadata key as FRAMEWORK-AUTHORITATIVE.\n *\n * ## Why a reserved namespace exists at all\n *\n * A provider checkout session carries ONE flat `metadata` map, and two parties want to write into\n * it: the framework (which needs to recognise the purchase when the provider echoes the session\n * back on `checkout.session.completed`) and the application's own caller (who legitimately wants\n * to tag the purchase for their analytics or reconciliation).\n *\n * Those two writers do not have the same authority. The framework's entries decide WHICH billing\n * account is credited and HOW MUCH — the provider replays them verbatim inside a genuinely SIGNED\n * webhook, so a signature proves the provider sent them, never that the framework wrote them. The\n * caller's entries decide nothing.\n *\n * Sharing one un-partitioned namespace between those two authorities is what turned a caller-supplied\n * map into a credit-minting primitive: the producer spread caller metadata LAST, so `billingAccountId`\n * / `productKey` / `quantity` were simply overwritable, and the webhook consumer read the result back\n * as trusted framework state. Ordering alone is not the fix — swapping the spread leaves an\n * unmarked namespace in which the NEXT authoritative key is one careless line from being overridable\n * again. The prefix makes the trust boundary a property of the KEY, so it survives refactors.\n *\n * The boundary is enforced in three places, deliberately overlapping:\n * 1. the OPEN_CHECKOUT request DTO REFUSES any caller key carrying this prefix (loud, at the edge);\n * 2. the metadata builder writes the reserved entries LAST (structural, cannot be forgotten);\n * 3. the webhook consumer reads ONLY reserved keys, and re-derives the billing account from\n *    provider-authoritative data rather than trusting the echoed value.\n *\n * @see BillingCheckoutMetadataKey for the reserved key vocabulary itself.\n */\nexport const BILLING_RESERVED_METADATA_KEY_PREFIX = 'wildo_';\n\n/**\n * The closed vocabulary of framework-authoritative provider-metadata keys.\n *\n * Every member MUST start with {@link BILLING_RESERVED_METADATA_KEY_PREFIX} — that is what makes the\n * DTO's caller-key refusal and the consumer's read-only-reserved rule line up. A member added\n * without the prefix would be silently overridable by a caller, which is the whole defect this\n * vocabulary exists to prevent, so a pinned test asserts the prefix across every member.\n *\n * Named rather than inlined because each member carries a different obligation on the consumer side\n * (one is cross-checked against provider truth, one selects the product, one is bounded and\n * strictly parsed) and a bare string literal has nowhere to record that.\n */\nexport enum BillingCheckoutMetadataKey {\n  /**\n   * The billing account the checkout was opened FOR.\n   *\n   * Written for traceability and cross-checking only. The webhook consumer re-derives the account\n   * from the provider-authoritative customer id on the event and REFUSES the event if the echoed\n   * value disagrees — it is never used as the account to credit.\n   */\n  BILLING_ACCOUNT_ID = 'wildo_billingAccountId',\n  /** The catalog product key purchased — selects the credit pool and credits-per-unit on top-up. */\n  PRODUCT_KEY = 'wildo_productKey',\n  /**\n   * The PROMOTION row whose code the framework validated when it opened this checkout, so the\n   * redemption can be counted when the session COMPLETES (#518).\n   *\n   * Absent when the purchase used no code, which is the common case.\n   *\n   * Stamped rather than re-derived from the completed session, because the provider reports the\n   * DISCOUNT it applied and not the Wildo row that authorised it — and the row is what carries\n   * `maxRedemptions`. Like every key here it is written for the framework's own reconciliation and is\n   * never trusted as authority on its own: the redemption is counted with a compare-and-swap that\n   * refuses past the cap, so a tampered value can at worst count a redemption against a promotion\n   * that has room for one.\n   */\n  PROMOTION_ID = 'wildo_promotionId',\n  /**\n   * The purchased quantity, as a decimal integer string (provider metadata values are strings).\n   * Strictly parsed and bounded by {@link BILLING_CHECKOUT_MAX_QUANTITY} on the way back in.\n   */\n  QUANTITY = 'wildo_quantity',\n}\n\n/**\n * Upper bound on a single checkout's line-item quantity, applied on BOTH sides of the provider\n * round trip: the OPEN_CHECKOUT request DTO refuses more, and the webhook consumer refuses to\n * honour more.\n *\n * One shared constant rather than two, because a consumer bound lower than the producer bound would\n * silently refuse legitimate large purchases the framework itself allowed to be billed — the\n * failure mode where the customer is charged and the credits never arrive.\n *\n * The value is a framework policy ceiling, not a provider-derived one: it is deliberately far above\n * any plausible self-serve purchase and far below the range where an unbounded quantity becomes a\n * credit-minting primitive. An application whose catalog genuinely sells in larger units should\n * raise it here, where both sides read it, rather than at either end.\n */\nexport const BILLING_CHECKOUT_MAX_QUANTITY = 999_999;\n"]}

package/dist/esm/billing/billing-types.shared.schemas.d.ts

@@ -141,11 +141,11 @@ export declare const BillingStateResponseSchema: z.ZodObject<{
                 requirePaymentMethod: z.ZodDefault<z.ZodBoolean>;
             }, z.core.$strip>>;
             upgrade: z.ZodOptional<z.ZodObject<{
-                proration: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").ProrationBehavior>>;
+                proration: z.ZodDefault<z.ZodEnum<typeof import("@wildo-ai/external-connectors-models").ProrationBehavior>>;
                 timing: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").BillingTiming>>;
             }, z.core.$strip>>;
             downgrade: z.ZodOptional<z.ZodObject<{
-                proration: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").ProrationBehavior>>;
+                proration: z.ZodDefault<z.ZodEnum<typeof import("@wildo-ai/external-connectors-models").ProrationBehavior>>;
                 timing: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").BillingTiming>>;
             }, z.core.$strip>>;
             cancellation: z.ZodOptional<z.ZodObject<{
@@ -193,7 +193,7 @@ export declare const BillingStateResponseSchema: z.ZodObject<{
     invoices: z.ZodArray<z.ZodObject<{
         _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
         billingAccountId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
-        status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodEnum<typeof import("./billing-enums.shared.schemas").InvoiceStatus>>>>;
+        status: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodEnum<typeof import("@wildo-ai/external-connectors-models").InvoiceStatus>>>>;
         total: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedMoneySchema>>;
         hostedInvoiceUrl: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>;
         invoicePdfUrl: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>;

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

@@ -1 +1 @@
-{"version":3,"file":"price.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/price.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,cAAc,EACf,MAAM,gCAAgC,CAAC;AAIxC;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;;iBAO1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAIxD,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;iBA4CtB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}
+{"version":3,"file":"price.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/price.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,cAAc,EACf,MAAM,gCAAgC,CAAC;AAIxC;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;;;;iBAO1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAIxD,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;iBAkDtB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}

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

@@ -55,7 +55,13 @@ export const PriceSchema = z.object({
     usageAggregation: z.enum(UsageAggregationType).optional(),
     /**
      * Tax behavior for this price (maps to Stripe's price.tax_behavior).
-     * Resolved from: price-level override > product.taxDisplayMode > BillingConfiguration.tax.defaultDisplayMode.
+     *
+     * There is NO resolution chain: this value alone reaches the provider. The catalog sync passes
+     * `taxBehavior` straight through on both the price upsert and the provider price creation, so
+     * leaving it unset does not fall back to `product.taxDisplayMode` or to
+     * `BillingConfiguration.tax.defaultDisplayMode`. The provider call simply omits `tax_behavior`
+     * and the billing account's own default decides. Declare it here on every price whose tax
+     * presentation matters.
      * - 'exclusive': amount is HT, tax added on top
      * - 'inclusive': amount is TTC, tax embedded
      * When absent: inherits from product, then from global config.

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

@@ -1 +1 @@
-{"version":3,"file":"price.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/price.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EACL,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,cAAc,GACf,MAAM,gCAAgC,CAAC;AAExC,sEAAsE;AAEtE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,sEAAsE;IACtE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,mCAAmC;IACnC,SAAS,EAAE,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IAChF,6DAA6D;IAC7D,SAAS,EAAE,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;CACjF,CAAC,CAAC;AAGH,sEAAsE;AAEtE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAElC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE;IACtD,sCAAsC;IACtC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,WAAW,EAAE;IAEzD,iEAAiE;IACjE,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,cAAc,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC;IACvE;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,cAAc,EAAE;IAEjG,uDAAuD;IACvD,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,QAAQ,EAAE,CAAC,cAAc,EAAE;IAC7D,iFAAiF;IACjF,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAE3C,gDAAgD;IAChD,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,QAAQ,EAAE;IAC1C,iEAAiE;IACjE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzC,gDAAgD;IAChD,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,QAAQ,EAAE;IAEzD;;;;;;OAMG;IACH,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE;IAE9C,mEAAmE;IACnE,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE;IACtD,4EAA4E;IAC5E,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACpC,mDAAmD;IACnD,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE;IAEjD,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;CACtF,CAAC,CAAC","sourcesContent":["/**\n * Price & Price Tier Schemas (Shared)\n *\n * Prices define how much a product costs. A product can have multiple prices\n * (e.g., monthly vs. yearly, different currencies).\n *\n * Prices are APPLICATION-scoped, linked to a Product via productId.\n * Like products, they are populated lazily from the code-defined catalog.\n *\n * @see billing-and-features-system.md §6.2 (Product & Price Catalog)\n */\n\nimport { z } from 'zod';\nimport { z_money, CurrencyAllowed } from '@wildo-ai/zod-decorators';\nimport {\n  PricingModel,\n  BillingInterval,\n  UsageAggregationType,\n  TaxDisplayMode,\n} from './billing-enums.shared.schemas';\n\n// ── Price Tier ─────────────────────────────────────────────────────\n\n/**\n * A single tier in a tiered/graduated pricing model.\n * `upTo: null` means \"infinity\" (the final open-ended tier).\n *\n * Tier amounts carry their own currency via z_money for:\n * - Self-describing data (no implicit dependency on parent Price's currency)\n * - Proper money input rendering in forms\n * - Bigint precision for all monetary values\n */\nexport const PriceTierSchema = z.object({\n  /** Upper bound for this tier (null = infinity, i.e. the last tier) */\n  upTo: z.number().nullable(),\n  /** Per-unit price for this tier */\n  unitPrice: z_money({ currenciesAllowed: [CurrencyAllowed.FIAT], minAmount: 0n }),\n  /** Flat price added to this tier (on top of unit pricing) */\n  flatPrice: z_money({ currenciesAllowed: [CurrencyAllowed.FIAT], minAmount: 0n }),\n});\nexport type PriceTier = z.infer<typeof PriceTierSchema>;\n\n// ── Price ──────────────────────────────────────────────────────────\n\nexport const PriceSchema = z.object({\n\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n  /** Reference to the parent product */\n  productId: z.string().min(1).isForeignKey().isDBIndexed(),\n\n  /** Pricing model (flat, per_unit, tiered, graduated, package) */\n  model: z.enum(PricingModel).isSummaryField().systemEnum('PricingModel'),\n  /**\n   * Unit price for FLAT/PER_UNIT models.\n   * Uses z_money for bigint precision, self-contained currency, and proper form rendering.\n   * Undefined for TIERED/GRADUATED models (use `tiers` instead).\n   */\n  unitPrice: z_money({ currenciesAllowed: [CurrencyAllowed.FIAT], minAmount: 0n }).isSummaryField(),\n\n  /** Billing interval (undefined for one-time prices) */\n  interval: z.enum(BillingInterval).optional().isSummaryField(),\n  /** Interval count (e.g., 3 for quarterly = interval:'month', intervalCount:3) */\n  intervalCount: z.number().min(1).default(1),\n\n  /** Tiers for TIERED/GRADUATED pricing models */\n  tiers: z.array(PriceTierSchema).optional(),\n  /** Package size for PACKAGE pricing model (price per N units) */\n  packageSize: z.number().min(1).optional(),\n  /** Usage aggregation type for metered prices */\n  usageAggregation: z.enum(UsageAggregationType).optional(),\n\n  /**\n   * Tax behavior for this price (maps to Stripe's price.tax_behavior).\n   * Resolved from: price-level override > product.taxDisplayMode > BillingConfiguration.tax.defaultDisplayMode.\n   * - 'exclusive': amount is HT, tax added on top\n   * - 'inclusive': amount is TTC, tax embedded\n   * When absent: inherits from product, then from global config.\n   */\n  taxBehavior: z.enum(TaxDisplayMode).optional(),\n\n  /** Provider sync (lazy: populated on first use, not at startup) */\n  providerPriceId: z.string().optional().isBackendOnly(),\n  /** Whether this is the default price for the product (shown first in UI) */\n  isDefault: z.boolean().default(true),\n  /** Whether this price is available for purchase */\n  isActive: z.boolean().default(true).isDBIndexed(),\n\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type Price = z.infer<typeof PriceSchema>;\n"]}
+{"version":3,"file":"price.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/price.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EACL,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,cAAc,GACf,MAAM,gCAAgC,CAAC;AAExC,sEAAsE;AAEtE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,sEAAsE;IACtE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,mCAAmC;IACnC,SAAS,EAAE,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IAChF,6DAA6D;IAC7D,SAAS,EAAE,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;CACjF,CAAC,CAAC;AAGH,sEAAsE;AAEtE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAElC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE;IACtD,sCAAsC;IACtC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,WAAW,EAAE;IAEzD,iEAAiE;IACjE,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,cAAc,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC;IACvE;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,cAAc,EAAE;IAEjG,uDAAuD;IACvD,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,QAAQ,EAAE,CAAC,cAAc,EAAE;IAC7D,iFAAiF;IACjF,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAE3C,gDAAgD;IAChD,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,QAAQ,EAAE;IAC1C,iEAAiE;IACjE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACzC,gDAAgD;IAChD,gBAAgB,EAAE,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,QAAQ,EAAE;IAEzD;;;;;;;;;;;;OAYG;IACH,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,QAAQ,EAAE;IAE9C,mEAAmE;IACnE,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE;IACtD,4EAA4E;IAC5E,SAAS,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACpC,mDAAmD;IACnD,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE;IAEjD,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;CACtF,CAAC,CAAC","sourcesContent":["/**\n * Price & Price Tier Schemas (Shared)\n *\n * Prices define how much a product costs. A product can have multiple prices\n * (e.g., monthly vs. yearly, different currencies).\n *\n * Prices are APPLICATION-scoped, linked to a Product via productId.\n * Like products, they are populated lazily from the code-defined catalog.\n *\n * @see billing-and-features-system.md §6.2 (Product & Price Catalog)\n */\n\nimport { z } from 'zod';\nimport { z_money, CurrencyAllowed } from '@wildo-ai/zod-decorators';\nimport {\n  PricingModel,\n  BillingInterval,\n  UsageAggregationType,\n  TaxDisplayMode,\n} from './billing-enums.shared.schemas';\n\n// ── Price Tier ─────────────────────────────────────────────────────\n\n/**\n * A single tier in a tiered/graduated pricing model.\n * `upTo: null` means \"infinity\" (the final open-ended tier).\n *\n * Tier amounts carry their own currency via z_money for:\n * - Self-describing data (no implicit dependency on parent Price's currency)\n * - Proper money input rendering in forms\n * - Bigint precision for all monetary values\n */\nexport const PriceTierSchema = z.object({\n  /** Upper bound for this tier (null = infinity, i.e. the last tier) */\n  upTo: z.number().nullable(),\n  /** Per-unit price for this tier */\n  unitPrice: z_money({ currenciesAllowed: [CurrencyAllowed.FIAT], minAmount: 0n }),\n  /** Flat price added to this tier (on top of unit pricing) */\n  flatPrice: z_money({ currenciesAllowed: [CurrencyAllowed.FIAT], minAmount: 0n }),\n});\nexport type PriceTier = z.infer<typeof PriceTierSchema>;\n\n// ── Price ──────────────────────────────────────────────────────────\n\nexport const PriceSchema = z.object({\n\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n  /** Reference to the parent product */\n  productId: z.string().min(1).isForeignKey().isDBIndexed(),\n\n  /** Pricing model (flat, per_unit, tiered, graduated, package) */\n  model: z.enum(PricingModel).isSummaryField().systemEnum('PricingModel'),\n  /**\n   * Unit price for FLAT/PER_UNIT models.\n   * Uses z_money for bigint precision, self-contained currency, and proper form rendering.\n   * Undefined for TIERED/GRADUATED models (use `tiers` instead).\n   */\n  unitPrice: z_money({ currenciesAllowed: [CurrencyAllowed.FIAT], minAmount: 0n }).isSummaryField(),\n\n  /** Billing interval (undefined for one-time prices) */\n  interval: z.enum(BillingInterval).optional().isSummaryField(),\n  /** Interval count (e.g., 3 for quarterly = interval:'month', intervalCount:3) */\n  intervalCount: z.number().min(1).default(1),\n\n  /** Tiers for TIERED/GRADUATED pricing models */\n  tiers: z.array(PriceTierSchema).optional(),\n  /** Package size for PACKAGE pricing model (price per N units) */\n  packageSize: z.number().min(1).optional(),\n  /** Usage aggregation type for metered prices */\n  usageAggregation: z.enum(UsageAggregationType).optional(),\n\n  /**\n   * Tax behavior for this price (maps to Stripe's price.tax_behavior).\n   *\n   * There is NO resolution chain: this value alone reaches the provider. The catalog sync passes\n   * `taxBehavior` straight through on both the price upsert and the provider price creation, so\n   * leaving it unset does not fall back to `product.taxDisplayMode` or to\n   * `BillingConfiguration.tax.defaultDisplayMode`. The provider call simply omits `tax_behavior`\n   * and the billing account's own default decides. Declare it here on every price whose tax\n   * presentation matters.\n   * - 'exclusive': amount is HT, tax added on top\n   * - 'inclusive': amount is TTC, tax embedded\n   * When absent: inherits from product, then from global config.\n   */\n  taxBehavior: z.enum(TaxDisplayMode).optional(),\n\n  /** Provider sync (lazy: populated on first use, not at startup) */\n  providerPriceId: z.string().optional().isBackendOnly(),\n  /** Whether this is the default price for the product (shown first in UI) */\n  isDefault: z.boolean().default(true),\n  /** Whether this price is available for purchase */\n  isActive: z.boolean().default(true).isDBIndexed(),\n\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type Price = z.infer<typeof PriceSchema>;\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"product-behavior-policy.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/product-behavior-policy.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,yBAAyB,EAC1B,MAAM,gCAAgC,CAAC;AAIxC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB;;;iBAK3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI1D;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqDtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}
+{"version":3,"file":"product-behavior-policy.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/product-behavior-policy.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,yBAAyB,EAC1B,MAAM,gCAAgC,CAAC;AAIxC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB;;;iBAK3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI1D;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8FtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}

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

@@ -44,7 +44,17 @@ export const ProductBehaviorPolicySchema = z.object({
     trial: z.object({
         /** Number of trial days (0 = no trial) */
         days: z.number().min(0).default(0),
-        /** Whether to require a payment method before trial starts */
+        /**
+         * Require a payment method before the trial starts. READ since 2026-09-08 (#408).
+         *
+         * It reached no provider call before that, so a trial declared as requiring a card behaved
+         * identically to one that did not — Wonder Todos' enterprise plan (`true`) and professional
+         * plan (`false`) were indistinguishable at the provider.
+         *
+         * Only meaningful WITH a trial: a product declaring it alongside `days: 0` demands nothing,
+         * because asking for a card up front on a purchase with no trial is a different decision and
+         * nobody authored it.
+         */
         requirePaymentMethod: z.boolean().default(false),
     }).optional(),
     /** Upgrade behavior (when switching TO this plan from a lower tier) */
@@ -67,22 +77,53 @@ export const ProductBehaviorPolicySchema = z.object({
         defaultBehavior: z.enum(BillingTiming).default(BillingTiming.AT_PERIOD_END),
     }).optional(),
     /**
-     * Authored metering policy (for METERED products only).
+     * Authored metering policy (for METERED products only), READ by
+     * `UsageMeteringBackendService` since 2026-09-08 (#415).
      *
-     * The current `UsageMeteringBackendService` does not yet consume these
-     * scheduling, aggregation-window or retry values: it groups every pending row
-     * by billing account and product whenever the externally scheduled flush runs.
-     * Keep this distinction visible so configuration documentation does not turn
-     * an accepted policy shape into a false runtime guarantee.
+     * Every field here was declared, defaulted, documented and read by NOTHING until then: the flush
+     * merged every pending row by billing account and product whatever the product said, so
+     * `preFlushAggregation: false` was unrepresentable and `aggregationWindow`'s two members selected
+     * between behaviours that were the same behaviour. The note that stood here said exactly that and
+     * asked that the gap stay visible rather than become "a false runtime guarantee"; this replaces it
+     * because the guarantee is now real, and says which reader makes each field true.
      */
     metering: z.object({
-        /** How often to flush aggregated usage to billing provider (minutes) */
+        /**
+         * How often to flush aggregated usage to the billing provider (minutes).
+         *
+         * Read by the engine's usage-flush batch, which picks the SHORTEST interval any metered product
+         * authors — a schedule is one thing and the products sharing it are many, so the fastest promise
+         * is the one that has to be kept. A product asking for less frequent reporting than its neighbour
+         * still gets reported at the neighbour's cadence, which costs nothing: reporting sooner than
+         * authored is never wrong, reporting later than authored is.
+         */
         flushIntervalMinutes: z.number().min(1).default(60),
-        /** Aggregation window for usage records before flush */
+        /**
+         * Whether one meter event may span a billing-period boundary.
+         *
+         * This is not a preference, it is a correctness choice about MONEY. A merged group carries ONE
+         * timestamp and the provider assigns the event to the period that timestamp falls in, so
+         * `PER_FLUSH` merging across a boundary bills the earlier period's usage into the later one.
+         * `PER_BILLING_PERIOD` splits at the boundary, derived from the subscription's own
+         * `currentPeriodStart` / `currentPeriodEnd`. Leave it `PER_FLUSH` when the product's periods do
+         * not change what it costs.
+         */
         aggregationWindow: z.enum(MeteringAggregationWindow).default(MeteringAggregationWindow.PER_FLUSH),
-        /** Aggregate locally before sending (sum up same-key records) */
+        /**
+         * Aggregate locally before sending (sum same-key records into one meter event).
+         *
+         * `false` sends one event per recorded row, each with its own instant. Choose it when the provider
+         * must see every event — because its aggregation is not a sum, or because the individual instants
+         * matter. Local merging destroys both irreversibly, before the provider ever sees them.
+         */
         preFlushAggregation: z.boolean().default(true),
-        /** Retry policy when provider flush fails */
+        /**
+         * Retry policy when a provider report fails.
+         *
+         * Safe only because every meter event carries a derived idempotency identifier: a retry after a
+         * response lost in transit re-sends the same identifier and the provider discards it. Retrying
+         * without that is how a timeout becomes a double charge, which is why the two shipped together.
+         */
         retryPolicy: z.object({
             maxRetries: z.number().default(3),
             backoffMultiplier: z.number().default(2),

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    /** Whether to require a payment method before trial starts */\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).\n   *\n   * The current `UsageMeteringBackendService` does not yet consume these\n   * scheduling, aggregation-window or retry values: it groups every pending row\n   * by billing account and product whenever the externally scheduled flush runs.\n   * Keep this distinction visible so configuration documentation does not turn\n   * an accepted policy shape into a false runtime guarantee.\n   */\n  metering: z.object({\n    /** How often to flush aggregated usage to billing provider (minutes) */\n    flushIntervalMinutes: z.number().min(1).default(60),\n    /** Aggregation window for usage records before flush */\n    aggregationWindow: z.enum(MeteringAggregationWindow).default(MeteringAggregationWindow.PER_FLUSH),\n    /** Aggregate locally before sending (sum up same-key records) */\n    preFlushAggregation: z.boolean().default(true),\n    /** Retry policy when provider flush fails */\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  }).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

@@ -74,11 +74,11 @@ export declare const ProductDefinitionSchema: z.ZodObject<{
             requirePaymentMethod: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strip>>;
         upgrade: z.ZodOptional<z.ZodObject<{
-            proration: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").ProrationBehavior>>;
+            proration: z.ZodDefault<z.ZodEnum<typeof import("@wildo-ai/external-connectors-models").ProrationBehavior>>;
             timing: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").BillingTiming>>;
         }, z.core.$strip>>;
         downgrade: z.ZodOptional<z.ZodObject<{
-            proration: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").ProrationBehavior>>;
+            proration: z.ZodDefault<z.ZodEnum<typeof import("@wildo-ai/external-connectors-models").ProrationBehavior>>;
             timing: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").BillingTiming>>;
         }, z.core.$strip>>;
         cancellation: z.ZodOptional<z.ZodObject<{

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

@@ -31,11 +31,11 @@ export declare const productsResourceConfiguration_InitializationFactory: (resou
             requirePaymentMethod: import("zod").ZodDefault<import("zod").ZodBoolean>;
         }, import("zod/v4/core").$strip>>;
         upgrade: import("zod").ZodOptional<import("zod").ZodObject<{
-            proration: import("zod").ZodDefault<import("zod").ZodEnum<typeof import("./billing-enums.shared.schemas").ProrationBehavior>>;
+            proration: import("zod").ZodDefault<import("zod").ZodEnum<typeof import("@wildo-ai/external-connectors-models").ProrationBehavior>>;
             timing: import("zod").ZodDefault<import("zod").ZodEnum<typeof import("./billing-enums.shared.schemas").BillingTiming>>;
         }, import("zod/v4/core").$strip>>;
         downgrade: import("zod").ZodOptional<import("zod").ZodObject<{
-            proration: import("zod").ZodDefault<import("zod").ZodEnum<typeof import("./billing-enums.shared.schemas").ProrationBehavior>>;
+            proration: import("zod").ZodDefault<import("zod").ZodEnum<typeof import("@wildo-ai/external-connectors-models").ProrationBehavior>>;
             timing: import("zod").ZodDefault<import("zod").ZodEnum<typeof import("./billing-enums.shared.schemas").BillingTiming>>;
         }, import("zod/v4/core").$strip>>;
         cancellation: import("zod").ZodOptional<import("zod").ZodObject<{

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

@@ -44,11 +44,11 @@ export declare const ProductSchema: z.ZodObject<{
             requirePaymentMethod: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strip>>;
         upgrade: z.ZodOptional<z.ZodObject<{
-            proration: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").ProrationBehavior>>;
+            proration: z.ZodDefault<z.ZodEnum<typeof import("@wildo-ai/external-connectors-models").ProrationBehavior>>;
             timing: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").BillingTiming>>;
         }, z.core.$strip>>;
         downgrade: z.ZodOptional<z.ZodObject<{
-            proration: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").ProrationBehavior>>;
+            proration: z.ZodDefault<z.ZodEnum<typeof import("@wildo-ai/external-connectors-models").ProrationBehavior>>;
             timing: z.ZodDefault<z.ZodEnum<typeof import("./billing-enums.shared.schemas").BillingTiming>>;
         }, z.core.$strip>>;
         cancellation: z.ZodOptional<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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0ExB,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;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"}

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

@@ -49,12 +49,16 @@ export const ProductSchema = z.object({
     /** For ADDON type: required plan tiers to subscribe to this addon (empty = no restriction) */
     requiredPlanTiers: z.array(z.string()).optional(),
     /**
-     * Tax display override for this product (overrides BillingConfiguration.tax.defaultDisplayMode).
+     * Tax display intent for this product, recorded on the product row.
      * - 'exclusive': price amounts are HT (tax added at checkout)
      * - 'inclusive': price amounts are TTC (tax embedded)
-     * When absent: uses global default from BillingConfiguration.
      *
-     * Common pattern: org products → exclusive, user products → inclusive.
+     * It is DECLARATIVE ONLY and does not reach the billing provider. The catalog sync stores it on
+     * the product and then sends each price's own `taxBehavior` unchanged, so a price that declares
+     * none is created without `tax_behavior` regardless of what this field says. To make the
+     * intention effective, set `taxBehavior` on the prices as well.
+     *
+     * Common pattern: org products exclusive, user products inclusive.
      */
     taxDisplayMode: z.enum(TaxDisplayMode).optional(),
     /**

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 override for this product (overrides BillingConfiguration.tax.defaultDisplayMode).\n   * - 'exclusive': price amounts are HT (tax added at checkout)\n   * - 'inclusive': price amounts are TTC (tax embedded)\n   * When absent: uses global default from BillingConfiguration.\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';\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/subscription.shared.resources-config.schemas.d.ts

@@ -23,7 +23,7 @@ export declare enum BillingSubscription_Operations {
 }
 /** Request DTO for CANCEL operation — shared between resource config and custom impl */
 export declare const BillingSubscription_CancelRequestDto: z.ZodObject<{
-    cancelImmediately: z.ZodDefault<z.ZodBoolean>;
+    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 */

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;;;iBAG/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;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"}