@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/billing/services/back-office/product-catalog-sync.backend.service.js

@@ -0,0 +1,371 @@
+/**
+ * Product Catalog Sync Backend Service
+ *
+ * Synchronizes the code-defined ProductDefinition catalog with the database
+ * and the billing provider. Two modes:
+ *
+ * 1. LAZY: `ensureProductSynced(key)` — On-demand, single product (first checkout or admin view)
+ * 2. BULK: `syncProductCatalog()` — Admin action, all products (post-deploy hook)
+ *
+ * Design:
+ * - Config (code) is the source of truth → DB always reflects code
+ * - Provider sync is separate from DB sync (happens on first use or bulk sync)
+ * - "features-dirty" detection: when grantedFeatures/grantedLimits change, trigger
+ *   feature recomputation for all affected subscriptions
+ *
+ * @see billing-and-features-system.md §8.6 (Product Catalog Versioning Strategy)
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject } from 'inversify';
+import { CoreResourceType, CoreResourceOperation, ErrorType, ErrorCustomMessageReference, } from '@wildo-ai/saas-models';
+import { AbstractBillingBackendService } from '../../../billing/services/back-office/abstract-billing.backend.service.js';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+// =====================================================
+// Service
+// =====================================================
+let ProductCatalogSyncBackendService = class ProductCatalogSyncBackendService extends AbstractBillingBackendService {
+    /** The product catalog from code (set at initialization) */
+    productCatalog = [];
+    constructor(logger, servicesRegistry, executionContextCreator, resourcesRegistry, errorBuilder) {
+        super(logger, servicesRegistry, executionContextCreator, resourcesRegistry, errorBuilder);
+    }
+    // ════════════════════════════════════════════════════════════
+    // Initialization
+    // ════════════════════════════════════════════════════════════
+    /**
+     * Initialize with the code-defined product catalog and billing provider.
+     */
+    async initialize(productCatalog, provider) {
+        if (this.isInitialized)
+            return;
+        this.productCatalog = productCatalog;
+        this.initializeProvider(provider);
+        this.logDebug('Product catalog sync initialized', {
+            productsInCatalog: productCatalog.length,
+        });
+    }
+    /**
+     * Returns the in-memory product catalog (set at initialization).
+     * Used by the companion labelling service to discover billing keys for i18n.
+     */
+    getProductDefinitions() {
+        return this.productCatalog;
+    }
+    // ════════════════════════════════════════════════════════════
+    // Lazy Sync (on-demand, single product)
+    // ════════════════════════════════════════════════════════════
+    /**
+     * Ensure a single product and its prices exist in DB and provider.
+     * Idempotent: safe to call multiple times.
+     *
+     * Flow:
+     * 1. Look up ProductDefinition by key in code catalog
+     * 2. Upsert Product DB record (key → _id mapping)
+     * 3. Upsert Price DB records for each inline price
+     * 4. If providerProductId is missing: sync to billing provider
+     */
+    async ensureProductSynced(productKey) {
+        this.ensureInitialized();
+        this.logDebug('Ensuring product synced', { productKey });
+        // 1. Find in code catalog
+        const definition = this.productCatalog.find(p => p.key === productKey);
+        if (!definition) {
+            throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+                customMessageReference: ErrorCustomMessageReference.BILLING_PRODUCT_NOT_FOUND,
+                context: { productKey },
+            });
+        }
+        // 2. Upsert product in DB
+        const product = await this.upsertProduct(definition);
+        // 3. Upsert prices
+        await this.upsertPrices(product._id, definition);
+        // 4. Sync to provider when available.
+        // Existing provider-linked products must still push any newly added local
+        // prices, otherwise the DB/provider catalogs silently drift.
+        if (this.billingProvider) {
+            if (!product.providerProductId) {
+                return await this.syncProductToProvider(product);
+            }
+            await this.syncUnsyncedPricesToProvider(product, product.providerProductId);
+        }
+        return product;
+    }
+    // ════════════════════════════════════════════════════════════
+    // Bulk Sync (admin action)
+    // ════════════════════════════════════════════════════════════
+    /**
+     * Sync ALL products from code catalog to DB + provider.
+     * Detects "features-dirty" products and returns their keys for
+     * downstream feature recomputation.
+     *
+     * Idempotent and safe to run multiple times.
+     */
+    async syncProductCatalog() {
+        this.ensureInitialized();
+        this.logDebug('Starting bulk product catalog sync', {
+            productsInCatalog: this.productCatalog.length,
+        });
+        const result = {
+            synced: 0,
+            created: 0,
+            updated: 0,
+            featuresDirty: [],
+            errors: [],
+        };
+        for (const definition of this.productCatalog) {
+            try {
+                // Check if existing product has different features/limits
+                const existingProduct = await this.findProductByKey(definition.key);
+                const isFeaturesDirty = existingProduct
+                    ? this.isFeaturesDirty(existingProduct, definition)
+                    : false;
+                // Upsert product (pass existing to avoid a second DB lookup)
+                const product = await this.upsertProduct(definition, existingProduct);
+                result.synced++;
+                if (!existingProduct) {
+                    result.created++;
+                }
+                else {
+                    result.updated++;
+                }
+                // Upsert prices
+                await this.upsertPrices(product._id, definition);
+                // Sync to provider when available.
+                if (this.billingProvider) {
+                    if (!product.providerProductId) {
+                        await this.syncProductToProvider(product);
+                    }
+                    else {
+                        await this.syncUnsyncedPricesToProvider(product, product.providerProductId);
+                    }
+                }
+                // Track features-dirty products
+                if (isFeaturesDirty) {
+                    result.featuresDirty.push(definition.key);
+                }
+            }
+            catch (error) {
+                result.errors.push(`${definition.key}: ${error.message}`);
+                this.logger.error('Failed to sync product', {
+                    productKey: definition.key,
+                    error: error.message,
+                });
+            }
+        }
+        this.logDebug('Bulk product catalog sync complete', { ...result });
+        return result;
+    }
+    // ════════════════════════════════════════════════════════════
+    // Private — Product Operations
+    // ════════════════════════════════════════════════════════════
+    async findProductByKey(productKey) {
+        try {
+            const ctx = await this.internalCtx(CoreResourceType.PRODUCTS, CoreResourceOperation.LIST);
+            const items = await this.servicesRegistry.list(CoreResourceType.PRODUCTS, ctx, { key: productKey });
+            return items.length > 0 ? items[0] : null;
+        }
+        catch (error) {
+            this.logDebug('Failed to find product by key', { productKey, error: error.message });
+            return null;
+        }
+    }
+    async upsertProduct(definition, existingProductHint) {
+        // Use the pre-fetched product if available (avoids double DB lookup in bulk sync)
+        const existingProduct = existingProductHint !== undefined
+            ? existingProductHint
+            : await this.findProductByKey(definition.key);
+        const productData = {
+            type: definition.type,
+            key: definition.key,
+            targetScopes: definition.targetScopes,
+            grantedFeatures: definition.grantedFeatures,
+            grantedLimits: definition.grantedLimits,
+            planTier: definition.planTier,
+            planTierOrder: definition.planTierOrder,
+            requiredPlanTiers: definition.requiredPlanTiers,
+            taxDisplayMode: definition.taxDisplayMode,
+            purchaseConfig: definition.purchaseConfig,
+            behaviorPolicy: definition.behaviorPolicy,
+            sortOrder: definition.sortOrder,
+            isPublic: definition.isPublic,
+            isActive: true,
+        };
+        if (existingProduct) {
+            // Update
+            const ctx = await this.internalCtx(CoreResourceType.PRODUCTS, CoreResourceOperation.UPDATE);
+            return await this.servicesRegistry.update(CoreResourceType.PRODUCTS, ctx, existingProduct._id, productData);
+        }
+        else {
+            // Create
+            const ctx = await this.internalCtx(CoreResourceType.PRODUCTS, CoreResourceOperation.CREATE);
+            return await this.servicesRegistry.create(CoreResourceType.PRODUCTS, ctx, productData);
+        }
+    }
+    async upsertPrices(productId, definition) {
+        for (const priceDef of definition.prices) {
+            const priceData = {
+                productId,
+                model: priceDef.model,
+                unitPrice: priceDef.unitPrice,
+                interval: priceDef.interval,
+                intervalCount: priceDef.intervalCount,
+                tiers: priceDef.tiers,
+                packageSize: priceDef.packageSize,
+                usageAggregation: priceDef.usageAggregation,
+                taxBehavior: priceDef.taxBehavior,
+                isDefault: priceDef.isDefault,
+                isActive: true,
+            };
+            // Try to find existing price for this product with same model+interval+currency
+            try {
+                const listCtx = await this.internalCtx(CoreResourceType.PRICES, CoreResourceOperation.LIST);
+                const items = await this.servicesRegistry.list(CoreResourceType.PRICES, listCtx, {
+                    productId,
+                    model: priceDef.model,
+                    'unitPrice.currency': priceDef.unitPrice.currency,
+                    ...(priceDef.interval && { interval: priceDef.interval }),
+                });
+                if (items.length > 0) {
+                    const updateCtx = await this.internalCtx(CoreResourceType.PRICES, CoreResourceOperation.UPDATE);
+                    await this.servicesRegistry.update(CoreResourceType.PRICES, updateCtx, items[0]._id, priceData);
+                }
+                else {
+                    const createCtx = await this.internalCtx(CoreResourceType.PRICES, CoreResourceOperation.CREATE);
+                    await this.servicesRegistry.create(CoreResourceType.PRICES, createCtx, priceData);
+                }
+            }
+            catch (error) {
+                this.logger.error('Failed to upsert price', {
+                    productId,
+                    model: priceDef.model,
+                    currency: priceDef.unitPrice.currency,
+                    error: error.message,
+                });
+            }
+        }
+    }
+    async syncProductToProvider(product) {
+        if (!this.billingProvider)
+            return product;
+        try {
+            // Sync product
+            const { providerProductId } = await this.billingProvider.syncProduct({
+                productKey: product.key,
+                name: product.key,
+                metadata: { key: product.key, type: product.type },
+            });
+            // Update local product with provider ID
+            const updateCtx = await this.internalCtx(CoreResourceType.PRODUCTS, CoreResourceOperation.UPDATE);
+            const updated = await this.servicesRegistry.update(CoreResourceType.PRODUCTS, updateCtx, product._id, { providerProductId });
+            await this.syncUnsyncedPricesToProvider(updated, providerProductId);
+            return updated;
+        }
+        catch (error) {
+            this.logger.error('Failed to sync product to provider', {
+                productKey: product.key,
+                error: error.message,
+            });
+            return product;
+        }
+    }
+    /**
+     * Sync any locally defined prices that do not yet have a provider identifier.
+     *
+     * This must run for both first-time product syncs and already-synced products,
+     * otherwise adding a new local price after the initial product sync leaves the
+     * provider catalog stale.
+     */
+    async syncUnsyncedPricesToProvider(product, providerProductId) {
+        if (!this.billingProvider)
+            return;
+        const listCtx = await this.internalCtx(CoreResourceType.PRICES, CoreResourceOperation.LIST);
+        const prices = await this.servicesRegistry.list(CoreResourceType.PRICES, listCtx, { productId: product._id });
+        for (const price of prices) {
+            if (price.providerPriceId)
+                continue;
+            try {
+                // Convert MoneyValue (bigint) → provider format (number in cents)
+                const { providerPriceId } = await this.billingProvider.syncPrice({
+                    providerProductId,
+                    amount: Number(price.unitPrice.amount),
+                    currency: price.unitPrice.currency,
+                    interval: price.interval,
+                    model: price.model,
+                    tiers: price.tiers?.map(t => ({
+                        upTo: t.upTo ?? null,
+                        unitAmount: Number(t.unitPrice.amount),
+                        flatAmount: Number(t.flatPrice.amount),
+                    })),
+                    packageSize: price.packageSize,
+                    taxBehavior: price.taxBehavior,
+                    metadata: { productKey: product.key },
+                });
+                const priceUpdateCtx = await this.internalCtx(CoreResourceType.PRICES, CoreResourceOperation.UPDATE);
+                await this.servicesRegistry.update(CoreResourceType.PRICES, priceUpdateCtx, price._id, { providerPriceId });
+            }
+            catch (error) {
+                this.logger.error('Failed to sync price to provider', {
+                    priceId: price._id,
+                    productKey: product.key,
+                    error: error.message,
+                });
+            }
+        }
+    }
+    // ════════════════════════════════════════════════════════════
+    // Private — Dirty Detection
+    // ════════════════════════════════════════════════════════════
+    /**
+     * Check if a product's features/limits have changed relative to the catalog definition.
+     * If so, all subscriptions using this product need feature recomputation.
+     */
+    isFeaturesDirty(existing, definition) {
+        // Check grantedFeatures
+        const existingFeatures = new Set(existing.grantedFeatures ?? []);
+        const newFeatures = new Set(definition.grantedFeatures ?? []);
+        if (existingFeatures.size !== newFeatures.size)
+            return true;
+        for (const f of existingFeatures) {
+            if (!newFeatures.has(f))
+                return true;
+        }
+        // Check grantedLimits
+        const existingLimits = existing.grantedLimits ?? {};
+        const newLimits = definition.grantedLimits ?? {};
+        const existingKeys = Object.keys(existingLimits);
+        const newKeys = Object.keys(newLimits);
+        if (existingKeys.length !== newKeys.length)
+            return true;
+        for (const key of existingKeys) {
+            if (!newLimits[key])
+                return true;
+            if (existingLimits[key].value !== newLimits[key].value)
+                return true;
+            if (existingLimits[key].mode !== newLimits[key].mode)
+                return true;
+        }
+        return false;
+    }
+};
+ProductCatalogSyncBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.ResourceRegistryService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __metadata("design:paramtypes", [Function, Function, Function, Function, Function])
+], ProductCatalogSyncBackendService);
+export { ProductCatalogSyncBackendService };
+//# sourceMappingURL=product-catalog-sync.backend.service.js.map

