@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/billing/services/custom-impl/billing-account.mutations.custom-impl.backend.service.js

@@ -0,0 +1,290 @@
+/**
+ * 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, } from '../../../base-classes/services/services/resource-operation-custom-implementation.factory.backend.js';
+import { getBillingProvider, getBillingConfig, getBillingStateService } from '../../../billing/services/custom-impl/billing-custom-implementations.backend.js';
+import { readProductByKey, readPriceById, readPromotionByCode, resolveBillingVariantsFromResourceType } from '../../../billing/services/custom-impl/billing-custom-impl-utils.backend.js';
+// ── Billing account polymorphic variant types ────────────────────────
+const BILLING_ACCOUNT_VARIANT_TYPES = [
+    CoreResourceType.ORGANIZATION_BILLING_ACCOUNTS,
+    CoreResourceType.USER_BILLING_ACCOUNTS,
+];
+// ════════════════════════════════════════════════════════════════════
+// 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() {
+    return BILLING_ACCOUNT_VARIANT_TYPES.map((variantResourceType) => {
+        const factory = (_resourcesRegistryService) => {
+            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;
+    });
+}
+// ════════════════════════════════════════════════════════════════════
+// 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() {
+    return BILLING_ACCOUNT_VARIANT_TYPES.map((variantResourceType) => {
+        const factory = (_resourcesRegistryService) => {
+            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);
+                        // 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;
+                        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;
+    });
+}
+// ════════════════════════════════════════════════════════════════════
+// 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() {
+    return BILLING_ACCOUNT_VARIANT_TYPES.map((variantResourceType) => {
+        const factory = (_resourcesRegistryService) => {
+            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;
+    });
+}
+// ════════════════════════════════════════════════════════════════════
+// 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() {
+    return BILLING_ACCOUNT_VARIANT_TYPES.map((variantResourceType) => {
+        const factory = (_resourcesRegistryService) => {
+            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];
+                        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;
+    });
+}
+//# sourceMappingURL=billing-account.mutations.custom-impl.backend.service.js.map

package/dist/esm/billing/services/custom-impl/billing-account.mutations.custom-impl.backend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing-account.mutations.custom-impl.backend.service.js","sourceRoot":"","sources":["../../../../../src/billing/services/custom-impl/billing-account.mutations.custom-impl.backend.service.ts"],"names":[],"mappings":"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"}

package/dist/esm/billing/services/custom-impl/billing-custom-impl-utils.backend.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 } from '@wildo-ai/saas-models';
+import type { ResourceOperation_CustomImplementation_Utils } from '../../../base-classes/services/services/resource-operation-custom-implementation-base.backend.service.js';
+import type { ExecutionContext } from '../../../runtime/models/execution-context.backend.schemas.js';
+/** All credit pool polymorphic variant types (org, user). */
+export declare const CREDIT_POOL_VARIANT_TYPES: readonly [CoreResourceType.ORGANIZATION_CREDIT_POOLS, CoreResourceType.USER_CREDIT_POOLS];
+/**
+ * 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 declare const BILLING_SCOPE_TO_VARIANTS: Record<string, Omit<BillingResolvedVariants, 'scopeKey'>>;
+/**
+ * Resolve billing variants from an execution context's scope IDs.
+ * Returns null for APPLICATION-scoped events (no entity scope).
+ */
+export declare function resolveBillingVariants(execCtx: ExecutionContext<any>): BillingResolvedVariants | null;
+export declare function resolveBillingVariantsFromResourceType(variantResourceType: string): BillingResolvedVariants | null;
+/**
+ * Resolve billing variants from a ResourcePrimaryScope value.
+ * Used by the billing state endpoint where the caller provides scopeType directly.
+ */
+export declare function resolveBillingVariantsFromScopeType(scopeType: ResourcePrimaryScope): BillingResolvedVariants | null;
+/**
+ * Read a product from the repository by key.
+ * Products are APPLICATION-scoped — no org/user scope filtering applies.
+ */
+export declare function readProductByKey(key: string, executionContext: ExecutionContext<any>, utils: ResourceOperation_CustomImplementation_Utils): Promise<any>;
+/**
+ * Read a product from the repository by ID.
+ */
+export declare function readProductById(productId: string, executionContext: ExecutionContext<any>, utils: ResourceOperation_CustomImplementation_Utils): Promise<any>;
+/**
+ * Read a price from the repository by ID.
+ * Prices are APPLICATION-scoped — no org/user scope filtering applies.
+ */
+export declare function readPriceById(priceId: string, executionContext: ExecutionContext<any>, utils: ResourceOperation_CustomImplementation_Utils): Promise<any>;
+/**
+ * Read an active promotion from the repository by its user-facing code.
+ * Returns null if no active promotion with that code exists.
+ */
+export declare function readPromotionByCode(code: string, executionContext: ExecutionContext<any>, utils: ResourceOperation_CustomImplementation_Utils): Promise<any>;
+/**
+ * Validate that a subscription has a provider subscription ID.
+ */
+export declare function validateProviderSubscription(subscription: any, subscriptionId: string, executionContext: ExecutionContext<any>, utils: ResourceOperation_CustomImplementation_Utils): void;
+/**
+ * Resolve the providerPriceId for each subscription item by reading prices.
+ */
+export declare function resolveProviderItems(items: any[], executionContext: ExecutionContext<any>, utils: ResourceOperation_CustomImplementation_Utils): Promise<Array<{
+    providerSubscriptionItemId?: string;
+    providerPriceId: string;
+    quantity: number;
+}>>;
+//# sourceMappingURL=billing-custom-impl-utils.backend.d.ts.map

