@wildo-ai/saas-backend-lib 1.0.1

package/src/billing/services/webhooks/billing-webhook-event-router.backend.service.ts

@@ -0,0 +1,727 @@
+/**
+ * Billing Webhook Event Router
+ *
+ * Routes incoming billing webhook events to the appropriate resource operations
+ * on the correct polymorphic variants. Replaces the orchestrator's
+ * handleProviderWebhook() dispatch.
+ *
+ * Flow:
+ *   BillingWebhookCapabilityHandler → routeEvent()
+ *     → resolveBillingVariants(execCtx)          → deterministic variant derivation from scope
+ *     → per-event handler                  → servicesRegistry.create/update/list on variant
+ *     → feature sync where needed          → via late-bound featureSyncService
+ *
+ * Uses the WEBHOOK_CALLBACK execution context from polymorphic scope resolution
+ * (no internalCtx()). The context's operation (APPLICATION.READ) differs from the
+ * target operations (SUBSCRIPTION.CREATE, etc.), but this is safe: doOperation()
+ * corrects executionContext.operation to match the actual operation before any
+ * pipeline logic (notifications, guidance, milestones) runs.
+ *
+ * @see billing-polymorphic-full-implementation.md §4.5
+ */
+
+import {
+  type Product,
+  type CreditPool,
+  type BillingAccount,
+  type BillingSubscriptionBase,
+  CoreResourceType,
+  CoreWebSocketEvent,
+  ResourcePrimaryScope,
+  SubscriptionStatus,
+  ProductType,
+  CreditPool_Operations,
+} from '@wildo-ai/saas-models';
+import type {
+  StandardBilling_WebhookEvent,
+  StandardBilling_SubscriptionData,
+} from '@wildo-ai/external-connectors-models';
+import type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import type { ServicesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';
+import type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import type { WebSocketService } from '~wildo-backend-lib/requests/service/websocket.service';
+import { getBillingProvider, getFeatureSyncService } from '~wildo-backend-lib/billing/services/custom-impl/billing-custom-implementations.backend';
+import { type BillingResolvedVariants, resolveBillingVariants } from '~wildo-backend-lib/billing/services/custom-impl/billing-custom-impl-utils.backend';
+
+// ── Provider Status Mapping ─────────────────────────────────────────
+
+const PROVIDER_STATUS_MAP: Record<string, SubscriptionStatus> = {
+  active: SubscriptionStatus.ACTIVE,
+  trialing: SubscriptionStatus.TRIALING,
+  past_due: SubscriptionStatus.PAST_DUE,
+  canceled: SubscriptionStatus.CANCELLED,
+  cancelled: SubscriptionStatus.CANCELLED,
+  unpaid: SubscriptionStatus.UNPAID,
+  incomplete: SubscriptionStatus.INCOMPLETE,
+  incomplete_expired: SubscriptionStatus.INCOMPLETE_EXPIRED,
+  paused: SubscriptionStatus.PAUSED,
+};
+
+function mapProviderStatus(providerStatus: string): SubscriptionStatus {
+  return PROVIDER_STATUS_MAP[providerStatus] ?? SubscriptionStatus.INCOMPLETE;
+}
+
+// ── Router ──────────────────────────────────────────────────────────
+
+export class BillingWebhookEventRouterBackendService {
+  /**
+   * In-memory dedup guard for checkout sessions.
+   * Prevents double top-ups on webhook retries within the same process.
+   * Capped to prevent unbounded memory growth; oldest entries evicted on overflow.
+   *
+   * Limitation: process-local only — does not protect against retries delivered
+   * to different instances in a multi-instance deployment. For production hardening,
+   * replace with a shared store (Redis SET with TTL or MongoDB dedup collection).
+   */
+  private readonly processedCheckoutSessions = new Set<string>();
+  private static readonly MAX_DEDUP_ENTRIES = 10_000;
+
+  constructor(
+    private readonly servicesRegistry: ServicesRegistryHandlerBackendService,
+    private readonly logger?: LoggerService,
+    private readonly webSocketService?: WebSocketService,
+  ) {}
+
+  private log(level: 'debug' | 'warn' | 'error', message: string, context?: Record<string, unknown>): void {
+    if (!this.logger) return;
+    this.logger[level](`[BillingWebhookRouter] ${message}`, context);
+  }
+
+  /**
+   * Route a billing webhook event to the appropriate resource operation.
+   */
+  async routeEvent(
+    event: StandardBilling_WebhookEvent,
+    execCtx: ExecutionContext<any>,
+  ): Promise<void> {
+    const eventType = event.type as string;
+
+    // APPLICATION-scoped events (product/price catalog events) have no entity scope.
+    // They are handled by the product catalog sync service, not here.
+    const variants = resolveBillingVariants(execCtx);
+    if (!variants) {
+      this.log('debug', 'No entity scope on execution context — skipping (APPLICATION-scoped event)', { eventType });
+      return;
+    }
+
+    this.log('debug', 'Routing webhook event', { eventType, scope: variants.scopeKey, eventId: event.providerEventId });
+
+    switch (eventType) {
+      case 'subscription.created':
+        await this.handleSubscriptionCreated(event, variants, execCtx);
+        break;
+      case 'subscription.updated':
+        await this.handleSubscriptionUpdated(event, variants, execCtx);
+        break;
+      case 'subscription.deleted':
+        await this.handleSubscriptionDeleted(event, variants, execCtx);
+        break;
+      case 'subscription.trial_will_end':
+        this.log('debug', 'Trial will end notification (no-op)', { eventId: event.providerEventId });
+        break;
+      case 'invoice.paid':
+        await this.handleInvoiceEvent(event, variants, execCtx, 'paid');
+        break;
+      case 'invoice.finalized':
+        await this.handleInvoiceEvent(event, variants, execCtx, 'open');
+        break;
+      case 'invoice.payment_failed':
+        await this.handleInvoiceEvent(event, variants, execCtx, 'failed');
+        break;
+      case 'checkout.session.completed':
+        await this.handleCheckoutCompleted(event, variants, execCtx);
+        break;
+      case 'customer.updated':
+        this.log('debug', 'Customer updated on provider (no local action)', { eventId: event.providerEventId });
+        break;
+      case 'customer.deleted':
+        await this.handleCustomerDeleted(event, variants, execCtx);
+        break;
+      case 'coupon.created':
+      case 'coupon.updated':
+      case 'coupon.deleted':
+        this.log('debug', 'Coupon event (coupons managed via Wildo promotion system)', { eventType, eventId: event.providerEventId });
+        break;
+      case 'customer.discount.created':
+      case 'customer.discount.updated':
+      case 'customer.discount.deleted':
+        await this.handleCustomerDiscountEvent(event, variants, execCtx);
+        break;
+      case 'payment_method.attached':
+      case 'payment_method.detached':
+        this.log('debug', 'Payment method event (no local action)', { eventType });
+        break;
+      default:
+        this.log('debug', 'Unknown webhook event type', { eventType });
+        break;
+    }
+  }
+
+  // ════════════════════════════════════════════════════════════════════
+  // Subscription Events
+  // ════════════════════════════════════════════════════════════════════
+
+  /**
+   * SUBSCRIPTION_CREATED: Retrieve full sub data from provider, create local record.
+   */
+  private async handleSubscriptionCreated(
+    event: StandardBilling_WebhookEvent,
+    variants: BillingResolvedVariants,
+    execCtx: ExecutionContext<any>,
+  ): Promise<void> {
+    const data = event.data as Record<string, unknown>;
+    const providerSubscriptionId = data.id as string;
+    if (!providerSubscriptionId) return;
+
+    // Check if subscription already exists (idempotency)
+    const existing = await this.findSubscriptionByProviderId(variants.subscription, execCtx, providerSubscriptionId);
+    if (existing) {
+      this.log('debug', 'Subscription already exists — syncing from provider', { providerSubscriptionId });
+      await this.syncSubscriptionFromProvider(variants, execCtx, existing._id, providerSubscriptionId);
+      // Feature sync fires automatically via post-operation hook on subscription update
+      return;
+    }
+
+    // Resolve billing account ID from metadata or re-lookup
+    const metadata = data.metadata as Record<string, string> | undefined;
+    const billingAccountId = metadata?.billingAccountId
+      ?? await this.resolveBillingAccountId(variants, execCtx, data.customer as string);
+
+    if (!billingAccountId) {
+      this.log('warn', 'Cannot resolve billing account for subscription.created', { providerSubscriptionId });
+      return;
+    }
+
+    // Retrieve authoritative subscription data from provider
+    const provider = getBillingProvider();
+    const providerData = await provider.retrieveSubscription(providerSubscriptionId);
+
+    // Resolve provider items to local product/price IDs
+    const items = await this.resolveSubscriptionItems(providerData, providerSubscriptionId, execCtx);
+
+    if (items.length === 0) {
+      this.log('warn', 'Subscription has no resolvable items — skipping creation (product/price catalog may not be synced yet)', {
+        providerSubscriptionId, billingAccountId,
+      });
+      return;
+    }
+
+    // Create local subscription
+    const createData: Record<string, unknown> = {
+      [variants.billingAccountFkField]: billingAccountId,
+      providerSubscriptionId,
+      status: mapProviderStatus(providerData.status as string),
+      items,
+      currentPeriodStart: providerData.currentPeriodStart,
+      currentPeriodEnd: providerData.currentPeriodEnd,
+      cancelAtPeriodEnd: providerData.cancelAtPeriodEnd,
+      ...(providerData.discount ? {
+        discount: {
+          providerCouponId: providerData.discount.providerCouponId,
+          percentOff: providerData.discount.percentOff,
+          amountOff: providerData.discount.amountOff,
+          currency: providerData.discount.currency,
+          duration: providerData.discount.duration,
+          durationInMonths: providerData.discount.durationInMonths,
+          end: providerData.discount.end,
+        },
+      } : {}),
+    };
+
+    await this.servicesRegistry.create(variants.subscription, execCtx, createData);
+    this.log('debug', 'Subscription created from webhook', { providerSubscriptionId, billingAccountId });
+    // Feature sync fires automatically via post-operation hook on subscription create
+    await this.emitBillingEvent(CoreWebSocketEvent.BILLING_SUBSCRIPTION_UPDATED, variants, billingAccountId, execCtx);
+  }
+
+  /**
+   * SUBSCRIPTION_UPDATED: Find local sub, sync status/period from provider.
+   * Items are NOT synced from webhooks — they are set at creation time and
+   * maintained through explicit plan change operations.
+   */
+  private async handleSubscriptionUpdated(
+    event: StandardBilling_WebhookEvent,
+    variants: BillingResolvedVariants,
+    execCtx: ExecutionContext<any>,
+  ): Promise<void> {
+    const data = event.data as Record<string, unknown>;
+    const providerSubscriptionId = data.id as string;
+    if (!providerSubscriptionId) return;
+
+    const localSub = await this.findSubscriptionByProviderId(variants.subscription, execCtx, providerSubscriptionId);
+    if (!localSub) {
+      this.log('warn', 'Subscription not found for update webhook', { providerSubscriptionId });
+      return;
+    }
+
+    await this.syncSubscriptionFromProvider(variants, execCtx, localSub._id, providerSubscriptionId);
+    // Feature sync fires automatically via post-operation hook on subscription update
+    const updatedBillingAccountId = localSub[variants.billingAccountFkField] as string;
+    if (updatedBillingAccountId) {
+      await this.emitBillingEvent(CoreWebSocketEvent.BILLING_SUBSCRIPTION_UPDATED, variants, updatedBillingAccountId, execCtx);
+    }
+  }
+
+  /**
+   * SUBSCRIPTION_DELETED: Mark as cancelled.
+   */
+  private async handleSubscriptionDeleted(
+    event: StandardBilling_WebhookEvent,
+    variants: BillingResolvedVariants,
+    execCtx: ExecutionContext<any>,
+  ): Promise<void> {
+    const data = event.data as Record<string, unknown>;
+    const providerSubscriptionId = data.id as string;
+    if (!providerSubscriptionId) return;
+
+    const localSub = await this.findSubscriptionByProviderId(variants.subscription, execCtx, providerSubscriptionId);
+    if (!localSub) return;
+
+    await this.servicesRegistry.update(variants.subscription, execCtx, localSub._id, {
+      status: SubscriptionStatus.CANCELLED,
+      cancelledAt: new Date(),
+    });
+
+    this.log('debug', 'Subscription marked as cancelled from webhook', { providerSubscriptionId });
+    // Feature sync fires automatically via post-operation hook on subscription update
+    const deletedBillingAccountId = localSub[variants.billingAccountFkField] as string;
+    if (deletedBillingAccountId) {
+      await this.emitBillingEvent(CoreWebSocketEvent.BILLING_SUBSCRIPTION_UPDATED, variants, deletedBillingAccountId, execCtx);
+    }
+  }
+
+  // ════════════════════════════════════════════════════════════════════
+  // Invoice Events
+  // ════════════════════════════════════════════════════════════════════
+
+  /**
+   * INVOICE_PAID / INVOICE_FINALIZED / INVOICE_PAYMENT_FAILED: Upsert invoice ref.
+   */
+  private async handleInvoiceEvent(
+    event: StandardBilling_WebhookEvent,
+    variants: BillingResolvedVariants,
+    execCtx: ExecutionContext<any>,
+    outcome: 'paid' | 'open' | 'failed',
+  ): Promise<void> {
+    const data = event.data as Record<string, unknown>;
+    const providerInvoiceId = data.id as string;
+    const providerCustomerId = data.customer as string;
+    if (!providerInvoiceId || !providerCustomerId) return;
+
+    // Re-lookup billing account to get its _id
+    const billingAccountId = await this.resolveBillingAccountId(variants, execCtx, providerCustomerId);
+    if (!billingAccountId) {
+      this.log('warn', 'Cannot resolve billing account for invoice event', { providerInvoiceId, providerCustomerId });
+      return;
+    }
+
+    // Map outcome to invoice status — 'failed' is not a valid InvoiceStatus, map to uncollectible
+    const invoiceStatus = outcome === 'failed' ? 'uncollectible' : outcome;
+
+    // Convert provider amount to MoneyValue
+    const rawAmount = data.amount_paid ?? data.total ?? 0;
+    const amountInCents = typeof rawAmount === 'string' ? parseInt(rawAmount, 10) || 0 : Number(rawAmount) || 0;
+    const currency = (data.currency as string) ?? 'usd';
+
+    const invoiceData: Record<string, unknown> = {
+      [variants.billingAccountFkField]: billingAccountId,
+      providerInvoiceId,
+      status: invoiceStatus,
+      total: {
+        amount: BigInt(amountInCents),
+        currency,
+        decimals: 2,
+      },
+      hostedInvoiceUrl: data.hosted_invoice_url as string | undefined,
+      invoicePdfUrl: data.invoice_pdf as string | undefined,
+    };
+
+    // Upsert: LIST by providerInvoiceId → CREATE or UPDATE
+    const existingInvoices = await this.servicesRegistry.list<{ _id: string }>(
+      variants.invoiceRef, execCtx, { providerInvoiceId },
+    ) as Array<{ _id: string }>;
+
+    if (existingInvoices.length > 0) {
+      await this.servicesRegistry.update(variants.invoiceRef, execCtx, existingInvoices[0]._id, invoiceData);
+    } else {
+      await this.servicesRegistry.create(variants.invoiceRef, execCtx, invoiceData);
+    }
+
+    this.log('debug', 'Invoice ref upserted', { providerInvoiceId, outcome });
+  }
+
+  // ════════════════════════════════════════════════════════════════════
+  // Checkout Events
+  // ════════════════════════════════════════════════════════════════════
+
+  /**
+   * CHECKOUT_SESSION_COMPLETED: Handle credit pack top-ups.
+   * For subscription products, SUBSCRIPTION_CREATED handles the subscription creation.
+   */
+  private async handleCheckoutCompleted(
+    event: StandardBilling_WebhookEvent,
+    variants: BillingResolvedVariants,
+    execCtx: ExecutionContext<any>,
+  ): Promise<void> {
+    // Idempotency: skip if this checkout session was already processed (webhook retry)
+    const checkoutSessionId = (event.data as Record<string, unknown>).id as string | undefined;
+    const dedupKey = checkoutSessionId ?? event.providerEventId;
+    if (dedupKey && this.processedCheckoutSessions.has(dedupKey)) {
+      this.log('debug', 'Skipping duplicate checkout.session.completed', { dedupKey });
+      return;
+    }
+
+    const data = event.data as Record<string, unknown>;
+    const metadata = data.metadata as Record<string, string> | undefined;
+    const productKey = metadata?.productKey;
+    const billingAccountId = metadata?.billingAccountId;
+
+    if (!billingAccountId || !productKey) {
+      this.log('debug', 'Checkout completed without billingAccountId or productKey in metadata');
+      return;
+    }
+
+    // Read product to check if it's a CREDIT_PACK
+    const products = await this.servicesRegistry.list<Product>(
+      CoreResourceType.PRODUCTS, execCtx, { key: productKey },
+    ) as Product[];
+    const product = products.length > 0 ? products[0] : null;
+
+    if (product?.type === ProductType.CREDIT_PACK && product.purchaseConfig?.creditPoolKey) {
+      const quantity = (metadata.quantity ? Number(metadata.quantity) : undefined) ?? 1;
+      const credits = (product.purchaseConfig.creditsPerUnit ?? 1) * quantity;
+      const poolKey = product.purchaseConfig.creditPoolKey;
+
+      // Find the credit pool, auto-create if first purchase
+      let pools = await this.servicesRegistry.list<CreditPool>(
+        variants.creditPool, execCtx,
+        { [variants.billingAccountFkField]: billingAccountId, poolKey },
+      ) as CreditPool[];
+
+      if (pools.length === 0) {
+        this.log('debug', 'Credit pool not found — auto-creating', { billingAccountId, poolKey });
+        const created = await this.servicesRegistry.create(
+          variants.creditPool, execCtx,
+          { [variants.billingAccountFkField]: billingAccountId, poolKey, available: 0, totalPurchased: 0, totalConsumed: 0 },
+        );
+        if (created) {
+          pools = [created as CreditPool];
+        }
+      }
+
+      if (pools.length > 0) {
+        const pool = pools[0];
+        await this.servicesRegistry.executeCustomOperation(
+          variants.creditPool,
+          CreditPool_Operations.TOP_UP,
+          execCtx,
+          pool._id,
+          { credits },
+        );
+        this.log('debug', 'Credit pack top-up completed via pipeline', {
+          billingAccountId, poolKey, credits,
+        });
+        await this.emitBillingEvent(CoreWebSocketEvent.BILLING_CREDIT_POOL_UPDATED, variants, billingAccountId, execCtx);
+      } else {
+        this.log('error', 'Failed to auto-create credit pool for top-up', {
+          billingAccountId, poolKey,
+        });
+      }
+    }
+
+    // Mark as processed for dedup
+    if (dedupKey) {
+      if (this.processedCheckoutSessions.size >= BillingWebhookEventRouterBackendService.MAX_DEDUP_ENTRIES) {
+        const first = this.processedCheckoutSessions.values().next().value;
+        if (first !== undefined) this.processedCheckoutSessions.delete(first);
+      }
+      this.processedCheckoutSessions.add(dedupKey);
+    }
+  }
+
+  // ════════════════════════════════════════════════════════════════════
+  // Customer Events
+  // ════════════════════════════════════════════════════════════════════
+
+  /**
+   * CUSTOMER_DELETED: Deactivate billing account, trigger feature sync.
+   */
+  private async handleCustomerDeleted(
+    event: StandardBilling_WebhookEvent,
+    variants: BillingResolvedVariants,
+    execCtx: ExecutionContext<any>,
+  ): Promise<void> {
+    const data = event.data as Record<string, unknown>;
+    const providerCustomerId = data.id as string;
+    if (!providerCustomerId) return;
+
+    // Find billing account by providerCustomerId in the derived variant
+    const billingAccounts = await this.servicesRegistry.list<{ _id: string }>(
+      variants.billingAccount, execCtx, { providerCustomerId },
+    ) as Array<{ _id: string }>;
+
+    if (billingAccounts.length === 0) {
+      this.log('warn', 'Billing account not found for customer.deleted', { providerCustomerId });
+      return;
+    }
+
+    const billingAccount = billingAccounts[0];
+    await this.servicesRegistry.update(variants.billingAccount, execCtx, billingAccount._id, {
+      isActive: false,
+    });
+
+    this.log('debug', 'Billing account deactivated from customer.deleted', { providerCustomerId });
+
+    await this.emitBillingEvent(CoreWebSocketEvent.BILLING_ACCOUNT_CHANGED, variants, billingAccount._id, execCtx);
+
+    // Remove all billing-derived features
+    await this.safeFeatureSync(billingAccount._id, variants);
+  }
+
+  // ════════════════════════════════════════════════════════════════════
+  // Customer Discount Events
+  // ════════════════════════════════════════════════════════════════════
+
+  /**
+   * CUSTOMER_DISCOUNT_CREATED/UPDATED/DELETED: Re-sync the affected subscription
+   * to pick up discount changes from the provider. The subscription.updated webhook
+   * usually fires alongside these events, but this handler provides a safety net.
+   */
+  private async handleCustomerDiscountEvent(
+    event: StandardBilling_WebhookEvent,
+    variants: BillingResolvedVariants,
+    execCtx: ExecutionContext<any>,
+  ): Promise<void> {
+    const data = event.data as Record<string, unknown>;
+    const subscription = data.subscription as string | undefined;
+
+    if (!subscription) {
+      this.log('debug', 'Customer discount event without subscription reference', { eventType: event.type });
+      return;
+    }
+
+    const localSub = await this.findSubscriptionByProviderId(variants.subscription, execCtx, subscription);
+    if (!localSub) {
+      this.log('debug', 'Subscription not found for discount event', { providerSubscriptionId: subscription });
+      return;
+    }
+
+    await this.syncSubscriptionFromProvider(variants, execCtx, localSub._id, subscription);
+    this.log('debug', 'Subscription re-synced after discount event', { eventType: event.type, providerSubscriptionId: subscription });
+
+    const billingAccountId = localSub[variants.billingAccountFkField] as string;
+    if (billingAccountId) {
+      await this.emitBillingEvent(CoreWebSocketEvent.BILLING_SUBSCRIPTION_UPDATED, variants, billingAccountId, execCtx);
+    }
+  }
+
+  // ════════════════════════════════════════════════════════════════════
+  // Helpers
+  // ════════════════════════════════════════════════════════════════════
+
+  /**
+   * Find a subscription by providerSubscriptionId in a specific variant collection.
+   */
+  private async findSubscriptionByProviderId(
+    subscriptionVariant: string,
+    execCtx: ExecutionContext<any>,
+    providerSubscriptionId: string,
+  ): Promise<(BillingSubscriptionBase & Record<string, unknown>) | null> {
+    try {
+      const items = await this.servicesRegistry.list<BillingSubscriptionBase>(
+        subscriptionVariant, execCtx, { providerSubscriptionId },
+      ) as Array<BillingSubscriptionBase & Record<string, unknown>>;
+      return items.length > 0 ? items[0] : null;
+    } catch (error) {
+      this.log('error', 'Failed to find subscription by provider ID', {
+        providerSubscriptionId, error: (error as Error).message,
+      });
+      return null;
+    }
+  }
+
+  /**
+   * Resolve billing account _id by providerCustomerId in the derived variant.
+   * One scoped query — not a full polymorphic lookup.
+   */
+  private async resolveBillingAccountId(
+    variants: BillingResolvedVariants,
+    execCtx: ExecutionContext<any>,
+    providerCustomerId: string,
+  ): Promise<string | null> {
+    if (!providerCustomerId) return null;
+    try {
+      const accounts = await this.servicesRegistry.list<{ _id: string }>(
+        variants.billingAccount, execCtx, { providerCustomerId },
+      ) as Array<{ _id: string }>;
+      return accounts.length > 0 ? accounts[0]._id : null;
+    } catch (error) {
+      this.log('error', 'Failed to resolve billing account by provider customer ID', {
+        providerCustomerId, error: (error as Error).message,
+      });
+      return null;
+    }
+  }
+
+  /**
+   * Sync a local subscription's status and period from the authoritative provider state.
+   * Items are NOT synced — they are set at creation time and maintained through
+   * explicit plan change operations (CHANGE_PLAN, ADD_ADDON, REMOVE_ADDON).
+   */
+  private async syncSubscriptionFromProvider(
+    variants: BillingResolvedVariants,
+    execCtx: ExecutionContext<any>,
+    localSubId: string,
+    providerSubscriptionId: string,
+  ): Promise<void> {
+    const provider = getBillingProvider();
+    const providerData = await provider.retrieveSubscription(providerSubscriptionId);
+
+    const updateData: Record<string, unknown> = {
+      status: mapProviderStatus(providerData.status as string),
+      currentPeriodStart: providerData.currentPeriodStart,
+      currentPeriodEnd: providerData.currentPeriodEnd,
+      cancelAtPeriodEnd: providerData.cancelAtPeriodEnd,
+    };
+
+    if (providerData.discount) {
+      updateData.discount = {
+        providerCouponId: providerData.discount.providerCouponId,
+        percentOff: providerData.discount.percentOff,
+        amountOff: providerData.discount.amountOff,
+        currency: providerData.discount.currency,
+        duration: providerData.discount.duration,
+        durationInMonths: providerData.discount.durationInMonths,
+        end: providerData.discount.end,
+      };
+    } else {
+      updateData.discount = null;
+    }
+
+    await this.servicesRegistry.update(variants.subscription, execCtx, localSubId, updateData);
+  }
+
+  /**
+   * Resolve provider subscription items to local schema format.
+   * Each item must have a local `_id`, `productId`, `priceId` resolved
+   * from the provider's product/price IDs via the synced catalog.
+   */
+  private async resolveSubscriptionItems(
+    providerData: StandardBilling_SubscriptionData,
+    providerSubscriptionId: string,
+    execCtx: ExecutionContext<any>,
+  ): Promise<Array<{ _id: string; productId: string; priceId: string; quantity: number; providerSubscriptionItemId?: string }>> {
+    const items: Array<{ _id: string; productId: string; priceId: string; quantity: number; providerSubscriptionItemId?: string }> = [];
+
+    for (let i = 0; i < (providerData.items ?? []).length; i++) {
+      const providerItem = providerData.items[i];
+
+      // Resolve local product by providerProductId
+      let productId: string | undefined;
+      try {
+        const products = await this.servicesRegistry.list<{ _id: string }>(
+          CoreResourceType.PRODUCTS, execCtx, { providerProductId: providerItem.providerProductId },
+        ) as Array<{ _id: string }>;
+        productId = products.length > 0 ? products[0]._id : undefined;
+      } catch {
+        this.log('warn', 'Failed to resolve product from provider ID', {
+          providerProductId: providerItem.providerProductId, providerSubscriptionId,
+        });
+      }
+
+      // Resolve local price by providerPriceId
+      let priceId: string | undefined;
+      try {
+        const prices = await this.servicesRegistry.list<{ _id: string }>(
+          CoreResourceType.PRICES, execCtx, { providerPriceId: providerItem.providerPriceId },
+        ) as Array<{ _id: string }>;
+        priceId = prices.length > 0 ? prices[0]._id : undefined;
+      } catch {
+        this.log('warn', 'Failed to resolve price from provider ID', {
+          providerPriceId: providerItem.providerPriceId, providerSubscriptionId,
+        });
+      }
+
+      if (productId && priceId) {
+        const itemIdSuffix = providerItem.providerSubscriptionItemId ?? `idx_${i}`;
+        items.push({
+          _id: `${providerSubscriptionId}_${itemIdSuffix}`,
+          productId,
+          priceId,
+          quantity: providerItem.quantity,
+          providerSubscriptionItemId: providerItem.providerSubscriptionItemId,
+        });
+      } else {
+        this.log('warn', 'Skipping subscription item — could not resolve local product/price', {
+          index: i, providerSubscriptionId,
+          providerProductId: providerItem.providerProductId,
+          providerPriceId: providerItem.providerPriceId,
+        });
+      }
+    }
+
+    return items;
+  }
+
+  /**
+   * Trigger feature sync, catching errors silently.
+   * Passes variant context so feature sync queries the correct polymorphic collections.
+   */
+  private async safeFeatureSync(billingAccountId: string, variants: BillingResolvedVariants): Promise<void> {
+    try {
+      const featureSyncService = getFeatureSyncService();
+      await featureSyncService.onSubscriptionChanged(billingAccountId, variants);
+    } catch (error) {
+      this.log('error', 'Feature sync failed after billing webhook change', {
+        billingAccountId, error: (error as Error).message,
+      });
+    }
+  }
+
+  /**
+   * Emit a billing WebSocket event for real-time frontend invalidation.
+   * Reads the billing account to resolve the scope entity ID,
+   * then dispatches to the correct scope room.
+   */
+  private async emitBillingEvent(
+    eventType: CoreWebSocketEvent,
+    variants: BillingResolvedVariants,
+    billingAccountId: string,
+    execCtx: ExecutionContext<any>,
+  ): Promise<void> {
+    if (!this.webSocketService) return;
+
+    try {
+      const accounts = await this.servicesRegistry.list<BillingAccount>(
+        variants.billingAccount, execCtx, { _id: billingAccountId },
+      ) as BillingAccount[];
+
+      const billingAccount = accounts.length > 0 ? accounts[0] : null;
+      if (!billingAccount) return;
+
+      const scopeEntityId = billingAccount[variants.scopeEntityDocField] as string;
+      if (!scopeEntityId) return;
+
+      const message = {
+        type: eventType,
+        payload: { scopeType: variants.scopeType, scopeEntityId, billingAccountId },
+        timestamp: new Date(),
+      };
+
+      switch (variants.scopeType) {
+        case ResourcePrimaryScope.ORGANIZATIONS:
+          await this.webSocketService.sendToOrganization(scopeEntityId, message);
+          break;
+        case ResourcePrimaryScope.USER_SELF:
+          await this.webSocketService.sendToUser(scopeEntityId, message);
+          break;
+      }
+
+      this.log('debug', 'Billing WebSocket event emitted', { eventType, scopeType: variants.scopeType, scopeEntityId });
+    } catch (error) {
+      this.log('warn', 'Failed to emit billing WebSocket event', {
+        eventType, billingAccountId, error: (error as Error).message,
+      });
+    }
+  }
+}