@wildo-ai/saas-models 1.1.4 → 1.1.6

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

@@ -15,6 +15,8 @@ import { PriceSchema } from './price.shared.schemas.js';
 import { InvoiceRefSchema } from './invoice-ref.shared.schemas.js';
 import { PromotionSchema } from './promotions.shared.schemas.js';
 import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
+import { CoreResourceType } from '../resources/resources.shared.core.definitions.js';
+import { markEmbeddedResourceSchema } from '../resources/embedded-resource-mark.shared.utils.js';
 // ── Usage Summary ──────────────────────────────────────────────────
 /**
  * Usage summary: aggregated usage data for the frontend UsageDashboard.
@@ -28,14 +30,14 @@ import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
 export const UsageSummarySchema = z.object({
     /** Usage per metered product, keyed by product key */
     byProduct: z.record(z.string(), z.object({
-        currentPeriodUsage: z.number(),
+        currentPeriodUsage: z.number().describe("Usage recorded in the current billing period."),
         /** Previous period (for trend display) */
-        previousPeriodUsage: z.number().optional(),
+        previousPeriodUsage: z.number().optional().describe("Usage recorded in the previous billing period."),
         /** Usage limit (from product/subscription, if applicable) */
-        limit: z.number().optional(),
+        limit: z.number().optional().describe("The usage limit set by the product or subscription, when one applies."),
         /** Last usage recorded at */
-        lastRecordedAt: z.date().optional(),
-    })),
+        lastRecordedAt: z.date().optional().describe("When usage was last recorded."),
+    })).describe("Usage per metered product, keyed by product key."),
 });
 // ── Billing State Response ─────────────────────────────────────────
 /**
@@ -45,9 +47,10 @@ export const UsageSummarySchema = z.object({
  * facade purely for the frontend balance display, keyed by pool key.
  */
 export const CreditPoolBalanceSchema = z.object({
-    available: z.number(),
-    totalPurchased: z.number(),
-    totalConsumed: z.number(),
+    available: z.number().describe("Credits available to spend."),
+    totalPurchased: z.number().describe("Credits purchased in total."),
+    totalGranted: z.number().describe("Credits given without a purchase in total, such as referral rewards."),
+    totalConsumed: z.number().describe("Credits consumed in total."),
 });
 /**
  * Aggregated billing state returned by the lazy facade endpoint.
@@ -63,14 +66,44 @@ export const CreditPoolBalanceSchema = z.object({
  * project the external response. `BillingStateResponse` is derived from it so the
  * type and the runtime contract cannot drift.
  */
+/** Independently loaded portions of the aggregate. Derived catalog projections use PRODUCTS. */
+export var BillingStateSlice;
+(function (BillingStateSlice) {
+    BillingStateSlice["BILLING_ACCOUNT"] = "billingAccount";
+    BillingStateSlice["SUBSCRIPTION"] = "subscription";
+    BillingStateSlice["PRODUCTS"] = "products";
+    BillingStateSlice["PRICES"] = "prices";
+    BillingStateSlice["INVOICES"] = "invoices";
+    BillingStateSlice["USAGE"] = "usage";
+    BillingStateSlice["CREDIT_POOLS"] = "creditPools";
+    BillingStateSlice["ACTIVE_PROMOTIONS"] = "activePromotions";
+})(BillingStateSlice || (BillingStateSlice = {}));
+/** Empty data is meaningful only when its query (and required dependencies) succeeded. */
+export var BillingSliceAvailability;
+(function (BillingSliceAvailability) {
+    BillingSliceAvailability["AVAILABLE"] = "available";
+    BillingSliceAvailability["UNAVAILABLE"] = "unavailable";
+})(BillingSliceAvailability || (BillingSliceAvailability = {}));
+export const BillingStateAvailabilitySchema = z.record(z.enum(BillingStateSlice), z.enum(BillingSliceAvailability));
 export const BillingStateResponseSchema = z.object({
-    billingAccount: BillingAccountSchema.nullable(),
-    subscription: BillingSubscriptionBaseSchema.nullable(),
-    products: z.array(ProductSchema),
-    prices: z.array(PriceSchema),
-    invoices: z.array(InvoiceRefSchema),
-    usage: UsageSummarySchema,
-    creditPools: z.record(z.string(), CreditPoolBalanceSchema),
+    /** Query failures keep their empty transport placeholders but MUST NOT be presented as absence. */
+    availability: BillingStateAvailabilitySchema.describe("Whether each part of this response loaded. A part marked `unavailable` failed to load: its empty value means nothing, and must not be read as absence."),
+    billingAccount: BillingAccountSchema.nullable().describe("The billing account of the caller's scope, or `null` when the scope has none."),
+    // The subscription and the invoice refs are not marked as embedded records like the products below: which resource
+    // they are depends on the caller's scope. So the few fields no other source describes here are described in place
+    // (#1625), rather than on the base schemas, where they would replace each resource's own, richer description.
+    subscription: BillingSubscriptionBaseSchema.extend({
+        status: BillingSubscriptionBaseSchema.shape.status.describe("The subscription's lifecycle state as the billing provider reports it, such as `active`, `trialing` or `past_due`."),
+    }).nullable().describe("The scope's current subscription, or `null` when it has none."),
+    // Products, prices and promotions are each one resource's records, described by that resource (#1625).
+    products: z.array(markEmbeddedResourceSchema(ProductSchema, CoreResourceType.PRODUCTS)).describe("Every product visible in this scope, including ones no longer on sale, so a plan someone already holds can still be named. Which of them can be acquired now is `acquirableProductKeys`."),
+    prices: z.array(markEmbeddedResourceSchema(PriceSchema, CoreResourceType.PRICES)).describe("The prices visible in this scope."),
+    invoices: z.array(InvoiceRefSchema.extend({
+        status: InvoiceRefSchema.shape.status.describe("The invoice's payment state as the billing provider reports it, such as `open`, `paid` or `void`."),
+        total: InvoiceRefSchema.shape.total.describe('The invoice total: an amount in minor units, with its currency.'),
+    })).describe("References to the scope's invoices."),
+    usage: UsageSummarySchema.describe("Metered usage in this scope."),
+    creditPools: z.record(z.string(), CreditPoolBalanceSchema).describe("Credit balances, keyed by credit pool."),
     /**
      * Scope/product-visible promotions for the current billing surface.
      *
@@ -79,7 +112,7 @@ export const BillingStateResponseSchema = z.object({
      * current scope. It is not a promise that every entry is redeemable for any
      * arbitrary checkout item the user might pick next.
      */
-    activePromotions: z.array(PromotionSchema),
+    activePromotions: z.array(markEmbeddedResourceSchema(PromotionSchema, CoreResourceType.PROMOTIONS)).describe("Promotions visible in this scope: active, not exhausted, synced with the billing provider, and targeting a product in scope. Not a promise that each one applies to a particular checkout."),
     /**
      * The subset of `products` (by `key`) a caller may ACQUIRE right now — buy, or move a
      * subscription onto.
@@ -110,21 +143,16 @@ export const BillingStateResponseSchema = z.object({
      * caller (a back-office catalog shows non-public rows). A customer pricing table composes the
      * two; it must not re-spell either.
      *
-     * ## Optional under protest — and what would make it required
-     *
-     * `BillingStateBackendService.getState` ALWAYS sets it, so on this engine's own wire it is never
-     * absent. It is `.optional()` for exactly one reason: `BillingContext.tsx` rebuilds the state
-     * object field-by-field from the HTTP response rather than passing it through, so every field
-     * added here is a compile break in a file this change may not edit. That hand-kept copy is the
-     * real defect — it makes any additive contract change breaking — and the field should be made
-     * REQUIRED in the same change that has the frontend read it.
+     * The aggregate producer sets this field and BillingContext preserves it. Consumers
+     * must check PRODUCTS availability before interpreting this projection: an empty set
+     * from an unavailable catalog does not prove that nothing can be acquired.
      *
      * Absence therefore means "the producer did not project acquirability", never "nothing is
      * acquirable" and never "everything is". A consumer that receives the set MUST use it in
      * preference to re-deriving the rule; a consumer that does not is on the older, weaker footing
      * this field exists to retire.
      */
-    acquirableProductKeys: z.array(z.string()).optional(),
-    scopeType: z.enum(ResourcePrimaryScope),
+    acquirableProductKeys: z.array(z.string()).optional().describe("The keys of the products in `products` that may be bought, or moved onto, right now. Absent means this was not computed, not that nothing can be acquired. Check `availability` for products first: from a catalog that failed to load, an empty list proves nothing."),
+    scopeType: z.enum(ResourcePrimaryScope).describe("The scope this billing state belongs to."),
 });
 //# sourceMappingURL=billing-types.shared.schemas.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"billing-types.shared.schemas.js","sourceRoot":"","sources":["../../../src/billing/billing-types.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AACxE,OAAO,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AA8B7E,sEAAsE;AAEtE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,sDAAsD;IACtD,SAAS,EAAE,CAAC,CAAC,MAAM,CACjB,CAAC,CAAC,MAAM,EAAE,EACV,CAAC,CAAC,MAAM,CAAC;QACP,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE;QAC9B,0CAA0C;QAC1C,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC1C,6DAA6D;QAC7D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC5B,6BAA6B;QAC7B,cAAc,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE;KACpC,CAAC,CACH;CACF,CAAC,CAAC;AAGH,sEAAsE;AAEtE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;CAC1B,CAAC,CAAC;AAGH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,cAAc,EAAE,oBAAoB,CAAC,QAAQ,EAAE;IAC/C,YAAY,EAAE,6BAA6B,CAAC,QAAQ,EAAE;IACtD,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC;IAChC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC;IAC5B,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC;IACnC,KAAK,EAAE,kBAAkB;IACzB,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,uBAAuB,CAAC;IAC1D;;;;;;;OAOG;IACH,gBAAgB,EAAE,CAAC,CAAC,KAAK,CAAC,eAAe,CAAC;IAC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,qBAAqB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACrD,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC;CACxC,CAAC,CAAC","sourcesContent":["/**\n * Billing Supporting Types (Shared)\n *\n * Types used by the billing API, frontend hooks, and provider interface.\n * These are NOT DB schemas — they are API response shapes, provider abstractions,\n * and aggregated views.\n *\n * @see billing-and-features-system.md §6.2c (Supporting Types)\n */\n\nimport { z } from 'zod';\nimport type { MoneyValue } from '@wildo-ai/zod-decorators';\nimport { BillingAccountSchema } from './billing-account.shared.schemas';\nimport { BillingSubscriptionBaseSchema } from './subscription.shared.schemas';\nimport { ProductSchema } from './product.shared.schemas';\nimport { PriceSchema } from './price.shared.schemas';\nimport { InvoiceRefSchema } from './invoice-ref.shared.schemas';\nimport { PromotionSchema } from './promotions.shared.schemas';\nimport { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\n\n// ── Provider Canonical Types ───────────────────────────────────────\n// StandardBilling_SubscriptionData and StandardBilling_InvoicePreview are\n// defined in @wildo-ai/external-connectors-models (standard billing interface)\n// and re-exported here for convenience.\nexport type { StandardBilling_SubscriptionData, StandardBilling_InvoicePreview } from '@wildo-ai/external-connectors-models';\n\n// ── Invoice Preview ────────────────────────────────────────────────\n\n/**\n * Invoice preview: returned by previewPlanChange() to show prorated cost before committing.\n * Data comes from provider (Stripe's upcoming invoice API), NOT stored locally.\n *\n * All monetary amounts use MoneyValue for bigint precision and self-contained currency.\n */\nexport interface InvoicePreview {\n  /** Prorated amount to charge/credit */\n  amount: MoneyValue;\n  /** Line items breakdown (what changed, prorated amounts) */\n  lineItems: Array<{\n    description: string;\n    amount: MoneyValue;\n    quantity: number;\n  }>;\n  /** When this amount would be charged */\n  periodStart: Date;\n  periodEnd: Date;\n}\n\n// ── Usage Summary ──────────────────────────────────────────────────\n\n/**\n * Usage summary: aggregated usage data for the frontend UsageDashboard.\n * Computed from UsageRecords, keyed by metered product key.\n *\n * Authored as a Zod schema (not a bare interface) so it can compose into\n * `BillingStateResponseSchema` — the runtime contract wired as the `GET_STATE`\n * custom operation's `customResponseDto`. `UsageSummary` is derived from it to\n * keep the type and the runtime shape from drifting.\n */\nexport const UsageSummarySchema = z.object({\n  /** Usage per metered product, keyed by product key */\n  byProduct: z.record(\n    z.string(),\n    z.object({\n      currentPeriodUsage: z.number(),\n      /** Previous period (for trend display) */\n      previousPeriodUsage: z.number().optional(),\n      /** Usage limit (from product/subscription, if applicable) */\n      limit: z.number().optional(),\n      /** Last usage recorded at */\n      lastRecordedAt: z.date().optional(),\n    }),\n  ),\n});\nexport type UsageSummary = z.infer<typeof UsageSummarySchema>;\n\n// ── Billing State Response ─────────────────────────────────────────\n\n/**\n * Per-pool credit balance projection embedded in the aggregated billing state.\n *\n * A lean view (NOT the full `CreditPool` resource) built by the billing-state\n * facade purely for the frontend balance display, keyed by pool key.\n */\nexport const CreditPoolBalanceSchema = z.object({\n  available: z.number(),\n  totalPurchased: z.number(),\n  totalConsumed: z.number(),\n});\nexport type CreditPoolBalance = z.infer<typeof CreditPoolBalanceSchema>;\n\n/**\n * Aggregated billing state returned by the lazy facade endpoint.\n * Single source of truth for frontend BillingProvider and backend controller.\n *\n * Authored as a Zod schema (not a bare interface) because the `GET_STATE`\n * custom operation wires it as its `customResponseDto`. That operation borrows\n * the COUNT verb for its route/verb via `resourceOperationLike` but returns\n * THIS aggregated shape — so without a `customResponseDto` the DTO builder would\n * assign it the COUNT default envelope (`{ count }`), and the service output\n * would fail `transformOutput`'s `internalDto.parse` → HTTP 500. The composed\n * schema gives the builder the real runtime contract to validate against and to\n * project the external response. `BillingStateResponse` is derived from it so the\n * type and the runtime contract cannot drift.\n */\nexport const BillingStateResponseSchema = z.object({\n  billingAccount: BillingAccountSchema.nullable(),\n  subscription: BillingSubscriptionBaseSchema.nullable(),\n  products: z.array(ProductSchema),\n  prices: z.array(PriceSchema),\n  invoices: z.array(InvoiceRefSchema),\n  usage: UsageSummarySchema,\n  creditPools: z.record(z.string(), CreditPoolBalanceSchema),\n  /**\n   * Scope/product-visible promotions for the current billing surface.\n   *\n   * This list intentionally excludes promotions that are inactive, exhausted,\n   * unsynced with the billing provider, or targeted only at products outside the\n   * current scope. It is not a promise that every entry is redeemable for any\n   * arbitrary checkout item the user might pick next.\n   */\n  activePromotions: z.array(PromotionSchema),\n  /**\n   * The subset of `products` (by `key`) a caller may ACQUIRE right now — buy, or move a\n   * subscription onto.\n   *\n   * ## Why a sibling key set rather than a filter on `products`\n   *\n   * One call serves two surfaces that want OPPOSITE things from it. An acquisition surface (a\n   * pricing table) must not offer a plan the purchase gate will refuse; a holding surface (the\n   * \"your current plan\" panel, the subscription-item → product resolution in the frontend billing\n   * context) must still be able to NAME a plan the catalogue has withdrawn, because a customer\n   * already on a retired plan is exactly who needs to see what they hold. Filtering `products` by\n   * `isActive` would serve the first and break the second — the same trade the `REMOVE_ADDON` call\n   * site settles by reading with `REFERENCE` intent rather than `ACQUIRE`.\n   *\n   * So the response DISTINGUISHES instead of filtering: `products` stays the full scope-visible\n   * catalog, and this set states which of them acquisition may offer.\n   *\n   * ## Why the server answers it at all\n   *\n   * `Product.isActive` is the declared off-boarding path, and the backend gate that makes\n   * retirement TRUE (`readProductByKey` with `ACQUIRE` intent) applies ONE predicate to it. A\n   * listing surface holds rows, not keys, so it cannot use that reader — and every listing left to\n   * itself re-derives the rule from the raw column. That had already happened twice by 2026-09-09,\n   * in a frontend component and in the reader, agreeing only by luck. This set is computed by the\n   * gate's own predicate, so a surface that reads it cannot drift from what checkout will accept.\n   *\n   * NOT a visibility answer: `isPublic` is a per-surface decision the server cannot take for every\n   * caller (a back-office catalog shows non-public rows). A customer pricing table composes the\n   * two; it must not re-spell either.\n   *\n   * ## Optional under protest — and what would make it required\n   *\n   * `BillingStateBackendService.getState` ALWAYS sets it, so on this engine's own wire it is never\n   * absent. It is `.optional()` for exactly one reason: `BillingContext.tsx` rebuilds the state\n   * object field-by-field from the HTTP response rather than passing it through, so every field\n   * added here is a compile break in a file this change may not edit. That hand-kept copy is the\n   * real defect — it makes any additive contract change breaking — and the field should be made\n   * REQUIRED in the same change that has the frontend read it.\n   *\n   * Absence therefore means \"the producer did not project acquirability\", never \"nothing is\n   * acquirable\" and never \"everything is\". A consumer that receives the set MUST use it in\n   * preference to re-deriving the rule; a consumer that does not is on the older, weaker footing\n   * this field exists to retire.\n   */\n  acquirableProductKeys: z.array(z.string()).optional(),\n  scopeType: z.enum(ResourcePrimaryScope),\n});\nexport type BillingStateResponse = z.infer<typeof BillingStateResponseSchema>;\n"]}
