rerobe-js-orm 4.8.7 → 4.9.0

package/lib/helpers/marketplace/FeeAllocationPolicy.js

@@ -0,0 +1,36 @@
+"use strict";
+// Strategy interface for distributing a basket-level fee across marketplace
+// line items. Concrete implementations live in sibling files. Callers should
+// depend on this abstraction (and the registered `basis` string) rather than
+// any concrete class so new bases can be added without modifying existing
+// fee-allocation call sites.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconcileAllocationsToTotal = exports.roundFeeAmount = void 0;
+// Pure money rounding to two decimals matches the rest of the marketplace
+// helpers and keeps allocations comparable to currency display values.
+const roundFeeAmount = (value) => Number(Number(value || 0).toFixed(2));
+exports.roundFeeAmount = roundFeeAmount;
+// Aligns the sum of allocations with the requested fee amount. Rounding can
+// drift cents, so the largest-share line absorbs the residual to keep the
+// invariant `sum(allocations) === requested fee` whenever possible.
+const reconcileAllocationsToTotal = (allocations, totalFeeAmount) => {
+    if (!Array.isArray(allocations) || allocations.length === 0) {
+        return [];
+    }
+    const total = (0, exports.roundFeeAmount)(totalFeeAmount);
+    const sum = (0, exports.roundFeeAmount)(allocations.reduce((acc, alloc) => acc + Number((alloc === null || alloc === void 0 ? void 0 : alloc.amount) || 0), 0));
+    const drift = (0, exports.roundFeeAmount)(total - sum);
+    if (drift === 0) {
+        return allocations;
+    }
+    // Apply the residual to the line with the largest absolute allocation.
+    let targetIdx = 0;
+    for (let i = 1; i < allocations.length; i += 1) {
+        if (Math.abs(Number(allocations[i].amount || 0)) > Math.abs(Number(allocations[targetIdx].amount || 0))) {
+            targetIdx = i;
+        }
+    }
+    return allocations.map((alloc, idx) => idx === targetIdx
+        ? Object.assign(Object.assign({}, alloc), { amount: (0, exports.roundFeeAmount)(Number(alloc.amount || 0) + drift) }) : alloc);
+};
+exports.reconcileAllocationsToTotal = reconcileAllocationsToTotal;

package/lib/helpers/marketplace/FeeAllocationPolicyRegistry.d.ts

@@ -0,0 +1,6 @@
+import { FeeAllocationPolicy } from './FeeAllocationPolicy';
+export declare const register: (policy: FeeAllocationPolicy) => void;
+export declare const get: (basis: string) => FeeAllocationPolicy;
+export declare const has: (basis: string) => boolean;
+export declare const getStripeFeePolicy: () => FeeAllocationPolicy;
+export declare const getRibbnFeePolicy: () => FeeAllocationPolicy;

package/lib/helpers/marketplace/FeeAllocationPolicyRegistry.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRibbnFeePolicy = exports.getStripeFeePolicy = exports.has = exports.get = exports.register = void 0;
+const marketplace_constants_1 = require("../../constants/marketplace-constants");
+const EvenPerSellerStripeFeePolicy_1 = require("./EvenPerSellerStripeFeePolicy");
+const ProportionalToLineNetPolicy_1 = require("./ProportionalToLineNetPolicy");
+// Process-wide registry for marketplace fee-allocation strategies. Built-in
+// strategies are registered eagerly. Bring-your-own bases (e.g. tier-based
+// fees) can be added at runtime via `register(policy)` to satisfy OCP.
+const REGISTRY = {};
+const register = (policy) => {
+    REGISTRY[policy.basis] = policy;
+};
+exports.register = register;
+const get = (basis) => REGISTRY[basis] || REGISTRY[marketplace_constants_1.DEFAULT_STRIPE_FEE_ALLOCATION_BASIS];
+exports.get = get;
+const has = (basis) => Boolean(REGISTRY[basis]);
+exports.has = has;
+// Convenience accessors so backend callers don't need to remember which
+// basis is the canonical default for each fee bucket.
+const getStripeFeePolicy = () => (0, exports.get)(marketplace_constants_1.DEFAULT_STRIPE_FEE_ALLOCATION_BASIS);
+exports.getStripeFeePolicy = getStripeFeePolicy;
+const getRibbnFeePolicy = () => (0, exports.get)(marketplace_constants_1.DEFAULT_RIBBN_FEE_ALLOCATION_BASIS);
+exports.getRibbnFeePolicy = getRibbnFeePolicy;
+(0, exports.register)(new EvenPerSellerStripeFeePolicy_1.default());
+(0, exports.register)(new ProportionalToLineNetPolicy_1.default());

