@wildo-ai/saas-models 1.0.1

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

@@ -0,0 +1,78 @@
+/**
+ * Billing Account Schema (Shared) — Polymorphic
+ *
+ * BillingAccount is the PURE SCOPE BRIDGE between a Wildo entity and the billing provider.
+ *
+ * POLYMORPHIC EXPANSION: The base schema does NOT contain identity scope fields
+ * (organizationId, userId). These are injected per variant by
+ * `declarePolymorphicSchemas()`, producing 2 concrete resources:
+ *   - organizationBillingAccounts  (with organizationId)
+ *   - userBillingAccounts          (with userId)
+ *
+ * DELEGATION PRINCIPLE: All customer details (contact info, billing address, tax IDs,
+ * payment methods) are managed by the provider. BillingAccount stores ONLY:
+ * 1. The provider reference (which provider customer this maps to)
+ * 2. Status
+ * The scope reference is the injected identity FK.
+ *
+ * @see polymorphic-scope-approach-A-expansion.md
+ * @see billing-and-features-system.md §6.1 (Core Design)
+ */
+import { z } from 'zod';
+import type { PolymorphicFkVariant } from '@wildo-ai/zod-decorators';
+import { type PolymorphicVariantDefinition } from '../resources/utils/resource-polymorphism.schemas.js';
+/**
+ * The 2 billing scope variants — shared across BillingAccounts, Subscriptions, and children.
+ * Centralised here to avoid repetition (DX concern from plan remarks #1).
+ */
+export declare const BILLING_SCOPE_VARIANTS: PolymorphicVariantDefinition[];
+/**
+ * FK variant definitions for child resources referencing polymorphic billing accounts.
+ * Used on `billingAccountId` fields as: `.isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS })`
+ *
+ * This tells the polymorphic engine to rename `billingAccountId` per variant:
+ *   - organizations → `organizationBillingAccountId`
+ *   - users → `userBillingAccountId`
+ */
+export declare const BILLING_SCOPE_FK_VARIANTS: PolymorphicFkVariant[];
+/**
+ * BillingAccount base schema — NO identity scope fields.
+ * The polymorphic declaration injects the parent FK (organizationId / userId)
+ * automatically per variant.
+ */
+export declare const BillingAccountBaseSchema: z.ZodObject<{
+    _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    providerCustomerId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
+    providerRef: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
+    isActive: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>;
+    updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>;
+}, z.core.$strip, core.$ZodObjectExtra>;
+export type BillingAccountBase = z.infer<typeof BillingAccountBaseSchema>;
+/**
+ * Polymorphic declaration for BillingAccounts.
+ * Produces 2 variants:
+ *   - organizations  → organizationBillingAccounts  (organizationId injected)
+ *   - users          → userBillingAccounts          (userId injected)
+ */
+export declare const billingAccountsPolymorphicDeclaration: import("../index.js").PolymorphicSchemaDeclaration<z.ZodObject<{
+    _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    providerCustomerId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
+    providerRef: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
+    isActive: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>;
+    updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>;
+}, z.core.$strip, core.$ZodObjectExtra>>;
+export declare const BillingAccountSchema: z.ZodObject<{
+    _id: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>;
+    providerCustomerId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
+    providerRef: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>;
+    isActive: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodBoolean>>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    createdAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>;
+    updatedAt: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodDate>>>;
+}, z.core.$strip, core.$ZodObjectExtra>;
+export type BillingAccount = z.infer<typeof BillingAccountBaseSchema>;
+//# sourceMappingURL=billing-account.shared.schemas.d.ts.map

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

@@ -0,0 +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;AACxB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAErE,OAAO,EAA6B,KAAK,4BAA4B,EAAE,MAAM,kDAAkD,CAAC;AAMhI;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,4BAA4B,EAGhE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,EAAE,oBAAoB,EAGzD,CAAC;AAMJ;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;uCAcnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAM1E;;;;;GAKG;AACH,eAAO,MAAM,qCAAqC;;;;;;;;wCAMhD,CAAC;AAMH,eAAO,MAAM,oBAAoB;;;;;;;;uCAA2B,CAAC;AAC7D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

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

