@wildo-ai/saas-models 1.1.5 → 1.1.7

package/dist/esm/applications/applications.shared.schemas.js

@@ -4,13 +4,15 @@ export var StaticFrontEndType;
     StaticFrontEndType["WEBSITE"] = "website";
     StaticFrontEndType["TECHNICAL_DOCUMENTATION"] = "technical_documentation";
 })(StaticFrontEndType || (StaticFrontEndType = {}));
+/**
+ * The backend endpoints the runtime topology declares. One: the backend process binds exactly one port,
+ * and serves health, webhooks, the OAuth provider and MCP as routes on it. Four "sibling" members
+ * (health, webhook, OAuth, MCP at the API port minus 1..4) were removed with #1783 — nothing listened on
+ * any of them, so each was a URL that refused every connection.
+ */
 export var BackendApiType;
 (function (BackendApiType) {
     BackendApiType["MAIN_BACKEND_API"] = "main_backend_api";
-    BackendApiType["HEALTH_CHECK_API"] = "health_check_api";
-    BackendApiType["MAIN_WEBHOOK_API"] = "main_webhook_api";
-    BackendApiType["OAUTH2_PROVIDER_API"] = "oauth2_provider_api";
-    BackendApiType["MCP_API"] = "mcp_api";
 })(BackendApiType || (BackendApiType = {}));
 /**
  * Background app-owned runtimes — kinds that an application owns but that

package/dist/esm/applications/applications.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"applications.shared.schemas.js","sourceRoot":"","sources":["../../../../src/applications/applications.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\n\nexport enum StaticFrontEndType {\n  WEBSITE = 'website',\n  TECHNICAL_DOCUMENTATION = 'technical_documentation',\n}\n\nexport enum BackendApiType {\n  MAIN_BACKEND_API = 'main_backend_api',\n  HEALTH_CHECK_API = 'health_check_api',\n  MAIN_WEBHOOK_API = 'main_webhook_api',\n  OAUTH2_PROVIDER_API = 'oauth2_provider_api',\n  MCP_API = 'mcp_api',\n}\n\n/**\n * Background app-owned runtimes — kinds that an application owns but that\n * do NOT serve user-facing requests directly (no public HTTP surface for\n * end-users, no rendered frontend).\n *\n * Introduced by the minions-and-workers plan\n * (`.claude/plans/minions-and-workers-implementation.md`, KD-9):\n *\n * - `MINION` — TS/Node single-instance process sharing the application\n *   scope (Mongo / Redis / RabbitMQ); hosts the actor system; consumes\n *   queue / cron ticks. Always-up or cron-triggered.\n * - `WORKER` — language-pluggable stateless HTTP subprocess (Rust / Node /\n *   Java / …) called by the backend-api with a Wildo JWT. No backing\n *   services; ClusterIP-only, no ingress.\n *\n * Deploy-time identity uses the `{kind, name}` vocabulary (`name` = the\n * `wildo.saas.config.ts` bucket key), surfaced in two forms — the\n * `APP_OWNED_SERVICE_KIND` + `APP_OWNED_SERVICE_NAME` **env** pair and the\n * matching `wildo.ai/owned-service-{kind,name}` pod **labels**. WHICH forms a\n * kind carries, and how it consumes them, differs because their runtimes differ:\n *\n * - `WORKER` — language-pluggable, so a non-Node runtime (the reference Rust\n *   worker) READS the `APP_OWNED_SERVICE_NAME` **env** var at boot and forwards\n *   it as the apps-manager `worker-bootstrap` path segment\n *   (`appConfig.workers[name]`). A Node worker instead hardcodes `workerName` in\n *   `defineWorkerInit`; the env pair is still stamped on every worker deploy path\n *   (k8s, docker-compose, CLI `.env`) for the language-agnostic case +\n *   observability, alongside the matching pod labels.\n * - `MINION` — always Node, and sources its `minionName` from its compiled-in\n *   `defineMinionInit({ minionName })` config (the minion package is\n *   domain-specific by construction), cross-validated at boot against the\n *   fetched `appConfig.minions[minionName]`. Because identity is a compile-time\n *   fact, minions carry it ONLY as the `wildo.ai/owned-service-{kind,name}` pod\n *   **labels** (operators, selectors, observability); the `APP_OWNED_SERVICE_*`\n *   **env** pair is deliberately omitted on EVERY minion deploy path (k8s, CLI\n *   `.env`, docker-compose), since an env identity would be a second,\n *   drift-prone authority (see `env-configuration-generator.service.ts`).\n */\nexport enum BackgroundRuntimeType {\n  MINION = 'minion',\n  WORKER = 'worker',\n}\n\n/**\n * Schema for all shared (non-platform-private) application types.\n *\n * Interactive frontend surfaces are config-defined strings keyed by frontend\n * service identity via `frontendServices` in AppConfiguration, not an enum.\n * `z.string()` accepts those config-defined values alongside the known\n * static-frontend and backend-API enums.\n */\nexport const AllSharedApplicationTypesSchema = z.union([\n  z.enum(StaticFrontEndType),\n  z.enum(BackendApiType),\n  z.string(),\n]);\nexport type AllSharedApplicationTypes = z.infer<typeof AllSharedApplicationTypesSchema>;\n\n/**\n * Full app-owned runtime identity surface: every primary application type\n * (`AllSharedApplicationTypesSchema` — backend kinds, static frontends,\n * dynamic-frontend keys) plus the background runtimes\n * (`BackgroundRuntimeType` — minions, workers).\n *\n * Use this where a process needs to declare what kind of app-owned\n * runtime it is without forcing every caller to switch on a coarse\n * vocabulary that overlaps the existing fine-grained enums.\n */\nexport const AllAppOwnedRuntimeTypesSchema = z.union([\n  AllSharedApplicationTypesSchema,\n  z.enum(BackgroundRuntimeType),\n]);\nexport type AllAppOwnedRuntimeTypes = z.infer<typeof AllAppOwnedRuntimeTypesSchema>;\n\nexport const ApplicationSchema = z.object({\n    _id : z.string().isPrimaryKey().isSummaryField(),\n    appSlug : z.string().isDBIndexed().isSummaryField().excludeFromUpdate(),\n    appDisplayName : z.string().isDBIndexed().isSummaryField(),\n    lastVersion : z.string().optional().excludeFromCreate().excludeFromUpdate(),\n    // Backend-only field - stored in DB but never sent to frontend\n    platformAppId : z.string().isDBIndexed().isBackendOnly(),\n    /**\n     * Serializes every decision about WHICH organization owns the application (#1054).\n     *\n     * ## The race it closes\n     *\n     * `organizations.promoteToOwnerOrganization` measures (\"does an owner organization exist?\") and\n     * then writes (`type`). Under snapshot isolation that is textbook WRITE SKEW: two operators\n     * promote two DIFFERENT organizations, each observes no owner, and both commit — producing the two\n     * owner organizations the whole design refuses, which neither was individually permitted to\n     * create. No amount of additional checking closes it: each transaction's view is internally\n     * consistent, and a re-measure after the write cannot see the other's uncommitted row.\n     *\n     * The remedy is to give the two transactions something to collide ON. The promotion bumps this\n     * token inside its transaction before measuring, so two of them touch the same document and the\n     * storage engine aborts the loser. Same mechanism, same reasoning, as\n     * `Organization.ownerFloorSerializationToken` — which is also where the trap is recorded: the\n     * write MUST carry `preserveServerInjectedFields` for this field, or the repository's strict\n     * re-parse silently strips it and the serialization protects nothing.\n     *\n     * ## Why the APPLICATION row and not an organization's\n     *\n     * The two racing promotions target DIFFERENT organizations, so neither organization's row is\n     * shared and colliding on one would serialize nothing. The APPLICATION row is the only row both\n     * transactions can be made to touch, and it is also the right subject semantically: the fact being\n     * protected is a property of the application (\"it has one owner organization\"), not of any tenant.\n     *\n     * The VALUE is irrelevant and nothing reads it, so a lost update here costs nothing; what matters\n     * is that the document is written at all. `.nullish()` because every existing application predates\n     * the field, and one that has never had a promotion legitimately has no token — absent and zero\n     * mean the same thing.\n     */\n    ownerOrganizationSerializationToken : z.number().int().nullish().excludeFromCreate().excludeFromUpdate().isBackendOnly().isHidden(),\n});\nexport type Application = z.infer<typeof ApplicationSchema>;\n\nexport const ApplicationVersionSchema = z.object({\n    _id : z.string().isPrimaryKey().isSummaryField(),\n    applicationId : z.string().isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n    version : z.string().isDBIndexed().isSummaryField(),\n    releaseDate : z.date().isDBIndexed().isSummaryField(),\n    releaseNotes : z.string(),\n});\nexport type ApplicationVersion = z.infer<typeof ApplicationVersionSchema>;\n\nexport const ApplicationMetadataSchema = z.object({\n    _id : z.string().isPrimaryKey().isSummaryField(),\n    /**\n     * The owning application — and this row's BUSINESS IDENTITY.\n     *\n     * `APPLICATION → APPLICATION_METADATA` is 1:1, so \"the metadata of application X\"\n     * identifies the row completely. Declaring that lets the framework's business-key\n     * repository helpers address it: the app-init seed\n     * (`engine-applications:application-metadata`) upserts through\n     * `upsertByBusinessKey`, which refuses a schema that declares no identity —\n     * \"Schema declares no business-key identity\" — rather than guessing one.\n     *\n     * `.isUnique()` carries the 1:1 down to the database. `.isBusinessKey()` alone is\n     * a pure marker with no index, so two concurrent creates could otherwise leave\n     * an application with two metadata rows, which no read path expects.\n     *\n     * The name is `applicationId`, matching the APPLICATION scope's registered field\n     * identifier and every other APPLICATION-scoped resource. It was `appId` until\n     * 2026-09-18, which silently excluded this resource — and its two siblings — from\n     * every mechanism keyed on that identifier, up to and including the settings panes\n     * that render it. See the APPLICATION_FEATURES edge in\n     * `resources-registry.shared.core.definitions.ts` for the measured consequences.\n     */\n    applicationId : z.string().isDBIndexed().isForeignKey().isBusinessKey().isUnique().isSummaryField().excludeFromUpdate(),\n    // `.default('')` so the row is eager-seedable via onParentCreate (placeholder;\n    // the app sets a real description later) — root-cause fix for the blocking field.\n    description : z.string().default('').isDBIndexed().isSummaryField(),\n});\nexport type ApplicationMetadata = z.infer<typeof ApplicationMetadataSchema>;\n"]}
+{"version":3,"file":"applications.shared.schemas.js","sourceRoot":"","sources":["../../../src/applications/applications.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\n\nexport enum StaticFrontEndType {\n  WEBSITE = 'website',\n  TECHNICAL_DOCUMENTATION = 'technical_documentation',\n}\n\n/**\n * The backend endpoints the runtime topology declares. One: the backend process binds exactly one port,\n * and serves health, webhooks, the OAuth provider and MCP as routes on it. Four \"sibling\" members\n * (health, webhook, OAuth, MCP at the API port minus 1..4) were removed with #1783 — nothing listened on\n * any of them, so each was a URL that refused every connection.\n */\nexport enum BackendApiType {\n  MAIN_BACKEND_API = 'main_backend_api',\n}\n\n/**\n * Background app-owned runtimes — kinds that an application owns but that\n * do NOT serve user-facing requests directly (no public HTTP surface for\n * end-users, no rendered frontend).\n *\n * Introduced by the minions-and-workers plan\n * (`.claude/plans/minions-and-workers-implementation.md`, KD-9):\n *\n * - `MINION` — TS/Node single-instance process sharing the application\n *   scope (Mongo / Redis / RabbitMQ); hosts the actor system; consumes\n *   queue / cron ticks. Always-up or cron-triggered.\n * - `WORKER` — language-pluggable stateless HTTP subprocess (Rust / Node /\n *   Java / …) called by the backend-api with a Wildo JWT. No backing\n *   services; ClusterIP-only, no ingress.\n *\n * Deploy-time identity uses the `{kind, name}` vocabulary (`name` = the\n * `wildo.saas.config.ts` bucket key), surfaced in two forms — the\n * `APP_OWNED_SERVICE_KIND` + `APP_OWNED_SERVICE_NAME` **env** pair and the\n * matching `wildo.ai/owned-service-{kind,name}` pod **labels**. WHICH forms a\n * kind carries, and how it consumes them, differs because their runtimes differ:\n *\n * - `WORKER` — language-pluggable, so a non-Node runtime (the reference Rust\n *   worker) READS the `APP_OWNED_SERVICE_NAME` **env** var at boot and forwards\n *   it as the apps-manager `worker-bootstrap` path segment\n *   (`appConfig.workers[name]`). A Node worker instead hardcodes `workerName` in\n *   `defineWorkerInit`; the env pair is still stamped on every worker deploy path\n *   (k8s, docker-compose, CLI `.env`) for the language-agnostic case +\n *   observability, alongside the matching pod labels.\n * - `MINION` — always Node, and sources its `minionName` from its compiled-in\n *   `defineMinionInit({ minionName })` config (the minion package is\n *   domain-specific by construction), cross-validated at boot against the\n *   fetched `appConfig.minions[minionName]`. Because identity is a compile-time\n *   fact, minions carry it ONLY as the `wildo.ai/owned-service-{kind,name}` pod\n *   **labels** (operators, selectors, observability); the `APP_OWNED_SERVICE_*`\n *   **env** pair is deliberately omitted on EVERY minion deploy path (k8s, CLI\n *   `.env`, docker-compose), since an env identity would be a second,\n *   drift-prone authority (see `env-configuration-generator.service.ts`).\n */\nexport enum BackgroundRuntimeType {\n  MINION = 'minion',\n  WORKER = 'worker',\n}\n\n/**\n * Schema for all shared (non-platform-private) application types.\n *\n * Interactive frontend surfaces are config-defined strings keyed by frontend\n * service identity via `frontendServices` in AppConfiguration, not an enum.\n * `z.string()` accepts those config-defined values alongside the known\n * static-frontend and backend-API enums.\n */\nexport const AllSharedApplicationTypesSchema = z.union([\n  z.enum(StaticFrontEndType),\n  z.enum(BackendApiType),\n  z.string(),\n]);\nexport type AllSharedApplicationTypes = z.infer<typeof AllSharedApplicationTypesSchema>;\n\n/**\n * Full app-owned runtime identity surface: every primary application type\n * (`AllSharedApplicationTypesSchema` — backend kinds, static frontends,\n * dynamic-frontend keys) plus the background runtimes\n * (`BackgroundRuntimeType` — minions, workers).\n *\n * Use this where a process needs to declare what kind of app-owned\n * runtime it is without forcing every caller to switch on a coarse\n * vocabulary that overlaps the existing fine-grained enums.\n */\nexport const AllAppOwnedRuntimeTypesSchema = z.union([\n  AllSharedApplicationTypesSchema,\n  z.enum(BackgroundRuntimeType),\n]);\nexport type AllAppOwnedRuntimeTypes = z.infer<typeof AllAppOwnedRuntimeTypesSchema>;\n\nexport const ApplicationSchema = z.object({\n    _id : z.string().isPrimaryKey().isSummaryField(),\n    appSlug : z.string().isDBIndexed().isSummaryField().excludeFromUpdate(),\n    appDisplayName : z.string().isDBIndexed().isSummaryField(),\n    lastVersion : z.string().optional().excludeFromCreate().excludeFromUpdate(),\n    // Backend-only field - stored in DB but never sent to frontend\n    platformAppId : z.string().isDBIndexed().isBackendOnly(),\n    /**\n     * Serializes every decision about WHICH organization owns the application (#1054).\n     *\n     * ## The race it closes\n     *\n     * `organizations.promoteToOwnerOrganization` measures (\"does an owner organization exist?\") and\n     * then writes (`type`). Under snapshot isolation that is textbook WRITE SKEW: two operators\n     * promote two DIFFERENT organizations, each observes no owner, and both commit — producing the two\n     * owner organizations the whole design refuses, which neither was individually permitted to\n     * create. No amount of additional checking closes it: each transaction's view is internally\n     * consistent, and a re-measure after the write cannot see the other's uncommitted row.\n     *\n     * The remedy is to give the two transactions something to collide ON. The promotion bumps this\n     * token inside its transaction before measuring, so two of them touch the same document and the\n     * storage engine aborts the loser. Same mechanism, same reasoning, as\n     * `Organization.ownerFloorSerializationToken` — which is also where the trap is recorded: the\n     * write MUST carry `preserveServerInjectedFields` for this field, or the repository's strict\n     * re-parse silently strips it and the serialization protects nothing.\n     *\n     * ## Why the APPLICATION row and not an organization's\n     *\n     * The two racing promotions target DIFFERENT organizations, so neither organization's row is\n     * shared and colliding on one would serialize nothing. The APPLICATION row is the only row both\n     * transactions can be made to touch, and it is also the right subject semantically: the fact being\n     * protected is a property of the application (\"it has one owner organization\"), not of any tenant.\n     *\n     * The VALUE is irrelevant and nothing reads it, so a lost update here costs nothing; what matters\n     * is that the document is written at all. `.nullish()` because every existing application predates\n     * the field, and one that has never had a promotion legitimately has no token — absent and zero\n     * mean the same thing.\n     */\n    ownerOrganizationSerializationToken : z.number().int().nullish().excludeFromCreate().excludeFromUpdate().isBackendOnly().isHidden(),\n});\nexport type Application = z.infer<typeof ApplicationSchema>;\n\nexport const ApplicationVersionSchema = z.object({\n    _id : z.string().isPrimaryKey().isSummaryField(),\n    applicationId : z.string().isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n    version : z.string().isDBIndexed().isSummaryField(),\n    releaseDate : z.date().isDBIndexed().isSummaryField(),\n    releaseNotes : z.string(),\n});\nexport type ApplicationVersion = z.infer<typeof ApplicationVersionSchema>;\n\nexport const ApplicationMetadataSchema = z.object({\n    _id : z.string().isPrimaryKey().isSummaryField(),\n    /**\n     * The owning application — and this row's BUSINESS IDENTITY.\n     *\n     * `APPLICATION → APPLICATION_METADATA` is 1:1, so \"the metadata of application X\"\n     * identifies the row completely. Declaring that lets the framework's business-key\n     * repository helpers address it: the app-init seed\n     * (`engine-applications:application-metadata`) upserts through\n     * `upsertByBusinessKey`, which refuses a schema that declares no identity —\n     * \"Schema declares no business-key identity\" — rather than guessing one.\n     *\n     * `.isUnique()` carries the 1:1 down to the database. `.isBusinessKey()` alone is\n     * a pure marker with no index, so two concurrent creates could otherwise leave\n     * an application with two metadata rows, which no read path expects.\n     *\n     * The name is `applicationId`, matching the APPLICATION scope's registered field\n     * identifier and every other APPLICATION-scoped resource. It was `appId` until\n     * 2026-09-18, which silently excluded this resource — and its two siblings — from\n     * every mechanism keyed on that identifier, up to and including the settings panes\n     * that render it. See the APPLICATION_FEATURES edge in\n     * `resources-registry.shared.core.definitions.ts` for the measured consequences.\n     */\n    applicationId : z.string().isDBIndexed().isForeignKey().isBusinessKey().isUnique().isSummaryField().excludeFromUpdate(),\n    // `.default('')` so the row is eager-seedable via onParentCreate (placeholder;\n    // the app sets a real description later) — root-cause fix for the blocking field.\n    description : z.string().default('').isDBIndexed().isSummaryField(),\n});\nexport type ApplicationMetadata = z.infer<typeof ApplicationMetadataSchema>;\n"]}

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

@@ -15,7 +15,12 @@ export declare enum BillingAccount_Operations {
     /** Open the Stripe Customer Portal for self-service management */
     OPEN_PORTAL = "open_portal",
     /** Fetch aggregated billing state (account, subscription, products, prices, credit pools) */
-    GET_STATE = "get_state"
+    GET_STATE = "get_state",
+    /**
+     * Redeem another account's referral code (#1802). Only a new customer may: an account that has never
+     * subscribed, is not already referred, and is not the referrer.
+     */
+    REDEEM_REFERRAL = "redeem_referral"
 }
 /** Request DTO for OPEN_CHECKOUT. Trial duration is server-owned product/application policy, never a payer option. */
 export declare const BillingAccount_OpenCheckoutRequestDto: z.ZodObject<{
@@ -27,6 +32,10 @@ export declare const BillingAccount_OpenCheckoutRequestDto: z.ZodObject<{
     promotionCode: z.ZodOptional<z.ZodString>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
+/** Request DTO for REDEEM_REFERRAL (#1802). */
+export declare const BillingAccount_RedeemReferralRequestDto: z.ZodObject<{
+    referralCode: z.ZodString;
+}, z.core.$strict>;
 /** Request DTO for OPEN_PORTAL operation */
 export declare const BillingAccount_OpenPortalRequestDto: z.ZodObject<{
     returnUrl: z.ZodURL;

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

@@ -1 +1 @@
-{"version":3,"file":"billing-account.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/billing-account.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAoB,MAAM,gDAAgD,CAAC;AAgBzG,oBAAY,yBAAyB;IACnC,wEAAwE;IACxE,aAAa,kBAAkB;IAC/B,kEAAkE;IAClE,WAAW,gBAAgB;IAC3B,6FAA6F;IAC7F,SAAS,cAAc;CACxB;AAID,sHAAsH;AACtH,eAAO,MAAM,qCAAqC;;;;;;;;iBAoChD,CAAC;AAEH,4CAA4C;AAC5C,eAAO,MAAM,mCAAmC;;iBAE9C,CAAC;AAMH;;;;;;;;GAQG;AACH,eAAO,MAAM,mCAAmC,2SAiM/C,CAAC"}
+{"version":3,"file":"billing-account.shared.resources-config.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/billing-account.shared.resources-config.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAoB,MAAM,gDAAgD,CAAC;AAiBzG,oBAAY,yBAAyB;IACnC,wEAAwE;IACxE,aAAa,kBAAkB;IAC/B,kEAAkE;IAClE,WAAW,gBAAgB;IAC3B,6FAA6F;IAC7F,SAAS,cAAc;IACvB;;;OAGG;IACH,eAAe,oBAAoB;CACpC;AAID,sHAAsH;AACtH,eAAO,MAAM,qCAAqC;;;;;;;;iBAoChD,CAAC;AAEH,+CAA+C;AAC/C,eAAO,MAAM,uCAAuC;;kBAElD,CAAC;AAEH,4CAA4C;AAC5C,eAAO,MAAM,mCAAmC;;iBAE9C,CAAC;AAMH;;;;;;;;GAQG;AACH,eAAO,MAAM,mCAAmC,2SAyN/C,CAAC"}

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

@@ -13,7 +13,8 @@ import { ResourceOperationRiskLevel, ResourceOperationVariantType, } from '../re
 import { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas.js';
 import { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory.js';
 import { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas.js';
-import { BILLING_CHECKOUT_MAX_QUANTITY, BILLING_RESERVED_METADATA_KEY_PREFIX } from './billing-enums.shared.schemas.js';
+import { BILLING_CHECKOUT_MAX_QUANTITY, BILLING_RESERVED_METADATA_KEY_PREFIX, ReferralStatus } from './billing-enums.shared.schemas.js';
+import { ReferredRewardSchema } from './referral-reward.shared.schemas.js';
 import { billingAccountsPolymorphicDeclaration } from './billing-account.shared.schemas.js';
 import { BillingStateResponseSchema } from './billing-types.shared.schemas.js';
 import { DataPortabilityProvenance } from '../compliance/privacy/subject-export.shared.schemas.js';
@@ -27,21 +28,26 @@ export var BillingAccount_Operations;
     BillingAccount_Operations["OPEN_PORTAL"] = "open_portal";
     /** Fetch aggregated billing state (account, subscription, products, prices, credit pools) */
     BillingAccount_Operations["GET_STATE"] = "get_state";
+    /**
+     * Redeem another account's referral code (#1802). Only a new customer may: an account that has never
+     * subscribed, is not already referred, and is not the referrer.
+     */
+    BillingAccount_Operations["REDEEM_REFERRAL"] = "redeem_referral";
 })(BillingAccount_Operations || (BillingAccount_Operations = {}));
 // ── Request DTOs ─────────────────────────────────────────────────────
 /** Request DTO for OPEN_CHECKOUT. Trial duration is server-owned product/application policy, never a payer option. */
 export const BillingAccount_OpenCheckoutRequestDto = z.object({
-    productKey: z.string().min(1),
-    priceId: z.string().min(1),
-    successUrl: z.url(),
-    cancelUrl: z.url(),
+    productKey: z.string().min(1).describe("The key of the product to buy. It must be available for purchase and offered to this account's scope."),
+    priceId: z.string().min(1).describe("The id of the price to buy the product at. It must be a price of that product."),
+    successUrl: z.url().describe("Where the billing provider sends the customer after a completed checkout."),
+    cancelUrl: z.url().describe("Where the billing provider sends the customer if they leave checkout without paying."),
     /**
      * Bounded by the same constant the webhook consumer honours. An unbounded quantity here would be
      * billed by the provider and then refused on the way back in, charging the customer for credits
      * that never arrive.
      */
-    quantity: z.number().int().min(1).max(BILLING_CHECKOUT_MAX_QUANTITY).default(1),
-    promotionCode: z.string().optional(),
+    quantity: z.number().int().min(1).max(BILLING_CHECKOUT_MAX_QUANTITY).default(1).describe("How many units to buy, such as seats or credit packs. Defaults to 1."),
+    promotionCode: z.string().optional().describe("A promotion code to apply. It is checked before checkout opens, and refused when it is unknown, inactive, outside its validity dates, used up, not valid for this product, or not set up with the billing provider. The checkout page accepts no code of its own."),
     /**
      * Caller-supplied tags mirrored to the provider for the application's own analytics or
      * reconciliation. They carry NO authority.
@@ -61,9 +67,13 @@ export const BillingAccount_OpenCheckoutRequestDto = z.object({
         .record(z.string().refine((key) => !key.startsWith(BILLING_RESERVED_METADATA_KEY_PREFIX), `Metadata keys starting with "${BILLING_RESERVED_METADATA_KEY_PREFIX}" are reserved by the framework and cannot be supplied by the caller`), z.string())
         .optional(),
 });
+/** Request DTO for REDEEM_REFERRAL (#1802). */
+export const BillingAccount_RedeemReferralRequestDto = z.strictObject({
+    referralCode: z.string().trim().min(1).max(64).describe('The referral code to redeem, as the referrer shared it.'),
+});
 /** Request DTO for OPEN_PORTAL operation */
 export const BillingAccount_OpenPortalRequestDto = z.object({
-    returnUrl: z.url(),
+    returnUrl: z.url().describe('Absolute URL the billing portal sends the customer back to when they leave it.'),
 });
 // =============================================================================
 // POLYMORPHIC FACTORY — 2 variants (org, user)
@@ -169,8 +179,8 @@ export const billingAccountsPolymorphicFactories = createPolymorphicResourceConf
                     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,
                 }],
@@ -191,8 +201,8 @@ export const billingAccountsPolymorphicFactories = createPolymorphicResourceConf
                     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.MEDIUM,
                 }],
@@ -223,8 +233,32 @@ export const billingAccountsPolymorphicFactories = createPolymorphicResourceConf
                     // session, NOT the billing-account resource. Without this the DTO builder
                     // would validate the service output against the resource schema and 500.
                     customResponseDto: z.object({
-                        url: z.url(),
-                        sessionId: z.string(),
+                        url: z.url().describe("The billing provider's hosted checkout page. Send the customer there to pay."),
+                        sessionId: z.string().describe("The billing provider's id for this checkout session."),
+                    }),
+                }],
+        },
+        /*
+         * #1802 — the account that was referred redeems the code. Refusals are the ones a person can act on:
+         * an unusable code, and an account that cannot be referred. The rewards are the referrer's policy,
+         * copied when the code was issued, and are reported back so the purchase screen can show them.
+         */
+        [BillingAccount_Operations.REDEEM_REFERRAL]: {
+            variants: [{
+                    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],
+                    },
+                    riskLevel: ResourceOperationRiskLevel.MEDIUM,
+                    resourceOperationLike: CoreResourceOperation.UPDATE,
+                    requestDto: BillingAccount_RedeemReferralRequestDto,
+                    // Returns the redemption, not the billing account.
+                    customResponseDto: z.object({
+                        referralId: z.string().describe('The id of the referral that was redeemed.'),
+                        status: z.enum(ReferralStatus).systemEnum('ReferralStatus').describe('`accepted`: the account is now the referred side, and the rewards are granted when it pays its first invoice.'),
+                        referredReward: ReferredRewardSchema.optional().describe('What this account receives. Absent when the referral gives the referred side nothing.'),
                     }),
                 }],
         },