package/lib/helpers/marketplace/InventoryPolicy.d.ts

@@ -0,0 +1,18 @@
+export type InventoryAdjustmentParams = {
+    variantId?: string;
+    locationId?: string;
+    defaultLocationId?: string;
+    quantity?: number;
+};
+export type InventoryAdjustmentResult = {
+    variantInventory?: VariantInventory[];
+    inventoryLocations?: InventoryLocation[];
+    quantity?: number;
+    stockStatus?: string;
+};
+export interface InventoryPolicy {
+    readonly kind: string;
+    canHandle(product: CompleteProduct | null | undefined): boolean;
+    decrement(product: CompleteProduct, params: InventoryAdjustmentParams): InventoryAdjustmentResult;
+    restore(product: CompleteProduct, params: InventoryAdjustmentParams): InventoryAdjustmentResult;
+}

package/lib/helpers/marketplace/InventoryPolicy.js

@@ -0,0 +1,7 @@
+"use strict";
+// Strategy interface for adjusting inventory in response to a marketplace
+// sale or refund. Concrete implementations are dispatched by the registry
+// based on `canHandle(product)`. Callers (backend triggers, web flows) ask
+// the registry for the right policy and apply it without branching on
+// product class or stock status.
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/helpers/marketplace/InventoryPolicyRegistry.d.ts

@@ -0,0 +1,4 @@
+import { InventoryPolicy } from './InventoryPolicy';
+export declare const register: (policy: InventoryPolicy, position?: "append" | "prepend") => void;
+export declare const list: () => InventoryPolicy[];
+export declare const find: (product: CompleteProduct | null | undefined) => InventoryPolicy | null;

package/lib/helpers/marketplace/InventoryPolicyRegistry.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.find = exports.list = exports.register = void 0;
+const MultivariantLocationInventoryPolicy_1 = require("./MultivariantLocationInventoryPolicy");
+const OneOfAKindInventoryPolicy_1 = require("./OneOfAKindInventoryPolicy");
+const UntrackedStockInventoryPolicy_1 = require("./UntrackedStockInventoryPolicy");
+// Order matters: the first policy whose `canHandle` returns true wins.
+// Untracked stock takes precedence so a multivariant product flagged as
+// indefinite stock is treated as untracked.
+const REGISTRY = [];
+const register = (policy, position = 'append') => {
+    if (position === 'prepend') {
+        REGISTRY.unshift(policy);
+        return;
+    }
+    REGISTRY.push(policy);
+};
+exports.register = register;
+const list = () => [...REGISTRY];
+exports.list = list;
+const find = (product) => {
+    if (!product)
+        return null;
+    return REGISTRY.find((policy) => policy.canHandle(product)) || null;
+};
+exports.find = find;
+(0, exports.register)(new UntrackedStockInventoryPolicy_1.default());
+(0, exports.register)(new MultivariantLocationInventoryPolicy_1.default());
+(0, exports.register)(new OneOfAKindInventoryPolicy_1.default());

package/lib/helpers/marketplace/LineNetCommissionPolicy.d.ts

@@ -0,0 +1,5 @@
+import { CommissionPolicy, CommissionPolicyContext, CommissionPolicyFeeContext, CommissionPolicyResult } from './CommissionPolicy';
+export default class LineNetCommissionPolicy implements CommissionPolicy {
+    readonly basis: "LINE_NET_EXCLUDING_TAX";
+    calculate({ taxableAmount, originalRate, marketplaceRate }: CommissionPolicyContext, { stripeFee, ribbnFee }: CommissionPolicyFeeContext): CommissionPolicyResult;
+}