@@ -0,0 +1,87 @@
+/**
+ * Billing Account Schema (Shared) — Polymorphic
+ *
+ * BillingAccount is the PURE SCOPE BRIDGE between a Wildo entity and the billing provider.
+ *
+ * POLYMORPHIC EXPANSION: The base schema does NOT contain identity scope fields
+ * (organizationId, userId). These are injected per variant by
+ * `declarePolymorphicSchemas()`, producing 2 concrete resources:
+ *   - organizationBillingAccounts  (with organizationId)
+ *   - userBillingAccounts          (with userId)
+ *
+ * DELEGATION PRINCIPLE: All customer details (contact info, billing address, tax IDs,
+ * payment methods) are managed by the provider. BillingAccount stores ONLY:
+ * 1. The provider reference (which provider customer this maps to)
+ * 2. Status
+ * The scope reference is the injected identity FK.
+ *
+ * @see polymorphic-scope-approach-A-expansion.md
+ * @see billing-and-features-system.md §6.1 (Core Design)
+ */
+import { z } from 'zod';
+import { CoreResourceType, coreResourceShared_FieldIdentifier } from '../resources/resources.shared.core.definitions.js';
+import { declarePolymorphicSchemas } from '../resources/utils/resource-polymorphism.schemas.js';
+// =============================================================================
+// SHARED VARIANT DEFINITIONS
+// =============================================================================
+/**
+ * The 2 billing scope variants — shared across BillingAccounts, Subscriptions, and children.
+ * Centralised here to avoid repetition (DX concern from plan remarks #1).
+ */
+export const BILLING_SCOPE_VARIANTS = [
+    { parentResourceType: CoreResourceType.ORGANIZATIONS, parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS], isPrimaryScope: true },
+    { parentResourceType: CoreResourceType.USERS, parentFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.USERS], isPrimaryScope: true },
+];
+/**
+ * FK variant definitions for child resources referencing polymorphic billing accounts.
+ * Used on `billingAccountId` fields as: `.isForeignKey({ polymorphicVariants: BILLING_SCOPE_FK_VARIANTS })`
+ *
+ * This tells the polymorphic engine to rename `billingAccountId` per variant:
+ *   - organizations → `organizationBillingAccountId`
+ *   - users → `userBillingAccountId`
+ */
+export const BILLING_SCOPE_FK_VARIANTS = BILLING_SCOPE_VARIANTS.map(v => ({
+    parentResourceType: v.parentResourceType,
+    parentFieldIdentifier: v.parentFieldIdentifier,
+}));
+// =============================================================================
+// BASE SCHEMA
+// =============================================================================
+/**
+ * BillingAccount base schema — NO identity scope fields.
+ * The polymorphic declaration injects the parent FK (organizationId / userId)
+ * automatically per variant.
+ */
+export const BillingAccountBaseSchema = z.object({
+    _id: z.string().min(1).isPrimaryKey().isSummaryField(),
+    /** Provider sync - the ONLY provider-side reference we store */
+    providerCustomerId: z.string().optional().isBackendOnly(),
+    /** Which provider (e.g., 'stripe') */
+    providerRef: z.string().optional().isBackendOnly(),
+    /** Status */
+    isActive: z.boolean().default(true).isDBIndexed().isSummaryField(),
+    metadata: z.record(z.string(), z.string()).optional(),
+    createdAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
+    updatedAt: z.date().default(() => new Date()).excludeFromCreate().excludeFromUpdate(),
+});
+// =============================================================================
+// POLYMORPHIC DECLARATION
+// =============================================================================
+/**
+ * Polymorphic declaration for BillingAccounts.
+ * Produces 2 variants:
+ *   - organizations  → organizationBillingAccounts  (organizationId injected)
+ *   - users          → userBillingAccounts          (userId injected)
+ */
+export const billingAccountsPolymorphicDeclaration = declarePolymorphicSchemas({
+    baseResourceType: 'billingAccounts',
+    baseFieldIdentifier: 'billingAccountId',
+    baseEnumKey: 'BILLING_ACCOUNTS',
+    baseSchema: BillingAccountBaseSchema,
+    variants: BILLING_SCOPE_VARIANTS,
+});
+// =============================================================================
+// EXPORTED SCHEMA & TYPE
+// =============================================================================
+export const BillingAccountSchema = BillingAccountBaseSchema;
+//# sourceMappingURL=billing-account.shared.schemas.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"billing-account.shared.schemas.js","sourceRoot":"","sources":["../../../src/billing/billing-account.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,gBAAgB,EAAE,kCAAkC,EAAE,MAAM,gDAAgD,CAAC;AACtH,OAAO,EAAE,yBAAyB,EAAqC,MAAM,kDAAkD,CAAC;AAEhI,gFAAgF;AAChF,6BAA6B;AAC7B,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAmC;IACpE,EAAE,kBAAkB,EAAE,gBAAgB,CAAC,aAAa,EAAE,qBAAqB,EAAE,kCAAkC,CAAC,gBAAgB,CAAC,aAAa,CAAC,EAAE,cAAc,EAAE,IAAI,EAAE;IACvK,EAAE,kBAAkB,EAAE,gBAAgB,CAAC,KAAK,EAAU,qBAAqB,EAAE,kCAAkC,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAU,cAAc,EAAE,IAAI,EAAE;CACxK,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAA2B,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAChG,kBAAkB,EAAE,CAAC,CAAC,kBAAkB;IACxC,qBAAqB,EAAE,CAAC,CAAC,qBAAqB;CAC/C,CAAC,CAAC,CAAC;AAEJ,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE;IAEtD,gEAAgE;IAChE,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE;IACzD,sCAAsC;IACtC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,aAAa,EAAE;IAElD,aAAa;IACb,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE;IAElE,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACrD,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IACrF,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;CACtF,CAAC,CAAC;AAGH,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAAG,yBAAyB,CAAC;IAC7E,gBAAgB,EAAE,iBAAiB;IACnC,mBAAmB,EAAE,kBAAkB;IACvC,WAAW,EAAE,kBAAkB;IAC/B,UAAU,EAAE,wBAAwB;IACpC,QAAQ,EAAE,sBAAsB;CACjC,CAAC,CAAC;AAEH,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEhF,MAAM,CAAC,MAAM,oBAAoB,GAAG,wBAAwB,CAAC"}

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

