rerobe-js-orm 4.8.8 → 4.9.0

package/lib/helpers/MarketplaceProductHelpers.js

@@ -0,0 +1,555 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarketplaceOwnershipError = exports.MarketplaceCommissionRateError = void 0;
+const ReRobeProductHelpers_1 = require("./ReRobeProductHelpers");
+const marketplace_constants_1 = require("../constants/marketplace-constants");
+const CommissionPolicyRegistry = require("./marketplace/CommissionPolicyRegistry");
+const FeeAllocationPolicyRegistry = require("./marketplace/FeeAllocationPolicyRegistry");
+const InventoryPolicyRegistry = require("./marketplace/InventoryPolicyRegistry");
+var MarketplaceErrors_1 = require("./marketplace/MarketplaceErrors");
+Object.defineProperty(exports, "MarketplaceCommissionRateError", { enumerable: true, get: function () { return MarketplaceErrors_1.MarketplaceCommissionRateError; } });
+Object.defineProperty(exports, "MarketplaceOwnershipError", { enumerable: true, get: function () { return MarketplaceErrors_1.MarketplaceOwnershipError; } });
+const MarketplaceErrors_2 = require("./marketplace/MarketplaceErrors");
+const roundMoney = (value) => Number(Number(value || 0).toFixed(2));
+const normalizeVariantOptionsInput = (options) => {
+    if (!options)
+        return undefined;
+    if (Array.isArray(options)) {
+        const normalized = options.reduce((acc, option) => {
+            const key = (option === null || option === void 0 ? void 0 : option.name) || (option === null || option === void 0 ? void 0 : option.key) || (option === null || option === void 0 ? void 0 : option.label) || '';
+            const value = option === null || option === void 0 ? void 0 : option.value;
+            if (key && value !== undefined && value !== null && String(value).trim()) {
+                acc[String(key)] = String(value);
+            }
+            return acc;
+        }, {});
+        return Object.keys(normalized).length ? normalized : undefined;
+    }
+    if (typeof options === 'object')
+        return options;
+    return undefined;
+};
+// Pulls a `VariantSelectionInput` out of an order line item, supporting the
+// shapes the backend currently produces:
+//   - `lineItem.variant.id`            (canonical ReRobe lines)
+//   - `lineItem.variantId`             (flattened shape some callers emit)
+//   - `lineItem.variant.options`       (options-map lines used by the form-state)
+//   - `lineItem.selectedOptions`       (Shopify/storefront shape we ingest)
+// Returns `undefined` when nothing variant-shaped is present so call-sites
+// fall back to product-level pricing/snapshotting without surprises.
+const deriveVariantSelectionFromLineItem = (lineItem) => {
+    if (!lineItem || typeof lineItem !== 'object')
+        return undefined;
+    const variantId = (lineItem.variant && lineItem.variant.id) ||
+        lineItem.variantId ||
+        (lineItem.variant && lineItem.variant.variantId) ||
+        '';
+    const options = (lineItem.variant && lineItem.variant.options) || lineItem.variantOptions || lineItem.selectedOptions || undefined;
+    const normalizedOptions = normalizeVariantOptionsInput(options);
+    if (!variantId && !normalizedOptions)
+        return undefined;
+    const selection = {};
+    if (variantId)
+        selection.variantId = String(variantId);
+    if (normalizedOptions)
+        selection.options = normalizedOptions;
+    return selection;
+};
+class MarketplaceProductHelpers {
+    static registerCommissionPolicy(policy) {
+        CommissionPolicyRegistry.register(policy);
+    }
+    static getCommissionPolicy(basis) {
+        return CommissionPolicyRegistry.get(basis);
+    }
+    static hasCommissionPolicy(basis) {
+        return CommissionPolicyRegistry.has(basis);
+    }
+    static emptyMarketplace() {
+        return {
+            visibleToMerchantIds: [],
+            listings: {},
+        };
+    }
+    static uniqueStrings(values = []) {
+        return Array.from(new Set((Array.isArray(values) ? values : [])
+            .filter((v) => v !== undefined && v !== null && String(v).trim())
+            .map((v) => String(v))));
+    }
+    static normalizeMarketplace(input) {
+        const visibleToMerchantIds = this.uniqueStrings((input === null || input === void 0 ? void 0 : input.visibleToMerchantIds) || []);
+        const rawListings = (input === null || input === void 0 ? void 0 : input.listings) && typeof input.listings === 'object' ? input.listings : {};
+        const listings = Object.keys(rawListings).reduce((acc, parentMarketplaceId) => {
+            const listing = rawListings[parentMarketplaceId] || {};
+            if (!parentMarketplaceId)
+                return acc;
+            acc[parentMarketplaceId] = {
+                relationshipId: String(listing.relationshipId || ''),
+                relationshipType: String(listing.relationshipType || ''),
+                status: String(listing.status || marketplace_constants_1.DEFAULT_MARKETPLACE_LISTING_STATUS),
+                listedAt: listing.listedAt === undefined || listing.listedAt === null ? null : Number(listing.listedAt),
+                updatedAt: listing.updatedAt === undefined || listing.updatedAt === null ? null : Number(listing.updatedAt),
+            };
+            return acc;
+        }, {});
+        return {
+            visibleToMerchantIds,
+            listings,
+        };
+    }
+    static buildMarketplace({ productMerchantId = '', listings = [], }) {
+        const normalizedListings = listings.reduce((acc, listing) => {
+            if (!(listing === null || listing === void 0 ? void 0 : listing.parentMarketplaceId))
+                return acc;
+            acc[listing.parentMarketplaceId] = {
+                relationshipId: String(listing.relationshipId || ''),
+                relationshipType: String(listing.relationshipType || marketplace_constants_1.DEFAULT_MARKETPLACE_RELATIONSHIP_TYPE),
+                status: String(listing.status || marketplace_constants_1.DEFAULT_MARKETPLACE_LISTING_STATUS),
+                listedAt: listing.listedAt === undefined || listing.listedAt === null ? null : Number(listing.listedAt),
+                updatedAt: listing.updatedAt === undefined || listing.updatedAt === null ? null : Number(listing.updatedAt),
+            };
+            return acc;
+        }, {});
+        const activeParentIds = Object.keys(normalizedListings).filter((parentId) => { var _a; return ((_a = normalizedListings[parentId]) === null || _a === void 0 ? void 0 : _a.status) !== marketplace_constants_1.MARKETPLACE_LISTING_STATUSES.removed; });
+        return {
+            visibleToMerchantIds: this.uniqueStrings([productMerchantId, ...activeParentIds]),
+            listings: normalizedListings,
+        };
+    }
+    static buildTypesenseFields(marketplace) {
+        const normalized = this.normalizeMarketplace(marketplace);
+        const marketplaceParentMerchantIds = Object.keys(normalized.listings).filter((parentId) => { var _a; return ((_a = normalized.listings[parentId]) === null || _a === void 0 ? void 0 : _a.status) !== marketplace_constants_1.MARKETPLACE_LISTING_STATUSES.removed; });
+        const marketplaceRelationshipIds = this.uniqueStrings(marketplaceParentMerchantIds.map((parentId) => { var _a; return (_a = normalized.listings[parentId]) === null || _a === void 0 ? void 0 : _a.relationshipId; }));
+        return {
+            marketplaceVisibleToMerchantIds: this.uniqueStrings(normalized.visibleToMerchantIds),
+            marketplaceParentMerchantIds,
+            marketplaceRelationshipIds,
+            isMarketplaceVisible: marketplaceParentMerchantIds.length > 0,
+        };
+    }
+    static toRate(value) {
+        return Number(ReRobeProductHelpers_1.default.commissionFixer(value === undefined || value === null ? '0' : value));
+    }
+    static roundMoney(value) {
+        return roundMoney(value);
+    }
+    static lineNetFromProduct(product, quantity = 1, variant) {
+        const priceSource = (variant === null || variant === void 0 ? void 0 : variant.isOnSale) === 'yes' && variant.salePrice ? variant.salePrice : variant === null || variant === void 0 ? void 0 : variant.price;
+        const productPriceSource = product.isOnSale === 'yes' && Boolean(product.clearanceTimestamp) && product.salePrice
+            ? product.salePrice
+            : product.price;
+        const unitPrice = Number(priceSource || productPriceSource || 0);
+        return roundMoney(unitPrice * (quantity || 1));
+    }
+    static selectVariant(product, selection = {}) {
+        const variants = Array.isArray(product.variantInventory) ? product.variantInventory : [];
+        if (!variants.length)
+            return null;
+        const variant = variants.find((v) => selection.variantId && (v === null || v === void 0 ? void 0 : v.id) === selection.variantId) ||
+            variants.find((v) => {
+                if (!selection.options)
+                    return false;
+                const optionKeys = Object.keys(selection.options);
+                return optionKeys.every((key) => { var _a, _b; return ((_a = v === null || v === void 0 ? void 0 : v.options) === null || _a === void 0 ? void 0 : _a[key]) === ((_b = selection.options) === null || _b === void 0 ? void 0 : _b[key]); });
+            }) ||
+            null;
+        if (!variant)
+            return null;
+        return {
+            variantId: String(variant.id || ''),
+            sku: String(variant.sku || product.sku || ''),
+            options: variant.options || {},
+            price: String(variant.price || product.price || ''),
+            compareAtPrice: variant.compareAtPrice || null,
+            salePrice: variant.salePrice || null,
+            isOnSale: variant.isOnSale || null,
+            taxable: variant.taxable || (product.isTaxable === 'yes' ? 'yes' : product.isTaxable === 'no' ? 'no' : null),
+            taxCategory: String(product.taxCategory || 'STANDARD'),
+            locations: Array.isArray(variant.locations)
+                ? variant.locations.map((loc) => (Object.assign(Object.assign({}, loc), { availableAmount: Number(loc === null || loc === void 0 ? void 0 : loc.availableAmount) || 0, incomingAmount: Number(loc === null || loc === void 0 ? void 0 : loc.incomingAmount) || 0 })))
+                : [],
+        };
+    }
+    static buildLineSnapshot({ product, parentMerchantId, managedMerchantId, relationshipId, sellerDisplayName, lineDisplayTitle, marketplaceCommissionRate, originalProductCommissionRate, marketplaceCommissionBasis = marketplace_constants_1.DEFAULT_MARKETPLACE_COMMISSION_BASIS, quantity = 1, currencyCode = '', discountAmount = 0, taxAmount = 0, stripeFeeAllocatedAmount = 0, ribbnFeeAllocatedAmount = 0, variantSelection = {}, }) {
+        const variant = this.selectVariant(product, variantSelection);
+        const q = Number(quantity) > 0 ? Number(quantity) : 1;
+        const lineNetAmount = this.lineNetFromProduct(product, q, variant || undefined);
+        const safeDiscount = roundMoney(Math.max(0, Number(discountAmount) || 0));
+        const taxableAmount = roundMoney(Math.max(0, lineNetAmount - safeDiscount));
+        const safeTax = roundMoney(Number(taxAmount) || 0);
+        const lineGrossAmount = roundMoney(taxableAmount + safeTax);
+        const originalRate = this.toRate(originalProductCommissionRate === undefined ? product.reRobeCommission || '0' : originalProductCommissionRate);
+        const marketplaceRate = this.toRate(marketplaceCommissionRate);
+        const safeStripeFee = roundMoney(Number(stripeFeeAllocatedAmount) || 0);
+        const safeRibbnFee = roundMoney(Number(ribbnFeeAllocatedAmount) || 0);
+        const policy = this.getCommissionPolicy(marketplaceCommissionBasis);
+        const policyResult = policy.calculate({ taxableAmount, originalRate, marketplaceRate }, { stripeFee: safeStripeFee, ribbnFee: safeRibbnFee });
+        const marketplaceProceedsAmount = roundMoney(policyResult.marketplaceCommissionAmount + safeStripeFee);
+        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ isMarketplaceItem: true, parentMerchantId: String(parentMerchantId || ''), managedMerchantId: String(managedMerchantId || product.merchantId || product.vendorId || ''), relationshipId: String(relationshipId || ''), productId: String(product.documentId || '') }, ((variant === null || variant === void 0 ? void 0 : variant.variantId) ? { variantId: variant.variantId } : {})), (sellerDisplayName ? { sellerDisplayName: String(sellerDisplayName) } : {})), (lineDisplayTitle ? { lineDisplayTitle: String(lineDisplayTitle) } : {})), { originalProductCommissionRate: String(originalRate), marketplaceCommissionRate: String(marketplaceRate), marketplaceCommissionBasis: policy.basis, quantity: q, currencyCode, amounts: {
+                lineNetAmount,
+                discountAmount: safeDiscount,
+                taxableAmount,
+                taxAmount: safeTax,
+                lineGrossAmount,
+                originalProductCommissionAmount: policyResult.originalProductCommissionAmount,
+                marketplaceCommissionAmount: policyResult.marketplaceCommissionAmount,
+                stripeFeeAllocatedAmount: safeStripeFee,
+                ribbnFeeAllocatedAmount: safeRibbnFee,
+                sellerProceedsAmount: policyResult.sellerProceedsAmount,
+                managedMerchantProceedsAmount: policyResult.managedMerchantProceedsAmount,
+                marketplaceProceedsAmount,
+            } }), (variant ? { variant } : {}));
+    }
+    // Derives a `VariantSelectionInput` from an order line item. Exposed so
+    // backend/web callers that load a product separately can resolve variant
+    // identity from a line item without re-implementing the shape juggling
+    // (canonical `variant.id` vs. flattened `variantId` vs. options maps).
+    static deriveVariantSelectionFromLineItem(lineItem) {
+        return deriveVariantSelectionFromLineItem(lineItem);
+    }
+    static buildLineSnapshotFromListing({ product, parentMerchantId, relationship = null, lineItem = {}, quantity, currencyCode, marketplaceCommissionRate, originalProductCommissionRate, marketplaceCommissionBasis, discountAmount, taxAmount, stripeFeeAllocatedAmount = 0, ribbnFeeAllocatedAmount = 0, variantSelection, }) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+        if (!product || !parentMerchantId)
+            return null;
+        const managedMerchantId = String(product.merchantId || product.vendorId || '');
+        if (!managedMerchantId || managedMerchantId === parentMerchantId)
+            return null;
+        const marketplace = this.normalizeMarketplace(product.marketplace);
+        const listing = marketplace.listings[parentMerchantId];
+        if (!listing || listing.status === marketplace_constants_1.MARKETPLACE_LISTING_STATUSES.removed) {
+            return null;
+        }
+        const q = Number(quantity !== null && quantity !== void 0 ? quantity : lineItem === null || lineItem === void 0 ? void 0 : lineItem.quantity) > 0 ? Number(quantity !== null && quantity !== void 0 ? quantity : lineItem === null || lineItem === void 0 ? void 0 : lineItem.quantity) : 1;
+        const originalAmount = Number((_a = lineItem === null || lineItem === void 0 ? void 0 : lineItem.originalTotalPrice) === null || _a === void 0 ? void 0 : _a.amount);
+        const discountedAmount = Number((_b = lineItem === null || lineItem === void 0 ? void 0 : lineItem.discountedPrice) === null || _b === void 0 ? void 0 : _b.amount);
+        const safeOriginal = Number.isFinite(originalAmount) ? originalAmount : this.lineNetFromProduct(product, q);
+        const safeDiscounted = Number.isFinite(discountedAmount) ? discountedAmount : safeOriginal;
+        const resolvedDiscount = discountAmount === undefined ? Math.max(0, safeOriginal - safeDiscounted) : Number(discountAmount) || 0;
+        const resolvedTax = taxAmount === undefined
+            ? Number((_f = (_d = (_c = lineItem === null || lineItem === void 0 ? void 0 : lineItem.taxAmount) === null || _c === void 0 ? void 0 : _c.amount) !== null && _d !== void 0 ? _d : (_e = lineItem === null || lineItem === void 0 ? void 0 : lineItem.taxAmountWithDiscount) === null || _e === void 0 ? void 0 : _e.amount) !== null && _f !== void 0 ? _f : 0) || 0
+            : Number(taxAmount) || 0;
+        const resolvedCurrency = currencyCode ||
+            ((_g = lineItem === null || lineItem === void 0 ? void 0 : lineItem.originalTotalPrice) === null || _g === void 0 ? void 0 : _g.currencyCode) ||
+            ((_h = lineItem === null || lineItem === void 0 ? void 0 : lineItem.discountedPrice) === null || _h === void 0 ? void 0 : _h.currencyCode) ||
+            ((_j = lineItem === null || lineItem === void 0 ? void 0 : lineItem.presentmentTotalPrice) === null || _j === void 0 ? void 0 : _j.currencyCode) ||
+            '';
+        const resolvedCommission = marketplaceCommissionRate === undefined || marketplaceCommissionRate === null
+            ? (_k = relationship === null || relationship === void 0 ? void 0 : relationship.marketplaceCommission) !== null && _k !== void 0 ? _k : '0'
+            : marketplaceCommissionRate;
+        const resolvedVariantSelection = variantSelection && (variantSelection.variantId || variantSelection.options)
+            ? variantSelection
+            : deriveVariantSelectionFromLineItem(lineItem) || {};
+        return this.buildLineSnapshot({
+            product,
+            parentMerchantId,
+            managedMerchantId,
+            relationshipId: String((relationship === null || relationship === void 0 ? void 0 : relationship.documentId) || listing.relationshipId || ''),
+            sellerDisplayName: String(product.vendorName || ''),
+            lineDisplayTitle: String(product.title || product.brand || ''),
+            marketplaceCommissionRate: resolvedCommission,
+            originalProductCommissionRate,
+            marketplaceCommissionBasis: marketplaceCommissionBasis || (relationship === null || relationship === void 0 ? void 0 : relationship.marketplaceCommissionBasis) || marketplace_constants_1.DEFAULT_MARKETPLACE_COMMISSION_BASIS,
+            quantity: q,
+            currencyCode: resolvedCurrency,
+            discountAmount: resolvedDiscount,
+            taxAmount: resolvedTax,
+            stripeFeeAllocatedAmount,
+            ribbnFeeAllocatedAmount,
+            variantSelection: resolvedVariantSelection,
+        });
+    }
+    static prorateAmounts(amounts, ratio) {
+        const safeRatio = Math.max(0, Math.min(1, Number(ratio) || 0));
+        return Object.keys(amounts).reduce((acc, key) => {
+            acc[key] = roundMoney(Number(amounts[key] || 0) * safeRatio);
+            return acc;
+        }, {});
+    }
+    static buildReturnAdjustment({ snapshot, quantityReturned }) {
+        // Use nullish coalescing so an explicit 0 means "no quantity returned"
+        // (zero-amount adjustment), while undefined/null still defaults to the
+        // full snapshot quantity (used by the post-payout refund flow).
+        const requested = quantityReturned === undefined || quantityReturned === null ? snapshot.quantity : Number(quantityReturned);
+        const returned = Math.max(0, Math.min(requested, snapshot.quantity));
+        const ratio = snapshot.quantity > 0 ? returned / snapshot.quantity : 0;
+        return {
+            quantityReturned: returned,
+            amounts: this.prorateAmounts(snapshot.amounts, ratio),
+            remainingQuantity: snapshot.quantity - returned,
+        };
+    }
+    static transformVariantInventory({ product, variantId, locationId = '', quantity = 1 }, direction) {
+        const variants = Array.isArray(product.variantInventory) ? product.variantInventory : [];
+        const qty = Math.max(0, Number(quantity) || 0);
+        return variants.map((variant) => {
+            if (variant.id !== variantId)
+                return variant;
+            const locations = Array.isArray(variant.locations) ? variant.locations : [];
+            const nextLocations = locations.map((loc, index) => {
+                if (locationId && loc.id !== locationId)
+                    return loc;
+                if (!locationId && index > 0)
+                    return loc;
+                const availableAmount = Number(loc.availableAmount) || 0;
+                return Object.assign(Object.assign({}, loc), { availableAmount: direction === 'restore' ? availableAmount + qty : Math.max(0, availableAmount - qty) });
+            });
+            return Object.assign(Object.assign({}, variant), { locations: nextLocations });
+        });
+    }
+    static decrementVariantInventory(params) {
+        return this.transformVariantInventory(params, 'decrement');
+    }
+    static restoreVariantInventory(params) {
+        return this.transformVariantInventory(params, 'restore');
+    }
+    // ---------------------------------------------------------------------
+    // Inventory dispatch (delegates to the InventoryPolicy registry)
+    // ---------------------------------------------------------------------
+    static registerInventoryPolicy(policy, position = 'append') {
+        InventoryPolicyRegistry.register(policy, position);
+    }
+    static findInventoryPolicy(product) {
+        return InventoryPolicyRegistry.find(product);
+    }
+    static adjustInventory(product, params, direction) {
+        if (!product)
+            return {};
+        const policy = InventoryPolicyRegistry.find(product);
+        if (!policy)
+            return {};
+        return direction === 'restore' ? policy.restore(product, params) : policy.decrement(product, params);
+    }
+    // Single entry point backend callers use to adjust inventory for one order
+    // line. Resolves `variantId` and `quantity` from the line item itself when
+    // not passed explicitly, derives variant identity from the same shapes
+    // `buildLineSnapshotFromListing` supports, then dispatches through the
+    // policy registry. The `defaultLocationId` (typically a merchant's default
+    // fulfillment location) is honored by both the multivariant and
+    // one-of-a-kind policies when no explicit `locationId` is supplied.
+    static adjustVariantInventoryForLine(product, { lineItem = {}, variantId, locationId, defaultLocationId, quantity, }, direction = 'decrement') {
+        if (!product)
+            return {};
+        const inferred = deriveVariantSelectionFromLineItem(lineItem) || {};
+        const inferredVariant = !variantId && !inferred.variantId ? this.selectVariant(product, inferred) : null;
+        const resolvedVariantId = String(variantId || inferred.variantId || (inferredVariant === null || inferredVariant === void 0 ? void 0 : inferredVariant.variantId) || '');
+        const quantityInput = quantity === undefined ? lineItem === null || lineItem === void 0 ? void 0 : lineItem.quantity : quantity;
+        const lineQty = Number(quantityInput);
+        const resolvedQuantity = quantityInput === undefined || quantityInput === null || !Number.isFinite(lineQty) ? 1 : Math.max(0, lineQty);
+        return this.adjustInventory(product, {
+            variantId: resolvedVariantId,
+            locationId: locationId || '',
+            defaultLocationId: defaultLocationId || '',
+            quantity: resolvedQuantity,
+        }, direction);
+    }
+    // ---------------------------------------------------------------------
+    // Fee allocation (delegates to the FeeAllocationPolicy registry)
+    // ---------------------------------------------------------------------
+    static registerFeeAllocationPolicy(policy) {
+        FeeAllocationPolicyRegistry.register(policy);
+    }
+    static getFeeAllocationPolicy(basis) {
+        return FeeAllocationPolicyRegistry.get(basis);
+    }
+    static allocateFee(context, basis = marketplace_constants_1.DEFAULT_STRIPE_FEE_ALLOCATION_BASIS) {
+        const policy = FeeAllocationPolicyRegistry.get(basis);
+        return policy.allocate(context);
+    }
+    static allocateStripeFee(context) {
+        return this.allocateFee(context, marketplace_constants_1.DEFAULT_STRIPE_FEE_ALLOCATION_BASIS);
+    }
+    static allocateRibbnFee(context) {
+        return this.allocateFee(context, marketplace_constants_1.DEFAULT_RIBBN_FEE_ALLOCATION_BASIS);
+    }
+    static buildFeeBasketFromProducts({ merchantId, products = [], }) {
+        return (Array.isArray(products) ? products : []).map((product, index) => ({
+            lineKey: `${String((product === null || product === void 0 ? void 0 : product.documentId) || 'product')}:${index}`,
+            sellerMerchantId: String((product === null || product === void 0 ? void 0 : product.vendorId) || (product === null || product === void 0 ? void 0 : product.merchantId) || ''),
+            lineNetAmount: (product === null || product === void 0 ? void 0 : product.vendorId) && product.vendorId !== merchantId ? Number((product === null || product === void 0 ? void 0 : product.salePrice) || (product === null || product === void 0 ? void 0 : product.price) || 0) : 0,
+            quantity: 1,
+        }));
+    }
+    static applyStripeFeeRecoupBumpToProducts({ merchantId, products = [], totalFeeAmount, basis = marketplace_constants_1.DEFAULT_STRIPE_FEE_ALLOCATION_BASIS, }) {
+        if (!merchantId || !Array.isArray(products) || products.length === 0) {
+            return products;
+        }
+        const safeTotal = Number(totalFeeAmount);
+        if (!Number.isFinite(safeTotal) || safeTotal <= 0) {
+            return products;
+        }
+        const basket = this.buildFeeBasketFromProducts({ merchantId, products });
+        const allocationsByLineKey = this.allocateFee({ totalFeeAmount: safeTotal, basket }, basis).reduce((acc, allocation) => {
+            acc[allocation.lineKey] = Number(allocation.amount || 0);
+            return acc;
+        }, {});
+        return products.map((product, index) => {
+            const sellerId = String((product === null || product === void 0 ? void 0 : product.vendorId) || (product === null || product === void 0 ? void 0 : product.merchantId) || '');
+            if (!sellerId || sellerId === merchantId)
+                return product;
+            const linePrice = Number((product === null || product === void 0 ? void 0 : product.salePrice) || (product === null || product === void 0 ? void 0 : product.price) || 0);
+            if (!Number.isFinite(linePrice) || linePrice <= 0)
+                return product;
+            const lineKey = `${String((product === null || product === void 0 ? void 0 : product.documentId) || 'product')}:${index}`;
+            const allocatedFee = Number(allocationsByLineKey[lineKey] || 0);
+            if (!allocatedFee)
+                return product;
+            const baseCommission = Number((product === null || product === void 0 ? void 0 : product.reRobeCommission) || 0);
+            const effective = baseCommission + allocatedFee / linePrice;
+            return Object.assign(Object.assign({}, product), { reRobeCommission: String(Number(effective.toFixed(6))) });
+        });
+    }
+    // ---------------------------------------------------------------------
+    // Listing transitions (immutable updates that bump updatedAt)
+    // ---------------------------------------------------------------------
+    static upsertListing(marketplace, parentMarketplaceId, partial = {}, options = {}) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        if (!parentMarketplaceId) {
+            return this.normalizeMarketplace(marketplace);
+        }
+        const ts = typeof options.at === 'number' ? options.at : Date.now();
+        const current = this.normalizeMarketplace(marketplace);
+        const existing = current.listings[parentMarketplaceId];
+        const ownerMerchantId = partial.ownerMerchantId || '';
+        const nextListing = {
+            relationshipId: String((_b = (_a = partial.relationshipId) !== null && _a !== void 0 ? _a : existing === null || existing === void 0 ? void 0 : existing.relationshipId) !== null && _b !== void 0 ? _b : ''),
+            relationshipType: String((_d = (_c = partial.relationshipType) !== null && _c !== void 0 ? _c : existing === null || existing === void 0 ? void 0 : existing.relationshipType) !== null && _d !== void 0 ? _d : marketplace_constants_1.MARKETPLACE_RELATIONSHIP_TYPES.marketplaceSeller),
+            status: String((_f = (_e = partial.status) !== null && _e !== void 0 ? _e : existing === null || existing === void 0 ? void 0 : existing.status) !== null && _f !== void 0 ? _f : marketplace_constants_1.DEFAULT_MARKETPLACE_LISTING_STATUS),
+            listedAt: (_g = existing === null || existing === void 0 ? void 0 : existing.listedAt) !== null && _g !== void 0 ? _g : (partial.listedAt === undefined ? ts : partial.listedAt),
+            updatedAt: ts,
+        };
+        const nextListings = Object.assign(Object.assign({}, current.listings), { [parentMarketplaceId]: nextListing });
+        const activeParentIds = Object.keys(nextListings).filter((id) => { var _a; return ((_a = nextListings[id]) === null || _a === void 0 ? void 0 : _a.status) !== marketplace_constants_1.MARKETPLACE_LISTING_STATUSES.removed; });
+        return {
+            visibleToMerchantIds: this.uniqueStrings([ownerMerchantId, ...activeParentIds]),
+            listings: nextListings,
+        };
+    }
+    static pauseListing(marketplace, parentMarketplaceId, options = {}) {
+        return this.upsertListing(marketplace, parentMarketplaceId, { status: marketplace_constants_1.MARKETPLACE_LISTING_STATUSES.paused, ownerMerchantId: options.ownerMerchantId }, options);
+    }
+    static resumeListing(marketplace, parentMarketplaceId, options = {}) {
+        return this.upsertListing(marketplace, parentMarketplaceId, { status: marketplace_constants_1.MARKETPLACE_LISTING_STATUSES.active, ownerMerchantId: options.ownerMerchantId }, options);
+    }
+    static removeListing(marketplace, parentMarketplaceId, options = {}) {
+        return this.upsertListing(marketplace, parentMarketplaceId, { status: marketplace_constants_1.MARKETPLACE_LISTING_STATUSES.removed, ownerMerchantId: options.ownerMerchantId }, options);
+    }
+    static buildCanonicalMarketplaceListingPatch({ product, parentMerchantId, relationshipId = '', relationshipType = marketplace_constants_1.MARKETPLACE_RELATIONSHIP_TYPES.marketplaceSeller, listingStatus = marketplace_constants_1.MARKETPLACE_LISTING_STATUSES.active, at = Date.now(), }) {
+        if (!(product === null || product === void 0 ? void 0 : product.documentId) || !parentMerchantId)
+            return null;
+        const ownerMerchantId = String(product.merchantId || product.vendorId || '');
+        if (!ownerMerchantId)
+            return null;
+        const current = this.normalizeMarketplace(product.marketplace);
+        const existing = current.listings[parentMerchantId];
+        const nextMarketplace = this.upsertListing(current, parentMerchantId, {
+            relationshipId,
+            relationshipType,
+            status: listingStatus,
+            ownerMerchantId,
+        }, { at });
+        const listingUnchanged = existing &&
+            existing.relationshipId === relationshipId &&
+            existing.relationshipType === relationshipType &&
+            existing.status === listingStatus;
+        const visibleUnchanged = JSON.stringify(this.uniqueStrings(current.visibleToMerchantIds).sort()) ===
+            JSON.stringify(this.uniqueStrings(nextMarketplace.visibleToMerchantIds).sort());
+        return listingUnchanged && visibleUnchanged ? null : { marketplace: nextMarketplace };
+    }
+    // ---------------------------------------------------------------------
+    // Shim helpers (replace ad-hoc backend/web logic with one ORM source)
+    // ---------------------------------------------------------------------
+    // Replaces backend `Procedure.resolveProductsWithEffectiveCommission` for
+    // a single product+relationship pair. Backend keeps the Firestore lookup
+    // and dispatches the override via this helper.
+    static resolveEffectiveCommission(product, relationship, contextMerchantId) {
+        const baseCommission = String((product === null || product === void 0 ? void 0 : product.reRobeCommission) || '');
+        if (!product || !relationship)
+            return baseCommission;
+        if (relationship.isActive === false)
+            return baseCommission;
+        if (relationship.relationshipType &&
+            relationship.relationshipType !== marketplace_constants_1.MARKETPLACE_RELATIONSHIP_TYPES.marketplaceSeller) {
+            return baseCommission;
+        }
+        if (contextMerchantId && relationship.parentMerchantId && relationship.parentMerchantId !== contextMerchantId) {
+            return baseCommission;
+        }
+        if (contextMerchantId && product.vendorId && product.vendorId === contextMerchantId) {
+            return baseCommission;
+        }
+        const override = relationship.marketplaceCommission;
+        if (override === undefined || override === null || override === '')
+            return baseCommission;
+        return String(override);
+    }
+    static applyEffectiveCommissionToProducts({ products = [], relationships = [], contextMerchantId, }) {
+        if (!Array.isArray(products) || products.length === 0)
+            return products;
+        const relationshipsBySellerId = (Array.isArray(relationships) ? relationships : []).reduce((acc, relationship) => {
+            const sellerId = String((relationship === null || relationship === void 0 ? void 0 : relationship.childMerchantId) || '');
+            if (sellerId)
+                acc[sellerId] = relationship;
+            return acc;
+        }, {});
+        return products.map((product) => {
+            const relationship = relationshipsBySellerId[String((product === null || product === void 0 ? void 0 : product.vendorId) || (product === null || product === void 0 ? void 0 : product.merchantId) || '')];
+            if (!relationship)
+                return product;
+            const effectiveCommission = this.resolveEffectiveCommission(product, relationship, contextMerchantId);
+            if (effectiveCommission === String((product === null || product === void 0 ? void 0 : product.reRobeCommission) || ''))
+                return product;
+            return Object.assign(Object.assign({}, product), { reRobeCommission: effectiveCommission });
+        });
+    }
+    // Replaces ad-hoc per-component branches in
+    // RetailProductQuickEntry / QuickProductUpload / SimplifiedManagedProductDetails.
+    // Always returns the canonical seller-owned shape regardless of `isActingAs`.
+    // `isActingAs` and `parentMerchantId` are accepted for API compatibility
+    // with the call sites being migrated, but ownership is intentionally
+    // independent of who initiated the create — marketplace visibility for the
+    // parent is derived later via `product.marketplace` and indexed Typesense
+    // fields.
+    static buildSellerProductOwnership(params) {
+        const sellerMerchantId = params === null || params === void 0 ? void 0 : params.sellerMerchantId;
+        if (!sellerMerchantId) {
+            throw new MarketplaceErrors_2.MarketplaceOwnershipError('sellerMerchantId is required');
+        }
+        return {
+            merchantId: sellerMerchantId,
+            vendorId: sellerMerchantId,
+            merchants: [sellerMerchantId],
+        };
+    }
+    static defaultSellerCommission() {
+        return marketplace_constants_1.MARKETPLACE_SELLER_DEFAULT_COMMISSION;
+    }
+    // Builds the Typesense filter expression that scopes parent-marketplace
+    // act-as searches to a single managed merchant. Returning an empty
+    // string allows callers to short-circuit without producing a malformed
+    // filter expression like `vendorId:=`.
+    static buildActAsTypesenseFilter(managedMerchantId) {
+        if (!managedMerchantId)
+            return '';
+        return `vendorId:=${String(managedMerchantId)}`;
+    }
+    // Normalizes an arbitrary commission rate input (string / number /
+    // comma-decimal) into the canonical `'0'..'1'` string. Throws a typed
+    // error for inputs outside the valid range so callers can surface UX
+    // copy without re-implementing validation.
+    static normalizeCommissionRate(value) {
+        if (value === null || value === undefined || value === '') {
+            throw new MarketplaceErrors_2.MarketplaceCommissionRateError('commission rate is required');
+        }
+        const sanitized = String(value).trim().replace(',', '.');
+        const numeric = Number(sanitized);
+        if (!Number.isFinite(numeric)) {
+            throw new MarketplaceErrors_2.MarketplaceCommissionRateError(`commission rate '${value}' is not a finite number`);
+        }
+        const normalized = numeric > 1 ? numeric / 100 : numeric;
+        if (normalized < 0 || normalized > 1) {
+            throw new MarketplaceErrors_2.MarketplaceCommissionRateError(`commission rate '${value}' must be between 0 and 1 inclusive`);
+        }
+        return String(Number(normalized.toFixed(6)));
+    }
+}
+exports.default = MarketplaceProductHelpers;

