@wildo-ai/saas-backend-lib 1.0.1

package/src/billing/services/back-office/usage-metering.backend.service.ts

@@ -0,0 +1,326 @@
+/**
+ * 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 { injectable, inject } from 'inversify';
+import {
+  type UsageRecord,
+  type BillingSubscriptionBase,
+  type Product,
+  UsageSourceType,
+  ProductType,
+  SubscriptionStatus,
+  CoreResourceType,
+  CoreResourceOperation,
+} from '@wildo-ai/saas-models';
+import type { StandardBilling_Interface } from '@wildo-ai/external-connectors-models';
+import { AbstractBillingBackendService } from '~wildo-backend-lib/billing/services/back-office/abstract-billing.backend.service';
+import { type BillingResolvedVariants, BILLING_SCOPE_TO_VARIANTS } from '~wildo-backend-lib/billing/services/custom-impl/billing-custom-impl-utils.backend';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import type { ServicesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';
+import type { ExecutionContextCreatorBackendService } from '~wildo-backend-lib/runtime/services/execution-context-creator.backend.service';
+import type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+import type { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import type { RepositoriesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';
+
+// =====================================================
+// Types
+// =====================================================
+
+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[];
+}
+
+// =====================================================
+// Service
+// =====================================================
+
+@injectable()
+export class UsageMeteringBackendService extends AbstractBillingBackendService {
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService) servicesRegistry: ServicesRegistryHandlerBackendService,
+    @inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService) executionContextCreator: ExecutionContextCreatorBackendService,
+    @inject(SAAS_SERVICE_TYPES.ResourceRegistryService) resourcesRegistry: ResourcesRegistryBackendService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService) private readonly repositoriesRegistry: RepositoriesRegistryHandlerBackendService,
+  ) {
+    super(logger, servicesRegistry, executionContextCreator, resourcesRegistry, errorBuilder);
+  }
+
+  // ════════════════════════════════════════════════════════════
+  // Initialization
+  // ════════════════════════════════════════════════════════════
+
+  public async initialize(provider: StandardBilling_Interface): Promise<void> {
+    if (this.isInitialized) return;
+    this.initializeProvider(provider);
+    this.logDebug('Usage metering service initialized');
+  }
+
+  // ════════════════════════════════════════════════════════════
+  // Public API
+  // ════════════════════════════════════════════════════════════
+
+  /**
+   * 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
+   */
+  public async recordUsage(
+    variants: BillingResolvedVariants,
+    billingAccountId: string,
+    productKey: string,
+    quantity: number,
+    options?: RecordUsageOptions,
+  ): Promise<void> {
+    this.logDebug('Recording usage', { billingAccountId, productKey, quantity, scope: variants.scopeType });
+
+    const hasSubscription = await this.hasActiveMeteredSubscription(variants, billingAccountId, productKey);
+    if (!hasSubscription) {
+      this.logger.warn('No active metered subscription found for usage recording', {
+        billingAccountId,
+        productKey,
+        scope: variants.scopeType,
+      });
+      return;
+    }
+
+    const ctx = await this.internalCtx(variants.usageRecord as CoreResourceType, CoreResourceOperation.CREATE);
+    await this.servicesRegistry.create(variants.usageRecord as CoreResourceType, ctx, {
+      [variants.billingAccountFkField]: billingAccountId,
+      productKey,
+      quantity,
+      timestamp: new Date(),
+      source: options?.source,
+      reportedToProvider: false,
+      metadata: options?.metadata,
+    });
+  }
+
+  /**
+   * Get usage summary for a billing account.
+   *
+   * @param variants — resolved billing polymorphic variants for the target scope
+   */
+  public async getUsage(
+    variants: BillingResolvedVariants,
+    billingAccountId: string,
+    productKey?: string,
+    period?: { start: Date; end: Date },
+  ): Promise<Record<string, number>> {
+    const filters: Record<string, unknown> = {
+      [variants.billingAccountFkField]: billingAccountId,
+      ...(productKey && { productKey }),
+      ...(period && {
+        timestamp: {
+          $gte: period.start,
+          $lte: period.end,
+        },
+      }),
+    };
+
+    const ctx = await this.internalCtx(variants.usageRecord as CoreResourceType, CoreResourceOperation.LIST);
+    const records = await this.servicesRegistry.list<UsageRecord>(variants.usageRecord as CoreResourceType, ctx, filters, { limit: 10000 }) as UsageRecord[];
+
+    // Aggregate by product key
+    const usage: Record<string, number> = {};
+    for (const record of records) {
+      usage[record.productKey] = (usage[record.productKey] ?? 0) + record.quantity;
+    }
+
+    return usage;
+  }
+
+  /**
+   * 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.
+   */
+  public async flushToProvider(): Promise<UsageFlushResult> {
+    if (!this.billingProvider) {
+      return { totalRecords: 0, reported: 0, failed: 0, errors: ['Provider not initialized'] };
+    }
+
+    this.logDebug('Starting usage flush to provider');
+
+    const result: UsageFlushResult = {
+      totalRecords: 0,
+      reported: 0,
+      failed: 0,
+      errors: [],
+    };
+
+    // Process each billing scope independently — usage records live in per-scope collections
+    for (const [scopeKey, scopeData] of Object.entries(BILLING_SCOPE_TO_VARIANTS)) {
+      const variants: BillingResolvedVariants = { scopeKey, ...scopeData };
+      try {
+        await this.flushScopeToProvider(variants, result);
+      } catch (error) {
+        result.errors.push(`Flush error for scope ${variants.scopeType}: ${(error as Error).message}`);
+      }
+    }
+
+    this.logDebug('Usage flush complete', { ...result });
+    return result;
+  }
+
+  // ════════════════════════════════════════════════════════════
+  // Private — Flush per scope
+  // ════════════════════════════════════════════════════════════
+
+  private async flushScopeToProvider(variants: BillingResolvedVariants, result: UsageFlushResult): Promise<void> {
+    // List unreported records from this scope's usage record collection
+    const listCtx = await this.internalCtx(variants.usageRecord as CoreResourceType, CoreResourceOperation.LIST);
+    const records = await this.servicesRegistry.list<UsageRecord>(
+      variants.usageRecord as CoreResourceType,
+      listCtx,
+      { reportedToProvider: false },
+      { limit: 10000 },
+    ) as UsageRecord[];
+
+    result.totalRecords += records.length;
+
+    if (records.length === 0) return;
+
+    // Aggregate by (billingAccountFkField value, productKey)
+    const billingAccountFk = variants.billingAccountFkField;
+    const aggregateKey = (r: UsageRecord) => `${(r as any)[billingAccountFk]}::${r.productKey}`;
+    const aggregated = new Map<string, { billingAccountId: string; productKey: string; quantity: number; recordIds: string[] }>();
+
+    for (const record of records) {
+      const key = aggregateKey(record);
+      const existing = aggregated.get(key);
+      if (existing) {
+        existing.quantity += record.quantity;
+        existing.recordIds.push(record._id);
+      } else {
+        aggregated.set(key, {
+          billingAccountId: (record as any)[billingAccountFk],
+          productKey: record.productKey,
+          quantity: record.quantity,
+          recordIds: [record._id],
+        });
+      }
+    }
+
+    // Report each aggregated group to provider via billing meter events
+    for (const [, group] of aggregated) {
+      try {
+        // Resolve provider customer ID from billing account
+        const providerCustomerId = await this.resolveProviderCustomerId(variants, group.billingAccountId);
+        if (!providerCustomerId) {
+          result.errors.push(`No provider customer ID for billing account ${group.billingAccountId} (scope: ${variants.scopeType})`);
+          result.failed += group.recordIds.length;
+          continue;
+        }
+
+        // The meterEventName is derived from the product key
+        // Convention: product key IS the meter event name (configured when creating the meter in Stripe)
+        await this.billingProvider!.reportUsage({
+          meterEventName: group.productKey,
+          providerCustomerId,
+          value: group.quantity,
+        });
+
+        // Bulk-mark all records in this group as reported (single DB call)
+        await this.repositoriesRegistry.bulkUpdateForInfrastructure(
+          variants.usageRecord,
+          { _id: { $in: group.recordIds } },
+          { $set: { reportedToProvider: true, reportedAt: new Date() } },
+        );
+
+        result.reported += group.recordIds.length;
+      } catch (error) {
+        result.errors.push(`${group.billingAccountId}/${group.productKey} (scope: ${variants.scopeType}): ${(error as Error).message}`);
+        result.failed += group.recordIds.length;
+      }
+    }
+  }
+
+  // ════════════════════════════════════════════════════════════
+  // Private — Resolution
+  // ════════════════════════════════════════════════════════════
+
+  /**
+   * 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 async hasActiveMeteredSubscription(
+    variants: BillingResolvedVariants,
+    billingAccountId: string,
+    productKey: string,
+  ): Promise<boolean> {
+    try {
+      const subsCtx = await this.internalCtx(variants.subscription as CoreResourceType, CoreResourceOperation.LIST);
+      const subscriptions = await this.servicesRegistry.list<BillingSubscriptionBase>(variants.subscription as CoreResourceType, subsCtx, {
+        [variants.billingAccountFkField]: billingAccountId,
+        status: { $in: [SubscriptionStatus.ACTIVE, SubscriptionStatus.TRIALING] },
+      }) as BillingSubscriptionBase[];
+
+      for (const sub of subscriptions) {
+        for (const item of sub.items) {
+          try {
+            const readCtx = await this.internalCtx(CoreResourceType.PRODUCTS, CoreResourceOperation.READ);
+            const product = await this.servicesRegistry.read<Product>(CoreResourceType.PRODUCTS, readCtx, item.productId);
+            if (product && product.key === productKey && product.type === ProductType.METERED) {
+              return true;
+            }
+          } catch (error) {
+            this.logDebug('Failed to read product for metered item lookup', { productId: item.productId, error: (error as Error).message });
+            continue;
+          }
+        }
+      }
+    } catch (error) {
+      this.logDebug('Failed to validate metered subscription', { billingAccountId, productKey, error: (error as Error).message });
+    }
+    return false;
+  }
+
+  private async resolveProviderCustomerId(variants: BillingResolvedVariants, billingAccountId: string): Promise<string | null> {
+    try {
+      const readCtx = await this.internalCtx(variants.billingAccount as CoreResourceType, CoreResourceOperation.READ);
+      const billingAccount = await this.servicesRegistry.read<{ providerCustomerId?: string }>(
+        variants.billingAccount as CoreResourceType, readCtx, billingAccountId,
+      );
+      return billingAccount?.providerCustomerId ?? null;
+    } catch (error) {
+      this.logDebug('Failed to resolve provider customer ID', { billingAccountId, scope: variants.scopeType, error: (error as Error).message });
+    }
+    return null;
+  }
+}

package/src/billing/services/billing.utils.ts

@@ -0,0 +1,26 @@
+/**
+ * Billing Utilities
+ *
+ * Shared utility functions used across billing services.
+ * Extracted to eliminate duplication between billing-feature-sync
+ * and feature-resolution services.
+ */
+
+import { FEATURES_UNLIMITED } from '@wildo-ai/saas-models';
+
+// ════════════════════════════════════════════════════════════
+// Feature Limits
+// ════════════════════════════════════════════════════════════
+
+/**
+ * Merge two feature limit values.
+ * FEATURES_UNLIMITED (-1) always wins over concrete numbers.
+ * Otherwise, takes the maximum of the two values.
+ *
+ * Used by both billing-feature-sync (aggregating product grants)
+ * and feature-resolution (merging scope features).
+ */
+export function mergeLimit(a: number, b: number): number {
+  if (a === FEATURES_UNLIMITED || b === FEATURES_UNLIMITED) return FEATURES_UNLIMITED;
+  return Math.max(a, b);
+}