package/dist/esm/billing/services/custom-impl/billing-custom-impl-utils.backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing-custom-impl-utils.backend.d.ts","sourceRoot":"","sources":["../../../../../src/billing/services/custom-impl/billing-custom-impl-utils.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EAGrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,4CAA4C,EAAE,MAAM,iHAAiH,CAAC;AACpL,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qEAAqE,CAAC;AAI5G,6DAA6D;AAC7D,eAAO,MAAM,yBAAyB,2FAG5B,CAAC;AAIX;;;;;;;GAOG;AACH,MAAM,WAAW,uBAAuB;IACtC,mGAAmG;IACnG,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oFAAoF;IACpF,SAAS,EAAE,oBAAoB,CAAC;IAChC,8FAA8F;IAC9F,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,uBAAuB,EAAE,UAAU,CAAC,CAqB/F,CAAC;AAEF;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,GAAG,uBAAuB,GAAG,IAAI,CAIrG;AAmBD,wBAAgB,sCAAsC,CAAC,mBAAmB,EAAE,MAAM,GAAG,uBAAuB,GAAG,IAAI,CAIlH;AAUD;;;GAGG;AACH,wBAAgB,mCAAmC,CAAC,SAAS,EAAE,oBAAoB,GAAG,uBAAuB,GAAG,IAAI,CAInH;AAID;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACvC,KAAK,EAAE,4CAA4C,GAClD,OAAO,CAAC,GAAG,CAAC,CAgBd;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACvC,KAAK,EAAE,4CAA4C,GAClD,OAAO,CAAC,GAAG,CAAC,CAgBd;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACvC,KAAK,EAAE,4CAA4C,GAClD,OAAO,CAAC,GAAG,CAAC,CAgBd;AAID;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACvC,KAAK,EAAE,4CAA4C,GAClD,OAAO,CAAC,GAAG,CAAC,CAKd;AAID;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,YAAY,EAAE,GAAG,EACjB,cAAc,EAAE,MAAM,EACtB,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACvC,KAAK,EAAE,4CAA4C,GAClD,IAAI,CAON;AAID;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,GAAG,EAAE,EACZ,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACvC,KAAK,EAAE,4CAA4C,GAClD,OAAO,CAAC,KAAK,CAAC;IAAE,0BAA0B,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAWpG"}

package/dist/esm/billing/services/custom-impl/billing-custom-impl-utils.backend.js

@@ -0,0 +1,193 @@
+/**
+ * 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';
+// ── 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,
+];
+/**
+ * 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 = {
+    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) {
+    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 = {
+    [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) {
+    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 = {
+    [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) {
+    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, executionContext, utils) {
+    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, executionContext, utils) {
+    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, executionContext, utils) {
+    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, executionContext, utils) {
+    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, subscriptionId, executionContext, utils) {
+    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, executionContext, utils) {
+    return Promise.all(items.map(async (item) => {
+        const price = await readPriceById(item.priceId, executionContext, utils);
+        return {
+            providerSubscriptionItemId: item.providerSubscriptionItemId,
+            providerPriceId: price.providerPriceId || item.priceId,
+            quantity: item.quantity,
+        };
+    }));
+}
+//# sourceMappingURL=billing-custom-impl-utils.backend.js.map

package/dist/esm/billing/services/custom-impl/billing-custom-impl-utils.backend.js.map

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