package/lib/helpers/marketplace/LineNetCommissionPolicy.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const marketplace_constants_1 = require("../../constants/marketplace-constants");
+const CommissionPolicy_1 = require("./CommissionPolicy");
+// Marketplace commission is computed on the line tax-exclusive net. The
+// original product commission still applies on top, so the marketplace cut
+// does not erode the seller's payout. Used as the default policy.
+class LineNetCommissionPolicy {
+    constructor() {
+        this.basis = marketplace_constants_1.MARKETPLACE_COMMISSION_BASES.lineNetExcludingTax;
+    }
+    calculate({ taxableAmount, originalRate, marketplaceRate }, { stripeFee, ribbnFee }) {
+        const originalProductCommissionAmount = (0, CommissionPolicy_1.roundCommissionAmount)(taxableAmount * originalRate);
+        const marketplaceCommissionAmount = (0, CommissionPolicy_1.roundCommissionAmount)(taxableAmount * marketplaceRate);
+        const managedMerchantProceedsAmount = (0, CommissionPolicy_1.roundCommissionAmount)(Math.max(0, originalProductCommissionAmount));
+        const sellerProceedsAmount = (0, CommissionPolicy_1.roundCommissionAmount)(Math.max(0, taxableAmount - originalProductCommissionAmount - marketplaceCommissionAmount - stripeFee - ribbnFee));
+        return {
+            originalProductCommissionAmount,
+            marketplaceCommissionAmount,
+            managedMerchantProceedsAmount,
+            sellerProceedsAmount,
+        };
+    }
+}
+exports.default = LineNetCommissionPolicy;

package/lib/helpers/marketplace/MarketplaceErrors.d.ts

@@ -0,0 +1,6 @@
+export declare class MarketplaceCommissionRateError extends Error {
+    constructor(message: string);
+}
+export declare class MarketplaceOwnershipError extends Error {
+    constructor(message: string);
+}

package/lib/helpers/marketplace/MarketplaceErrors.js

@@ -0,0 +1,21 @@
+"use strict";
+// Typed errors thrown by MarketplaceProductHelpers and adjacent strategies.
+// Living in their own module satisfies the tslint max-classes-per-file rule
+// while keeping error semantics encapsulated.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarketplaceOwnershipError = exports.MarketplaceCommissionRateError = void 0;
+/* tslint:disable:max-classes-per-file */
+class MarketplaceCommissionRateError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MarketplaceCommissionRateError';
+    }
+}
+exports.MarketplaceCommissionRateError = MarketplaceCommissionRateError;
+class MarketplaceOwnershipError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'MarketplaceOwnershipError';
+    }
+}
+exports.MarketplaceOwnershipError = MarketplaceOwnershipError;

package/lib/helpers/marketplace/MarketplaceLedgerHelpers.d.ts

@@ -0,0 +1,40 @@
+import { MarketplaceLedgerStatusValue } from '../../constants/marketplace-constants';
+export declare class MarketplaceLedgerTransitionError extends Error {
+    constructor(currentStatus: string, nextStatus: string);
+}
+type BuildEntryFromSnapshotParams = {
+    snapshot: MarketplaceLineSnapshot;
+    parentOrderId: string;
+    parentOrderLineItemId?: string;
+    documentId?: string;
+    returnDeadlineTimestamp?: number | null;
+    status?: MarketplaceLedgerStatusValue;
+    at?: number;
+};
+export declare const buildEntryFromSnapshot: ({ snapshot, parentOrderId, parentOrderLineItemId, documentId, returnDeadlineTimestamp, status, at, }: BuildEntryFromSnapshotParams) => MarketplaceLedgerEntry;
+export declare const isTransitionAllowed: (current: string, next: string) => boolean;
+export declare const transitionStatus: (entry: MarketplaceLedgerEntry, nextStatus: MarketplaceLedgerStatusValue, options?: {
+    at?: number;
+}) => MarketplaceLedgerEntry;
+type ApplyReturnParams = {
+    entry: MarketplaceLedgerEntry;
+    quantityReturned?: number;
+    at?: number;
+};
+export declare const applyReturn: ({ entry, quantityReturned, at, }: ApplyReturnParams) => {
+    entry: MarketplaceLedgerEntry;
+    adjustment: MarketplaceReturnAdjustment;
+};
+declare const _default: {
+    buildEntryFromSnapshot: ({ snapshot, parentOrderId, parentOrderLineItemId, documentId, returnDeadlineTimestamp, status, at, }: BuildEntryFromSnapshotParams) => MarketplaceLedgerEntry;
+    transitionStatus: (entry: MarketplaceLedgerEntry, nextStatus: MarketplaceLedgerStatusValue, options?: {
+        at?: number;
+    }) => MarketplaceLedgerEntry;
+    isTransitionAllowed: (current: string, next: string) => boolean;
+    applyReturn: ({ entry, quantityReturned, at, }: ApplyReturnParams) => {
+        entry: MarketplaceLedgerEntry;
+        adjustment: MarketplaceReturnAdjustment;
+    };
+    MarketplaceLedgerTransitionError: typeof MarketplaceLedgerTransitionError;
+};
+export default _default;