+{"version":3,"file":"billing-types.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/billing-types.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Billing Supporting Types (Shared)\n *\n * Types used by the billing API, frontend hooks, and provider interface.\n * These are NOT DB schemas — they are API response shapes, provider abstractions,\n * and aggregated views.\n *\n * @see billing-and-features-system.md §6.2c (Supporting Types)\n */\n\nimport { z } from 'zod';\nimport type { MoneyValue } from '@wildo-ai/zod-decorators';\nimport type { BillingTiming } from './billing-enums.shared.schemas';\nimport { BillingAccountSchema } from './billing-account.shared.schemas';\nimport { BillingSubscriptionBaseSchema } from './subscription.shared.schemas';\nimport { ProductSchema } from './product.shared.schemas';\nimport { PriceSchema } from './price.shared.schemas';\nimport { InvoiceRefSchema } from './invoice-ref.shared.schemas';\nimport { PromotionSchema } from './promotions.shared.schemas';\nimport { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\nimport { CoreResourceType } from '../resources/resources.shared.core.definitions';\nimport { markEmbeddedResourceSchema } from '../resources/embedded-resource-mark.shared.utils';\n\n// ── Provider Canonical Types ───────────────────────────────────────\n// StandardBilling_SubscriptionData and StandardBilling_InvoicePreview are\n// defined in @wildo-ai/external-connectors-models (standard billing interface)\n// and re-exported here for convenience.\nexport type { StandardBilling_SubscriptionData, StandardBilling_InvoicePreview } from '@wildo-ai/external-connectors-models';\n\n// ── Invoice Preview ────────────────────────────────────────────────\n\n/**\n * Presentation value used by the billing plan-change preview. BillingContext transports the\n * provider DTO; the plan-change flow converts its minor-unit amounts into this money shape.\n * Invoice amount due must not be presented as an immediate charge without the resolved settlement policy.\n *\n * All monetary amounts use MoneyValue for bigint precision and self-contained currency.\n */\nexport interface InvoicePreview {\n  /** Previewed invoice amount due; settlement timing must be stated separately. */\n  amount: MoneyValue;\n  /** Line items breakdown (what changed, prorated amounts) */\n  lineItems: Array<{\n    description: string;\n    amount: MoneyValue;\n    quantity: number;\n  }>;\n  /** Invoice period boundaries, not a guaranteed charge time. */\n  periodStart: Date;\n  periodEnd: Date;\n  /**\n   * When the change takes effect (#1868): `immediate`, or `at_period_end` — then the previewed invoice is the renewal invoice on the\n   * new plan, and confirming charges nothing now.\n   */\n  timing: BillingTiming;\n  /** When the change takes effect: now, or the end of the current period. */\n  effectiveAt: Date;\n}\n\n// ── Usage Summary ──────────────────────────────────────────────────\n\n/**\n * Usage summary: aggregated usage data for the frontend UsageDashboard.\n * Computed from UsageRecords, keyed by metered product key.\n *\n * Authored as a Zod schema (not a bare interface) so it can compose into\n * `BillingStateResponseSchema` — the runtime contract wired as the `GET_STATE`\n * custom operation's `customResponseDto`. `UsageSummary` is derived from it to\n * keep the type and the runtime shape from drifting.\n */\nexport const UsageSummarySchema = z.object({\n  /** Usage per metered product, keyed by product key */\n  byProduct: z.record(\n    z.string(),\n    z.object({\n      currentPeriodUsage: z.number().describe(\"Usage recorded in the current billing period.\"),\n      /** Previous period (for trend display) */\n      previousPeriodUsage: z.number().optional().describe(\"Usage recorded in the previous billing period.\"),\n      /** Usage limit (from product/subscription, if applicable) */\n      limit: z.number().optional().describe(\"The usage limit set by the product or subscription, when one applies.\"),\n      /** Last usage recorded at */\n      lastRecordedAt: z.date().optional().describe(\"When usage was last recorded.\"),\n    }),\n  ).describe(\"Usage per metered product, keyed by product key.\"),\n});\nexport type UsageSummary = z.infer<typeof UsageSummarySchema>;\n\n// ── Billing State Response ─────────────────────────────────────────\n\n/**\n * Per-pool credit balance projection embedded in the aggregated billing state.\n *\n * A lean view (NOT the full `CreditPool` resource) built by the billing-state\n * facade purely for the frontend balance display, keyed by pool key.\n */\nexport const CreditPoolBalanceSchema = z.object({\n  available: z.number().describe(\"Credits available to spend.\"),\n  totalPurchased: z.number().describe(\"Credits purchased in total.\"),\n  totalGranted: z.number().describe(\"Credits given without a purchase in total, such as referral rewards.\"),\n  totalConsumed: z.number().describe(\"Credits consumed in total.\"),\n});\nexport type CreditPoolBalance = z.infer<typeof CreditPoolBalanceSchema>;\n\n/**\n * Aggregated billing state returned by the lazy facade endpoint.\n * Single source of truth for frontend BillingProvider and backend controller.\n *\n * Authored as a Zod schema (not a bare interface) because the `GET_STATE`\n * custom operation wires it as its `customResponseDto`. That operation borrows\n * the COUNT verb for its route/verb via `resourceOperationLike` but returns\n * THIS aggregated shape — so without a `customResponseDto` the DTO builder would\n * assign it the COUNT default envelope (`{ count }`), and the service output\n * would fail `transformOutput`'s `internalDto.parse` → HTTP 500. The composed\n * schema gives the builder the real runtime contract to validate against and to\n * project the external response. `BillingStateResponse` is derived from it so the\n * type and the runtime contract cannot drift.\n */\n/** Independently loaded portions of the aggregate. Derived catalog projections use PRODUCTS. */\nexport enum BillingStateSlice {\n  BILLING_ACCOUNT = 'billingAccount',\n  SUBSCRIPTION = 'subscription',\n  PRODUCTS = 'products',\n  PRICES = 'prices',\n  INVOICES = 'invoices',\n  USAGE = 'usage',\n  CREDIT_POOLS = 'creditPools',\n  ACTIVE_PROMOTIONS = 'activePromotions',\n}\n\n/** Empty data is meaningful only when its query (and required dependencies) succeeded. */\nexport enum BillingSliceAvailability {\n  AVAILABLE = 'available',\n  UNAVAILABLE = 'unavailable',\n}\n\nexport const BillingStateAvailabilitySchema = z.record(z.enum(BillingStateSlice), z.enum(BillingSliceAvailability));\nexport type BillingStateAvailability = z.infer<typeof BillingStateAvailabilitySchema>;\n\nexport const BillingStateResponseSchema = z.object({\n  /** Query failures keep their empty transport placeholders but MUST NOT be presented as absence. */\n  availability: BillingStateAvailabilitySchema.describe(\"Whether each part of this response loaded. A part marked `unavailable` failed to load: its empty value means nothing, and must not be read as absence.\"),\n  billingAccount: BillingAccountSchema.nullable().describe(\"The billing account of the caller's scope, or `null` when the scope has none.\"),\n  // The subscription and the invoice refs are not marked as embedded records like the products below: which resource\n  // they are depends on the caller's scope. So the few fields no other source describes here are described in place\n  // (#1625), rather than on the base schemas, where they would replace each resource's own, richer description.\n  subscription: BillingSubscriptionBaseSchema.extend({\n    status: BillingSubscriptionBaseSchema.shape.status.describe(\"The subscription's lifecycle state as the billing provider reports it, such as `active`, `trialing` or `past_due`.\"),\n  }).nullable().describe(\"The scope's current subscription, or `null` when it has none.\"),\n  // Products, prices and promotions are each one resource's records, described by that resource (#1625).\n  products: z.array(markEmbeddedResourceSchema(ProductSchema, CoreResourceType.PRODUCTS)).describe(\"Every product visible in this scope, including ones no longer on sale, so a plan someone already holds can still be named. Which of them can be acquired now is `acquirableProductKeys`.\"),\n  prices: z.array(markEmbeddedResourceSchema(PriceSchema, CoreResourceType.PRICES)).describe(\"The prices visible in this scope.\"),\n  invoices: z.array(InvoiceRefSchema.extend({\n    status: InvoiceRefSchema.shape.status.describe(\"The invoice's payment state as the billing provider reports it, such as `open`, `paid` or `void`.\"),\n    total: InvoiceRefSchema.shape.total.describe('The invoice total: an amount in minor units, with its currency.'),\n  })).describe(\"References to the scope's invoices.\"),\n  usage: UsageSummarySchema.describe(\"Metered usage in this scope.\"),\n  creditPools: z.record(z.string(), CreditPoolBalanceSchema).describe(\"Credit balances, keyed by credit pool.\"),\n  /**\n   * Scope/product-visible promotions for the current billing surface.\n   *\n   * This list intentionally excludes promotions that are inactive, exhausted,\n   * unsynced with the billing provider, or targeted only at products outside the\n   * current scope. It is not a promise that every entry is redeemable for any\n   * arbitrary checkout item the user might pick next.\n   */\n  activePromotions: z.array(markEmbeddedResourceSchema(PromotionSchema, CoreResourceType.PROMOTIONS)).describe(\"Promotions visible in this scope: active, not exhausted, synced with the billing provider, and targeting a product in scope. Not a promise that each one applies to a particular checkout.\"),\n  /**\n   * The subset of `products` (by `key`) a caller may ACQUIRE right now — buy, or move a\n   * subscription onto.\n   *\n   * ## Why a sibling key set rather than a filter on `products`\n   *\n   * One call serves two surfaces that want OPPOSITE things from it. An acquisition surface (a\n   * pricing table) must not offer a plan the purchase gate will refuse; a holding surface (the\n   * \"your current plan\" panel, the subscription-item → product resolution in the frontend billing\n   * context) must still be able to NAME a plan the catalogue has withdrawn, because a customer\n   * already on a retired plan is exactly who needs to see what they hold. Filtering `products` by\n   * `isActive` would serve the first and break the second — the same trade the `REMOVE_ADDON` call\n   * site settles by reading with `REFERENCE` intent rather than `ACQUIRE`.\n   *\n   * So the response DISTINGUISHES instead of filtering: `products` stays the full scope-visible\n   * catalog, and this set states which of them acquisition may offer.\n   *\n   * ## Why the server answers it at all\n   *\n   * `Product.isActive` is the declared off-boarding path, and the backend gate that makes\n   * retirement TRUE (`readProductByKey` with `ACQUIRE` intent) applies ONE predicate to it. A\n   * listing surface holds rows, not keys, so it cannot use that reader — and every listing left to\n   * itself re-derives the rule from the raw column. That had already happened twice by 2026-09-09,\n   * in a frontend component and in the reader, agreeing only by luck. This set is computed by the\n   * gate's own predicate, so a surface that reads it cannot drift from what checkout will accept.\n   *\n   * NOT a visibility answer: `isPublic` is a per-surface decision the server cannot take for every\n   * caller (a back-office catalog shows non-public rows). A customer pricing table composes the\n   * two; it must not re-spell either.\n   *\n   * The aggregate producer sets this field and BillingContext preserves it. Consumers\n   * must check PRODUCTS availability before interpreting this projection: an empty set\n   * from an unavailable catalog does not prove that nothing can be acquired.\n   *\n   * Absence therefore means \"the producer did not project acquirability\", never \"nothing is\n   * acquirable\" and never \"everything is\". A consumer that receives the set MUST use it in\n   * preference to re-deriving the rule; a consumer that does not is on the older, weaker footing\n   * this field exists to retire.\n   */\n  acquirableProductKeys: z.array(z.string()).optional().describe(\"The keys of the products in `products` that may be bought, or moved onto, right now. Absent means this was not computed, not that nothing can be acquired. Check `availability` for products first: from a catalog that failed to load, an empty list proves nothing.\"),\n  scopeType: z.enum(ResourcePrimaryScope).describe(\"The scope this billing state belongs to.\"),\n});\nexport type BillingStateResponse = z.infer<typeof BillingStateResponseSchema>;\n"]}

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