package/dist/esm/billing/services/back-office/product-catalog-sync.backend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-catalog-sync.backend.service.js","sourceRoot":"","sources":["../../../../../src/billing/services/back-office/product-catalog-sync.backend.service.ts"],"names":[],"mappings":"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"}

package/dist/esm/billing/services/back-office/usage-metering.backend.service.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Usage Metering Backend Service
+ *
+ * Tracks and reports usage for METERED products.
+ * Usage is recorded locally (buffered) and periodically flushed to the billing provider.
+ *
+ * Flow:
+ * 1. Operation hook calls recordUsage() after successful operation
+ * 2. Usage records are stored in DB (reportedToProvider: false)
+ * 3. Periodic flush (cron) aggregates and reports to provider
+ * 4. Provider bills at the end of the billing period
+ *
+ * @see billing-and-features-system.md §9 (Usage & Consumption Tracking)
+ */
+import { UsageSourceType } from '@wildo-ai/saas-models';
+import type { StandardBilling_Interface } from '@wildo-ai/external-connectors-models';
+import { AbstractBillingBackendService } from '../../../billing/services/back-office/abstract-billing.backend.service.js';
+import { type BillingResolvedVariants } from '../../../billing/services/custom-impl/billing-custom-impl-utils.backend.js';
+import type { LoggerService } from '../../../monitoring/logger/services/logger.service.js';
+import type { ServicesRegistryHandlerBackendService } from '../../../base-classes/services/services/services-registry-handler.backend.service.js';
+import type { ExecutionContextCreatorBackendService } from '../../../runtime/services/execution-context-creator.backend.service.js';
+import type { ResourcesRegistryBackendService } from '../../../resources/services/resources-registry.backend.service.js';
+import type { ErrorBuilderBackendService } from '../../../errors/services/error-builder.backend.service.js';
+import type { RepositoriesRegistryHandlerBackendService } from '../../../base-classes/services/repositories/repositories-registry-handler.backend.service.js';
+export interface RecordUsageOptions {
+    /** What generated this usage */
+    source?: {
+        type: UsageSourceType;
+        resourceType?: string;
+        operationIdentifier?: string;
+        description?: string;
+    };
+    metadata?: Record<string, string>;
+}
+export interface UsageFlushResult {
+    totalRecords: number;
+    reported: number;
+    failed: number;
+    errors: string[];
+}
+export declare class UsageMeteringBackendService extends AbstractBillingBackendService {
+    private readonly repositoriesRegistry;
+    constructor(logger: LoggerService, servicesRegistry: ServicesRegistryHandlerBackendService, executionContextCreator: ExecutionContextCreatorBackendService, resourcesRegistry: ResourcesRegistryBackendService, errorBuilder: ErrorBuilderBackendService, repositoriesRegistry: RepositoriesRegistryHandlerBackendService);
+    initialize(provider: StandardBilling_Interface): Promise<void>;
+    /**
+     * Record a usage event for a billing account.
+     * Stores locally — NOT reported to provider immediately.
+     *
+     * @param variants — resolved billing polymorphic variants for the target scope
+     */
+    recordUsage(variants: BillingResolvedVariants, billingAccountId: string, productKey: string, quantity: number, options?: RecordUsageOptions): Promise<void>;
+    /**
+     * Get usage summary for a billing account.
+     *
+     * @param variants — resolved billing polymorphic variants for the target scope
+     */
+    getUsage(variants: BillingResolvedVariants, billingAccountId: string, productKey?: string, period?: {
+        start: Date;
+        end: Date;
+    }): Promise<Record<string, number>>;
+    /**
+     * Flush unreported usage records to the billing provider.
+     * Called periodically by a cron job.
+     *
+     * Iterates all billing scopes, aggregates records by (billingAccountId, productKey)
+     * per scope, then reports to the provider.
+     */
+    flushToProvider(): Promise<UsageFlushResult>;
+    private flushScopeToProvider;
+    /**
+     * Validate that the billing account has an active subscription containing
+     * a metered product matching the given product key. Returns true as soon
+     * as one matching item is found — the item identity is not needed because
+     * the Billing Meter provider API routes usage by meterEventName + customer,
+     * not by subscription item.
+     */
+    private hasActiveMeteredSubscription;
+    private resolveProviderCustomerId;
+}
+//# sourceMappingURL=usage-metering.backend.service.d.ts.map