package/lib/helpers/marketplace/MarketplaceLedgerHelpers.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyReturn = exports.transitionStatus = exports.isTransitionAllowed = exports.buildEntryFromSnapshot = exports.MarketplaceLedgerTransitionError = void 0;
+const marketplace_constants_1 = require("../../constants/marketplace-constants");
+const MarketplaceProductHelpers_1 = require("../MarketplaceProductHelpers");
+const STATUS_TIMESTAMP_KEYS = {
+    [marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.pendingReturnPeriod]: 'pendingReturnPeriodAtTimestamp',
+    [marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.payable]: 'payableAtTimestamp',
+    [marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.paidOut]: 'paidOutAtTimestamp',
+    [marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.returnedBeforePayout]: 'returnedBeforePayoutAtTimestamp',
+    [marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.refundedAfterPayout]: 'refundedAfterPayoutAtTimestamp',
+    [marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.transferReversed]: 'transferReversedAtTimestamp',
+};
+// Allowed transitions encode the marketplace ledger lifecycle. Returns are
+// terminal in their respective branches; cross-branch hops are rejected.
+const ALLOWED_TRANSITIONS = {
+    [marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.pendingReturnPeriod]: [
+        marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.payable,
+        marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.returnedBeforePayout,
+    ],
+    [marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.payable]: [
+        marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.paidOut,
+        marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.returnedBeforePayout,
+    ],
+    [marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.paidOut]: [
+        marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.refundedAfterPayout,
+        marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.transferReversed,
+    ],
+    [marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.refundedAfterPayout]: [marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.transferReversed],
+    [marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.returnedBeforePayout]: [],
+    [marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.transferReversed]: [],
+};
+class MarketplaceLedgerTransitionError extends Error {
+    constructor(currentStatus, nextStatus) {
+        super(`Marketplace ledger transition not allowed: ${currentStatus} -> ${nextStatus}`);
+        this.name = 'MarketplaceLedgerTransitionError';
+    }
+}
+exports.MarketplaceLedgerTransitionError = MarketplaceLedgerTransitionError;
+const now = () => Date.now();
+const buildEntryFromSnapshot = ({ snapshot, parentOrderId, parentOrderLineItemId, documentId, returnDeadlineTimestamp, status = marketplace_constants_1.DEFAULT_MARKETPLACE_LEDGER_STATUS, at, }) => {
+    if (!snapshot) {
+        throw new Error('snapshot is required to build a marketplace ledger entry');
+    }
+    if (!parentOrderId) {
+        throw new Error('parentOrderId is required to build a marketplace ledger entry');
+    }
+    const ts = typeof at === 'number' ? at : now();
+    const lifecycle = {
+        createdAtTimestamp: ts,
+        updatedAtTimestamp: ts,
+    };
+    const tsKey = STATUS_TIMESTAMP_KEYS[status];
+    if (tsKey)
+        lifecycle[tsKey] = ts;
+    return {
+        documentId,
+        parentOrderId,
+        parentOrderLineItemId,
+        parentMerchantId: snapshot.parentMerchantId,
+        managedMerchantId: snapshot.managedMerchantId,
+        relationshipId: snapshot.relationshipId,
+        productId: snapshot.productId,
+        variantId: snapshot.variantId,
+        status,
+        snapshot,
+        returnDeadlineTimestamp: returnDeadlineTimestamp === undefined ? null : returnDeadlineTimestamp,
+        lifecycle,
+    };
+};
+exports.buildEntryFromSnapshot = buildEntryFromSnapshot;
+const isTransitionAllowed = (current, next) => {
+    if (!current || !next)
+        return false;
+    if (current === next)
+        return true;
+    const allowed = ALLOWED_TRANSITIONS[current];
+    return Array.isArray(allowed) && allowed.includes(next);
+};
+exports.isTransitionAllowed = isTransitionAllowed;
+const transitionStatus = (entry, nextStatus, options = {}) => {
+    if (!entry) {
+        throw new Error('entry is required to transition status');
+    }
+    if (!(0, exports.isTransitionAllowed)(entry.status, nextStatus)) {
+        throw new MarketplaceLedgerTransitionError(String(entry.status), String(nextStatus));
+    }
+    if (entry.status === nextStatus) {
+        return entry;
+    }
+    const ts = typeof options.at === 'number' ? options.at : now();
+    const lifecycle = Object.assign(Object.assign({}, entry.lifecycle), { updatedAtTimestamp: ts });
+    const tsKey = STATUS_TIMESTAMP_KEYS[nextStatus];
+    if (tsKey)
+        lifecycle[tsKey] = ts;
+    return Object.assign(Object.assign({}, entry), { status: nextStatus, lifecycle });
+};
+exports.transitionStatus = transitionStatus;
+const applyReturn = ({ entry, quantityReturned, at, }) => {
+    if (!entry) {
+        throw new Error('entry is required to apply a return');
+    }
+    const adjustment = MarketplaceProductHelpers_1.default.buildReturnAdjustment({
+        snapshot: entry.snapshot,
+        quantityReturned,
+    });
+    const targetStatus = entry.status === marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.paidOut
+        ? marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.refundedAfterPayout
+        : marketplace_constants_1.MARKETPLACE_LEDGER_STATUSES.returnedBeforePayout;
+    const transitioned = (0, exports.transitionStatus)(entry, targetStatus, { at });
+    return { entry: transitioned, adjustment };
+};
+exports.applyReturn = applyReturn;
+exports.default = {
+    buildEntryFromSnapshot: exports.buildEntryFromSnapshot,
+    transitionStatus: exports.transitionStatus,
+    isTransitionAllowed: exports.isTransitionAllowed,
+    applyReturn: exports.applyReturn,
+    MarketplaceLedgerTransitionError,
+};