@@ -7,6 +7,7 @@
  */
 import { z } from 'zod';
 import { CoreResourceOperation } from '../resources/resources.shared.core.definitions';
+import { CreditPoolTopUpSource } from './billing-enums.shared.schemas';
 export declare enum CreditPool_Operations {
     /** Consume credits from the pool. System-only (INTERNAL_CALL) — called by custom service code that
      *  meters a paid capability, never directly by a client. */
@@ -20,6 +21,7 @@ export declare const CreditPool_ConsumeRequestDto: z.ZodObject<{
 }, z.core.$strip>;
 export declare const CreditPool_TopUpRequestDto: z.ZodObject<{
     credits: z.ZodNumber;
+    source: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof CreditPoolTopUpSource>>>;
 }, z.core.$strip>;
 export declare const creditPoolsPolymorphicFactories: Record<string, import("..").ResourceConfiguration_InitializationFactory<typeof CreditPool_Operations, CoreResourceOperation.READ | CoreResourceOperation.UPDATE | CoreResourceOperation.UPDATE_MANY | CoreResourceOperation.CREATE | CoreResourceOperation.LIST, any>>;
 //# sourceMappingURL=credit-pool.shared.resources-config.schemas.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"credit-pool.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/credit-pool.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAoB,MAAM,gDAAgD,CAAC;AAczG,oBAAY,qBAAqB;IAC/B;gEAC4D;IAC5D,OAAO,YAAY;IACnB;8GAC0G;IAC1G,MAAM,WAAW;CAClB;AAID,eAAO,MAAM,4BAA4B;;iBAEvC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;iBAErC,CAAC;AAEH,eAAO,MAAM,+BAA+B,wQA0J3C,CAAC"}
+{"version":3,"file":"credit-pool.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/credit-pool.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAoB,MAAM,gDAAgD,CAAC;AAQzG,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAOvE,oBAAY,qBAAqB;IAC/B;gEAC4D;IAC5D,OAAO,YAAY;IACnB;8GAC0G;IAC1G,MAAM,WAAW;CAClB;AAID,eAAO,MAAM,4BAA4B;;iBAEvC,CAAC;AAEH,eAAO,MAAM,0BAA0B;;;iBAOrC,CAAC;AAEH,eAAO,MAAM,+BAA+B,wQA+J3C,CAAC"}

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

@@ -11,6 +11,7 @@ import { ResourceOperationRiskLevel, ResourceOperationVariantType, } from '../re
 import { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory.js';
 import { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas.js';
 import { creditPoolsPolymorphicDeclaration } from './credit-pool.shared.schemas.js';
+import { CreditPoolTopUpSource } from './billing-enums.shared.schemas.js';
 import { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas.js';
 import { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas.js';
 import { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas.js';
@@ -30,12 +31,22 @@ export const CreditPool_ConsumeRequestDto = z.object({
 });
 export const CreditPool_TopUpRequestDto = z.object({
     credits: z.number().min(1),
+    /**
+     * Whether the credits were bought or given (#1802). A purchase counts toward `totalPurchased`, a grant
+     * toward `totalGranted`; both add to `available`. Defaults to `purchase`, the credit-pack checkout.
+     */
+    source: z.enum(CreditPoolTopUpSource).default(CreditPoolTopUpSource.PURCHASE).systemEnum('CreditPoolTopUpSource'),
 });
 export const creditPoolsPolymorphicFactories = createPolymorphicResourceConfigurations(creditPoolsPolymorphicDeclaration, {
     isSystemResource: true,
     customOperation: CreditPool_Operations,
     /** Subject-export disclosure. The subject's own credit balances. Secrets and backend-only values are withheld by the export's security floor regardless of this grant. On a polymorphic resource this grant applies to EVERY generated variant, which is the documented intent of the shared config. */
-    systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },
+    systemAccessPolicy: {
+        exportSubject: ResourceSystemAccessMode.ALLOWED,
+        // A referral credit (#1802) is granted to an account that may never have bought a pack, so its pool is created
+        // by the referral program — a trusted in-process write with no request, whose scope FK comes from the account.
+        create: ResourceSystemAccessMode.ALLOWED,
+    },
     portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.DERIVED },
     /**
      * Subject erasure RETAINS this row and scrubs nothing, because there is nothing here to scrub.
@@ -98,8 +109,8 @@ export const creditPoolsPolymorphicFactories = createPolymorphicResourceConfigur
                     variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
                     polymorphicRole: {
-                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],
-                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],
                     },
                     riskLevel: ResourceOperationRiskLevel.LOW,
                 }],
@@ -109,8 +120,8 @@ export const creditPoolsPolymorphicFactories = createPolymorphicResourceConfigur
                     variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
                     polymorphicRole: {
-                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],
-                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],
                     },
                     riskLevel: ResourceOperationRiskLevel.LOW,
                 }],
@@ -169,8 +180,8 @@ export const creditPoolsPolymorphicFactories = createPolymorphicResourceConfigur
                     variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
                     polymorphicRole: {
-                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],
-                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],
                     },
                     riskLevel: ResourceOperationRiskLevel.MEDIUM,
                     resourceOperationLike: CoreResourceOperation.UPDATE,

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

@@ -1 +1 @@
-{"version":3,"file":"credit-pool.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/credit-pool.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Credit Pool Resource Configuration — Polymorphic\n *\n * Produces 3 factory functions (one per scope variant) via the polymorphic factory.\n * Spread into the registry factory map:\n *   ...creditPoolsPolymorphicFactories\n */\n\nimport { z } from 'zod';\nimport { CoreResourceOperation, CoreResourceType } from '../resources/resources.shared.core.definitions';\nimport {\n  ResourceOperationRiskLevel,\n  ResourceOperationVariantType,\n} from '../resources/resources.shared.schemas';\nimport { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory';\nimport { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { creditPoolsPolymorphicDeclaration } from './credit-pool.shared.schemas';\nimport { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';\nimport { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas';\n\n// ── Custom Operations ────────────────────────────────────────────────\n\nexport enum CreditPool_Operations {\n  /** Consume credits from the pool. System-only (INTERNAL_CALL) — called by custom service code that\n   *  meters a paid capability, never directly by a client. */\n  CONSUME = 'consume',\n  /** Top up credits. System-only (INTERNAL_CALL) — invoked by the billing webhook router after a\n   *  verified CREDIT_PACK purchase, never by a client. The client \"buy credits\" action is OPEN_CHECKOUT. */\n  TOP_UP = 'top_up',\n}\n\n// ── Request DTOs ─────────────────────────────────────────────────────\n\nexport const CreditPool_ConsumeRequestDto = z.object({\n  credits: z.number().min(1),\n});\n\nexport const CreditPool_TopUpRequestDto = z.object({\n  credits: z.number().min(1),\n});\n\nexport const creditPoolsPolymorphicFactories = createPolymorphicResourceConfigurations(\n  creditPoolsPolymorphicDeclaration,\n  {\n    isSystemResource: true,\n    customOperation: CreditPool_Operations,\n    /** Subject-export disclosure. The subject's own credit balances. Secrets and backend-only values are withheld by the export's security floor regardless of this grant. On a polymorphic resource this grant applies to EVERY generated variant, which is the documented intent of the shared config. */\n    systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },\n    portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.DERIVED },\n\n    /**\n     * Subject erasure RETAINS this row and scrubs nothing, because there is nothing here to scrub.\n *\n * `RETAIN_ONLY` is a positive ASSERTION that this resource holds no personal data of its own. The row is\n * credit balances — available, purchased and consumed amounts — amounts and contract terms about the ACCOUNT. They\n * describe nobody once the linked USER row is scrubbed, and they must survive erasure for the tax/audit\n * obligation this family exists to serve, so they can be neither scrubbed nor honestly declared as\n * personal data the row holds. The person is the scope foreign key, which the never-scrub floor protects.\n *\n * The assertion is CHECKED in both directions: the factory refuses `RETAIN_ONLY` if any field declares an\n * impersonalize treatment, and (since 2026-08-31) if any non-floor field declares `.dataCategories()`.\n     */\n    retentionPolicy: {\n      mode: ErasureRetentionMode.RETAIN_ONLY,\n    },\n\n    /**\n     * Erasing one of these rows revokes NO session. The row is not a person — its owner FK names the ACTOR the\n *  record belongs to — and the enum prescribes `NO_PRINCIPAL` for exactly that shape. The subject's own\n *  session ends through the `USERS` row, which is `SELF_PRINCIPAL`.\n     */\n    dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },\n\n    coreOperations: [\n      CoreResourceOperation.READ,\n      CoreResourceOperation.LIST,\n      CoreResourceOperation.CREATE,\n      CoreResourceOperation.UPDATE,\n      // Route-less; `retentionPolicy` requires READ + LIST + UPDATE_MANY.\n      CoreResourceOperation.UPDATE_MANY,\n    ],\n    operationsConfiguration: {\n      /*\n       * Route-less retention plumbing — INTERNAL_CALL registers no route, so no API surface is added, and it\n       * must not be REPOSITORY_ONLY: the retention primitives resolve through `getServiceOperationPathDefault`,\n       * which matches only INTERNAL_CALL / API_CALL. LIST is LOW (a read-shaped op may not claim the\n       * HIGH/CRITICAL band, which carries an audit-emission obligation); UPDATE_MANY is CRITICAL — it is the\n       * verb the impersonalize writer uses to stamp the retention markers.\n       */\n      [CoreResourceOperation.UPDATE_MANY]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.CRITICAL,\n        }],\n      },\n\n      [CoreResourceOperation.READ]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.LIST]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.CREATE]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.UPDATE]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      // assurance-control: WILDO.BILLING.CREDIT_GRANT_INTEGRITY — a credit-balance mutation is\n      // system-only; it is never client-initiated.\n      //\n      // CONSUME is INTERNAL_CALL (no HTTP route), matching TOP_UP and the CRUD siblings. It is invoked\n      // by service code that meters a paid feature (its enum doc: \"called by custom service code\"), not\n      // by a client — the balance decrement happens as a side effect of using a metered capability, not\n      // as a direct client action. Leaving it API_CALL let a client spend its own credits arbitrarily\n      // (self-harm, not a grant) and, more importantly, made a system-automated op part of the client\n      // attack surface. The `polymorphicRole` is retained for internal-authorization parity and no\n      // longer confers client reachability.\n      [CreditPool_Operations.CONSUME]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_MEMBER],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.MEDIUM,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: CreditPool_ConsumeRequestDto,\n        }],\n      },\n      // assurance-control: WILDO.BILLING.CREDIT_GRANT_INTEGRITY — a credit GRANT (balance increase)\n      // is system/payment-gated only; it is never client-initiated.\n      //\n      // TOP_UP is INTERNAL_CALL (no HTTP route), matching its CREATE/UPDATE siblings above. It\n      // increments the spendable balance, so it must be reachable ONLY from server code that has\n      // already verified payment: the billing webhook router computes `credits` from the PAID\n      // product/quantity and invokes it via `executeCustomOperation` (which resolves the INTERNAL_CALL\n      // default through `getServiceOperationPathDefault`). It was previously API_CALL gated to\n      // ORG_OWNER, which let a tenant owner `PUT …/credit-pools/{id}/top-up {credits: N}` and\n      // self-grant unlimited paid credits — the client \"buy credits\" action is OPEN_CHECKOUT, not a\n      // direct balance write, so this route had no legitimate client caller. (The spec previously\n      // hinted at a manual admin grant here; a support-initiated grant, if ever needed, belongs on a\n      // separate platform-super-admin op with a mandatory audit event, NOT on a tenant-owner route.)\n      // The `polymorphicRole` below is retained for internal-authorization parity with the CRUD ops\n      // and no longer confers any client reachability.\n      [CreditPool_Operations.TOP_UP]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.MEDIUM,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: CreditPool_TopUpRequestDto,\n        }],\n      },\n    },\n  },\n);\n"]}
+{"version":3,"file":"credit-pool.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/credit-pool.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Credit Pool Resource Configuration — Polymorphic\n *\n * Produces 3 factory functions (one per scope variant) via the polymorphic factory.\n * Spread into the registry factory map:\n *   ...creditPoolsPolymorphicFactories\n */\n\nimport { z } from 'zod';\nimport { CoreResourceOperation, CoreResourceType } from '../resources/resources.shared.core.definitions';\nimport {\n  ResourceOperationRiskLevel,\n  ResourceOperationVariantType,\n} from '../resources/resources.shared.schemas';\nimport { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory';\nimport { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { creditPoolsPolymorphicDeclaration } from './credit-pool.shared.schemas';\nimport { CreditPoolTopUpSource } from './billing-enums.shared.schemas';\nimport { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';\nimport { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas';\n\n// ── Custom Operations ────────────────────────────────────────────────\n\nexport enum CreditPool_Operations {\n  /** Consume credits from the pool. System-only (INTERNAL_CALL) — called by custom service code that\n   *  meters a paid capability, never directly by a client. */\n  CONSUME = 'consume',\n  /** Top up credits. System-only (INTERNAL_CALL) — invoked by the billing webhook router after a\n   *  verified CREDIT_PACK purchase, never by a client. The client \"buy credits\" action is OPEN_CHECKOUT. */\n  TOP_UP = 'top_up',\n}\n\n// ── Request DTOs ─────────────────────────────────────────────────────\n\nexport const CreditPool_ConsumeRequestDto = z.object({\n  credits: z.number().min(1),\n});\n\nexport const CreditPool_TopUpRequestDto = z.object({\n  credits: z.number().min(1),\n  /**\n   * Whether the credits were bought or given (#1802). A purchase counts toward `totalPurchased`, a grant\n   * toward `totalGranted`; both add to `available`. Defaults to `purchase`, the credit-pack checkout.\n   */\n  source: z.enum(CreditPoolTopUpSource).default(CreditPoolTopUpSource.PURCHASE).systemEnum('CreditPoolTopUpSource'),\n});\n\nexport const creditPoolsPolymorphicFactories = createPolymorphicResourceConfigurations(\n  creditPoolsPolymorphicDeclaration,\n  {\n    isSystemResource: true,\n    customOperation: CreditPool_Operations,\n    /** Subject-export disclosure. The subject's own credit balances. Secrets and backend-only values are withheld by the export's security floor regardless of this grant. On a polymorphic resource this grant applies to EVERY generated variant, which is the documented intent of the shared config. */\n    systemAccessPolicy: {\n      exportSubject: ResourceSystemAccessMode.ALLOWED,\n      // A referral credit (#1802) is granted to an account that may never have bought a pack, so its pool is created\n      // by the referral program — a trusted in-process write with no request, whose scope FK comes from the account.\n      create: ResourceSystemAccessMode.ALLOWED,\n    },\n    portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.DERIVED },\n\n    /**\n     * Subject erasure RETAINS this row and scrubs nothing, because there is nothing here to scrub.\n *\n * `RETAIN_ONLY` is a positive ASSERTION that this resource holds no personal data of its own. The row is\n * credit balances — available, purchased and consumed amounts — amounts and contract terms about the ACCOUNT. They\n * describe nobody once the linked USER row is scrubbed, and they must survive erasure for the tax/audit\n * obligation this family exists to serve, so they can be neither scrubbed nor honestly declared as\n * personal data the row holds. The person is the scope foreign key, which the never-scrub floor protects.\n *\n * The assertion is CHECKED in both directions: the factory refuses `RETAIN_ONLY` if any field declares an\n * impersonalize treatment, and (since 2026-08-31) if any non-floor field declares `.dataCategories()`.\n     */\n    retentionPolicy: {\n      mode: ErasureRetentionMode.RETAIN_ONLY,\n    },\n\n    /**\n     * Erasing one of these rows revokes NO session. The row is not a person — its owner FK names the ACTOR the\n *  record belongs to — and the enum prescribes `NO_PRINCIPAL` for exactly that shape. The subject's own\n *  session ends through the `USERS` row, which is `SELF_PRINCIPAL`.\n     */\n    dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },\n\n    coreOperations: [\n      CoreResourceOperation.READ,\n      CoreResourceOperation.LIST,\n      CoreResourceOperation.CREATE,\n      CoreResourceOperation.UPDATE,\n      // Route-less; `retentionPolicy` requires READ + LIST + UPDATE_MANY.\n      CoreResourceOperation.UPDATE_MANY,\n    ],\n    operationsConfiguration: {\n      /*\n       * Route-less retention plumbing — INTERNAL_CALL registers no route, so no API surface is added, and it\n       * must not be REPOSITORY_ONLY: the retention primitives resolve through `getServiceOperationPathDefault`,\n       * which matches only INTERNAL_CALL / API_CALL. LIST is LOW (a read-shaped op may not claim the\n       * HIGH/CRITICAL band, which carries an audit-emission obligation); UPDATE_MANY is CRITICAL — it is the\n       * verb the impersonalize writer uses to stamp the retention markers.\n       */\n      [CoreResourceOperation.UPDATE_MANY]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.CRITICAL,\n        }],\n      },\n\n      [CoreResourceOperation.READ]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.LIST]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.CREATE]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.UPDATE]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      // assurance-control: WILDO.BILLING.CREDIT_GRANT_INTEGRITY — a credit-balance mutation is\n      // system-only; it is never client-initiated.\n      //\n      // CONSUME is INTERNAL_CALL (no HTTP route), matching TOP_UP and the CRUD siblings. It is invoked\n      // by service code that meters a paid feature (its enum doc: \"called by custom service code\"), not\n      // by a client — the balance decrement happens as a side effect of using a metered capability, not\n      // as a direct client action. Leaving it API_CALL let a client spend its own credits arbitrarily\n      // (self-harm, not a grant) and, more importantly, made a system-automated op part of the client\n      // attack surface. The `polymorphicRole` is retained for internal-authorization parity and no\n      // longer confers client reachability.\n      [CreditPool_Operations.CONSUME]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_MEMBER],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.MEDIUM,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: CreditPool_ConsumeRequestDto,\n        }],\n      },\n      // assurance-control: WILDO.BILLING.CREDIT_GRANT_INTEGRITY — a credit GRANT (balance increase)\n      // is system/payment-gated only; it is never client-initiated.\n      //\n      // TOP_UP is INTERNAL_CALL (no HTTP route), matching its CREATE/UPDATE siblings above. It\n      // increments the spendable balance, so it must be reachable ONLY from server code that has\n      // already verified payment: the billing webhook router computes `credits` from the PAID\n      // product/quantity and invokes it via `executeCustomOperation` (which resolves the INTERNAL_CALL\n      // default through `getServiceOperationPathDefault`). It was previously API_CALL gated to\n      // ORG_OWNER, which let a tenant owner `PUT …/credit-pools/{id}/top-up {credits: N}` and\n      // self-grant unlimited paid credits — the client \"buy credits\" action is OPEN_CHECKOUT, not a\n      // direct balance write, so this route had no legitimate client caller. (The spec previously\n      // hinted at a manual admin grant here; a support-initiated grant, if ever needed, belongs on a\n      // separate platform-super-admin op with a mandatory audit event, NOT on a tenant-owner route.)\n      // The `polymorphicRole` below is retained for internal-authorization parity with the CRUD ops\n      // and no longer confers any client reachability.\n      [CreditPool_Operations.TOP_UP]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],\n          },\n          riskLevel: ResourceOperationRiskLevel.MEDIUM,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: CreditPool_TopUpRequestDto,\n        }],\n      },\n    },\n  },\n);\n"]}

package/dist/esm/billing/credit-pool.shared.schemas.d.ts

@@ -30,6 +30,7 @@ export declare const CreditPoolSchema: z.ZodObject<{
     poolKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;
     available: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodNumber>>>;
     totalPurchased: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodNumber>>>;
+    totalGranted: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodNumber>>>;
     totalConsumed: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodNumber>>>;
     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>>>;
@@ -41,6 +42,7 @@ export declare const creditPoolsPolymorphicDeclaration: import("..").Polymorphic
     poolKey: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;
     available: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodNumber>>>;
     totalPurchased: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodNumber>>>;
+    totalGranted: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodNumber>>>;
     totalConsumed: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodNumber>>>;
     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/credit-pool.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credit-pool.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/credit-pool.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,gBAAgB;;;;;;;;;iBAwB3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI1D,eAAO,MAAM,iCAAiC;;;;;;;;;kBAU5C,CAAC"}
+{"version":3,"file":"credit-pool.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/credit-pool.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,gBAAgB;;;;;;;;;;iBA8B3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI1D,eAAO,MAAM,iCAAiC;;;;;;;;;;kBAU5C,CAAC"}

package/dist/esm/billing/credit-pool.shared.schemas.js

@@ -28,7 +28,7 @@ import { declarePolymorphicSchemas, optOutPolymorphicAutoBusinessKey } from '../
 import { BILLING_SCOPE_VARIANTS, BILLING_SCOPE_FK_VARIANTS } from './billing-account.shared.schemas.js';
 export const CreditPoolSchema = z.object({
     _id: z.string().min(1).isPrimaryKey(),
-    billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed().isSummaryField(),
+    billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed().isSummaryField().describe("The id of the billing account that holds these credits."),
     /** Pool identifier (matches ProductDefinition.purchaseConfig.creditPoolKey, e.g., 'ai_tokens') */
     poolKey: z.string().min(1).isDBIndexed().isSummaryField().isNotEditable()
         .isUnique({ compoundWith: 'billingAccountId' }),
@@ -43,6 +43,12 @@ export const CreditPoolSchema = z.object({
     available: z.number().min(0).default(0).isSummaryField().isNotEditable(),
     /** Total credits ever purchased (for audit/display) */
     totalPurchased: z.number().min(0).default(0).isSummaryField().isNotEditable(),
+    /**
+     * Total credits ever GIVEN rather than bought — a referral reward, for instance (#1802). Kept apart from
+     * `totalPurchased` so the pool still answers what was sold: `available` is `totalPurchased + totalGranted
+     * - totalConsumed`.
+     */
+    totalGranted: z.number().min(0).default(0).isSummaryField().isNotEditable().describe('Credits given to the account without a purchase, such as a referral reward. Counted apart from purchased credits.'),
     /** Total credits consumed (for audit/display) */
     totalConsumed: z.number().min(0).default(0).isSummaryField().isNotEditable(),
     createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),

package/dist/esm/billing/credit-pool.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"credit-pool.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/credit-pool.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,yBAAyB,EAAE,gCAAgC,EAAE,MAAM,kDAAkD,CAAC;AAC/H,OAAO,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAErG,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE;IACrC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE;IAEnI,kGAAkG;IAClG,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE;SACtE,QAAQ,CAAC,EAAE,YAAY,EAAE,kBAAkB,EAAE,CAAC;IAEjD,gCAAgC;IAChC,iGAAiG;IACjG,gDAAgD;IAChD,mGAAmG;IACnG,oGAAoG;IACpG,qGAAqG;IACrG,sGAAsG;IACtG,0BAA0B;IAC1B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE;IACxE,uDAAuD;IACvD,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE;IAC7E,iDAAiD;IACjD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE;IAE5E,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IACrF,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;CACtF,CAAC,CAAC;AAGH,sEAAsE;AAEtE,MAAM,CAAC,MAAM,iCAAiC,GAAG,yBAAyB,CAAC;IACzE,gBAAgB,EAAE,aAAa;IAC/B,mBAAmB,EAAE,cAAc;IACnC,WAAW,EAAE,cAAc;IAC3B,UAAU,EAAE,gBAAgB;IAC5B,4EAA4E;IAC5E,sEAAsE;IACtE,uEAAuE;IACvE,yEAAyE;IACzE,QAAQ,EAAE,sBAAsB,CAAC,GAAG,CAAC,gCAAgC,CAAC;CACvE,CAAC,CAAC","sourcesContent":["/**\n * Credit Pool Schema (Shared) — Polymorphic\n *\n * Tracks credit balances for CREDIT_PACK products.\n * Created/topped-up when a CREDIT_PACK purchase completes.\n * Decremented when credits are consumed (via custom service code).\n *\n * One pool per creditPoolKey per billing account.\n * Database index: `{ billingAccountId: 1, poolKey: 1 }` compound unique.\n *\n * POLYMORPHIC EXPANSION: Like subscriptions, credit pools are scope-expanded.\n * The `billingAccountId` FK is renamed per variant via polymorphic FK transformation:\n *   - organizationCreditPools  (with organizationId + organizationBillingAccountId)\n *   - userCreditPools          (with userId + userBillingAccountId)\n *\n *\n * Credit flow:\n * 1. User purchases CREDIT_PACK → Checkout completes → webhook\n * 2. Webhook router: creates/updates CreditPool (available += creditsPerUnit * quantity)\n * 3. CreditPool CONSUME custom op: validates balance and decrements available\n * 4. CreditPool TOP_UP custom op: increments available after purchase\n * 5. Frontend shows balance via BillingStateResponse.creditPools\n *\n * @see billing-and-features-system.md §9 (Credit Pool)\n */\n\nimport { z } from 'zod';\nimport { declarePolymorphicSchemas, optOutPolymorphicAutoBusinessKey } from '../resources/utils/resource-polymorphism.schemas';\nimport { BILLING_SCOPE_VARIANTS, BILLING_SCOPE_FK_VARIANTS } from './billing-account.shared.schemas';\n\nexport const CreditPoolSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey(),\n  billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed().isSummaryField(),\n\n  /** Pool identifier (matches ProductDefinition.purchaseConfig.creditPoolKey, e.g., 'ai_tokens') */\n  poolKey: z.string().min(1).isDBIndexed().isSummaryField().isNotEditable()\n    .isUnique({ compoundWith: 'billingAccountId' }),\n\n  /** Current available balance */\n  // FINANCIAL — see the note on `billing-account.shared.schemas.ts`. A balance is a financial fact\n  // about the account holder, not a usage metric.\n  // No `.dataCategories()`: this is an amount/term about the ACCOUNT, not a description of a person.\n  // The person is the scope foreign key, which the never-scrub floor preserves in every mode, and the\n  // value must survive erasure for the tax/audit obligation this family exists to serve — so it can be\n  // neither scrubbed nor honestly declared as personal data the row holds. See `retentionPolicy` on the\n  // resource config (#138).\n  available: z.number().min(0).default(0).isSummaryField().isNotEditable(),\n  /** Total credits ever purchased (for audit/display) */\n  totalPurchased: z.number().min(0).default(0).isSummaryField().isNotEditable(),\n  /** Total credits consumed (for audit/display) */\n  totalConsumed: z.number().min(0).default(0).isSummaryField().isNotEditable(),\n\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type CreditPool = z.infer<typeof CreditPoolSchema>;\n\n// ── Polymorphic Declaration ────────────────────────────────────────\n\nexport const creditPoolsPolymorphicDeclaration = declarePolymorphicSchemas({\n  baseResourceType: 'creditPools',\n  baseFieldIdentifier: 'creditPoolId',\n  baseEnumKey: 'CREDIT_POOLS',\n  baseSchema: CreditPoolSchema,\n  // Many pools per billing-account / scope (composite key: billingAccountId +\n  // poolKey) — opt out of the polymorphism engine's singleton-per-scope\n  // business-key auto-default. If pools ever become seedable, declare an\n  // explicit `businessKeyFields: ['billingAccountId', 'poolKey']` instead.\n  variants: BILLING_SCOPE_VARIANTS.map(optOutPolymorphicAutoBusinessKey),\n});\n"]}
+{"version":3,"file":"credit-pool.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/credit-pool.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,yBAAyB,EAAE,gCAAgC,EAAE,MAAM,kDAAkD,CAAC;AAC/H,OAAO,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AAErG,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE;IACrC,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,QAAQ,CAAC,yDAAyD,CAAC;IAEvM,kGAAkG;IAClG,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE;SACtE,QAAQ,CAAC,EAAE,YAAY,EAAE,kBAAkB,EAAE,CAAC;IAEjD,gCAAgC;IAChC,iGAAiG;IACjG,gDAAgD;IAChD,mGAAmG;IACnG,oGAAoG;IACpG,qGAAqG;IACrG,sGAAsG;IACtG,0BAA0B;IAC1B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE;IACxE,uDAAuD;IACvD,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE;IAC7E;;;;OAIG;IACH,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE,CAAC,QAAQ,CAAC,mHAAmH,CAAC;IACzM,iDAAiD;IACjD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,CAAC,aAAa,EAAE;IAE5E,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IACrF,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;CACtF,CAAC,CAAC;AAGH,sEAAsE;AAEtE,MAAM,CAAC,MAAM,iCAAiC,GAAG,yBAAyB,CAAC;IACzE,gBAAgB,EAAE,aAAa;IAC/B,mBAAmB,EAAE,cAAc;IACnC,WAAW,EAAE,cAAc;IAC3B,UAAU,EAAE,gBAAgB;IAC5B,4EAA4E;IAC5E,sEAAsE;IACtE,uEAAuE;IACvE,yEAAyE;IACzE,QAAQ,EAAE,sBAAsB,CAAC,GAAG,CAAC,gCAAgC,CAAC;CACvE,CAAC,CAAC","sourcesContent":["/**\n * Credit Pool Schema (Shared) — Polymorphic\n *\n * Tracks credit balances for CREDIT_PACK products.\n * Created/topped-up when a CREDIT_PACK purchase completes.\n * Decremented when credits are consumed (via custom service code).\n *\n * One pool per creditPoolKey per billing account.\n * Database index: `{ billingAccountId: 1, poolKey: 1 }` compound unique.\n *\n * POLYMORPHIC EXPANSION: Like subscriptions, credit pools are scope-expanded.\n * The `billingAccountId` FK is renamed per variant via polymorphic FK transformation:\n *   - organizationCreditPools  (with organizationId + organizationBillingAccountId)\n *   - userCreditPools          (with userId + userBillingAccountId)\n *\n *\n * Credit flow:\n * 1. User purchases CREDIT_PACK → Checkout completes → webhook\n * 2. Webhook router: creates/updates CreditPool (available += creditsPerUnit * quantity)\n * 3. CreditPool CONSUME custom op: validates balance and decrements available\n * 4. CreditPool TOP_UP custom op: increments available after purchase\n * 5. Frontend shows balance via BillingStateResponse.creditPools\n *\n * @see billing-and-features-system.md §9 (Credit Pool)\n */\n\nimport { z } from 'zod';\nimport { declarePolymorphicSchemas, optOutPolymorphicAutoBusinessKey } from '../resources/utils/resource-polymorphism.schemas';\nimport { BILLING_SCOPE_VARIANTS, BILLING_SCOPE_FK_VARIANTS } from './billing-account.shared.schemas';\n\nexport const CreditPoolSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey(),\n  billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed().isSummaryField().describe(\"The id of the billing account that holds these credits.\"),\n\n  /** Pool identifier (matches ProductDefinition.purchaseConfig.creditPoolKey, e.g., 'ai_tokens') */\n  poolKey: z.string().min(1).isDBIndexed().isSummaryField().isNotEditable()\n    .isUnique({ compoundWith: 'billingAccountId' }),\n\n  /** Current available balance */\n  // FINANCIAL — see the note on `billing-account.shared.schemas.ts`. A balance is a financial fact\n  // about the account holder, not a usage metric.\n  // No `.dataCategories()`: this is an amount/term about the ACCOUNT, not a description of a person.\n  // The person is the scope foreign key, which the never-scrub floor preserves in every mode, and the\n  // value must survive erasure for the tax/audit obligation this family exists to serve — so it can be\n  // neither scrubbed nor honestly declared as personal data the row holds. See `retentionPolicy` on the\n  // resource config (#138).\n  available: z.number().min(0).default(0).isSummaryField().isNotEditable(),\n  /** Total credits ever purchased (for audit/display) */\n  totalPurchased: z.number().min(0).default(0).isSummaryField().isNotEditable(),\n  /**\n   * Total credits ever GIVEN rather than bought — a referral reward, for instance (#1802). Kept apart from\n   * `totalPurchased` so the pool still answers what was sold: `available` is `totalPurchased + totalGranted\n   * - totalConsumed`.\n   */\n  totalGranted: z.number().min(0).default(0).isSummaryField().isNotEditable().describe('Credits given to the account without a purchase, such as a referral reward. Counted apart from purchased credits.'),\n  /** Total credits consumed (for audit/display) */\n  totalConsumed: z.number().min(0).default(0).isSummaryField().isNotEditable(),\n\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type CreditPool = z.infer<typeof CreditPoolSchema>;\n\n// ── Polymorphic Declaration ────────────────────────────────────────\n\nexport const creditPoolsPolymorphicDeclaration = declarePolymorphicSchemas({\n  baseResourceType: 'creditPools',\n  baseFieldIdentifier: 'creditPoolId',\n  baseEnumKey: 'CREDIT_POOLS',\n  baseSchema: CreditPoolSchema,\n  // Many pools per billing-account / scope (composite key: billingAccountId +\n  // poolKey) — opt out of the polymorphism engine's singleton-per-scope\n  // business-key auto-default. If pools ever become seedable, declare an\n  // explicit `businessKeyFields: ['billingAccountId', 'poolKey']` instead.\n  variants: BILLING_SCOPE_VARIANTS.map(optOutPolymorphicAutoBusinessKey),\n});\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"invoice-ref.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/invoice-ref.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAoB,MAAM,gDAAgD,CAAC;AAYzG,eAAO,MAAM,+BAA+B,oRAwH3C,CAAC"}
+{"version":3,"file":"invoice-ref.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/invoice-ref.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAoB,MAAM,gDAAgD,CAAC;AAYzG,eAAO,MAAM,+BAA+B,oRAwH3C,CAAC"}

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

@@ -80,8 +80,8 @@ export const invoiceRefsPolymorphicFactories = createPolymorphicResourceConfigur
                     variantType: ResourceOperationVariantType.API_CALL,
                     isDefault: true,
                     polymorphicRole: {
-                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],
-                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],
                     },
                     riskLevel: ResourceOperationRiskLevel.LOW,
                 }],
@@ -108,8 +108,8 @@ export const invoiceRefsPolymorphicFactories = createPolymorphicResourceConfigur
                     variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
                     polymorphicRole: {
-                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],
-                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],
                     },
                     riskLevel: ResourceOperationRiskLevel.LOW,
                 }],
@@ -119,8 +119,8 @@ export const invoiceRefsPolymorphicFactories = createPolymorphicResourceConfigur
                     variantType: ResourceOperationVariantType.INTERNAL_CALL,
                     isDefault: true,
                     polymorphicRole: {
-                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],
-                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],
+                        [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],
+                        [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],
                     },
                     riskLevel: ResourceOperationRiskLevel.LOW,
                 }],

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