@@ -242,7 +276,7 @@ export const billingAccountsPolymorphicFactories = createPolymorphicResourceConf
                     // Borrows READ for its route/verb but returns the provider portal
                     // redirect URL, NOT the billing-account resource.
                     customResponseDto: z.object({
-                        url: z.url(),
+                        url: z.url().describe("The billing provider's customer portal, where the customer manages their billing. Send the customer there; the portal links back to `returnUrl`."),
                     }),
                 }],
         },

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

@@ -1 +1 @@
-{"version":3,"file":"billing-account.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../src/billing/billing-account.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Billing Account 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 *   ...billingAccountsPolymorphicFactories\n *\n * @see polymorphic-scope-approach-A-expansion.md — Phase 3\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 { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory';\nimport { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { BILLING_CHECKOUT_MAX_QUANTITY, BILLING_RESERVED_METADATA_KEY_PREFIX } from './billing-enums.shared.schemas';\nimport { billingAccountsPolymorphicDeclaration } from './billing-account.shared.schemas';\nimport { BillingStateResponseSchema } from './billing-types.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 BillingAccount_Operations {\n  /** Create a Stripe Checkout Session for the user to complete payment */\n  OPEN_CHECKOUT = 'open_checkout',\n  /** Open the Stripe Customer Portal for self-service management */\n  OPEN_PORTAL = 'open_portal',\n  /** Fetch aggregated billing state (account, subscription, products, prices, credit pools) */\n  GET_STATE = 'get_state',\n}\n\n// ── Request DTOs ─────────────────────────────────────────────────────\n\n/** Request DTO for OPEN_CHECKOUT. Trial duration is server-owned product/application policy, never a payer option. */\nexport const BillingAccount_OpenCheckoutRequestDto = z.object({\n  productKey: z.string().min(1),\n  priceId: z.string().min(1),\n  successUrl: z.url(),\n  cancelUrl: z.url(),\n  /**\n   * Bounded by the same constant the webhook consumer honours. An unbounded quantity here would be\n   * billed by the provider and then refused on the way back in, charging the customer for credits\n   * that never arrive.\n   */\n  quantity: z.number().int().min(1).max(BILLING_CHECKOUT_MAX_QUANTITY).default(1),\n  promotionCode: z.string().optional(),\n  /**\n   * Caller-supplied tags mirrored to the provider for the application's own analytics or\n   * reconciliation. They carry NO authority.\n   *\n   * Keys in the framework-reserved namespace are REFUSED here rather than silently dropped: the\n   * caller is trying to write into the namespace that decides which billing account gets credited\n   * and by how much, and an app developer who typed a reserved key deserves to be told, not to\n   * watch their tag vanish. Refusal at the DTO is the loud, outermost half of the boundary; the\n   * builder's write-reserved-last ordering and the consumer's read-only-reserved rule are the two\n   * structural halves. See {@link BILLING_RESERVED_METADATA_KEY_PREFIX}.\n   *\n   * The refinement sits on the KEY schema, not on the record: it keeps the DTO a plain `ZodRecord`\n   * for the OpenAPI projector and the request-validation pipeline, where a wrapping effect would\n   * change the node type every consumer of this DTO narrows on.\n   */\n  metadata: z\n    .record(\n      z.string().refine(\n        (key) => !key.startsWith(BILLING_RESERVED_METADATA_KEY_PREFIX),\n        `Metadata keys starting with \"${BILLING_RESERVED_METADATA_KEY_PREFIX}\" are reserved by the framework and cannot be supplied by the caller`,\n      ),\n      z.string(),\n    )\n    .optional(),\n});\n\n/** Request DTO for OPEN_PORTAL operation */\nexport const BillingAccount_OpenPortalRequestDto = z.object({\n  returnUrl: z.url(),\n});\n\n// =============================================================================\n// POLYMORPHIC FACTORY — 2 variants (org, user)\n// =============================================================================\n\n/**\n * Polymorphic factory map for billing accounts.\n * Spread into `coreShared_ResourcesConfigurations_FactoryMap`:\n *   ...billingAccountsPolymorphicFactories\n *\n * Produces entries for:\n *   - organizationBillingAccounts\n *   - userBillingAccounts\n */\nexport const billingAccountsPolymorphicFactories = createPolymorphicResourceConfigurations(\n  billingAccountsPolymorphicDeclaration,\n  {\n    isSystemResource: true,\n    // System-context CREATE opt-in (fail-closed default is FORBIDDEN). The billing\n    // account is auto-created by `BillingStateBackendService.getState()` on first\n    // access via `SystemAccessBackendService.createAsSystem` — a trusted in-process\n    // write with no HTTP surface and no request context to seed the scope FK. That\n    // path relocates the ACL onto the billing service (which has already resolved\n    // the scope) and injects the scope FK (`organizationId` / `userId`) through the\n    // execution context map. Resource-level and shared by BOTH scope variants\n    // (org + user) per the polymorphic-resource contract on ResourceSystemAccessPolicy.\n    systemAccessPolicy: {\n      // Subject-export disclosure. The subject's own billing account. 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      exportSubject: ResourceSystemAccessMode.ALLOWED,\n      create: ResourceSystemAccessMode.ALLOWED,\n      // System-context LIST opt-in. Subject erasure must enumerate the erased person's billing\n      // accounts to reach their provider customer (cancel subscriptions, anonymize, detach payment\n      // methods). That runs with no request context — the subject is being erased — so it reads\n      // through `SystemAccessBackendService.listAsSystem`, which is fail-closed and refuses a\n      // resource that has not opted in here.\n      //\n      // Safe to grant: LIST is the READ side, and the erasure path filters by the subject's own\n      // scope FK. The default LIST variant is API_CALL, so it resolves through\n      // `getServiceOperationPathDefault` — a REPOSITORY_ONLY-only LIST would pass this grant and\n      // then fail to resolve at erasure time, which is the failure mode this comment exists to\n      // stop someone from reintroducing.\n      list: ResourceSystemAccessMode.ALLOWED,\n    },\n    portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.OBSERVED },\n\n    /**\n     * Subject erasure RETAINS this row and scrubs the provider customer id.\n *\n * The financial record is kept for the tax/audit obligation this family exists to serve, and — as the\n * family's authoring rule states — erasure scrubs the linked USER rather than these rows, because the\n * person is a foreign key. `providerCustomerId` is the exception the rule does not cover: it is a stable\n * handle that re-identifies the person INSIDE the payment provider, so it is personal data this row holds.\n * It takes `REMOVE`; everything else is retained.\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    customOperation: BillingAccount_Operations,\n    coreOperations: [\n      CoreResourceOperation.READ,\n      CoreResourceOperation.LIST,\n      CoreResourceOperation.CREATE,\n      CoreResourceOperation.UPDATE,\n      CoreResourceOperation.DELETE,\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: the billing account is a user-facing record (Settings Hub → Billing →\n          // Account, and the resource presets' LIST/READ views). REPOSITORY_ONLY would strip\n          // the op from the frontend registry and register no HTTP route. Writes (auto-create\n          // + webhook sync) are INTERNAL_CALL — run through the service pipeline, no HTTP surface.\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.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.MEDIUM,\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.MEDIUM,\n        }],\n      },\n      [CoreResourceOperation.DELETE]: {\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.CRITICAL,\n        }],\n      },\n      [BillingAccount_Operations.OPEN_CHECKOUT]: {\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.HIGH,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: BillingAccount_OpenCheckoutRequestDto,\n          // Borrows UPDATE for its route/verb but returns the provider checkout\n          // session, NOT the billing-account resource. Without this the DTO builder\n          // would validate the service output against the resource schema and 500.\n          customResponseDto: z.object({\n            url: z.url(),\n            sessionId: z.string(),\n          }),\n        }],\n      },\n      [BillingAccount_Operations.OPEN_PORTAL]: {\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          resourceOperationLike: CoreResourceOperation.READ,\n          requestDto: BillingAccount_OpenPortalRequestDto,\n          // Borrows READ for its route/verb but returns the provider portal\n          // redirect URL, NOT the billing-account resource.\n          customResponseDto: z.object({\n            url: z.url(),\n          }),\n        }],\n      },\n      [BillingAccount_Operations.GET_STATE]: {\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          resourceOperationLike: CoreResourceOperation.COUNT,\n          // Borrows COUNT for its route/verb but returns the aggregated billing\n          // state bundle, NOT a `{ count }`. Without this the DTO builder would\n          // assign the COUNT default envelope and the service output would fail\n          // `transformOutput`'s `internalDto.parse` → HTTP 500.\n          customResponseDto: BillingStateResponseSchema,\n        }],\n      },\n    },\n  },\n);\n"]}
+{"version":3,"file":"billing-account.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../src/billing/billing-account.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Billing Account 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 *   ...billingAccountsPolymorphicFactories\n *\n * @see polymorphic-scope-approach-A-expansion.md — Phase 3\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 { ResourceSystemAccessMode } from '../resources/resources-config.shared.schemas';\nimport { createPolymorphicResourceConfigurations } from '../resources/utils/resource-polymorphism.factory';\nimport { CORE_APP_ROLES, CORE_ORG_ROLES } from '../security/authorizations/roles.shared.schemas';\nimport { BILLING_CHECKOUT_MAX_QUANTITY, BILLING_RESERVED_METADATA_KEY_PREFIX, ReferralStatus } from './billing-enums.shared.schemas';\nimport { ReferredRewardSchema } from './referral-reward.shared.schemas';\nimport { billingAccountsPolymorphicDeclaration } from './billing-account.shared.schemas';\nimport { BillingStateResponseSchema } from './billing-types.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 BillingAccount_Operations {\n  /** Create a Stripe Checkout Session for the user to complete payment */\n  OPEN_CHECKOUT = 'open_checkout',\n  /** Open the Stripe Customer Portal for self-service management */\n  OPEN_PORTAL = 'open_portal',\n  /** Fetch aggregated billing state (account, subscription, products, prices, credit pools) */\n  GET_STATE = 'get_state',\n  /**\n   * Redeem another account's referral code (#1802). Only a new customer may: an account that has never\n   * subscribed, is not already referred, and is not the referrer.\n   */\n  REDEEM_REFERRAL = 'redeem_referral',\n}\n\n// ── Request DTOs ─────────────────────────────────────────────────────\n\n/** Request DTO for OPEN_CHECKOUT. Trial duration is server-owned product/application policy, never a payer option. */\nexport const BillingAccount_OpenCheckoutRequestDto = z.object({\n  productKey: z.string().min(1).describe(\"The key of the product to buy. It must be available for purchase and offered to this account's scope.\"),\n  priceId: z.string().min(1).describe(\"The id of the price to buy the product at. It must be a price of that product.\"),\n  successUrl: z.url().describe(\"Where the billing provider sends the customer after a completed checkout.\"),\n  cancelUrl: z.url().describe(\"Where the billing provider sends the customer if they leave checkout without paying.\"),\n  /**\n   * Bounded by the same constant the webhook consumer honours. An unbounded quantity here would be\n   * billed by the provider and then refused on the way back in, charging the customer for credits\n   * that never arrive.\n   */\n  quantity: z.number().int().min(1).max(BILLING_CHECKOUT_MAX_QUANTITY).default(1).describe(\"How many units to buy, such as seats or credit packs. Defaults to 1.\"),\n  promotionCode: z.string().optional().describe(\"A promotion code to apply. It is checked before checkout opens, and refused when it is unknown, inactive, outside its validity dates, used up, not valid for this product, or not set up with the billing provider. The checkout page accepts no code of its own.\"),\n  /**\n   * Caller-supplied tags mirrored to the provider for the application's own analytics or\n   * reconciliation. They carry NO authority.\n   *\n   * Keys in the framework-reserved namespace are REFUSED here rather than silently dropped: the\n   * caller is trying to write into the namespace that decides which billing account gets credited\n   * and by how much, and an app developer who typed a reserved key deserves to be told, not to\n   * watch their tag vanish. Refusal at the DTO is the loud, outermost half of the boundary; the\n   * builder's write-reserved-last ordering and the consumer's read-only-reserved rule are the two\n   * structural halves. See {@link BILLING_RESERVED_METADATA_KEY_PREFIX}.\n   *\n   * The refinement sits on the KEY schema, not on the record: it keeps the DTO a plain `ZodRecord`\n   * for the OpenAPI projector and the request-validation pipeline, where a wrapping effect would\n   * change the node type every consumer of this DTO narrows on.\n   */\n  metadata: z\n    .record(\n      z.string().refine(\n        (key) => !key.startsWith(BILLING_RESERVED_METADATA_KEY_PREFIX),\n        `Metadata keys starting with \"${BILLING_RESERVED_METADATA_KEY_PREFIX}\" are reserved by the framework and cannot be supplied by the caller`,\n      ),\n      z.string(),\n    )\n    .optional(),\n});\n\n/** Request DTO for REDEEM_REFERRAL (#1802). */\nexport const BillingAccount_RedeemReferralRequestDto = z.strictObject({\n  referralCode: z.string().trim().min(1).max(64).describe('The referral code to redeem, as the referrer shared it.'),\n});\n\n/** Request DTO for OPEN_PORTAL operation */\nexport const BillingAccount_OpenPortalRequestDto = z.object({\n  returnUrl: z.url().describe('Absolute URL the billing portal sends the customer back to when they leave it.'),\n});\n\n// =============================================================================\n// POLYMORPHIC FACTORY — 2 variants (org, user)\n// =============================================================================\n\n/**\n * Polymorphic factory map for billing accounts.\n * Spread into `coreShared_ResourcesConfigurations_FactoryMap`:\n *   ...billingAccountsPolymorphicFactories\n *\n * Produces entries for:\n *   - organizationBillingAccounts\n *   - userBillingAccounts\n */\nexport const billingAccountsPolymorphicFactories = createPolymorphicResourceConfigurations(\n  billingAccountsPolymorphicDeclaration,\n  {\n    isSystemResource: true,\n    // System-context CREATE opt-in (fail-closed default is FORBIDDEN). The billing\n    // account is auto-created by `BillingStateBackendService.getState()` on first\n    // access via `SystemAccessBackendService.createAsSystem` — a trusted in-process\n    // write with no HTTP surface and no request context to seed the scope FK. That\n    // path relocates the ACL onto the billing service (which has already resolved\n    // the scope) and injects the scope FK (`organizationId` / `userId`) through the\n    // execution context map. Resource-level and shared by BOTH scope variants\n    // (org + user) per the polymorphic-resource contract on ResourceSystemAccessPolicy.\n    systemAccessPolicy: {\n      // Subject-export disclosure. The subject's own billing account. 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      exportSubject: ResourceSystemAccessMode.ALLOWED,\n      create: ResourceSystemAccessMode.ALLOWED,\n      // System-context LIST opt-in. Subject erasure must enumerate the erased person's billing\n      // accounts to reach their provider customer (cancel subscriptions, anonymize, detach payment\n      // methods). That runs with no request context — the subject is being erased — so it reads\n      // through `SystemAccessBackendService.listAsSystem`, which is fail-closed and refuses a\n      // resource that has not opted in here.\n      //\n      // Safe to grant: LIST is the READ side, and the erasure path filters by the subject's own\n      // scope FK. The default LIST variant is API_CALL, so it resolves through\n      // `getServiceOperationPathDefault` — a REPOSITORY_ONLY-only LIST would pass this grant and\n      // then fail to resolve at erasure time, which is the failure mode this comment exists to\n      // stop someone from reintroducing.\n      list: ResourceSystemAccessMode.ALLOWED,\n    },\n    portabilityPolicy: { defaultProvenance: DataPortabilityProvenance.OBSERVED },\n\n    /**\n     * Subject erasure RETAINS this row and scrubs the provider customer id.\n *\n * The financial record is kept for the tax/audit obligation this family exists to serve, and — as the\n * family's authoring rule states — erasure scrubs the linked USER rather than these rows, because the\n * person is a foreign key. `providerCustomerId` is the exception the rule does not cover: it is a stable\n * handle that re-identifies the person INSIDE the payment provider, so it is personal data this row holds.\n * It takes `REMOVE`; everything else is retained.\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    customOperation: BillingAccount_Operations,\n    coreOperations: [\n      CoreResourceOperation.READ,\n      CoreResourceOperation.LIST,\n      CoreResourceOperation.CREATE,\n      CoreResourceOperation.UPDATE,\n      CoreResourceOperation.DELETE,\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: the billing account is a user-facing record (Settings Hub → Billing →\n          // Account, and the resource presets' LIST/READ views). REPOSITORY_ONLY would strip\n          // the op from the frontend registry and register no HTTP route. Writes (auto-create\n          // + webhook sync) are INTERNAL_CALL — run through the service pipeline, no HTTP surface.\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.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.MEDIUM,\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.MEDIUM,\n        }],\n      },\n      [CoreResourceOperation.DELETE]: {\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.CRITICAL,\n        }],\n      },\n      [BillingAccount_Operations.OPEN_CHECKOUT]: {\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.HIGH,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: BillingAccount_OpenCheckoutRequestDto,\n          // Borrows UPDATE for its route/verb but returns the provider checkout\n          // session, NOT the billing-account resource. Without this the DTO builder\n          // would validate the service output against the resource schema and 500.\n          customResponseDto: z.object({\n            url: z.url().describe(\"The billing provider's hosted checkout page. Send the customer there to pay.\"),\n            sessionId: z.string().describe(\"The billing provider's id for this checkout session.\"),\n          }),\n        }],\n      },\n      /*\n       * #1802 — the account that was referred redeems the code. Refusals are the ones a person can act on:\n       * an unusable code, and an account that cannot be referred. The rewards are the referrer's policy,\n       * copied when the code was issued, and are reported back so the purchase screen can show them.\n       */\n      [BillingAccount_Operations.REDEEM_REFERRAL]: {\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.MEDIUM,\n          resourceOperationLike: CoreResourceOperation.UPDATE,\n          requestDto: BillingAccount_RedeemReferralRequestDto,\n          // Returns the redemption, not the billing account.\n          customResponseDto: z.object({\n            referralId: z.string().describe('The id of the referral that was redeemed.'),\n            status: z.enum(ReferralStatus).systemEnum('ReferralStatus').describe('`accepted`: the account is now the referred side, and the rewards are granted when it pays its first invoice.'),\n            referredReward: ReferredRewardSchema.optional().describe('What this account receives. Absent when the referral gives the referred side nothing.'),\n          }),\n        }],\n      },\n      [BillingAccount_Operations.OPEN_PORTAL]: {\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          resourceOperationLike: CoreResourceOperation.READ,\n          requestDto: BillingAccount_OpenPortalRequestDto,\n          // Borrows READ for its route/verb but returns the provider portal\n          // redirect URL, NOT the billing-account resource.\n          customResponseDto: z.object({\n            url: z.url().describe(\"The billing provider's customer portal, where the customer manages their billing. Send the customer there; the portal links back to `returnUrl`.\"),\n          }),\n        }],\n      },\n      [BillingAccount_Operations.GET_STATE]: {\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          resourceOperationLike: CoreResourceOperation.COUNT,\n          // Borrows COUNT for its route/verb but returns the aggregated billing\n          // state bundle, NOT a `{ count }`. Without this the DTO builder would\n          // assign the COUNT default envelope and the service output would fail\n          // `transformOutput`'s `internalDto.parse` → HTTP 500.\n          customResponseDto: BillingStateResponseSchema,\n        }],\n      },\n    },\n  },\n);\n"]}

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