package/lib/helpers/marketplace/MarketplaceLegacyAdapters.d.ts

@@ -0,0 +1,53 @@
+export declare const isLegacyDuplicateProduct: (product: any) => boolean;
+export declare const parseRibbnIdTag: (tagsLike: any) => string | null;
+type FromLegacyDuplicateLineParams = {
+    lineItem: ReRobeOrderLineItem;
+    originalProduct: CompleteProduct;
+    relationship: {
+        documentId?: string;
+        parentMerchantId?: string;
+        marketplaceCommission?: string | number;
+    };
+    parentMerchantId?: string;
+    stripeFeeAllocatedAmount?: number;
+    ribbnFeeAllocatedAmount?: number;
+};
+type BuildCanonicalMigrationPlanParams = {
+    duplicateProduct: any;
+    originalProduct: CompleteProduct;
+    relationship: {
+        documentId?: string;
+        parentMerchantId?: string;
+        childMerchantId?: string;
+    };
+    at?: number;
+};
+export declare const fromLegacyDuplicateLine: ({ lineItem, originalProduct, relationship, parentMerchantId, stripeFeeAllocatedAmount, ribbnFeeAllocatedAmount, }: FromLegacyDuplicateLineParams) => MarketplaceLineSnapshot;
+export declare const getOriginalProductIdFromDuplicate: (duplicateProduct: any) => string | null;
+export declare const buildCanonicalMigrationPlan: ({ duplicateProduct, originalProduct, relationship, at, }: BuildCanonicalMigrationPlanParams) => {
+    duplicateProductId: any;
+    originalProductId: string | null;
+    parentMerchantId: any;
+    childMerchantId: string;
+    patch: {
+        marketplace: ProductMarketplace;
+    } | null;
+    alreadyCanonical: boolean;
+};
+declare const _default: {
+    isLegacyDuplicateProduct: (product: any) => boolean;
+    parseRibbnIdTag: (tagsLike: any) => string | null;
+    fromLegacyDuplicateLine: ({ lineItem, originalProduct, relationship, parentMerchantId, stripeFeeAllocatedAmount, ribbnFeeAllocatedAmount, }: FromLegacyDuplicateLineParams) => MarketplaceLineSnapshot;
+    getOriginalProductIdFromDuplicate: (duplicateProduct: any) => string | null;
+    buildCanonicalMigrationPlan: ({ duplicateProduct, originalProduct, relationship, at, }: BuildCanonicalMigrationPlanParams) => {
+        duplicateProductId: any;
+        originalProductId: string | null;
+        parentMerchantId: any;
+        childMerchantId: string;
+        patch: {
+            marketplace: ProductMarketplace;
+        } | null;
+        alreadyCanonical: boolean;
+    };
+};
+export default _default;