@@ -0,0 +1,43 @@
+/**
+ * Billing Configuration Schema (Shared)
+ *
+ * Top-level billing configuration that custom apps provide at startup.
+ * Controls: provider selection, currency, tax policy, enabled scopes,
+ * and default behavior policies.
+ *
+ * @see billing-and-features-system.md §6.7 (Billing Configuration)
+ */
+import { z } from 'zod';
+import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
+import { TaxCalculationMode, TaxDisplayMode, ProrationBehavior, BillingTiming } from './billing-enums.shared.schemas.js';
+export declare const BillingConfigurationSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    providerRef: z.ZodOptional<z.ZodString>;
+    webhooks: z.ZodOptional<z.ZodObject<{
+        path: z.ZodDefault<z.ZodString>;
+        signingSecretRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip, core.$ZodObjectExtra>>;
+    defaultCurrency: z.ZodDefault<z.ZodUnion<[z.ZodEnum<typeof import("@wildo-ai/zod-decorators").AvailableCurrency>, z.ZodString]>>;
+    supportedCurrencies: z.ZodDefault<z.ZodArray<z.ZodUnion<[z.ZodEnum<typeof import("@wildo-ai/zod-decorators").AvailableCurrency>, z.ZodString]>>>;
+    tax: z.ZodDefault<z.ZodObject<{
+        calculationMode: z.ZodDefault<z.ZodEnum<typeof TaxCalculationMode>>;
+        defaultDisplayMode: z.ZodDefault<z.ZodEnum<typeof TaxDisplayMode>>;
+    }, z.core.$strip, core.$ZodObjectExtra>>;
+    enabledScopes: z.ZodDefault<z.ZodArray<z.ZodEnum<typeof ResourcePrimaryScope>>>;
+    promotions: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip, core.$ZodObjectExtra>>;
+    creditPools: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        defaultInitialBalance: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip, core.$ZodObjectExtra>>;
+    defaultBehaviorPolicy: z.ZodDefault<z.ZodObject<{
+        defaultTrialDays: z.ZodDefault<z.ZodNumber>;
+        paymentGracePeriodDays: z.ZodDefault<z.ZodNumber>;
+        maxPaymentRetries: z.ZodDefault<z.ZodNumber>;
+        defaultProration: z.ZodDefault<z.ZodEnum<typeof ProrationBehavior>>;
+        defaultCancellation: z.ZodDefault<z.ZodEnum<typeof BillingTiming>>;
+    }, z.core.$strip, core.$ZodObjectExtra>>;
+}, z.core.$strip, core.$ZodObjectExtra>;
+export type BillingConfiguration = z.infer<typeof BillingConfigurationSchema>;
+//# sourceMappingURL=billing-configuration.shared.schemas.d.ts.map

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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;uCA6FrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC"}

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