@@ -1 +1 @@
-{"version":3,"file":"billing-account.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/billing-account.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAErE,OAAO,EAA6B,KAAK,4BAA4B,EAAE,MAAM,kDAAkD,CAAC;AAShI;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,4BAA4B,EAGhE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,EAAE,oBAAoB,EAGzD,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,uCAAuC,EAAE,oBAAoB,EAWzE,CAAC;AAMF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;iBAkDnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAM1E;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC;;;;;;;;kBAMhD,CAAC;AAMH,eAAO,MAAM,oBAAoB;;;;;;;;iBAA2B,CAAC;AAC7D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"billing-account.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/billing-account.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAErE,OAAO,EAA6B,KAAK,4BAA4B,EAAE,MAAM,kDAAkD,CAAC;AAShI;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,4BAA4B,EAGhE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,EAAE,oBAAoB,EAGzD,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,uCAAuC,EAAE,oBAAoB,EAWzE,CAAC;AAMF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;iBAkDnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAM1E;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC;;;;;;;;kBAMhD,CAAC;AAMH,eAAO,MAAM,oBAAoB;;;;;;;;iBAA2B,CAAC;AAC7D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

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

@@ -112,7 +112,7 @@ export const BillingAccountBaseSchema = z.object({
     /** Which provider (e.g., 'stripe') */
     providerRef: z.string().optional().isBackendOnly(),
     /** Status */
-    isActive: z.boolean().default(true).isDBIndexed().isSummaryField(),
+    isActive: z.boolean().default(true).isDBIndexed().isSummaryField().describe("Whether the account is active. It becomes `false` when the customer is deleted at the billing provider, and an inactive account is skipped when every account's features are recomputed."),
     /**
      * Open key-value bag for operational tagging (cost-centre, campaign ref, internal correlation id).
      *
@@ -132,7 +132,7 @@ export const BillingAccountBaseSchema = z.object({
      * hide/freeze to become separable from scrub — a real capability change with no current consumer.
      * Revisit only if an app is found using the bag this way.
      */
-    metadata: z.record(z.string(), z.string()).optional(),
+    metadata: z.record(z.string(), z.string()).optional().describe("String tags the application's own code may attach to the account. Do not store personal data here: this record is kept when its owner is erased."),
     createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
     updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
 });

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

@@ -1 +1 @@
-{"version":3,"file":"billing-account.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/billing-account.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Billing Account Schema (Shared) — Polymorphic\n *\n * BillingAccount is the PURE SCOPE BRIDGE between a Wildo entity and the billing provider.\n *\n * POLYMORPHIC EXPANSION: The base schema does NOT contain identity scope fields\n * (organizationId, userId). These are injected per variant by\n * `declarePolymorphicSchemas()`, producing 2 concrete resources:\n *   - organizationBillingAccounts  (with organizationId)\n *   - userBillingAccounts          (with userId)\n *\n * DELEGATION PRINCIPLE: All customer details (contact info, billing address, tax IDs,\n * payment methods) are managed by the provider. BillingAccount stores ONLY:\n * 1. The provider reference (which provider customer this maps to)\n * 2. Status\n * The scope reference is the injected identity FK.\n *\n * @see polymorphic-scope-approach-A-expansion.md\n * @see billing-and-features-system.md §6.1 (Core Design)\n */\n\nimport { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport type { PolymorphicFkVariant } from '@wildo-ai/zod-decorators';\nimport { CoreResourceType, coreResourceShared_FieldIdentifier } from '../resources/resources.shared.core.definitions';\nimport { declarePolymorphicSchemas, type PolymorphicVariantDefinition } from '../resources/utils/resource-polymorphism.schemas';\nimport { BillingScopeType } from './billing-enums.shared.schemas';\nimport { RedactionType } from '../compliance/privacy/redaction.shared.schemas';\nimport { addImpersonalizeWith } from '@wildo-ai/zod-decorators';\n\n// =============================================================================\n// SHARED VARIANT DEFINITIONS\n// =============================================================================\n\n/**\n * The 2 billing scope variants — shared across BillingAccounts, Subscriptions, and children.\n * Centralised here to avoid repetition (DX concern from plan remarks #1).\n */\nexport const BILLING_SCOPE_VARIANTS: PolymorphicVariantDefinition[] = [\n  { parentResourceType: CoreResourceType.ORGANIZATIONS, parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS], isPrimaryScope: true },\n  { parentResourceType: CoreResourceType.USERS,         parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.USERS],         isPrimaryScope: true },\n];\n\n/**\n * FK variant definitions for child resources referencing polymorphic billing accounts.\n * Used on `billingAccountId` fields as: `.isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS })`\n *\n * This tells the polymorphic engine to rename `billingAccountId` per variant:\n *   - organizations → `organizationBillingAccountId`\n *   - users → `userBillingAccountId`\n */\nexport const BILLING_SCOPE_FK_VARIANTS: PolymorphicFkVariant[] = BILLING_SCOPE_VARIANTS.map(v => ({\n  parentResourceType: v.parentResourceType,\n  parentFieldIdentifier: v.parentFieldIdentifier,\n}));\n\n/**\n * FK variant definitions for a SHARED-FIELD DISCRIMINATED polymorphic\n * billing-account FK — e.g. a referral's `referrerBillingAccountId`, a single\n * column on the flat `referrals` resource that points at EITHER a user OR an\n * organization billing account, with the branch chosen PER RECORD by a sibling\n * `*ScopeType` field.\n *\n * Same scope branches as {@link BILLING_SCOPE_FK_VARIANTS}, but each variant\n * additionally carries the `discriminatorValue` ({@link BillingScopeType}) that\n * the holder record's discriminator field uses to select the branch. Declare as:\n *\n * ```ts\n * referrerBillingAccountId: z.string().min(1).isForeignKey({\n *   polymorphicVariants: BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS,\n *   polymorphicDiscriminatorField: 'referrerScopeType',\n * })\n * ```\n *\n * Contrast with {@link BILLING_SCOPE_FK_VARIANTS} (rename-only, used when the\n * HOLDER is itself polymorphically expanded). The branch TARGET is resolved at\n * runtime via the scope bridge: `discriminatorValue` selects the variant, whose\n * `parentResourceType` scope root matches the branch's `resourcePrimaryScope`.\n */\nexport const BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS: PolymorphicFkVariant[] = [\n  {\n    parentResourceType: CoreResourceType.ORGANIZATIONS,\n    parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS],\n    discriminatorValue: BillingScopeType.ORGANIZATIONS,\n  },\n  {\n    parentResourceType: CoreResourceType.USERS,\n    parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.USERS],\n    discriminatorValue: BillingScopeType.USER_SELF,\n  },\n];\n\n// =============================================================================\n// BASE SCHEMA\n// =============================================================================\n\n/**\n * BillingAccount base schema — NO identity scope fields.\n * The polymorphic declaration injects the parent FK (organizationId / userId)\n * automatically per variant.\n */\nexport const BillingAccountBaseSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /** Provider sync - the ONLY provider-side reference we store */\n  // ── FINANCIAL, and declared on the SHARED base rather than per scope variant ──\n  //\n  // This family is polymorphic: `userBillingAccounts` holds a person's billing relationship,\n  // `organizationBillingAccounts` a company's, and both are built from this one schema. A category\n  // declared here therefore reaches both, and that is the direction to err in — an organization on a\n  // single-seat plan is one person, and the framework cannot tell which. Declaring only on a\n  // hypothetical user-only variant would UNDER-report, which is the silent failure a notice must\n  // never make; declaring on both at worst tells a reader the operator holds financial data, which\n  // it does. The same note applies to the invoice, usage, credit-pool and subscription siblings.\n  // REMOVE on erasure. This is the person's identifier AT THE PAYMENT PROVIDER — a stable handle that\n  // re-identifies them in a system we do not own, which is personal data this row HOLDS rather than a\n  // link it merely carries. The provider-side customer is retired by the billing subject-erasure\n  // external effect, so keeping the id afterwards would leave a dangling pointer at a deleted person.\n  // Clearable: the field is `.optional()`, so REMOVE resolves to a removed key rather than a rejected null.\n  providerCustomerId: addImpersonalizeWith(\n    z.string().optional().isBackendOnly().dataCategories(PersonalDataCategory.FINANCIAL),\n    RedactionType.REMOVE,\n  ),\n  /** Which provider (e.g., 'stripe') */\n  providerRef: z.string().optional().isBackendOnly(),\n\n  /** Status */\n  isActive: z.boolean().default(true).isDBIndexed().isSummaryField(),\n\n  /**\n   * Open key-value bag for operational tagging (cost-centre, campaign ref, internal correlation id).\n   *\n   * ⚠️ **AUTHORING RULE — never store personal data here.** This row is RETAINED when its subject is\n   * erased: the billing-retention decision keeps the financial record for tax/audit obligations, and\n   * subject erasure scrubs the linked USER rather than these rows, because a billing row holds no\n   * personal data of its own — the person is a foreign key. An open bag is the one place that\n   * assumption can be broken by an app author, and nothing would catch it: the erasure scrub is\n   * field-directed (`.impersonalizeWith()`), and it cannot reach inside an arbitrary record whose\n   * keys it does not know.\n   *\n   * Concretely: no names, emails, phone numbers, addresses, free-text notes about a person, or\n   * anything else that identifies one. Personal data written here SURVIVES an erasure — a compliance\n   * breach that the retained label makes look intentional.\n   *\n   * Enforcement is deliberately NOT built (Q3, 2026-07-31): scrubbing these rows would require\n   * hide/freeze to become separable from scrub — a real capability change with no current consumer.\n   * Revisit only if an app is found using the bag this way.\n   */\n  metadata: z.record(z.string(), z.string()).optional(),\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type BillingAccountBase = z.infer<typeof BillingAccountBaseSchema>;\n\n// =============================================================================\n// POLYMORPHIC DECLARATION\n// =============================================================================\n\n/**\n * Polymorphic declaration for BillingAccounts.\n * Produces 2 variants:\n *   - organizations  → organizationBillingAccounts  (organizationId injected)\n *   - users          → userBillingAccounts          (userId injected)\n */\nexport const billingAccountsPolymorphicDeclaration = declarePolymorphicSchemas({\n  baseResourceType: 'billingAccounts',\n  baseFieldIdentifier: 'billingAccountId',\n  baseEnumKey: 'BILLING_ACCOUNTS',\n  baseSchema: BillingAccountBaseSchema,\n  variants: BILLING_SCOPE_VARIANTS,\n});\n\n// =============================================================================\n// EXPORTED SCHEMA & TYPE\n// =============================================================================\n\nexport const BillingAccountSchema = BillingAccountBaseSchema;\nexport type BillingAccount = z.infer<typeof BillingAccountBaseSchema>;\n"]}
+{"version":3,"file":"billing-account.shared.schemas.js","sourceRoot":"","sources":["../../../src/billing/billing-account.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Billing Account Schema (Shared) — Polymorphic\n *\n * BillingAccount is the PURE SCOPE BRIDGE between a Wildo entity and the billing provider.\n *\n * POLYMORPHIC EXPANSION: The base schema does NOT contain identity scope fields\n * (organizationId, userId). These are injected per variant by\n * `declarePolymorphicSchemas()`, producing 2 concrete resources:\n *   - organizationBillingAccounts  (with organizationId)\n *   - userBillingAccounts          (with userId)\n *\n * DELEGATION PRINCIPLE: All customer details (contact info, billing address, tax IDs,\n * payment methods) are managed by the provider. BillingAccount stores ONLY:\n * 1. The provider reference (which provider customer this maps to)\n * 2. Status\n * The scope reference is the injected identity FK.\n *\n * @see polymorphic-scope-approach-A-expansion.md\n * @see billing-and-features-system.md §6.1 (Core Design)\n */\n\nimport { z } from 'zod';\nimport { PersonalDataCategory } from '../compliance/privacy/personal-data-category.shared.schemas';\nimport type { PolymorphicFkVariant } from '@wildo-ai/zod-decorators';\nimport { CoreResourceType, coreResourceShared_FieldIdentifier } from '../resources/resources.shared.core.definitions';\nimport { declarePolymorphicSchemas, type PolymorphicVariantDefinition } from '../resources/utils/resource-polymorphism.schemas';\nimport { BillingScopeType } from './billing-enums.shared.schemas';\nimport { RedactionType } from '../compliance/privacy/redaction.shared.schemas';\nimport { addImpersonalizeWith } from '@wildo-ai/zod-decorators';\n\n// =============================================================================\n// SHARED VARIANT DEFINITIONS\n// =============================================================================\n\n/**\n * The 2 billing scope variants — shared across BillingAccounts, Subscriptions, and children.\n * Centralised here to avoid repetition (DX concern from plan remarks #1).\n */\nexport const BILLING_SCOPE_VARIANTS: PolymorphicVariantDefinition[] = [\n  { parentResourceType: CoreResourceType.ORGANIZATIONS, parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS], isPrimaryScope: true },\n  { parentResourceType: CoreResourceType.USERS,         parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.USERS],         isPrimaryScope: true },\n];\n\n/**\n * FK variant definitions for child resources referencing polymorphic billing accounts.\n * Used on `billingAccountId` fields as: `.isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS })`\n *\n * This tells the polymorphic engine to rename `billingAccountId` per variant:\n *   - organizations → `organizationBillingAccountId`\n *   - users → `userBillingAccountId`\n */\nexport const BILLING_SCOPE_FK_VARIANTS: PolymorphicFkVariant[] = BILLING_SCOPE_VARIANTS.map(v => ({\n  parentResourceType: v.parentResourceType,\n  parentFieldIdentifier: v.parentFieldIdentifier,\n}));\n\n/**\n * FK variant definitions for a SHARED-FIELD DISCRIMINATED polymorphic\n * billing-account FK — e.g. a referral's `referrerBillingAccountId`, a single\n * column on the flat `referrals` resource that points at EITHER a user OR an\n * organization billing account, with the branch chosen PER RECORD by a sibling\n * `*ScopeType` field.\n *\n * Same scope branches as {@link BILLING_SCOPE_FK_VARIANTS}, but each variant\n * additionally carries the `discriminatorValue` ({@link BillingScopeType}) that\n * the holder record's discriminator field uses to select the branch. Declare as:\n *\n * ```ts\n * referrerBillingAccountId: z.string().min(1).isForeignKey({\n *   polymorphicVariants: BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS,\n *   polymorphicDiscriminatorField: 'referrerScopeType',\n * })\n * ```\n *\n * Contrast with {@link BILLING_SCOPE_FK_VARIANTS} (rename-only, used when the\n * HOLDER is itself polymorphically expanded). The branch TARGET is resolved at\n * runtime via the scope bridge: `discriminatorValue` selects the variant, whose\n * `parentResourceType` scope root matches the branch's `resourcePrimaryScope`.\n */\nexport const BILLING_SCOPE_DISCRIMINATED_FK_VARIANTS: PolymorphicFkVariant[] = [\n  {\n    parentResourceType: CoreResourceType.ORGANIZATIONS,\n    parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS],\n    discriminatorValue: BillingScopeType.ORGANIZATIONS,\n  },\n  {\n    parentResourceType: CoreResourceType.USERS,\n    parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.USERS],\n    discriminatorValue: BillingScopeType.USER_SELF,\n  },\n];\n\n// =============================================================================\n// BASE SCHEMA\n// =============================================================================\n\n/**\n * BillingAccount base schema — NO identity scope fields.\n * The polymorphic declaration injects the parent FK (organizationId / userId)\n * automatically per variant.\n */\nexport const BillingAccountBaseSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /** Provider sync - the ONLY provider-side reference we store */\n  // ── FINANCIAL, and declared on the SHARED base rather than per scope variant ──\n  //\n  // This family is polymorphic: `userBillingAccounts` holds a person's billing relationship,\n  // `organizationBillingAccounts` a company's, and both are built from this one schema. A category\n  // declared here therefore reaches both, and that is the direction to err in — an organization on a\n  // single-seat plan is one person, and the framework cannot tell which. Declaring only on a\n  // hypothetical user-only variant would UNDER-report, which is the silent failure a notice must\n  // never make; declaring on both at worst tells a reader the operator holds financial data, which\n  // it does. The same note applies to the invoice, usage, credit-pool and subscription siblings.\n  // REMOVE on erasure. This is the person's identifier AT THE PAYMENT PROVIDER — a stable handle that\n  // re-identifies them in a system we do not own, which is personal data this row HOLDS rather than a\n  // link it merely carries. The provider-side customer is retired by the billing subject-erasure\n  // external effect, so keeping the id afterwards would leave a dangling pointer at a deleted person.\n  // Clearable: the field is `.optional()`, so REMOVE resolves to a removed key rather than a rejected null.\n  providerCustomerId: addImpersonalizeWith(\n    z.string().optional().isBackendOnly().dataCategories(PersonalDataCategory.FINANCIAL),\n    RedactionType.REMOVE,\n  ),\n  /** Which provider (e.g., 'stripe') */\n  providerRef: z.string().optional().isBackendOnly(),\n\n  /** Status */\n  isActive: z.boolean().default(true).isDBIndexed().isSummaryField().describe(\"Whether the account is active. It becomes `false` when the customer is deleted at the billing provider, and an inactive account is skipped when every account's features are recomputed.\"),\n\n  /**\n   * Open key-value bag for operational tagging (cost-centre, campaign ref, internal correlation id).\n   *\n   * ⚠️ **AUTHORING RULE — never store personal data here.** This row is RETAINED when its subject is\n   * erased: the billing-retention decision keeps the financial record for tax/audit obligations, and\n   * subject erasure scrubs the linked USER rather than these rows, because a billing row holds no\n   * personal data of its own — the person is a foreign key. An open bag is the one place that\n   * assumption can be broken by an app author, and nothing would catch it: the erasure scrub is\n   * field-directed (`.impersonalizeWith()`), and it cannot reach inside an arbitrary record whose\n   * keys it does not know.\n   *\n   * Concretely: no names, emails, phone numbers, addresses, free-text notes about a person, or\n   * anything else that identifies one. Personal data written here SURVIVES an erasure — a compliance\n   * breach that the retained label makes look intentional.\n   *\n   * Enforcement is deliberately NOT built (Q3, 2026-07-31): scrubbing these rows would require\n   * hide/freeze to become separable from scrub — a real capability change with no current consumer.\n   * Revisit only if an app is found using the bag this way.\n   */\n  metadata: z.record(z.string(), z.string()).optional().describe(\"String tags the application's own code may attach to the account. Do not store personal data here: this record is kept when its owner is erased.\"),\n  createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),\n});\nexport type BillingAccountBase = z.infer<typeof BillingAccountBaseSchema>;\n\n// =============================================================================\n// POLYMORPHIC DECLARATION\n// =============================================================================\n\n/**\n * Polymorphic declaration for BillingAccounts.\n * Produces 2 variants:\n *   - organizations  → organizationBillingAccounts  (organizationId injected)\n *   - users          → userBillingAccounts          (userId injected)\n */\nexport const billingAccountsPolymorphicDeclaration = declarePolymorphicSchemas({\n  baseResourceType: 'billingAccounts',\n  baseFieldIdentifier: 'billingAccountId',\n  baseEnumKey: 'BILLING_ACCOUNTS',\n  baseSchema: BillingAccountBaseSchema,\n  variants: BILLING_SCOPE_VARIANTS,\n});\n\n// =============================================================================\n// EXPORTED SCHEMA & TYPE\n// =============================================================================\n\nexport const BillingAccountSchema = BillingAccountBaseSchema;\nexport type BillingAccount = z.infer<typeof BillingAccountBaseSchema>;\n"]}

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

