@wildo-ai/saas-backend-lib 1.0.1

package/src/billing/services/custom-impl/billing-account.mutations.custom-impl.backend.service.ts

@@ -0,0 +1,342 @@
+/**
+ * Billing Account Mutations Custom Implementations
+ *
+ * Implements CREATE, OPEN_CHECKOUT, OPEN_PORTAL operations
+ * on billing account polymorphic variants.
+ *
+ * Patterns:
+ *   CREATE        → PREFIX_CORE_OPERATIONS — PREFIX calls provider.createCustomer(), core CREATE writes to DB
+ *   OPEN_CHECKOUT → REPLACE_CORE_OPERATIONS — calls provider.createCheckoutSession(), returns { url, sessionId }
+ *   OPEN_PORTAL   → REPLACE_CORE_OPERATIONS — calls provider.createCustomerPortalSession(), returns { url }
+ *
+ * One factory per polymorphic variant (org, user) per operation.
+ *
+ * @see billing-polymorphic-full-implementation.md §4.4
+ */
+
+import {
+  CoreResourceOperation,
+  CoreResourceType,
+  ResourceOperationVariantType,
+  ResourcePrimaryScope,
+  ProductType,
+  ErrorType,
+  ErrorCustomMessageReference,
+  BillingAccount_Operations,
+  BillingAccount_OpenCheckoutRequestDto,
+  BillingAccount_OpenPortalRequestDto,
+} from '@wildo-ai/saas-models';
+import {
+  createResourceCustomServiceImplementation,
+  type ResourceCustomServiceImplementationFactory,
+} from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation.factory.backend';
+import type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+import { getBillingProvider, getBillingConfig, getBillingStateService } from '~wildo-backend-lib/billing/services/custom-impl/billing-custom-implementations.backend';
+import { readProductByKey, readPriceById, readPromotionByCode, resolveBillingVariantsFromResourceType } from '~wildo-backend-lib/billing/services/custom-impl/billing-custom-impl-utils.backend';
+
+// ── Billing account polymorphic variant types ────────────────────────
+
+const BILLING_ACCOUNT_VARIANT_TYPES = [
+  CoreResourceType.ORGANIZATION_BILLING_ACCOUNTS,
+  CoreResourceType.USER_BILLING_ACCOUNTS,
+] as const;
+
+// ════════════════════════════════════════════════════════════════════
+// CREATE — PREFIX_CORE_OPERATIONS
+// ════════════════════════════════════════════════════════════════════
+
+/**
+ * Create billing account CREATE custom impl factories for all variants.
+ *
+ * PREFIX: Creates a customer on the billing provider (Stripe), returns the create data
+ * augmented with providerCustomerId and providerRef.
+ * CORE: Standard CREATE writes to DB.
+ */
+export function createBillingAccountCreateFactories(): ResourceCustomServiceImplementationFactory[] {
+  return BILLING_ACCOUNT_VARIANT_TYPES.map((variantResourceType) => {
+    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {
+      return createResourceCustomServiceImplementation({
+        operationPath: {
+          resourceIdentifier: variantResourceType,
+          operationIdentifier: CoreResourceOperation.CREATE,
+          variantType: ResourceOperationVariantType.REPOSITORY_ONLY,
+          isOperationDefault: true,
+        },
+        handlers: {
+          prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {
+            const provider = getBillingProvider();
+            const config = getBillingConfig();
+
+            // Extract contact info from the initiator's user context
+            const userContext = utils.initiatorUserContext;
+            const email = userContext?.email || 'unknown@example.com';
+            const name = userContext?.displayName || userContext?.name || userContext?.email || 'Unknown';
+
+            const { providerCustomerId } = await provider.createCustomer({
+              email,
+              name,
+              metadata: {
+                resourceType: variantResourceType,
+                ...input.metadata,
+              },
+            });
+
+            return {
+              ...input,
+              providerCustomerId,
+              providerRef: config.providerRef || 'stripe',
+              isActive: true,
+            };
+          },
+        },
+      });
+    };
+
+    return factory as unknown as ResourceCustomServiceImplementationFactory;
+  });
+}
+
+// ════════════════════════════════════════════════════════════════════
+// OPEN_CHECKOUT — REPLACE_CORE_OPERATIONS
+// ════════════════════════════════════════════════════════════════════
+
+/**
+ * Create OPEN_CHECKOUT custom impl factories for all variants.
+ *
+ * REPLACE: Resolves the billing account, product, and price.
+ * Creates a Stripe Checkout Session and returns the redirect URL.
+ * No DB write — the subscription is created by webhook after payment.
+ */
+export function createBillingAccountOpenCheckoutFactories(): ResourceCustomServiceImplementationFactory[] {
+  return BILLING_ACCOUNT_VARIANT_TYPES.map((variantResourceType) => {
+    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {
+      return createResourceCustomServiceImplementation({
+        operationPath: {
+          resourceIdentifier: variantResourceType,
+          operationIdentifier: BillingAccount_Operations.OPEN_CHECKOUT,
+          variantType: ResourceOperationVariantType.API_CALL,
+          isOperationDefault: true,
+        },
+        requestDtoSchema: BillingAccount_OpenCheckoutRequestDto,
+        handlers: {
+          replaceCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {
+            const billingAccount = utils.currentObject;
+
+            if (!billingAccount?.providerCustomerId) {
+              throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.BILLING_NO_PROVIDER_CUSTOMER,
+                context: { billingAccountId: _id },
+              });
+            }
+
+            // Resolve product and price
+            const product = await readProductByKey(input.productKey, executionContext, utils);
+
+            // Validate product scope — prevent purchasing a product targeted at a different scope
+            const variants = resolveBillingVariantsFromResourceType(variantResourceType);
+            if (variants && product.targetScopes && !product.targetScopes.includes(variants.scopeType)) {
+              throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.BILLING_PRODUCT_SCOPE_MISMATCH,
+                context: {
+                  productKey: input.productKey,
+                  productScopes: product.targetScopes,
+                  currentScope: variants.scopeType,
+                },
+              });
+            }
+
+            const price = await readPriceById(input.priceId, executionContext, utils);
+
+            if (!price.providerPriceId) {
+              throw utils.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.BILLING_NO_PROVIDER_PRICE,
+                context: { priceId: input.priceId, productKey: input.productKey },
+              });
+            }
+
+            // Determine checkout mode based on product type
+            const isSubscription = [ProductType.PLAN, ProductType.ADDON, ProductType.METERED].includes(product.type as ProductType);
+
+            // Resolve trial days
+            const config = getBillingConfig();
+            const trialDays = input.trialDays
+              ?? product.behaviorPolicy?.trial?.days
+              ?? config.defaultBehaviorPolicy.defaultTrialDays;
+
+            // Resolve promotion code → provider promotion code ID (C1 + H3)
+            let providerPromotionCodeId: string | undefined;
+            if (input.promotionCode) {
+              const promotion = await readPromotionByCode(input.promotionCode, executionContext, utils);
+              if (!promotion) {
+                throw utils.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {
+                  customMessageReference: ErrorCustomMessageReference.BILLING_PROMOTION_NOT_FOUND,
+                  context: { code: input.promotionCode },
+                });
+              }
+
+              const now = new Date();
+              if (promotion.validFrom && now < new Date(promotion.validFrom)) {
+                throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
+                  customMessageReference: ErrorCustomMessageReference.BILLING_PROMOTION_INVALID,
+                  context: { code: input.promotionCode, reason: 'Promotion has not started yet' },
+                });
+              }
+              if (promotion.validUntil && now > new Date(promotion.validUntil)) {
+                throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
+                  customMessageReference: ErrorCustomMessageReference.BILLING_PROMOTION_INVALID,
+                  context: { code: input.promotionCode, reason: 'Promotion has expired' },
+                });
+              }
+              if (promotion.maxRedemptions !== null && promotion.maxRedemptions !== undefined) {
+                if ((promotion.timesRedeemed ?? 0) >= promotion.maxRedemptions) {
+                  throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.BILLING_PROMOTION_INVALID,
+                    context: { code: input.promotionCode, reason: 'Maximum redemptions reached' },
+                  });
+                }
+              }
+              if (promotion.applicableProducts?.length > 0 && !promotion.applicableProducts.includes(input.productKey)) {
+                throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
+                  customMessageReference: ErrorCustomMessageReference.BILLING_PROMOTION_INVALID,
+                  context: { code: input.promotionCode, reason: 'Promotion is not applicable to this product', productKey: input.productKey },
+                });
+              }
+              if (!promotion.providerPromotionId && !promotion.providerCouponId) {
+                throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
+                  customMessageReference: ErrorCustomMessageReference.BILLING_PROMOTION_INVALID,
+                  context: { code: input.promotionCode, reason: 'Promotion is not synced to billing provider' },
+                });
+              }
+              providerPromotionCodeId = promotion.providerPromotionId;
+            }
+
+            // Create checkout session on provider
+            const provider = getBillingProvider();
+            const session = await provider.createCheckoutSession({
+              providerCustomerId: billingAccount.providerCustomerId,
+              lineItems: [{ providerPriceId: price.providerPriceId, quantity: input.quantity }],
+              mode: isSubscription ? 'subscription' : 'payment',
+              successUrl: input.successUrl,
+              cancelUrl: input.cancelUrl,
+              trialPeriodDays: isSubscription && trialDays > 0 ? trialDays : undefined,
+              allowPromotionCodes: !providerPromotionCodeId,
+              providerPromotionCodeId,
+              metadata: {
+                billingAccountId: _id!,
+                productKey: input.productKey,
+                ...(input.quantity && input.quantity > 1 ? { quantity: String(input.quantity) } : {}),
+                ...input.metadata,
+              },
+            });
+
+            return { url: session.url, sessionId: session.sessionId };
+          },
+        },
+      });
+    };
+
+    return factory as unknown as ResourceCustomServiceImplementationFactory;
+  });
+}
+
+// ════════════════════════════════════════════════════════════════════
+// OPEN_PORTAL — REPLACE_CORE_OPERATIONS
+// ════════════════════════════════════════════════════════════════════
+
+/**
+ * Create OPEN_PORTAL custom impl factories for all variants.
+ *
+ * REPLACE: Resolves the billing account's providerCustomerId, creates a
+ * Stripe Customer Portal session, and returns the redirect URL.
+ * No DB write.
+ */
+export function createBillingAccountOpenPortalFactories(): ResourceCustomServiceImplementationFactory[] {
+  return BILLING_ACCOUNT_VARIANT_TYPES.map((variantResourceType) => {
+    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {
+      return createResourceCustomServiceImplementation({
+        operationPath: {
+          resourceIdentifier: variantResourceType,
+          operationIdentifier: BillingAccount_Operations.OPEN_PORTAL,
+          variantType: ResourceOperationVariantType.API_CALL,
+          isOperationDefault: true,
+        },
+        requestDtoSchema: BillingAccount_OpenPortalRequestDto,
+        handlers: {
+          replaceCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {
+            const billingAccount = utils.currentObject;
+
+            if (!billingAccount?.providerCustomerId) {
+              throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.BILLING_NO_PROVIDER_CUSTOMER,
+                context: { billingAccountId: _id },
+              });
+            }
+
+            const provider = getBillingProvider();
+            const result = await provider.createCustomerPortalSession(
+              billingAccount.providerCustomerId,
+              input.returnUrl,
+            );
+
+            return { url: result.url };
+          },
+        },
+      });
+    };
+
+    return factory as unknown as ResourceCustomServiceImplementationFactory;
+  });
+}
+
+// ════════════════════════════════════════════════════════════════════
+// GET_STATE — REPLACE_CORE_OPERATIONS (collection-level)
+// ════════════════════════════════════════════════════════════════════
+
+/**
+ * Create GET_STATE custom impl factories for all variants.
+ *
+ * REPLACE: Collection-level operation (no entity ID). Resolves scopeType
+ * and scopeEntityId from execution context, delegates to BillingStateBackendService.
+ * Returns the full aggregated billing state with automatic authorization via
+ * the engine's parent scope validation.
+ */
+export function createBillingAccountGetStateFactories(): ResourceCustomServiceImplementationFactory[] {
+  return BILLING_ACCOUNT_VARIANT_TYPES.map((variantResourceType) => {
+    const factory = (_resourcesRegistryService: ResourcesRegistryBackendService) => {
+      return createResourceCustomServiceImplementation({
+        operationPath: {
+          resourceIdentifier: variantResourceType,
+          operationIdentifier: BillingAccount_Operations.GET_STATE,
+          variantType: ResourceOperationVariantType.API_CALL,
+          isOperationDefault: true,
+        },
+        handlers: {
+          replaceCoreOperations: async (_id, _input, executionContext, _operationPath, _utils) => {
+            const variants = resolveBillingVariantsFromResourceType(variantResourceType);
+            if (!variants) {
+              throw _utils.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.BILLING_SCOPE_NOT_ENABLED,
+                context: { resourceType: variantResourceType },
+              });
+            }
+
+            const scopeEntityId = executionContext[variants.scopeKey] as string | undefined;
+            if (!scopeEntityId) {
+              throw _utils.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                context: { message: 'Missing scope entity ID in execution context', scopeKey: variants.scopeKey },
+              });
+            }
+
+            const billingConfig = getBillingConfig();
+            const enabledScopes = billingConfig.enabledScopes ?? [ResourcePrimaryScope.ORGANIZATIONS];
+
+            const billingStateService = getBillingStateService();
+            return billingStateService.getState(variants.scopeType, scopeEntityId, enabledScopes);
+          },
+        },
+      });
+    };
+
+    return factory as unknown as ResourceCustomServiceImplementationFactory;
+  });
+}