@@ -1 +1 @@
-{"version":3,"file":"invoice-ref.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/invoice-ref.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Invoice Reference Resource Configuration — Polymorphic\n *\n * Produces 3 factory functions (one per scope variant) via the polymorphic factory.\n * Spread into the registry factory map:\n *   ...invoiceRefsPolymorphicFactories\n */\n\nimport { CoreResourceOperation, CoreResourceType } from '../resources/resources.shared.core.definitions';\nimport {\n  ResourceOperationRiskLevel,\n  ResourceOperationVariantType,\n} from '../resources/resources.shared.schemas';\nimport { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory';\nimport { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { invoiceRefsPolymorphicDeclaration } from './invoice-ref.shared.schemas';\nimport { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';\nimport { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas';\n\nexport const invoiceRefsPolymorphicFactories = createPolymorphicResourceConfigurations(\n  invoiceRefsPolymorphicDeclaration,\n  {\n    isSystemResource: true,\n    /** Subject-export disclosure. The subject's own invoice references — also legally retained records they are entitled to. Secrets and backend-only values are withheld by the export's security floor regardless of this grant. On a polymorphic resource this grant applies to EVERY generated variant, which is the documented intent of the shared config. */\n    systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },\n    portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.OBSERVED },\n\n    /**\n     * Subject erasure RETAINS this row and scrubs the provider-hosted document URLs.\n *\n * `hostedInvoiceUrl` and `invoicePdfUrl` address documents that carry the person's name and billing\n * address, so they are personal data this row holds and take `REMOVE`. `total` deliberately keeps its\n * FINANCIAL category and takes NO treatment: it is retained under the same tax obligation, and the mode\n * permits a categorized field to survive when the law requires it.\n     */\n    retentionPolicy: {\n      mode: ErasureRetentionMode.RETAIN_AND_IMPERSONALIZE,\n    },\n\n    /**\n     * Erasing one of these rows revokes NO session. The row is not a person — its owner FK names the ACTOR the\n *  record belongs to — and the enum prescribes `NO_PRINCIPAL` for exactly that shape. The subject's own\n *  session ends through the `USERS` row, which is `SELF_PRINCIPAL`.\n     */\n    dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },\n\n    coreOperations: [\n      CoreResourceOperation.READ,\n      CoreResourceOperation.LIST,\n      CoreResourceOperation.SEARCH,\n      CoreResourceOperation.CREATE,\n      CoreResourceOperation.UPDATE,\n      // Route-less; `retentionPolicy` requires READ + LIST + UPDATE_MANY.\n      CoreResourceOperation.UPDATE_MANY,\n    ],\n    operationsConfiguration: {\n      /*\n       * Route-less retention plumbing — INTERNAL_CALL registers no route, so no API surface is added, and it\n       * must not be REPOSITORY_ONLY: the retention primitives resolve through `getServiceOperationPathDefault`,\n       * which matches only INTERNAL_CALL / API_CALL. LIST is LOW (a read-shaped op may not claim the\n       * HIGH/CRITICAL band, which carries an audit-emission obligation); UPDATE_MANY is CRITICAL — it is the\n       * verb the impersonalize writer uses to stamp the retention markers.\n       */\n      [CoreResourceOperation.UPDATE_MANY]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.CRITICAL,\n        }],\n      },\n\n      [CoreResourceOperation.READ]: {\n        variants: [{\n          // API_CALL: invoices are a user-facing collection (Settings Hub → Billing →\n          // Invoices, and the resource presets' LIST/READ views). REPOSITORY_ONLY would\n          // strip the op from the frontend registry and register no HTTP route.\n          // Writes are INTERNAL_CALL (service-pipeline, no HTTP; created by Stripe webhooks, not users).\n          variantType: ResourceOperationVariantType.API_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.LIST]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.API_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.SEARCH]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n          isSearchable: true,\n          searchableFields: ['status'],\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          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.UPDATE]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n    },\n  },\n);\n"]}
+{"version":3,"file":"invoice-ref.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/invoice-ref.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Invoice Reference Resource Configuration — Polymorphic\n *\n * Produces 3 factory functions (one per scope variant) via the polymorphic factory.\n * Spread into the registry factory map:\n *   ...invoiceRefsPolymorphicFactories\n */\n\nimport { CoreResourceOperation, CoreResourceType } from '../resources/resources.shared.core.definitions';\nimport {\n  ResourceOperationRiskLevel,\n  ResourceOperationVariantType,\n} from '../resources/resources.shared.schemas';\nimport { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory';\nimport { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { invoiceRefsPolymorphicDeclaration } from './invoice-ref.shared.schemas';\nimport { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas';\nimport { ErasureRetentionMode, ResourceDataSubjectKind } from '../compliance/privacy/impersonalization.shared.schemas';\n\nexport const invoiceRefsPolymorphicFactories = createPolymorphicResourceConfigurations(\n  invoiceRefsPolymorphicDeclaration,\n  {\n    isSystemResource: true,\n    /** Subject-export disclosure. The subject's own invoice references — also legally retained records they are entitled to. Secrets and backend-only values are withheld by the export's security floor regardless of this grant. On a polymorphic resource this grant applies to EVERY generated variant, which is the documented intent of the shared config. */\n    systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.ALLOWED },\n    portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.OBSERVED },\n\n    /**\n     * Subject erasure RETAINS this row and scrubs the provider-hosted document URLs.\n *\n * `hostedInvoiceUrl` and `invoicePdfUrl` address documents that carry the person's name and billing\n * address, so they are personal data this row holds and take `REMOVE`. `total` deliberately keeps its\n * FINANCIAL category and takes NO treatment: it is retained under the same tax obligation, and the mode\n * permits a categorized field to survive when the law requires it.\n     */\n    retentionPolicy: {\n      mode: ErasureRetentionMode.RETAIN_AND_IMPERSONALIZE,\n    },\n\n    /**\n     * Erasing one of these rows revokes NO session. The row is not a person — its owner FK names the ACTOR the\n *  record belongs to — and the enum prescribes `NO_PRINCIPAL` for exactly that shape. The subject's own\n *  session ends through the `USERS` row, which is `SELF_PRINCIPAL`.\n     */\n    dataSubjectPolicy: { kind: ResourceDataSubjectKind.NO_PRINCIPAL },\n\n    coreOperations: [\n      CoreResourceOperation.READ,\n      CoreResourceOperation.LIST,\n      CoreResourceOperation.SEARCH,\n      CoreResourceOperation.CREATE,\n      CoreResourceOperation.UPDATE,\n      // Route-less; `retentionPolicy` requires READ + LIST + UPDATE_MANY.\n      CoreResourceOperation.UPDATE_MANY,\n    ],\n    operationsConfiguration: {\n      /*\n       * Route-less retention plumbing — INTERNAL_CALL registers no route, so no API surface is added, and it\n       * must not be REPOSITORY_ONLY: the retention primitives resolve through `getServiceOperationPathDefault`,\n       * which matches only INTERNAL_CALL / API_CALL. LIST is LOW (a read-shaped op may not claim the\n       * HIGH/CRITICAL band, which carries an audit-emission obligation); UPDATE_MANY is CRITICAL — it is the\n       * verb the impersonalize writer uses to stamp the retention markers.\n       */\n      [CoreResourceOperation.UPDATE_MANY]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n          riskLevel: ResourceOperationRiskLevel.CRITICAL,\n        }],\n      },\n\n      [CoreResourceOperation.READ]: {\n        variants: [{\n          // API_CALL: invoices are a user-facing collection (Settings Hub → Billing →\n          // Invoices, and the resource presets' LIST/READ views). REPOSITORY_ONLY would\n          // strip the op from the frontend registry and register no HTTP route.\n          // Writes are INTERNAL_CALL (service-pipeline, no HTTP; created by Stripe webhooks, not users).\n          variantType: ResourceOperationVariantType.API_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.LIST]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.API_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.SEARCH]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n          isSearchable: true,\n          searchableFields: ['status'],\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          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n      [CoreResourceOperation.UPDATE]: {\n        variants: [{\n          variantType: ResourceOperationVariantType.INTERNAL_CALL,\n          isDefault: true,\n          polymorphicRole: {\n            [CoreResourceType.ORGANIZATIONS]: [CORE_ORG_ROLES.ORG_OWNER, CORE_ORG_ROLES.ORG_ADMIN, CORE_ORG_ROLES.ORG_BILLING_PROVIDER_EVENTS],\n            [CoreResourceType.USERS]: [CORE_APP_ROLES.APP_USER, CORE_APP_ROLES.APP_BILLING_PROVIDER_EVENTS],\n          },\n          riskLevel: ResourceOperationRiskLevel.LOW,\n        }],\n      },\n    },\n  },\n);\n"]}