@@ -27,6 +27,31 @@ export declare const BillingConfigurationSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         defaultInitialBalance: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    referrals: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        referrerReward: z.ZodOptional<z.ZodObject<{
+            credits: z.ZodOptional<z.ZodNumber>;
+            creditPoolKey: z.ZodOptional<z.ZodString>;
+            featureKey: z.ZodOptional<z.ZodString>;
+            durationDays: z.ZodOptional<z.ZodNumber>;
+            percentOff: z.ZodOptional<z.ZodNumber>;
+            discountDuration: z.ZodOptional<z.ZodEnum<typeof import("./billing-enums.shared.schemas").PromotionDuration>>;
+            discountDurationInMonths: z.ZodOptional<z.ZodNumber>;
+            type: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodEnum<typeof import("./billing-enums.shared.schemas").ReferrerRewardType>>;
+        }, z.core.$strip>>;
+        referredReward: z.ZodOptional<z.ZodObject<{
+            trialExtensionDays: z.ZodOptional<z.ZodNumber>;
+            credits: z.ZodOptional<z.ZodNumber>;
+            creditPoolKey: z.ZodOptional<z.ZodString>;
+            featureKey: z.ZodOptional<z.ZodString>;
+            durationDays: z.ZodOptional<z.ZodNumber>;
+            percentOff: z.ZodOptional<z.ZodNumber>;
+            discountDuration: z.ZodOptional<z.ZodEnum<typeof import("./billing-enums.shared.schemas").PromotionDuration>>;
+            discountDurationInMonths: z.ZodOptional<z.ZodNumber>;
+            type: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodEnum<typeof import("./billing-enums.shared.schemas").ReferredRewardType>>;
+        }, z.core.$strip>>;
+        codeValidityDays: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
     defaultBehaviorPolicy: z.ZodDefault<z.ZodObject<{
         defaultTrialDays: z.ZodDefault<z.ZodNumber>;
         paymentGracePeriodDays: z.ZodDefault<z.ZodNumber>;

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

@@ -1 +1 @@
-{"version":3,"file":"billing-configuration.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/billing/billing-configuration.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACd,MAAM,gCAAgC,CAAC;AAExC,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;iBAsIrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC"}
+{"version":3,"file":"billing-configuration.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/billing-configuration.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACd,MAAM,gCAAgC,CAAC;AAGxC,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAyJrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC"}

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

@@ -11,6 +11,7 @@ import { z } from 'zod';
 import { CurrencySchema } from '@wildo-ai/zod-decorators';
 import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
 import { TaxCalculationMode, TaxDisplayMode, ProrationBehavior, BillingTiming, } from './billing-enums.shared.schemas.js';
+import { ReferredRewardSchema, ReferrerRewardSchema } from './referral-reward.shared.schemas.js';
 export const BillingConfigurationSchema = z.object({
     /** Master switch: is billing enabled for this app? */
     enabled: z.boolean().default(false),
@@ -105,6 +106,24 @@ export const BillingConfigurationSchema = z.object({
         enabled: true,
         defaultInitialBalance: 0,
     })),
+    /** @wildo_source:part:start saas.models.billing.referral-program facet:layer:shared facet:audience:app-developer */
+    /**
+     * The referral program (#1802): whether organizations may issue referral codes, and what each side
+     * receives when a referral converts (the referred account's first paid invoice).
+     *
+     * The rewards are copied onto each referral when its code is issued, so changing them here affects
+     * codes issued afterwards and never re-prices a referral already made. A reward's `featureKey` must
+     * name a registered boolean feature; startup WARNS about one that does not, like every other feature
+     * reference, and a feature nobody registered grants nothing.
+     */
+    referrals: z.object({
+        /** Off by default: issuing codes that promise rewards is a commercial decision the application makes. */
+        enabled: z.boolean().default(false).describe('Whether organizations may issue referral codes. Redeeming and converting codes already issued keeps working when this is turned off.'),
+        referrerReward: ReferrerRewardSchema.optional().describe('What the referrer receives when a referral converts. Absent means nothing.'),
+        referredReward: ReferredRewardSchema.optional().describe('What the referred account receives. Absent means nothing.'),
+        codeValidityDays: z.number().int().min(1).default(30).describe('How many days a referral code can be redeemed after it is issued. Defaults to 30.'),
+    }).default(() => ({ enabled: false, codeValidityDays: 30 })),
+    /** @wildo_source:part:end saas.models.billing.referral-program */
     /** Global billing policy defaults (overridden by ProductBehaviorPolicy per product) */
     defaultBehaviorPolicy: z.object({
         /** Default trial days for new subscriptions (0 = no trial) */

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

@@ -1 +1 @@
-{"version":3,"file":"billing-configuration.shared.schemas.js","sourceRoot":"","sources":["../../../../src/billing/billing-configuration.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Billing Configuration Schema (Shared)\n *\n * Top-level billing configuration that custom apps provide at startup.\n * Controls: provider selection, currency, tax policy, enabled scopes,\n * and default behavior policies.\n *\n * @see billing-and-features-system.md §6.7 (Billing Configuration)\n */\n\nimport { z } from 'zod';\nimport { CurrencySchema } from '@wildo-ai/zod-decorators';\nimport { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\nimport {\n  TaxCalculationMode,\n  TaxDisplayMode,\n  ProrationBehavior,\n  BillingTiming,\n} from './billing-enums.shared.schemas';\n\nexport const BillingConfigurationSchema = z.object({\n  /** Master switch: is billing enabled for this app? */\n  enabled: z.boolean().default(false),\n  /** Which billing provider to use (e.g., 'stripe') */\n  providerRef: z.string().optional(),\n\n  /*\n   * NO `webhooks` block. `path` and `signingSecretRef` were declared here and read by NOTHING —\n   * `signingSecretRef` had zero references outside its own declaration — and they were removed on\n   * 2026-09-08 (#408) rather than relabelled, because unlike the commercial-intent keys below they\n   * were not even an input to anything.\n   *\n   * The route and the signing secret both come from the provider module's `WEBHOOK_ORIGINATOR`\n   * contract: `buildWebhookEndpoints` mounts it at `/api/v1/webhooks/<provider>/billing`. That is\n   * the single authority, and `webhook-auto-controller.backend.service.ts` already recorded the\n   * same conclusion when endpoint-level path/secret extras were dropped as dead in the 2026-05-06\n   * reshape. This block was the copy that survived that sweep.\n   */\n\n  /**\n   * DECLARATION-ONLY (#408, 2026-09-08). Read by the application-creation commercial-model brief and\n   * by no runtime billing path: nothing validates a product's currency against these, and what\n   * reaches the provider is each price's own `currency`. Authoring them records the commercial\n   * intent a reviewer reads; it enforces nothing.\n   */\n  defaultCurrency: CurrencySchema.default('USD'),\n  /** DECLARATION-ONLY — see `defaultCurrency`. */\n  supportedCurrencies: z.array(CurrencySchema).default(['USD']),\n\n  /**\n   * Tax configuration — calculation is ALWAYS delegated to provider (Stripe Tax, etc.).\n   * We never calculate tax locally.\n   */\n  tax: z.object({\n    /**\n     * Whether the PROVIDER computes tax on a purchase. READ since 2026-09-08 (#408): the checkout\n     * path — the only production purchase route — sends `automaticTax` from this value.\n     *\n     * It reached nothing before that, so `PROVIDER_MANAGED` changed no behaviour and the provider\n     * account's own configuration silently decided. Enabling it changes invoice totals and the tax\n     * amounts persisted against them, which is why it is a decision an application makes rather\n     * than a default the framework picks.\n     */\n    calculationMode: z.enum(TaxCalculationMode).default(TaxCalculationMode.DISABLED),\n\n    /**\n     * How prices are DISPLAYED to users (does not affect provider calculation).\n     * - 'exclusive': Prices shown excluding tax (HT / ex-VAT). Tax added at checkout.\n     *   Common for B2B. Shows \"$49/mo\" and tax is added separately.\n     * - 'inclusive': Prices shown including tax (TTC / inc-VAT). Tax is embedded.\n     *   Common for consumer-facing. Shows \"€49/mo TTC\" and tax is extracted at checkout.\n     *\n     * DECLARATIVE ONLY: nothing reads this value. It is not an application-wide default that\n     * `product.taxDisplayMode` and `price.taxBehavior` override, because there is no resolution\n     * chain between the three. What reaches the billing provider is each price's own\n     * `taxBehavior`, and only that.\n     */\n    defaultDisplayMode: z.enum(TaxDisplayMode).default(TaxDisplayMode.EXCLUSIVE),\n  }).default(() => ({\n    calculationMode: TaxCalculationMode.DISABLED,\n    defaultDisplayMode: TaxDisplayMode.EXCLUSIVE,\n  })),\n\n  /**\n   * Which scopes can have billing accounts (default: ORGANIZATIONS only).\n   * Can be extended to include USER_SELF (personal billing).\n   */\n  enabledScopes: z.array(z.enum(ResourcePrimaryScope)).default([ResourcePrimaryScope.ORGANIZATIONS]),\n\n  /**\n   * Promotions configuration.\n   * Controls whether the promotions subsystem is active.\n   */\n  promotions: z.object({\n    /**\n     * DECLARATION-ONLY (#408, 2026-09-08), and the sharpest of them: the promotions subsystem runs\n     * UNCONDITIONALLY. Promotion codes are applied at `billing-account.mutations` and resolved in\n     * `billing-state`, neither of which consults this flag — so setting it `false` disables\n     * nothing, which is a stronger statement than \"is not read\".\n     */\n    enabled: z.boolean().default(true),\n  }).default(() => ({\n    enabled: true,\n  })),\n\n  /**\n   * Credit pool configuration.\n   * Controls whether credit pools are enabled and defines default pool behavior.\n   */\n  creditPools: z.object({\n    /**\n     * DECLARATION-ONLY (#408, 2026-09-08) — same shape as `promotions.enabled` above, and the same\n     * correction: credit pools run unconditionally in `billing-state`, so `false` disables nothing.\n     */\n    enabled: z.boolean().default(true),\n    /** Default initial balance for auto-created pools (default 0) */\n    defaultInitialBalance: z.number().min(0).default(0),\n  }).default(() => ({\n    enabled: true,\n    defaultInitialBalance: 0,\n  })),\n\n  /** Global billing policy defaults (overridden by ProductBehaviorPolicy per product) */\n  defaultBehaviorPolicy: z.object({\n    /** Default trial days for new subscriptions (0 = no trial) */\n    defaultTrialDays: z.number().min(0).default(0),\n    /**\n     * DECLARATION-ONLY (#408, 2026-09-08). Dunning — how long to wait and how often to retry after a\n     * failed payment — is configured at the PROVIDER, on its own schedule, and nothing here reaches\n     * it. Binding them would mean writing a provider's retry settings from application config, which\n     * is a different feature from reading a policy at a call site.\n     */\n    paymentGracePeriodDays: z.number().min(0).default(3),\n    /** DECLARATION-ONLY — see `paymentGracePeriodDays`. */\n    maxPaymentRetries: z.number().min(0).default(3),\n    /** Default proration when no product-specific policy. READ by the change-plan path. */\n    defaultProration: z.enum(ProrationBehavior).default(ProrationBehavior.CREATE_PRORATIONS),\n    /**\n     * Default cancellation timing when neither the caller nor the plan product names one.\n     *\n     * READ since 2026-09-08 (#408). It was dead until then, and it is bound rather than relabelled\n     * because — unlike its neighbours above — it needs no provider call at all: cancellation timing\n     * is resolved locally, so the only thing standing between this key and meaning something was a\n     * reader. The chain is caller → product `behaviorPolicy.cancellation.defaultBehavior` → this →\n     * period-end.\n     */\n    defaultCancellation: z.enum(BillingTiming).default(BillingTiming.AT_PERIOD_END),\n  }).default(() => ({\n    defaultTrialDays: 0,\n    paymentGracePeriodDays: 3,\n    maxPaymentRetries: 3,\n    defaultProration: ProrationBehavior.CREATE_PRORATIONS,\n    defaultCancellation: BillingTiming.AT_PERIOD_END,\n  })),\n});\nexport type BillingConfiguration = z.infer<typeof BillingConfigurationSchema>;\n"]}
+{"version":3,"file":"billing-configuration.shared.schemas.js","sourceRoot":"","sources":["../../../src/billing/billing-configuration.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Billing Configuration Schema (Shared)\n *\n * Top-level billing configuration that custom apps provide at startup.\n * Controls: provider selection, currency, tax policy, enabled scopes,\n * and default behavior policies.\n *\n * @see billing-and-features-system.md §6.7 (Billing Configuration)\n */\n\nimport { z } from 'zod';\nimport { CurrencySchema } from '@wildo-ai/zod-decorators';\nimport { ResourcePrimaryScope } from '../resources/resources.shared.schemas';\nimport {\n  TaxCalculationMode,\n  TaxDisplayMode,\n  ProrationBehavior,\n  BillingTiming,\n} from './billing-enums.shared.schemas';\nimport { ReferredRewardSchema, ReferrerRewardSchema } from './referral-reward.shared.schemas';\n\nexport const BillingConfigurationSchema = z.object({\n  /** Master switch: is billing enabled for this app? */\n  enabled: z.boolean().default(false),\n  /** Which billing provider to use (e.g., 'stripe') */\n  providerRef: z.string().optional(),\n\n  /*\n   * NO `webhooks` block. `path` and `signingSecretRef` were declared here and read by NOTHING —\n   * `signingSecretRef` had zero references outside its own declaration — and they were removed on\n   * 2026-09-08 (#408) rather than relabelled, because unlike the commercial-intent keys below they\n   * were not even an input to anything.\n   *\n   * The route and the signing secret both come from the provider module's `WEBHOOK_ORIGINATOR`\n   * contract: `buildWebhookEndpoints` mounts it at `/api/v1/webhooks/<provider>/billing`. That is\n   * the single authority, and `webhook-auto-controller.backend.service.ts` already recorded the\n   * same conclusion when endpoint-level path/secret extras were dropped as dead in the 2026-05-06\n   * reshape. This block was the copy that survived that sweep.\n   */\n\n  /**\n   * DECLARATION-ONLY (#408, 2026-09-08). Read by the application-creation commercial-model brief and\n   * by no runtime billing path: nothing validates a product's currency against these, and what\n   * reaches the provider is each price's own `currency`. Authoring them records the commercial\n   * intent a reviewer reads; it enforces nothing.\n   */\n  defaultCurrency: CurrencySchema.default('USD'),\n  /** DECLARATION-ONLY — see `defaultCurrency`. */\n  supportedCurrencies: z.array(CurrencySchema).default(['USD']),\n\n  /**\n   * Tax configuration — calculation is ALWAYS delegated to provider (Stripe Tax, etc.).\n   * We never calculate tax locally.\n   */\n  tax: z.object({\n    /**\n     * Whether the PROVIDER computes tax on a purchase. READ since 2026-09-08 (#408): the checkout\n     * path — the only production purchase route — sends `automaticTax` from this value.\n     *\n     * It reached nothing before that, so `PROVIDER_MANAGED` changed no behaviour and the provider\n     * account's own configuration silently decided. Enabling it changes invoice totals and the tax\n     * amounts persisted against them, which is why it is a decision an application makes rather\n     * than a default the framework picks.\n     */\n    calculationMode: z.enum(TaxCalculationMode).default(TaxCalculationMode.DISABLED),\n\n    /**\n     * How prices are DISPLAYED to users (does not affect provider calculation).\n     * - 'exclusive': Prices shown excluding tax (HT / ex-VAT). Tax added at checkout.\n     *   Common for B2B. Shows \"$49/mo\" and tax is added separately.\n     * - 'inclusive': Prices shown including tax (TTC / inc-VAT). Tax is embedded.\n     *   Common for consumer-facing. Shows \"€49/mo TTC\" and tax is extracted at checkout.\n     *\n     * DECLARATIVE ONLY: nothing reads this value. It is not an application-wide default that\n     * `product.taxDisplayMode` and `price.taxBehavior` override, because there is no resolution\n     * chain between the three. What reaches the billing provider is each price's own\n     * `taxBehavior`, and only that.\n     */\n    defaultDisplayMode: z.enum(TaxDisplayMode).default(TaxDisplayMode.EXCLUSIVE),\n  }).default(() => ({\n    calculationMode: TaxCalculationMode.DISABLED,\n    defaultDisplayMode: TaxDisplayMode.EXCLUSIVE,\n  })),\n\n  /**\n   * Which scopes can have billing accounts (default: ORGANIZATIONS only).\n   * Can be extended to include USER_SELF (personal billing).\n   */\n  enabledScopes: z.array(z.enum(ResourcePrimaryScope)).default([ResourcePrimaryScope.ORGANIZATIONS]),\n\n  /**\n   * Promotions configuration.\n   * Controls whether the promotions subsystem is active.\n   */\n  promotions: z.object({\n    /**\n     * DECLARATION-ONLY (#408, 2026-09-08), and the sharpest of them: the promotions subsystem runs\n     * UNCONDITIONALLY. Promotion codes are applied at `billing-account.mutations` and resolved in\n     * `billing-state`, neither of which consults this flag — so setting it `false` disables\n     * nothing, which is a stronger statement than \"is not read\".\n     */\n    enabled: z.boolean().default(true),\n  }).default(() => ({\n    enabled: true,\n  })),\n\n  /**\n   * Credit pool configuration.\n   * Controls whether credit pools are enabled and defines default pool behavior.\n   */\n  creditPools: z.object({\n    /**\n     * DECLARATION-ONLY (#408, 2026-09-08) — same shape as `promotions.enabled` above, and the same\n     * correction: credit pools run unconditionally in `billing-state`, so `false` disables nothing.\n     */\n    enabled: z.boolean().default(true),\n    /** Default initial balance for auto-created pools (default 0) */\n    defaultInitialBalance: z.number().min(0).default(0),\n  }).default(() => ({\n    enabled: true,\n    defaultInitialBalance: 0,\n  })),\n\n  /** @wildo_source:part:start saas.models.billing.referral-program facet:layer:shared facet:audience:app-developer */\n  /**\n   * The referral program (#1802): whether organizations may issue referral codes, and what each side\n   * receives when a referral converts (the referred account's first paid invoice).\n   *\n   * The rewards are copied onto each referral when its code is issued, so changing them here affects\n   * codes issued afterwards and never re-prices a referral already made. A reward's `featureKey` must\n   * name a registered boolean feature; startup WARNS about one that does not, like every other feature\n   * reference, and a feature nobody registered grants nothing.\n   */\n  referrals: z.object({\n    /** Off by default: issuing codes that promise rewards is a commercial decision the application makes. */\n    enabled: z.boolean().default(false).describe('Whether organizations may issue referral codes. Redeeming and converting codes already issued keeps working when this is turned off.'),\n    referrerReward: ReferrerRewardSchema.optional().describe('What the referrer receives when a referral converts. Absent means nothing.'),\n    referredReward: ReferredRewardSchema.optional().describe('What the referred account receives. Absent means nothing.'),\n    codeValidityDays: z.number().int().min(1).default(30).describe('How many days a referral code can be redeemed after it is issued. Defaults to 30.'),\n  }).default(() => ({ enabled: false, codeValidityDays: 30 })),\n  /** @wildo_source:part:end saas.models.billing.referral-program */\n\n  /** Global billing policy defaults (overridden by ProductBehaviorPolicy per product) */\n  defaultBehaviorPolicy: z.object({\n    /** Default trial days for new subscriptions (0 = no trial) */\n    defaultTrialDays: z.number().min(0).default(0),\n    /**\n     * DECLARATION-ONLY (#408, 2026-09-08). Dunning — how long to wait and how often to retry after a\n     * failed payment — is configured at the PROVIDER, on its own schedule, and nothing here reaches\n     * it. Binding them would mean writing a provider's retry settings from application config, which\n     * is a different feature from reading a policy at a call site.\n     */\n    paymentGracePeriodDays: z.number().min(0).default(3),\n    /** DECLARATION-ONLY — see `paymentGracePeriodDays`. */\n    maxPaymentRetries: z.number().min(0).default(3),\n    /** Default proration when no product-specific policy. READ by the change-plan path. */\n    defaultProration: z.enum(ProrationBehavior).default(ProrationBehavior.CREATE_PRORATIONS),\n    /**\n     * Default cancellation timing when neither the caller nor the plan product names one.\n     *\n     * READ since 2026-09-08 (#408). It was dead until then, and it is bound rather than relabelled\n     * because — unlike its neighbours above — it needs no provider call at all: cancellation timing\n     * is resolved locally, so the only thing standing between this key and meaning something was a\n     * reader. The chain is caller → product `behaviorPolicy.cancellation.defaultBehavior` → this →\n     * period-end.\n     */\n    defaultCancellation: z.enum(BillingTiming).default(BillingTiming.AT_PERIOD_END),\n  }).default(() => ({\n    defaultTrialDays: 0,\n    paymentGracePeriodDays: 3,\n    maxPaymentRetries: 3,\n    defaultProration: ProrationBehavior.CREATE_PRORATIONS,\n    defaultCancellation: BillingTiming.AT_PERIOD_END,\n  })),\n});\nexport type BillingConfiguration = z.infer<typeof BillingConfigurationSchema>;\n"]}