package/dist/esm/billing/services/back-office/usage-metering.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-metering.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/billing/services/back-office/usage-metering.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAIL,eAAe,EAKhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AACtF,OAAO,EAAE,6BAA6B,EAAE,MAAM,kFAAkF,CAAC;AACjI,OAAO,EAAE,KAAK,uBAAuB,EAA6B,MAAM,mFAAmF,CAAC;AAE5J,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,6FAA6F,CAAC;AACzJ,OAAO,KAAK,EAAE,qCAAqC,EAAE,MAAM,+EAA+E,CAAC;AAC3I,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,0EAA0E,CAAC;AAChI,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AACnH,OAAO,KAAK,EAAE,yCAAyC,EAAE,MAAM,qGAAqG,CAAC;AAMrK,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,MAAM,CAAC,EAAE;QACP,IAAI,EAAE,eAAe,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAMD,qBACa,2BAA4B,SAAQ,6BAA6B;IAQX,OAAO,CAAC,QAAQ,CAAC,oBAAoB;gBALjE,MAAM,EAAE,aAAa,EACG,gBAAgB,EAAE,qCAAqC,EAChD,uBAAuB,EAAE,qCAAqC,EAC5E,iBAAiB,EAAE,+BAA+B,EACtD,YAAY,EAAE,0BAA0B,EACR,oBAAoB,EAAE,yCAAyC;IASpI,UAAU,CAAC,QAAQ,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC;IAU3E;;;;;OAKG;IACU,WAAW,CACtB,QAAQ,EAAE,uBAAuB,EACjC,gBAAgB,EAAE,MAAM,EACxB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,IAAI,CAAC;IAyBhB;;;;OAIG;IACU,QAAQ,CACnB,QAAQ,EAAE,uBAAuB,EACjC,gBAAgB,EAAE,MAAM,EACxB,UAAU,CAAC,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,IAAI,CAAC;QAAC,GAAG,EAAE,IAAI,CAAA;KAAE,GAClC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAwBlC;;;;;;OAMG;IACU,eAAe,IAAI,OAAO,CAAC,gBAAgB,CAAC;YAgC3C,oBAAoB;IAyElC;;;;;;OAMG;YACW,4BAA4B;YAgC5B,yBAAyB;CAYxC"}