package/lib/helpers/OrderHelpers.d.ts

@@ -1,9 +1,11 @@
+import { OrderLinePricing, OrderLinePricingLike } from '../types/pricing-types';
 export default class OrderHelpers {
+    getLinePricing(line: OrderLinePricingLike | null | undefined): OrderLinePricing;
     getOrderIdFromShopifyObj(order: ShopifyRestApiOrderObj): string | number | null;
     getShippingTypeFromShopifyObj(shippingLines: ShippingLineRest[] | null | undefined): string;
     getPaymentTypeUsingTags(tags: string | null | undefined): string | null;
     getSalesChannelUsingTags(tags: string | null | undefined): string | null;
-    buildLineItemFromProduct(product: CompleteProduct, currencyCode: string, quantity?: number, taxProps?: RibbnTaxProps): ReRobeOrderLineItem;
+    buildLineItemFromProduct(product: CompleteProduct, currencyCode: string, quantity?: number, taxProps?: RibbnTaxProps, marketplace?: MarketplaceLineSnapshot): ReRobeOrderLineItem;
     toFixedPointPrice(price: number | string): string;
     getAmountSumByField(array: OrderRefund[] | ReRobeOrderLineItem[], fieldKey: string): number;
     getOrderInfoWithRefundsAndFulfillments(order: CompleteOrder): OrderWithRefundsAndFulfillmentsInfoObj;
@@ -47,7 +49,7 @@ export default class OrderHelpers {
     getPaymentTerminalReceiptInfo(payload?: any): PaymentTerminalReceiptInfo;
     getFormattedFulfillmentLocation(order: ReRobeOrderObj): string;
     generateReceiptLabels(locale: string, paymentMethod: string, entryMode?: string): ReceiptLabels;
-    buildReceiptObjFromOrder({ order, merchant, merchantLogoUrl, receiptNumber, additionalInfo, isRefund, refundId, originalReceiptNumber, }: {
+    buildReceiptObjFromOrder({ order, merchant, merchantLogoUrl, receiptNumber, additionalInfo, isRefund, refundId, originalReceiptNumber, includeMarketplaceSellerPrefix, }: {
         order: ReRobeOrderObj;
         merchant: MerchantObj;
         merchantLogoUrl: string;
@@ -56,6 +58,7 @@ export default class OrderHelpers {
         isRefund?: boolean;
         refundId?: string | null;
         originalReceiptNumber?: string | null;
+        includeMarketplaceSellerPrefix?: boolean;
     }): ReceiptObj;
     /**
      * Generates an idempotency key from a ReRobeOrderObj to prevent duplicate order creation

package/lib/helpers/OrderHelpers.js

@@ -5,7 +5,17 @@ const Utilities_1 = require("../helpers/Utilities");
 const order_constants_1 = require("../constants/order-constants");
 const translations_1 = require("../translations");
 const CryptoPolyfill_1 = require("./CryptoPolyfill");
+const PricingHelpers_1 = require("./PricingHelpers");
+const MarketplaceLineDisplayHelpers_1 = require("./marketplace/MarketplaceLineDisplayHelpers");
 class OrderHelpers {
+    // Frozen-rate pricing snapshot for a single order line item. Reads
+    // `line.taxRate` (captured at order creation) so the gross display
+    // reflects the tax actually charged, not whatever the current catalog
+    // says. Non-breaking — `buildReceiptObjFromOrder` continues to compute
+    // its own gross math inline; new callers can opt in via this accessor.
+    getLinePricing(line) {
+        return PricingHelpers_1.default.getOrderLinePricing(line);
+    }
     getOrderIdFromShopifyObj(order) {
         const { id, tags } = order;
         if (!tags) {
@@ -66,7 +76,7 @@ class OrderHelpers {
         }
         return null;
     }
-    buildLineItemFromProduct(product, currencyCode, quantity = 1, taxProps = {}) {
+    buildLineItemFromProduct(product, currencyCode, quantity = 1, taxProps = {}, marketplace) {
         var _a;
         const q = quantity || 1;
         const getImgSrc = () => {
@@ -78,7 +88,7 @@ class OrderHelpers {
             }
             return '';
         };
-        return {
+        const lineItem = {
             title: product.title,
             quantity: q,
             variant: {
@@ -119,6 +129,10 @@ class OrderHelpers {
             },
             handle: product.handle || '',
         };
+        if (marketplace) {
+            lineItem.marketplace = marketplace;
+        }
+        return lineItem;
     }
     toFixedPointPrice(price) {
         return Number(price).toFixed(2);
@@ -579,7 +593,7 @@ class OrderHelpers {
             entryModeLabel,
         };
     }
-    buildReceiptObjFromOrder({ order, merchant, merchantLogoUrl = '', receiptNumber = '', additionalInfo = '', isRefund = false, refundId = null, originalReceiptNumber = null, }) {
+    buildReceiptObjFromOrder({ order, merchant, merchantLogoUrl = '', receiptNumber = '', additionalInfo = '', isRefund = false, refundId = null, originalReceiptNumber = null, includeMarketplaceSellerPrefix = false, }) {
         var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x;
         const { address: merchantAddress, legalName, name, contactEmail, phone = '', organizationNumber = '', primaryDomain, currency: storeCurrencyCode, returnPolicy, } = merchant;
         const currencyCode = ((_a = order.totalPricePresentment) === null || _a === void 0 ? void 0 : _a.currencyCode) || storeCurrencyCode;
@@ -594,7 +608,7 @@ class OrderHelpers {
             if (isRefund) {
                 totalPrice = -Math.abs(totalPrice);
             }
-            let title = l.title || l.brand || '';
+            let title = (0, MarketplaceLineDisplayHelpers_1.formatMarketplaceLineDisplayTitle)({ lineItem: l }, { includeSellerPrefix: includeMarketplaceSellerPrefix });
             if (Number(l === null || l === void 0 ? void 0 : l.quantity) > 1) {
                 const unitPrice = isRefund
                     ? -Math.abs(Number((_c = (_b = l === null || l === void 0 ? void 0 : l.originalUnitPrice) === null || _b === void 0 ? void 0 : _b.amount) !== null && _c !== void 0 ? _c : 0))