package/dist/esm/billing/invoice-ref.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invoice-ref.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/invoice-ref.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAG/D,eAAO,MAAM,gBAAgB;;;;;;;;;;iBAmD3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI1D,eAAO,MAAM,iCAAiC;;;;;;;;;;kBAQ5C,CAAC"}
+{"version":3,"file":"invoice-ref.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/invoice-ref.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAG/D,eAAO,MAAM,gBAAgB;;;;;;;;;;iBAmD3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI1D,eAAO,MAAM,iCAAiC;;;;;;;;;;kBAQ5C,CAAC"}

package/dist/esm/billing/invoice-ref.shared.schemas.js

@@ -21,7 +21,7 @@ import { InvoiceStatus } from './billing-enums.shared.schemas.js';
 import { RedactionType } from '../compliance/privacy/redaction.shared.schemas.js';
 export const InvoiceRefSchema = z.object({
     _id: z.string().min(1).isPrimaryKey().isSummaryField(),
-    billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed(),
+    billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed().describe("The id of the billing account this invoice was issued to."),
     /** Status - needed for billing status checks (past_due detection, etc.) */
     status: z.enum(InvoiceStatus).isDBIndexed().isSummaryField().systemEnum('InvoiceStatus'),
     /** Total amount - needed for quick display in subscription overview */

package/dist/esm/billing/invoice-ref.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"invoice-ref.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/invoice-ref.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,6DAA6D,CAAC;AACnG,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAAE,yBAAyB,EAAE,gCAAgC,EAAE,MAAM,kDAAkD,CAAC;AAC/H,OAAO,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AACrG,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,gDAAgD,CAAC;AAE/E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE;IACtD,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,CAAC,CAAC,WAAW,EAAE;IAElH,2EAA2E;IAC3E,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC;IAExF,uEAAuE;IACvE,sGAAsG;IACtG,KAAK,EAAE,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,cAAc,EAAE,CAAC,cAAc,CAAC,oBAAoB,CAAC,SAAS,CAAC;IAE7H;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,iGAAiG;IACjG,uGAAuG;IACvG,wGAAwG;IACxG,uGAAuG;IACvG,uFAAuF;IACvF,gBAAgB,EAAE,oBAAoB,CACpC,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE,CAAC,cAAc,CAAC,oBAAoB,CAAC,SAAS,CAAC,EACpF,aAAa,CAAC,MAAM,CACrB;IACD,aAAa,EAAE,oBAAoB,CACjC,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE,CAAC,cAAc,CAAC,oBAAoB,CAAC,SAAS,CAAC,EACpF,aAAa,CAAC,MAAM,CACrB;IAED,yBAAyB;IACzB,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,aAAa,EAAE;IAE7C,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IACrF,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;CACtF,CAAC,CAAC;AAGH,sEAAsE;AAEtE,MAAM,CAAC,MAAM,iCAAiC,GAAG,yBAAyB,CAAC;IACzE,gBAAgB,EAAE,aAAa;IAC/B,mBAAmB,EAAE,cAAc;IACnC,WAAW,EAAE,cAAc;IAC3B,UAAU,EAAE,gBAAgB;IAC5B,uEAAuE;IACvE,uEAAuE;IACvE,QAAQ,EAAE,sBAAsB,CAAC,GAAG,CAAC,gCAAgC,CAAC;CACvE,CAAC,CAAC","sourcesContent":["/**\n * Invoice Reference Schema (Shared) — Polymorphic\n *\n * Thin reference synced FROM provider (webhook-driven), NOT created by Wildo.\n * Only stores what's needed for: billing status checks, quick display, and provider links.\n *\n * POLYMORPHIC EXPANSION: Like subscriptions, invoice refs are scope-expanded.\n * The `billingAccountId` FK is renamed per variant via polymorphic FK transformation:\n *   - organizationInvoiceRefs  (with organizationId + organizationBillingAccountId)\n *   - userInvoiceRefs          (with userId + userBillingAccountId)\n *\n *\n * @see billing-and-features-system.md §6.4 (Invoice References)\n */\n\nimport { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { z_money, CurrencyAllowed, addImpersonalizeWith } from '@wildo-ai/zod-decorators';\nimport { declarePolymorphicSchemas, optOutPolymorphicAutoBusinessKey } from '../resources/utils/resource-polymorphism.schemas';\nimport { BILLING_SCOPE_VARIANTS, BILLING_SCOPE_FK_VARIANTS } from './billing-account.shared.schemas';\nimport { InvoiceStatus } from './billing-enums.shared.schemas';\nimport { RedactionType } from '../compliance/privacy/redaction.shared.schemas';\n\nexport const InvoiceRefSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n  billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed(),\n\n  /** Status - needed for billing status checks (past_due detection, etc.) */\n  status: z.enum(InvoiceStatus).isDBIndexed().isSummaryField().systemEnum('InvoiceStatus'),\n\n  /** Total amount - needed for quick display in subscription overview */\n  // FINANCIAL — see the note on `billing-account.shared.schemas.ts` for why this rides the shared base.\n  total: z_money({ currenciesAllowed: [CurrencyAllowed.FIAT] }).isSummaryField().dataCategories(PersonalDataCategory.FINANCIAL),\n\n  /**\n   * Provider-hosted invoice URLs — **backend-only, deliberately not exposed to clients.**\n   *\n   * These are CAPABILITY-STYLE links: whoever holds one can open the document, with no\n   * authentication. And the document is a tax invoice, which is legally required to carry the\n   * customer's full name and billing address (EU VAT Directive 2006/112/EC Art. 226(5), and\n   * equivalents elsewhere) — so the invoice PDF is personal data even though this row is not.\n   *\n   * That combination is why the URLs cannot sit in the response DTO. After a subject erasure the\n   * row is deliberately RETAINED and stays visible for accounting, and an ordinarily-readable link\n   * to a document rendering the erased person's name and address would defeat the erasure.\n   *\n   * The document itself is NEVER scrubbed or unlinked: mutilating it would void it as a tax\n   * record, which is precisely what the retention obligation exists to preserve (GDPR Art. 17(3)(b)\n   * exempts processing required by a legal obligation). Access is what is controlled, not content.\n   *\n   * The user-facing door is the provider's own customer portal\n   * (`StandardBilling_Interface.createCustomerPortalSession`, surfaced as the billing account's\n   * `open_portal` operation), which authenticates the viewer provider-side and is the conventional\n   * SaaS shape. Backend code reads these fields normally — they are present on `internalDto`.\n   */\n  // The URL IS the invoice: anyone holding it reads the line items. A category, not mere metadata.\n  // REMOVE both URLs on erasure. They address provider-hosted documents that CARRY the person's name and\n  // billing address — content about them, not an amount about the invoice. `total` deliberately keeps its\n  // category and takes NO treatment: it is retained under the tax/audit obligation this family exists to\n  // serve, and the mode permits a categorized field to survive when the law requires it.\n  hostedInvoiceUrl: addImpersonalizeWith(\n    z.string().optional().isBackendOnly().dataCategories(PersonalDataCategory.FINANCIAL),\n    RedactionType.REMOVE,\n  ),\n  invoicePdfUrl: addImpersonalizeWith(\n    z.string().optional().isBackendOnly().dataCategories(PersonalDataCategory.FINANCIAL),\n    RedactionType.REMOVE,\n  ),\n\n  /** Provider reference */\n  providerInvoiceId: z.string().isBackendOnly(),\n\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type InvoiceRef = z.infer<typeof InvoiceRefSchema>;\n\n// ── Polymorphic Declaration ────────────────────────────────────────\n\nexport const invoiceRefsPolymorphicDeclaration = declarePolymorphicSchemas({\n  baseResourceType: 'invoiceRefs',\n  baseFieldIdentifier: 'invoiceRefId',\n  baseEnumKey: 'INVOICE_REFS',\n  baseSchema: InvoiceRefSchema,\n  // Many invoices per scope (LIST/SEARCH/CREATE/UPDATE) — opt out of the\n  // polymorphism engine's singleton-per-scope business-key auto-default.\n  variants: BILLING_SCOPE_VARIANTS.map(optOutPolymorphicAutoBusinessKey),\n});\n"]}
+{"version":3,"file":"invoice-ref.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/invoice-ref.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,6DAA6D,CAAC;AACnG,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAC1F,OAAO,EAAE,yBAAyB,EAAE,gCAAgC,EAAE,MAAM,kDAAkD,CAAC;AAC/H,OAAO,EAAE,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAC;AACrG,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,gDAAgD,CAAC;AAE/E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE;IACtD,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,2DAA2D,CAAC;IAExL,2EAA2E;IAC3E,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,UAAU,CAAC,eAAe,CAAC;IAExF,uEAAuE;IACvE,sGAAsG;IACtG,KAAK,EAAE,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,cAAc,EAAE,CAAC,cAAc,CAAC,oBAAoB,CAAC,SAAS,CAAC;IAE7H;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,iGAAiG;IACjG,uGAAuG;IACvG,wGAAwG;IACxG,uGAAuG;IACvG,uFAAuF;IACvF,gBAAgB,EAAE,oBAAoB,CACpC,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE,CAAC,cAAc,CAAC,oBAAoB,CAAC,SAAS,CAAC,EACpF,aAAa,CAAC,MAAM,CACrB;IACD,aAAa,EAAE,oBAAoB,CACjC,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE,CAAC,cAAc,CAAC,oBAAoB,CAAC,SAAS,CAAC,EACpF,aAAa,CAAC,MAAM,CACrB;IAED,yBAAyB;IACzB,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,aAAa,EAAE;IAE7C,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IACrF,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;CACtF,CAAC,CAAC;AAGH,sEAAsE;AAEtE,MAAM,CAAC,MAAM,iCAAiC,GAAG,yBAAyB,CAAC;IACzE,gBAAgB,EAAE,aAAa;IAC/B,mBAAmB,EAAE,cAAc;IACnC,WAAW,EAAE,cAAc;IAC3B,UAAU,EAAE,gBAAgB;IAC5B,uEAAuE;IACvE,uEAAuE;IACvE,QAAQ,EAAE,sBAAsB,CAAC,GAAG,CAAC,gCAAgC,CAAC;CACvE,CAAC,CAAC","sourcesContent":["/**\n * Invoice Reference Schema (Shared) — Polymorphic\n *\n * Thin reference synced FROM provider (webhook-driven), NOT created by Wildo.\n * Only stores what's needed for: billing status checks, quick display, and provider links.\n *\n * POLYMORPHIC EXPANSION: Like subscriptions, invoice refs are scope-expanded.\n * The `billingAccountId` FK is renamed per variant via polymorphic FK transformation:\n *   - organizationInvoiceRefs  (with organizationId + organizationBillingAccountId)\n *   - userInvoiceRefs          (with userId + userBillingAccountId)\n *\n *\n * @see billing-and-features-system.md §6.4 (Invoice References)\n */\n\nimport { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport { z_money, CurrencyAllowed, addImpersonalizeWith } from '@wildo-ai/zod-decorators';\nimport { declarePolymorphicSchemas, optOutPolymorphicAutoBusinessKey } from '../resources/utils/resource-polymorphism.schemas';\nimport { BILLING_SCOPE_VARIANTS, BILLING_SCOPE_FK_VARIANTS } from './billing-account.shared.schemas';\nimport { InvoiceStatus } from './billing-enums.shared.schemas';\nimport { RedactionType } from '../compliance/privacy/redaction.shared.schemas';\n\nexport const InvoiceRefSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n  billingAccountId: z.string().min(1).isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS }).isDBIndexed().describe(\"The id of the billing account this invoice was issued to.\"),\n\n  /** Status - needed for billing status checks (past_due detection, etc.) */\n  status: z.enum(InvoiceStatus).isDBIndexed().isSummaryField().systemEnum('InvoiceStatus'),\n\n  /** Total amount - needed for quick display in subscription overview */\n  // FINANCIAL — see the note on `billing-account.shared.schemas.ts` for why this rides the shared base.\n  total: z_money({ currenciesAllowed: [CurrencyAllowed.FIAT] }).isSummaryField().dataCategories(PersonalDataCategory.FINANCIAL),\n\n  /**\n   * Provider-hosted invoice URLs — **backend-only, deliberately not exposed to clients.**\n   *\n   * These are CAPABILITY-STYLE links: whoever holds one can open the document, with no\n   * authentication. And the document is a tax invoice, which is legally required to carry the\n   * customer's full name and billing address (EU VAT Directive 2006/112/EC Art. 226(5), and\n   * equivalents elsewhere) — so the invoice PDF is personal data even though this row is not.\n   *\n   * That combination is why the URLs cannot sit in the response DTO. After a subject erasure the\n   * row is deliberately RETAINED and stays visible for accounting, and an ordinarily-readable link\n   * to a document rendering the erased person's name and address would defeat the erasure.\n   *\n   * The document itself is NEVER scrubbed or unlinked: mutilating it would void it as a tax\n   * record, which is precisely what the retention obligation exists to preserve (GDPR Art. 17(3)(b)\n   * exempts processing required by a legal obligation). Access is what is controlled, not content.\n   *\n   * The user-facing door is the provider's own customer portal\n   * (`StandardBilling_Interface.createCustomerPortalSession`, surfaced as the billing account's\n   * `open_portal` operation), which authenticates the viewer provider-side and is the conventional\n   * SaaS shape. Backend code reads these fields normally — they are present on `internalDto`.\n   */\n  // The URL IS the invoice: anyone holding it reads the line items. A category, not mere metadata.\n  // REMOVE both URLs on erasure. They address provider-hosted documents that CARRY the person's name and\n  // billing address — content about them, not an amount about the invoice. `total` deliberately keeps its\n  // category and takes NO treatment: it is retained under the tax/audit obligation this family exists to\n  // serve, and the mode permits a categorized field to survive when the law requires it.\n  hostedInvoiceUrl: addImpersonalizeWith(\n    z.string().optional().isBackendOnly().dataCategories(PersonalDataCategory.FINANCIAL),\n    RedactionType.REMOVE,\n  ),\n  invoicePdfUrl: addImpersonalizeWith(\n    z.string().optional().isBackendOnly().dataCategories(PersonalDataCategory.FINANCIAL),\n    RedactionType.REMOVE,\n  ),\n\n  /** Provider reference */\n  providerInvoiceId: z.string().isBackendOnly(),\n\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type InvoiceRef = z.infer<typeof InvoiceRefSchema>;\n\n// ── Polymorphic Declaration ────────────────────────────────────────\n\nexport const invoiceRefsPolymorphicDeclaration = declarePolymorphicSchemas({\n  baseResourceType: 'invoiceRefs',\n  baseFieldIdentifier: 'invoiceRefId',\n  baseEnumKey: 'INVOICE_REFS',\n  baseSchema: InvoiceRefSchema,\n  // Many invoices per scope (LIST/SEARCH/CREATE/UPDATE) — opt out of the\n  // polymorphism engine's singleton-per-scope business-key auto-default.\n  variants: BILLING_SCOPE_VARIANTS.map(optOutPolymorphicAutoBusinessKey),\n});\n"]}