package/lib/helpers/marketplace/MarketplaceLegacyAdapters.js

@@ -0,0 +1,99 @@
+"use strict";
+// Backwards-compatibility helpers for orders/products created under the
+// duplicate-based marketplace model. The new canonical model exposes
+// `lineItem.marketplace` snapshots directly; these adapters lift legacy
+// data into the same shape so payouts, refunds, and reporting do not need
+// to branch on era. All helpers are pure and accept already-loaded data.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCanonicalMigrationPlan = exports.getOriginalProductIdFromDuplicate = exports.fromLegacyDuplicateLine = exports.parseRibbnIdTag = exports.isLegacyDuplicateProduct = void 0;
+const marketplace_constants_1 = require("../../constants/marketplace-constants");
+const MarketplaceProductHelpers_1 = require("../MarketplaceProductHelpers");
+const LEGACY_DUPLICATE_SYSTEM_TAG = 'marketplaceSellerProduct';
+const RIBBN_ID_TAG_PREFIX = 'ribbnId:';
+const stringArray = (value) => Array.isArray(value) ? value.filter((v) => typeof v === 'string' && v.length > 0) : [];
+const findRibbnIdInTags = (tags) => {
+    const tag = tags.find((t) => typeof t === 'string' && t.indexOf(RIBBN_ID_TAG_PREFIX) === 0);
+    if (!tag)
+        return null;
+    const value = tag.slice(RIBBN_ID_TAG_PREFIX.length);
+    return value || null;
+};
+const isLegacyDuplicateProduct = (product) => {
+    if (!product)
+        return false;
+    const systemTags = stringArray(product.systemTags);
+    return systemTags.includes(LEGACY_DUPLICATE_SYSTEM_TAG);
+};
+exports.isLegacyDuplicateProduct = isLegacyDuplicateProduct;
+const parseRibbnIdTag = (tagsLike) => {
+    if (Array.isArray(tagsLike)) {
+        return findRibbnIdInTags(stringArray(tagsLike));
+    }
+    if (tagsLike && typeof tagsLike === 'object') {
+        const merged = [...stringArray(tagsLike.systemTags), ...stringArray(tagsLike.tags)];
+        return findRibbnIdInTags(merged);
+    }
+    return null;
+};
+exports.parseRibbnIdTag = parseRibbnIdTag;
+// Produces a `MarketplaceLineSnapshot` for an old duplicate-tagged line item
+// using the same line-net commission policy as new orders so payout/refund
+// math stays consistent across eras. The original product's owner is used
+// as `managedMerchantId`; the relationship contributes the marketplace rate
+// and parent id.
+const fromLegacyDuplicateLine = ({ lineItem, originalProduct, relationship, parentMerchantId, stripeFeeAllocatedAmount = 0, ribbnFeeAllocatedAmount = 0, }) => {
+    var _a, _b, _c, _d, _e;
+    const quantity = Number(lineItem === null || lineItem === void 0 ? void 0 : lineItem.quantity) > 0 ? Number(lineItem.quantity) : 1;
+    const discountedAmount = Number((_a = lineItem === null || lineItem === void 0 ? void 0 : lineItem.discountedPrice) === null || _a === void 0 ? void 0 : _a.amount);
+    const originalAmount = Number((_b = lineItem === null || lineItem === void 0 ? void 0 : lineItem.originalTotalPrice) === null || _b === void 0 ? void 0 : _b.amount);
+    const safeOriginal = Number.isFinite(originalAmount) ? originalAmount : 0;
+    const safeDiscounted = Number.isFinite(discountedAmount) ? discountedAmount : safeOriginal;
+    const discountAmount = Math.max(0, safeOriginal - safeDiscounted);
+    const taxAmount = Number((_c = lineItem === null || lineItem === void 0 ? void 0 : lineItem.taxAmount) === null || _c === void 0 ? void 0 : _c.amount) || 0;
+    const currencyCode = ((_d = lineItem === null || lineItem === void 0 ? void 0 : lineItem.originalTotalPrice) === null || _d === void 0 ? void 0 : _d.currencyCode) || ((_e = lineItem === null || lineItem === void 0 ? void 0 : lineItem.discountedPrice) === null || _e === void 0 ? void 0 : _e.currencyCode) || '';
+    return MarketplaceProductHelpers_1.default.buildLineSnapshot({
+        product: originalProduct,
+        parentMerchantId: String(parentMerchantId || (relationship === null || relationship === void 0 ? void 0 : relationship.parentMerchantId) || ''),
+        managedMerchantId: String((originalProduct === null || originalProduct === void 0 ? void 0 : originalProduct.merchantId) || (originalProduct === null || originalProduct === void 0 ? void 0 : originalProduct.vendorId) || ''),
+        relationshipId: String((relationship === null || relationship === void 0 ? void 0 : relationship.documentId) || ''),
+        marketplaceCommissionRate: (relationship === null || relationship === void 0 ? void 0 : relationship.marketplaceCommission) === undefined || (relationship === null || relationship === void 0 ? void 0 : relationship.marketplaceCommission) === null
+            ? '0'
+            : relationship.marketplaceCommission,
+        marketplaceCommissionBasis: marketplace_constants_1.DEFAULT_MARKETPLACE_COMMISSION_BASIS,
+        quantity,
+        currencyCode,
+        discountAmount,
+        taxAmount,
+        stripeFeeAllocatedAmount,
+        ribbnFeeAllocatedAmount,
+    });
+};
+exports.fromLegacyDuplicateLine = fromLegacyDuplicateLine;
+const getOriginalProductIdFromDuplicate = (duplicateProduct) => (0, exports.parseRibbnIdTag)(duplicateProduct);
+exports.getOriginalProductIdFromDuplicate = getOriginalProductIdFromDuplicate;
+const buildCanonicalMigrationPlan = ({ duplicateProduct, originalProduct, relationship, at, }) => {
+    const originalProductId = (originalProduct === null || originalProduct === void 0 ? void 0 : originalProduct.documentId) || (0, exports.getOriginalProductIdFromDuplicate)(duplicateProduct);
+    const parentMerchantId = (relationship === null || relationship === void 0 ? void 0 : relationship.parentMerchantId) || (duplicateProduct === null || duplicateProduct === void 0 ? void 0 : duplicateProduct.merchantId) || '';
+    const patch = MarketplaceProductHelpers_1.default.buildCanonicalMarketplaceListingPatch({
+        product: Object.assign(Object.assign({}, originalProduct), { documentId: originalProductId }),
+        parentMerchantId,
+        relationshipId: (relationship === null || relationship === void 0 ? void 0 : relationship.documentId) || '',
+        at,
+    });
+    return {
+        duplicateProductId: (duplicateProduct === null || duplicateProduct === void 0 ? void 0 : duplicateProduct.documentId) || '',
+        originalProductId,
+        parentMerchantId,
+        childMerchantId: (relationship === null || relationship === void 0 ? void 0 : relationship.childMerchantId) || (originalProduct === null || originalProduct === void 0 ? void 0 : originalProduct.merchantId) || (originalProduct === null || originalProduct === void 0 ? void 0 : originalProduct.vendorId) || '',
+        patch,
+        alreadyCanonical: !patch,
+    };
+};
+exports.buildCanonicalMigrationPlan = buildCanonicalMigrationPlan;
+exports.default = {
+    isLegacyDuplicateProduct: exports.isLegacyDuplicateProduct,
+    parseRibbnIdTag: exports.parseRibbnIdTag,
+    fromLegacyDuplicateLine: exports.fromLegacyDuplicateLine,
+    getOriginalProductIdFromDuplicate: exports.getOriginalProductIdFromDuplicate,
+    buildCanonicalMigrationPlan: exports.buildCanonicalMigrationPlan,
+};