package/src/billing/services/custom-impl/billing-custom-impl-utils.backend.ts

@@ -0,0 +1,274 @@
+/**
+ * Shared helpers for billing custom implementations.
+ *
+ * Used by subscription and billing account custom impl factories,
+ * the webhook event router, and the feature sync service
+ * for cross-resource reads, provider validation, variant resolution,
+ * and feature sync.
+ */
+
+import {
+  CoreResourceType,
+  ResourcePrimaryScope,
+  ErrorType,
+  ErrorCustomMessageReference,
+} from '@wildo-ai/saas-models';
+import type { ResourceOperation_CustomImplementation_Utils } from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation-base.backend.service';
+import type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+
+// ── Credit Pool Variant Types ───────────────────────────────────────
+
+/** All credit pool polymorphic variant types (org, user). */
+export const CREDIT_POOL_VARIANT_TYPES = [
+  CoreResourceType.ORGANIZATION_CREDIT_POOLS,
+  CoreResourceType.USER_CREDIT_POOLS,
+] as const;
+
+// ── Polymorphic Variant Resolution ──────────────────────────────────
+
+/**
+ * Resolved billing polymorphic variant context.
+ *
+ * Provides the concrete resource types and FK field names for a specific
+ * billing scope (organization or user). Used by the webhook
+ * router, custom implementation postfix handlers, and the feature sync service
+ * to query the correct polymorphic collections with the correct field names.
+ */
+export interface BillingResolvedVariants {
+  /** The scope key on ExecutionContext that identifies this variant ('organizationId' | 'userId') */
+  scopeKey: string;
+  /**
+   * The scope entity FK field name as it appears on variant DOCUMENTS.
+   * May differ from `scopeKey` for some variants.
+   */
+  scopeEntityDocField: string;
+  /** The corresponding ResourcePrimaryScope value for features resource resolution */
+  scopeType: ResourcePrimaryScope;
+  /** The polymorphic FK field name on child resources (e.g., 'organizationBillingAccountId') */
+  billingAccountFkField: string;
+  /** The billing account variant resource type */
+  billingAccount: string;
+  /** The subscription variant resource type */
+  subscription: string;
+  /** The invoice ref variant resource type */
+  invoiceRef: string;
+  /** The credit pool variant resource type */
+  creditPool: string;
+  /** The usage record variant resource type */
+  usageRecord: string;
+}
+
+/**
+ * Deterministic mapping from execution context scope key to billing polymorphic variants.
+ * All billing child resources share the same scope prefix per variant.
+ */
+export const BILLING_SCOPE_TO_VARIANTS: Record<string, Omit<BillingResolvedVariants, 'scopeKey'>> = {
+  organizationId: {
+    scopeEntityDocField: 'organizationId',
+    scopeType: ResourcePrimaryScope.ORGANIZATIONS,
+    billingAccountFkField: 'organizationBillingAccountId',
+    billingAccount: CoreResourceType.ORGANIZATION_BILLING_ACCOUNTS,
+    subscription: CoreResourceType.ORGANIZATION_SUBSCRIPTIONS,
+    invoiceRef: CoreResourceType.ORGANIZATION_INVOICE_REFS,
+    creditPool: CoreResourceType.ORGANIZATION_CREDIT_POOLS,
+    usageRecord: CoreResourceType.ORGANIZATION_USAGE_RECORDS,
+  },
+  userId: {
+    scopeEntityDocField: 'userId',
+    scopeType: ResourcePrimaryScope.USER_SELF,
+    billingAccountFkField: 'userBillingAccountId',
+    billingAccount: CoreResourceType.USER_BILLING_ACCOUNTS,
+    subscription: CoreResourceType.USER_SUBSCRIPTIONS,
+    invoiceRef: CoreResourceType.USER_INVOICE_REFS,
+    creditPool: CoreResourceType.USER_CREDIT_POOLS,
+    usageRecord: CoreResourceType.USER_USAGE_RECORDS,
+  },
+};
+
+/**
+ * Resolve billing variants from an execution context's scope IDs.
+ * Returns null for APPLICATION-scoped events (no entity scope).
+ */
+export function resolveBillingVariants(execCtx: ExecutionContext<any>): BillingResolvedVariants | null {
+  if (execCtx.organizationId) return { scopeKey: 'organizationId', ...BILLING_SCOPE_TO_VARIANTS.organizationId };
+  if (execCtx.userId) return { scopeKey: 'userId', ...BILLING_SCOPE_TO_VARIANTS.userId };
+  return null;
+}
+
+/**
+ * Resolve billing variants from a known variant resource type.
+ * Used by custom implementation factories that know their variant at registration time.
+ */
+const VARIANT_TO_SCOPE_KEY: Record<string, string> = {
+  [CoreResourceType.ORGANIZATION_BILLING_ACCOUNTS]: 'organizationId',
+  [CoreResourceType.USER_BILLING_ACCOUNTS]: 'userId',
+  [CoreResourceType.ORGANIZATION_SUBSCRIPTIONS]: 'organizationId',
+  [CoreResourceType.USER_SUBSCRIPTIONS]: 'userId',
+  [CoreResourceType.ORGANIZATION_CREDIT_POOLS]: 'organizationId',
+  [CoreResourceType.USER_CREDIT_POOLS]: 'userId',
+  [CoreResourceType.ORGANIZATION_INVOICE_REFS]: 'organizationId',
+  [CoreResourceType.USER_INVOICE_REFS]: 'userId',
+  [CoreResourceType.ORGANIZATION_USAGE_RECORDS]: 'organizationId',
+  [CoreResourceType.USER_USAGE_RECORDS]: 'userId',
+};
+
+export function resolveBillingVariantsFromResourceType(variantResourceType: string): BillingResolvedVariants | null {
+  const scopeKey = VARIANT_TO_SCOPE_KEY[variantResourceType];
+  if (!scopeKey) return null;
+  return { scopeKey, ...BILLING_SCOPE_TO_VARIANTS[scopeKey] };
+}
+
+/**
+ * Reverse mapping: ResourcePrimaryScope → scope key for BILLING_SCOPE_TO_VARIANTS.
+ */
+const SCOPE_TYPE_TO_SCOPE_KEY: Record<string, string> = {
+  [ResourcePrimaryScope.ORGANIZATIONS]: 'organizationId',
+  [ResourcePrimaryScope.USER_SELF]: 'userId',
+};
+
+/**
+ * Resolve billing variants from a ResourcePrimaryScope value.
+ * Used by the billing state endpoint where the caller provides scopeType directly.
+ */
+export function resolveBillingVariantsFromScopeType(scopeType: ResourcePrimaryScope): BillingResolvedVariants | null {
+  const scopeKey = SCOPE_TYPE_TO_SCOPE_KEY[scopeType];
+  if (!scopeKey || !BILLING_SCOPE_TO_VARIANTS[scopeKey]) return null;
+  return { scopeKey, ...BILLING_SCOPE_TO_VARIANTS[scopeKey] };
+}
+
+// ── Product / Price repository reads ────────────────────────────────
+
+/**
+ * Read a product from the repository by key.
+ * Products are APPLICATION-scoped — no org/user scope filtering applies.
+ */
+export async function readProductByKey(
+  key: string,
+  executionContext: ExecutionContext<any>,
+  utils: ResourceOperation_CustomImplementation_Utils,
+): Promise<any> {
+  const productRepo = utils.repositoriesRegistry.getRepository(CoreResourceType.PRODUCTS);
+  if (!productRepo) {
+    throw utils.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+      customMessageReference: ErrorCustomMessageReference.BILLING_PRODUCT_NOT_FOUND,
+      context: { productKey: key },
+    });
+  }
+  const product = await productRepo.read(executionContext, { key });
+  if (!product) {
+    throw utils.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {
+      customMessageReference: ErrorCustomMessageReference.BILLING_PRODUCT_NOT_FOUND,
+      context: { productKey: key },
+    });
+  }
+  return product;
+}
+
+/**
+ * Read a product from the repository by ID.
+ */
+export async function readProductById(
+  productId: string,
+  executionContext: ExecutionContext<any>,
+  utils: ResourceOperation_CustomImplementation_Utils,
+): Promise<any> {
+  const productRepo = utils.repositoriesRegistry.getRepository(CoreResourceType.PRODUCTS);
+  if (!productRepo) {
+    throw utils.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+      customMessageReference: ErrorCustomMessageReference.BILLING_PRODUCT_NOT_FOUND,
+      context: { productId },
+    });
+  }
+  const product = await productRepo.read(executionContext, productId);
+  if (!product) {
+    throw utils.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {
+      customMessageReference: ErrorCustomMessageReference.BILLING_PRODUCT_NOT_FOUND,
+      context: { productId },
+    });
+  }
+  return product;
+}
+
+/**
+ * Read a price from the repository by ID.
+ * Prices are APPLICATION-scoped — no org/user scope filtering applies.
+ */
+export async function readPriceById(
+  priceId: string,
+  executionContext: ExecutionContext<any>,
+  utils: ResourceOperation_CustomImplementation_Utils,
+): Promise<any> {
+  const priceRepo = utils.repositoriesRegistry.getRepository(CoreResourceType.PRICES);
+  if (!priceRepo) {
+    throw utils.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+      customMessageReference: ErrorCustomMessageReference.BILLING_PRICE_NOT_FOUND,
+      context: { priceId },
+    });
+  }
+  const price = await priceRepo.read(executionContext, priceId);
+  if (!price) {
+    throw utils.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {
+      customMessageReference: ErrorCustomMessageReference.BILLING_PRICE_NOT_FOUND,
+      context: { priceId },
+    });
+  }
+  return price;
+}
+
+// ── Promotion resolution ────────────────────────────────────────────
+
+/**
+ * Read an active promotion from the repository by its user-facing code.
+ * Returns null if no active promotion with that code exists.
+ */
+export async function readPromotionByCode(
+  code: string,
+  executionContext: ExecutionContext<any>,
+  utils: ResourceOperation_CustomImplementation_Utils,
+): Promise<any> {
+  const promoRepo = utils.repositoriesRegistry.getRepository(CoreResourceType.PROMOTIONS);
+  if (!promoRepo) return null;
+  const promotion = await promoRepo.read(executionContext, { code, isActive: true });
+  return promotion ?? null;
+}
+
+// ── Provider validation ─────────────────────────────────────────────
+
+/**
+ * Validate that a subscription has a provider subscription ID.
+ */
+export function validateProviderSubscription(
+  subscription: any,
+  subscriptionId: string,
+  executionContext: ExecutionContext<any>,
+  utils: ResourceOperation_CustomImplementation_Utils,
+): void {
+  if (!subscription?.providerSubscriptionId) {
+    throw utils.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
+      customMessageReference: ErrorCustomMessageReference.BILLING_NO_PROVIDER_SUBSCRIPTION,
+      context: { subscriptionId },
+    });
+  }
+}
+
+// ── Provider item resolution ────────────────────────────────────────
+
+/**
+ * Resolve the providerPriceId for each subscription item by reading prices.
+ */
+export async function resolveProviderItems(
+  items: any[],
+  executionContext: ExecutionContext<any>,
+  utils: ResourceOperation_CustomImplementation_Utils,
+): Promise<Array<{ providerSubscriptionItemId?: string; providerPriceId: string; quantity: number }>> {
+  return Promise.all(
+    items.map(async (item: any) => {
+      const price = await readPriceById(item.priceId, executionContext, utils);
+      return {
+        providerSubscriptionItemId: item.providerSubscriptionItemId,
+        providerPriceId: price.providerPriceId || item.priceId,
+        quantity: item.quantity,
+      };
+    }),
+  );
+}