@@ -0,0 +1,100 @@
+/**
+ * Billing Configuration Schema (Shared)
+ *
+ * Top-level billing configuration that custom apps provide at startup.
+ * Controls: provider selection, currency, tax policy, enabled scopes,
+ * and default behavior policies.
+ *
+ * @see billing-and-features-system.md §6.7 (Billing Configuration)
+ */
+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';
+export const BillingConfigurationSchema = z.object({
+    /** Master switch: is billing enabled for this app? */
+    enabled: z.boolean().default(false),
+    /** Which billing provider to use (e.g., 'stripe') */
+    providerRef: z.string().optional(),
+    /** Webhook configuration */
+    webhooks: z.object({
+        /** Path for billing webhook endpoint */
+        path: z.string().default('/api/v1/webhooks/billing'),
+        /** Reference to the webhook signing secret (resolved from secrets at runtime) */
+        signingSecretRef: z.string().optional(),
+    }).optional(),
+    /** Default ISO 4217 currency for new billing accounts / products */
+    defaultCurrency: CurrencySchema.default('USD'),
+    /** Supported currencies (for multi-currency apps) */
+    supportedCurrencies: z.array(CurrencySchema).default(['USD']),
+    /**
+     * Tax configuration — calculation is ALWAYS delegated to provider (Stripe Tax, etc.).
+     * We never calculate tax locally.
+     */
+    tax: z.object({
+        /** How the provider handles tax calculation */
+        calculationMode: z.enum(TaxCalculationMode).default(TaxCalculationMode.DISABLED),
+        /**
+         * How prices are DISPLAYED to users (does not affect provider calculation).
+         * - 'exclusive': Prices shown excluding tax (HT / ex-VAT). Tax added at checkout.
+         *   Common for B2B. Shows "$49/mo" and tax is added separately.
+         * - 'inclusive': Prices shown including tax (TTC / inc-VAT). Tax is embedded.
+         *   Common for consumer-facing. Shows "€49/mo TTC" and tax is extracted at checkout.
+         *
+         * Overridable per product (product.taxDisplayMode) and per price (price.taxBehavior).
+         */
+        defaultDisplayMode: z.enum(TaxDisplayMode).default(TaxDisplayMode.EXCLUSIVE),
+    }).default(() => ({
+        calculationMode: TaxCalculationMode.DISABLED,
+        defaultDisplayMode: TaxDisplayMode.EXCLUSIVE,
+    })),
+    /**
+     * Which scopes can have billing accounts (default: ORGANIZATIONS only).
+     * Can be extended to include USER_SELF (personal billing) and
+     * USER_SELF (personal billing).
+     */
+    enabledScopes: z.array(z.enum(ResourcePrimaryScope)).default([ResourcePrimaryScope.ORGANIZATIONS]),
+    /**
+     * Promotions configuration.
+     * Controls whether the promotions subsystem is active.
+     */
+    promotions: z.object({
+        /** Whether promotions/coupons are enabled */
+        enabled: z.boolean().default(true),
+    }).default(() => ({
+        enabled: true,
+    })),
+    /**
+     * Credit pool configuration.
+     * Controls whether credit pools are enabled and defines default pool behavior.
+     */
+    creditPools: z.object({
+        /** Whether credit pool functionality is enabled (auto-creation on CREDIT_PACK purchase) */
+        enabled: z.boolean().default(true),
+        /** Default initial balance for auto-created pools (default 0) */
+        defaultInitialBalance: z.number().min(0).default(0),
+    }).default(() => ({
+        enabled: true,
+        defaultInitialBalance: 0,
+    })),
+    /** Global billing policy defaults (overridden by ProductBehaviorPolicy per product) */
+    defaultBehaviorPolicy: z.object({
+        /** Default trial days for new subscriptions (0 = no trial) */
+        defaultTrialDays: z.number().min(0).default(0),
+        /** Grace period before marking subscription as past_due after failed payment */
+        paymentGracePeriodDays: z.number().min(0).default(3),
+        /** Maximum automatic payment retries before giving up */
+        maxPaymentRetries: z.number().min(0).default(3),
+        /** Default proration when no product-specific policy */
+        defaultProration: z.enum(ProrationBehavior).default(ProrationBehavior.CREATE_PRORATIONS),
+        /** Default cancellation behavior */
+        defaultCancellation: z.enum(BillingTiming).default(BillingTiming.AT_PERIOD_END),
+    }).default(() => ({
+        defaultTrialDays: 0,
+        paymentGracePeriodDays: 3,
+        maxPaymentRetries: 3,
+        defaultProration: ProrationBehavior.CREATE_PRORATIONS,
+        defaultCancellation: BillingTiming.AT_PERIOD_END,
+    })),
+});
+//# sourceMappingURL=billing-configuration.shared.schemas.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"billing-configuration.shared.schemas.js","sourceRoot":"","sources":["../../../src/billing/billing-configuration.shared.schemas.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,173 @@
+/**
+ * Billing Enums (Shared)
+ *
+ * All billing-system enums used across backend, frontend, and shared models.
+ * These supersede the legacy enums from billing.shared.schemas.ts.
+ *
+ * Enums shared with the standard billing interface (PricingModel, BillingInterval,
+ * TaxDisplayMode, SubscriptionStatus) are defined in @wildo-ai/external-connectors-models
+ * and re-exported here for convenience.
+ *
+ * @see billing-and-features-system.md §6 (Billing Schemas)
+ */
+export { PricingModel, BillingInterval, TaxDisplayMode, SubscriptionStatus } from '@wildo-ai/external-connectors-models';
+/**
+ * Product types available in the billing catalog.
+ *
+ * | Type        | Creates subscription? | Repeatable? | Grants features? | Usage tracked? |
+ * |-------------|----------------------|-------------|------------------|----------------|
+ * | PLAN        | Yes (exclusive)      | No (switch) | Yes              | No             |
+ * | ADDON       | Yes (stackable)      | No (toggle) | Yes              | No             |
+ * | METERED     | Yes                  | No          | Optional         | Yes            |
+ * | ONE_TIME    | No                   | No (once)   | Optional         | No             |
+ * | CREDIT_PACK | No                   | Yes         | No (credits)     | Credits-based  |
+ * | ITEM        | No                   | Yes         | Optional         | No             |
+ */
+export declare enum ProductType {
+    /** Subscription plan, mutually exclusive per billing account */
+    PLAN = "plan",
+    /** Optional subscription add-on, stackable on top of plan */
+    ADDON = "addon",
+    /** Usage-based subscription (consumption reported to provider) */
+    METERED = "metered",
+    /** Single purchase, once per billing account (e.g., setup fee, migration) */
+    ONE_TIME = "one_time",
+    /** Buy a pack of credits/tokens (repeatable, consumable over time) */
+    CREDIT_PACK = "credit_pack",
+    /** Purchasable item, repeatable (e.g., report generation, data export) */
+    ITEM = "item"
+}
+/**
+ * Limit grant mode: how this product's limits compose with other products.
+ * - SET: absolute value (replaces, used for PLAN base limits)
+ * - ADD: additive (stacks on top, used for ADDON bonus limits)
+ */
+export declare enum LimitGrantMode {
+    SET = "set",
+    ADD = "add"
+}
+/**
+ * Proration behavior for plan changes (upgrade/downgrade).
+ */
+export declare enum ProrationBehavior {
+    CREATE_PRORATIONS = "create_prorations",
+    NONE = "none",
+    ALWAYS_INVOICE = "always_invoice"
+}
+/**
+ * Billing timing: when to apply plan changes.
+ */
+export declare enum BillingTiming {
+    IMMEDIATE = "immediate",
+    AT_PERIOD_END = "at_period_end"
+}
+/**
+ * Metering aggregation window for usage records.
+ */
+export declare enum MeteringAggregationWindow {
+    PER_FLUSH = "per_flush",
+    PER_BILLING_PERIOD = "per_billing_period"
+}
+/**
+ * Usage aggregation type for metered prices.
+ */
+export declare enum UsageAggregationType {
+    SUM = "sum",
+    MAX = "max",
+    LAST = "last"
+}
+/**
+ * Usage record source type.
+ */
+export declare enum UsageSourceType {
+    OPERATION = "operation",
+    RESOURCE_COUNT = "resource_count",
+    CUSTOM = "custom"
+}
+/**
+ * Tax calculation mode: provider-managed or disabled.
+ */
+export declare enum TaxCalculationMode {
+    PROVIDER_MANAGED = "provider_managed",
+    DISABLED = "disabled"
+}
+/**
+ * Invoice status values (maps to Stripe invoice statuses).
+ *
+ * Invoices are created and managed entirely by the billing provider.
+ * We store a thin reference for status tracking and quick display.
+ */
+export declare enum InvoiceStatus {
+    DRAFT = "draft",
+    OPEN = "open",
+    PAID = "paid",
+    VOID = "void",
+    UNCOLLECTIBLE = "uncollectible"
+}
+/**
+ * Billing-compatible scope types.
+ * Subset of ResourcePrimaryScope — excludes APPLICATION which has no billing variants.
+ * Used by scope-agnostic billing resources (e.g., Referrals) that reference
+ * billing accounts across different polymorphic collections.
+ */
+export declare enum BillingScopeType {
+    ORGANIZATIONS = "organizations",
+    USER_SELF = "user_self"
+}
+/**
+ * Promotion type.
+ */
+export declare enum PromotionType {
+    /** Direct discount */
+    COUPON = "coupon",
+    /** Code-based discount */
+    PROMOTION_CODE = "promotion_code",
+    /** Referral program */
+    REFERRAL = "referral",
+    /** Special deal/offer */
+    DEAL = "deal"
+}
+/**
+ * Discount type for promotions.
+ */
+export declare enum DiscountType {
+    PERCENTAGE = "percentage",
+    FIXED_AMOUNT = "fixed_amount"
+}
+/**
+ * Promotion duration (how long the discount applies).
+ */
+export declare enum PromotionDuration {
+    ONCE = "once",
+    REPEATING = "repeating",
+    FOREVER = "forever"
+}
+/**
+ * Referral status lifecycle.
+ */
+export declare enum ReferralStatus {
+    PENDING = "pending",
+    ACCEPTED = "accepted",
+    CONVERTED = "converted",
+    EXPIRED = "expired",
+    CANCELLED = "cancelled"
+}
+/**
+ * Reward type for the referrer (person who referred).
+ */
+export declare enum ReferrerRewardType {
+    CREDIT = "credit",
+    DISCOUNT = "discount",
+    FEATURE = "feature",
+    COMMISSION = "commission"
+}
+/**
+ * Reward type for the referred (new customer).
+ */
+export declare enum ReferredRewardType {
+    CREDIT = "credit",
+    DISCOUNT = "discount",
+    FEATURE = "feature",
+    TRIAL_EXTENSION = "trial_extension"
+}
+//# sourceMappingURL=billing-enums.shared.schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"billing-enums.shared.schemas.d.ts","sourceRoot":"","sources":["../../../src/billing/billing-enums.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAIzH;;;;;;;;;;;GAWG;AACH,oBAAY,WAAW;IACrB,gEAAgE;IAChE,IAAI,SAAS;IACb,6DAA6D;IAC7D,KAAK,UAAU;IACf,kEAAkE;IAClE,OAAO,YAAY;IACnB,6EAA6E;IAC7E,QAAQ,aAAa;IACrB,sEAAsE;IACtE,WAAW,gBAAgB;IAC3B,0EAA0E;IAC1E,IAAI,SAAS;CACd;AAED;;;;GAIG;AACH,oBAAY,cAAc;IACxB,GAAG,QAAQ;IACX,GAAG,QAAQ;CACZ;AAID;;GAEG;AACH,oBAAY,iBAAiB;IAC3B,iBAAiB,sBAAsB;IACvC,IAAI,SAAS;IACb,cAAc,mBAAmB;CAClC;AAED;;GAEG;AACH,oBAAY,aAAa;IACvB,SAAS,cAAc;IACvB,aAAa,kBAAkB;CAChC;AAMD;;GAEG;AACH,oBAAY,yBAAyB;IACnC,SAAS,cAAc;IACvB,kBAAkB,uBAAuB;CAC1C;AAED;;GAEG;AACH,oBAAY,oBAAoB;IAC9B,GAAG,QAAQ;IACX,GAAG,QAAQ;IACX,IAAI,SAAS;CACd;AAED;;GAEG;AACH,oBAAY,eAAe;IACzB,SAAS,cAAc;IACvB,cAAc,mBAAmB;IACjC,MAAM,WAAW;CAClB;AAMD;;GAEG;AACH,oBAAY,kBAAkB;IAC5B,gBAAgB,qBAAqB;IACrC,QAAQ,aAAa;CACtB;AAMD;;;;;GAKG;AACH,oBAAY,aAAa;IACvB,KAAK,UAAU;IACf,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,aAAa,kBAAkB;CAChC;AAID;;;;;GAKG;AACH,oBAAY,gBAAgB;IAC1B,aAAa,kBAAkB;IAC/B,SAAS,cAAc;CACxB;AAID;;GAEG;AACH,oBAAY,aAAa;IACvB,sBAAsB;IACtB,MAAM,WAAW;IACjB,0BAA0B;IAC1B,cAAc,mBAAmB;IACjC,uBAAuB;IACvB,QAAQ,aAAa;IACrB,yBAAyB;IACzB,IAAI,SAAS;CACd;AAED;;GAEG;AACH,oBAAY,YAAY;IACtB,UAAU,eAAe;IACzB,YAAY,iBAAiB;CAC9B;AAED;;GAEG;AACH,oBAAY,iBAAiB;IAC3B,IAAI,SAAS;IACb,SAAS,cAAc;IACvB,OAAO,YAAY;CACpB;AAED;;GAEG;AACH,oBAAY,cAAc;IACxB,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,SAAS,cAAc;IACvB,OAAO,YAAY;IACnB,SAAS,cAAc;CACxB;AAED;;GAEG;AACH,oBAAY,kBAAkB;IAC5B,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,UAAU,eAAe;CAC1B;AAED;;GAEG;AACH,oBAAY,kBAAkB;IAC5B,MAAM,WAAW;IACjB,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,eAAe,oBAAoB;CACpC"}