package/lib/helpers/marketplace/MarketplaceLineDisplayHelpers.d.ts

@@ -0,0 +1,40 @@
+export type MarketplaceLineDisplayMode = 'customer' | 'staff' | 'receipt';
+type MarketplaceVariantOptionsInput = Record<string, any> | {
+    name?: any;
+    key?: any;
+    label?: any;
+    value?: any;
+}[];
+export type MarketplaceLineDisplayTitleInput = {
+    lineItem?: ReRobeOrderLineItem | null;
+    title?: string | null;
+    brand?: string | null;
+    sellerDisplayName?: string | null;
+    variantOptions?: MarketplaceVariantOptionsInput | null;
+    variantSku?: string | null;
+};
+export type MarketplaceLineDisplayTitleOptions = {
+    mode?: MarketplaceLineDisplayMode;
+    includeSellerPrefix?: boolean;
+    prefixSeparator?: string;
+    appendVariantLabel?: boolean;
+};
+export type MarketplaceLineDisplayTitleResult = {
+    baseTitle: string;
+    displayTitle: string;
+    sellerDisplayName: string;
+    variantLabel: string;
+};
+export declare const getMarketplaceLineSellerDisplayName: (lineItem?: ReRobeOrderLineItem | null, fallbackSellerDisplayName?: string | null) => string;
+export declare const getMarketplaceLineVariantLabel: (input: MarketplaceLineDisplayTitleInput) => string;
+export declare const stripMarketplaceSellerPrefix: (title: string | null | undefined, sellerDisplayName: string | null | undefined, prefixSeparator?: string) => string;
+export declare const buildMarketplaceLineDisplayTitle: (input: MarketplaceLineDisplayTitleInput, options?: MarketplaceLineDisplayTitleOptions) => MarketplaceLineDisplayTitleResult;
+export declare const formatMarketplaceLineDisplayTitle: (input: MarketplaceLineDisplayTitleInput, options?: MarketplaceLineDisplayTitleOptions) => string;
+declare const _default: {
+    buildMarketplaceLineDisplayTitle: (input: MarketplaceLineDisplayTitleInput, options?: MarketplaceLineDisplayTitleOptions) => MarketplaceLineDisplayTitleResult;
+    formatMarketplaceLineDisplayTitle: (input: MarketplaceLineDisplayTitleInput, options?: MarketplaceLineDisplayTitleOptions) => string;
+    getMarketplaceLineSellerDisplayName: (lineItem?: ReRobeOrderLineItem | null, fallbackSellerDisplayName?: string | null) => string;
+    getMarketplaceLineVariantLabel: (input: MarketplaceLineDisplayTitleInput) => string;
+    stripMarketplaceSellerPrefix: (title: string | null | undefined, sellerDisplayName: string | null | undefined, prefixSeparator?: string) => string;
+};
+export default _default;